Skip to main content
Risksheet AppPOST /changeDocStatusWorkflow Action
(Status Change----------------------->Servlet
Command)
1. Validate dirty state2. Begin transaction
2. Show progress toast3. Execute workflow action
3. Reload page on success4. 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 workflow configuration.
PropertyTypeDefaultDescription
MethodGET or POST—Both HTTP methods are supported
projectstringRequiredPolarion project identifier
workItemIdstringRequiredWork 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 (module).
PropertyTypeDefaultDescription
MethodPOST—Only POST is supported for status changes
projectstringRequiredPolarion project identifier
documentstringRequiredDocument location path
actionIdstringRequiredWorkflow 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"
}

​
Client-Side Behavior

​
Pre-Validation

Before executing a status change, the client validates:
CheckBehaviorDescription
Dirty stateBlockedStatus changes are blocked when the sheet has unsaved changes
Unsaved editsError toastYou 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

StageToast TitleMessage
In progressChanging Document StatusPlease wait...
SuccessDocument Status Changed—
FailureDocument Status Change FailedServer 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). 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:
ConditionBehavior
Document accessibleProceeds with workflow action
Document unresolvableReturns error: Document not accessible: [location]
Document deletedReturns error with inaccessible status

​
Error Handling

Error messages from the server are displayed verbatim to help you diagnose problems. Common error scenarios:
Error TypeCauseResolution
Validation failureRequired fields not populatedFill in required fields before transitioning
Permission deniedInsufficient user permissionsContact your Polarion administrator
Workflow rule violationTransition not allowed from current stateVerify available transitions for the current status
Document not accessibleDocument deleted, moved, or access restrictedCheck 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 configuration properties:
PropertyTypeDefaultDescription
actionIdstringNoneIdentifier for the specific workflow action to execute
projectstringRequiredPolarion project containing the document
documentstringRequiredDocument 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 using the API: 
{
  "reviews": {
    "reviewManager": "WorkItemBased",
    "typeProperties": {
      "linkTypes": "review",
      "linkRole": "relates_to"
    }
  },
  "dataTypes": {
    "risk": {
      "type": "fmea_risk",
      "rejectedAction": "reject",
      "rejectedStatus": "rejected",
      "rejectedResolution": "invalid"
    }
  }
}
In this 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.
Source Code
  • StatusChangeCommand.ts
  • WorkflowActionServlet.java
  • CommandFactory.ts
  • AppConfig.ts
  • AppConfigParser.ts