> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Actions API

> Nextedy RISKSHEET provides server-side endpoints for querying available workflow actions and executing document status transitions directly from the risk analysis interface.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

```text theme={null}
Risksheet App                POST /changeDocStatus           Workflow Action Servlet

1. Validate dirty state      ─────────────────────────►      2. Begin transaction
2. Show progress toast                                       3. Execute workflow action
3. Reload page on success    ◄─────────────────────────      4. Save & commit module
5. Return result
```

## Endpoints

### Get Available Workflow Actions

Retrieves the list of available workflow actions (status transitions) for a specific work item based on its current state and Polarion workflow configuration.

| Property     | Type            | Default  | Description                                 |
| ------------ | --------------- | -------- | ------------------------------------------- |
| Method       | `GET` or `POST` | --       | Both HTTP methods are supported             |
| `project`    | `string`        | Required | Polarion project identifier                 |
| `workItemId` | `string`        | Required | Work item ID to query available actions for |

The response contains valid workflow transitions determined by the current work item state and the Polarion workflow configuration.

### Change Document Status

Executes a workflow action to change the status of a Polarion document (LiveDoc).

| Property   | Type     | Default  | Description                                                                 |
| ---------- | -------- | -------- | --------------------------------------------------------------------------- |
| Method     | `POST`   | --       | Only POST is supported for status changes                                   |
| `project`  | `string` | Required | Polarion project identifier                                                 |
| `document` | `string` | Required | Document location path                                                      |
| `actionId` | `string` | Required | Workflow action identifier (e.g., `approve`, `reject`, `submit_for_review`) |

<Warning title="Action ID Values">
  The `actionId` values are defined in the Polarion workflow configuration and must match configured transition names exactly. Check your project's workflow definitions for valid action identifiers.
</Warning>

**Request payload:**

```json theme={null}
{
  "project": "MyProject",
  "document": "Risks/FMEA_BrakeSystem",
  "actionId": "approve"
}
```

**Success response:**

```json theme={null}
{
  "success": true,
  "message": "Document Status Changed"
}
```

**Error response:**

```json theme={null}
{
  "success": false,
  "message": "Workflow transition failed: required fields are missing"
}
```

<Note title="Approval Review Limitation">
  Risksheet's approval review creates approval-tagged comments on work items but does **not** trigger Polarion's formal approval state transitions (draft → reviewed → approved). To advance a document through Polarion's formal approval workflow, call the **Change Document Status** endpoint with an `actionId` that maps to a configured workflow transition.
</Note>

## Client-Side Behavior

### Pre-Validation

Before executing a status change, the client validates:

| Check         | Behavior    | Description                                                              |
| ------------- | ----------- | ------------------------------------------------------------------------ |
| Dirty state   | Blocked     | Status changes are blocked when the sheet has unsaved changes            |
| Unsaved edits | Error toast | You must save all pending changes before triggering workflow transitions |

<Tip title="Save Before Transitioning">
  Always save your work before attempting a document status change. The system validates that no unsaved edits exist to prevent data inconsistency.
</Tip>

### Progress Notifications

| Stage       | Toast Title                     | Message                                 |
| ----------- | ------------------------------- | --------------------------------------- |
| In progress | `Changing Document Status`      | `Please wait...`                        |
| Success     | `Document Status Changed`       | --                                      |
| Failure     | `Document Status Change Failed` | Server error message displayed verbatim |

### Page Reload

After a successful status change, the entire browser page automatically reloads. This ensures all UI elements -- buttons, permissions, validation rules, and available workflow actions -- reflect the new document status.

## Transaction Management

All document status changes are executed within Polarion transactions (`beginTx`/`commitTx`). All data lives in Polarion work items — Risksheet visualizes and edits Polarion data, it does not store data separately. If an error occurs during the workflow execution:

1. The transaction is rolled back
2. The error message is returned to the client
3. The document remains in its previous state

## Document Accessibility Validation

The system validates document accessibility before attempting workflow actions:

| Condition             | Behavior                                             |
| --------------------- | ---------------------------------------------------- |
| Document accessible   | Proceeds with workflow action                        |
| Document unresolvable | Returns error: `Document not accessible: [location]` |
| Document deleted      | Returns error with inaccessible status               |

## Error Handling

Error messages from the server are displayed verbatim to help you diagnose problems. Common error scenarios:

| Error Type              | Cause                                         | Resolution                                          |
| ----------------------- | --------------------------------------------- | --------------------------------------------------- |
| Validation failure      | Required fields not populated                 | Fill in required fields before transitioning        |
| Permission denied       | Insufficient user permissions                 | Contact your Polarion administrator                 |
| Workflow rule violation | Transition not allowed from current state     | Verify available transitions for the current status |
| Document not accessible | Document deleted, moved, or access restricted | Check document location and permissions             |

<Info title="Verify in application">
  Console logging is available for debugging workflow executions. Open browser developer tools to view `actionId`, response data, and document state during troubleshooting.
</Info>

## Configuration Dependencies

The workflow actions API interacts with several request properties:

| Property   | Type     | Default  | Description                                            |
| ---------- | -------- | -------- | ------------------------------------------------------ |
| `actionId` | `string` | None     | Identifier for the specific workflow action to execute |
| `project`  | `string` | Required | Polarion project containing the document               |
| `document` | `string` | Required | Document location path within the project              |

These three properties co-occur in the request payload. The `actionId` must correspond to a valid transition defined in the Polarion workflow configuration for the target document type.

## Complete Example

A typical document approval workflow integrates with the sheet configuration's `reviews` section. The example below uses YAML, the recommended format for editing sheet configuration (the configuration editor supports YAML since v25.5.0):

```yaml theme={null}
reviews:
  reviewManager: WorkItemBased
  typeProperties:
    itemTypes: review
    linkRole: relates_to
dataTypes:
  risk:
    type: fmea_risk
    rejectedAction: reject
    rejectedStatus: rejected
    rejectedResolution: invalid
```

In this sheet configuration, the `rejectedAction` property specifies the workflow `actionId` used when a risk item is rejected during review. The workflow actions API processes this transition and updates the document status accordingly.

<Note title="Review Manager Reminder">
  Three review managers are available: **CommentBased**, **ApprovalBased**, and **WorkItemBased**. The **ApprovalBased** review creates approval-tagged comments but does not trigger Polarion's formal approval state transitions — use the workflow actions API for formal status changes. **WorkItemBased** review (shown above) creates dedicated review work items linked to the risk item via the configured `itemTypes` (mandatory work item type) and `linkRole` (mandatory link role).
</Note>

## Related Pages

* [Velocity Template Context](/risksheet/reference/api/velocity-context) -- Velocity context variables available during workflow processing
* [Configuration Properties Index](/risksheet/reference/configuration/properties-index) -- all configuration properties
* [Sheet Configuration Format](/risksheet/reference/configuration/risksheet-json-format) -- complete sheet configuration reference

<LastReviewed date="2026-06-09" />