Workflow Actions API - Nextedy Documentation

Risksheet App                POST /changeDocStatus           Workflow Action Servlet

Validate dirty state      ─────────────────────────►      2. Begin transaction
Show progress toast                                       3. Execute workflow action
Reload page on success    ◄─────────────────────────      4. Save & commit module
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`)

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.

Request payload:

{
  "project": "MyProject",
  "document": "Risks/FMEA_BrakeSystem",
  "actionId": "approve"
}

Success response:

{
  "success": true,
  "message": "Document Status Changed"
}

Error response:

{
  "success": false,
  "message": "Workflow transition failed: required fields are missing"
}

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.

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

Always save your work before attempting a document status change. The system validates that no unsaved edits exist to prevent data inconsistency.

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:

The transaction is rolled back
The error message is returned to the client
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

Console logging is available for debugging workflow executions. Open browser developer tools to view actionId, response data, and document state during troubleshooting.

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):

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.

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).

Velocity Template Context — Velocity context variables available during workflow processing
Configuration Properties Index — all configuration properties
Sheet Configuration Format — complete sheet configuration reference

​Endpoints

​Get Available Workflow Actions

​Change Document Status

​Client-Side Behavior

​Pre-Validation

​Progress Notifications

​Page Reload

​Transaction Management

​Document Accessibility Validation

​Error Handling

​Configuration Dependencies

​Complete Example

​Related Pages

Endpoints

Get Available Workflow Actions

Change Document Status

Client-Side Behavior

Pre-Validation

Progress Notifications

Page Reload

Transaction Management

Document Accessibility Validation

Error Handling

Configuration Dependencies

Complete Example

Related Pages