Skip to main content

​
Base URL

Workflow action endpoints are accessed through: 
{baseUrl}/risksheet/api/
Where {baseUrl} is the RISKSHEET application server URL.

​
Authentication

All workflow API requests require valid Polarion user authentication via HTTP Basic Auth or session cookies.

​
Get Available Actions

Retrrieves the list of workflow actions available for a specific work item based on its current state. 
GET {baseUrl}/risksheet/api/getWorkflowActions

​
Request Parameters

ParameterTypeRequiredDescription
projectIdquery stringYesPolarion project identifier
workItemIdquery stringYesWork item identifier (e.g., ‘RISK-001’)

​
Query Examples

GET /risksheet/api/getWorkflowActions?projectId=PROJ&workItemId=RISK-001
GET /risksheet/api/getWorkflowActions?projectId=PROJ&workItemId=REQ-042

​
Response Format

{
  "actions": [
    {
      "id": "review",
      "name": "Send for Review",
      "description": "Submit item for review approval"
    },
    {
      "id": "approve",
      "name": "Approve",
      "description": "Approve reviewed item"
    },
    {
      "id": "reject",
      "name": "Reject",
      "description": "Return item for revision"
    }
  ]
}

​
Response Properties

PropertyTypeDescription
actionsarrayList of available workflow actions
actions[].idstringUnique action identifier for use in changeStatus requests
actions[].namestringDisplay name of the workflow action
actions[].descriptionstringHuman-readable description of what the action does

​
Execute Workflow Action

Executes a workflow action to transition a work item to a new status. 
POST {baseUrl}/risksheet/api/changeWorkItemStatus

​
Request Body

{
  "projectId": "PROJ",
  "workItemId": "RISK-001",
  "actionId": "review"
}
PropertyTypeRequiredDescription
projectIdstringYesPolarion project identifier
workItemIdstringYesWork item identifier to transition
actionIdstringYesAction ID from getWorkflowActions response

​
Response Format

Success Response: 
{
  "status": "success",
  "message": "Workflow action executed successfully",
  "newStatus": "In Review"
}
Error Response: 
{
  "status": "error",
  "message": "Cannot review item: required field 'Risk Level' is empty",
  "errorCode": "MISSING_REQUIRED_FIELD"
}

​
Response Properties

PropertyTypeDescription
statusstringsuccess or error
messagestringResult message or error description
newStatusstringNew status value after successful transition
errorCodestringError code for programmatic handling (only in error responses)

​
Change Document Status

Executes a workflow action on a RISKSHEET document (Polarion module). 
POST {baseUrl}/risksheet/api/changeDocumentStatus

​
Request Body

{
  "projectId": "PROJ",
  "documentLocation": "space/path/DocumentName",
  "actionId": "approve"
}
PropertyTypeRequiredDescription
projectIdstringYesPolarion project identifier
documentLocationstringYesDocument path (e.g., ‘MySpace/RiskAnalysis’)
actionIdstringYesWorkflow action ID to execute

​
Response Format

Same as work item status change: 
{
  "status": "success",
  "message": "Document status changed successfully",
  "newStatus": "Approved"
}

​
Common Error Codes

Error CodeHTTP StatusDescriptionResolution
ITEM_NOT_FOUND404Work item or document does not existVerify projectId and workItemId/documentLocation
INVALID_ACTION400Action ID is not valid for this itemCall getWorkflowActions to get valid actions
ACCESS_DENIED403User lacks permissions for this actionCheck user roles and permissions in Polarion
MISSING_REQUIRED_FIELD400Required field is empty or invalidComplete all required fields before transitioning
DOCUMENT_NOT_ACCESSIBLE404Document was deleted or access deniedVerify document exists and is accessible
TRANSACTION_FAILED500Database transaction error occurredRetry request; contact administrator if persists

​
Status Transition Flow

User selects workflow action
        |
        v
Query getWorkflowActions
  ?projectId=PROJ&workItemId=ITEM
        |
        v
Display available actions
  - Review
  - Approve
  - Reject
        |
        v
User clicks action
        |
        v
POST changeWorkItemStatus
  projectId: PROJ
  workItemId: ITEM
  actionId: selected_action
        |
        v
Validate required fields
        |
   +----+----+
   |         |
   v         v
Success    Error
(New)    (Show message)
Status
   |         |
   +----+----+
        |
        v
  Refresh UI

​
Required Field Validation

Before executing a workflow action, Nextedy RISKSHEET validates that all required fields for that status are populated. If validation fails:
  1. The action is not executed
  2. Error response indicates which fields are missing
  3. User must complete required fields before retrying
Workflow actions are configured in Polarion’s workflow definition. The RISKSHEET API exposes whatever actions are available in the underlying Polarion workflow. To modify available actions or required fields, configure the workflow in Polarion’s workflow manager.

​
Suggestions API

The API can optionally provide suggested workflow actions based on item state: 
GET /risksheet/api/suggestedActions?projectId=PROJ&workItemId=ITEM
This returns a filtered list of the most relevant actions for the current state, ordered by likelihood of use. Example Response: 
{
  "suggested": [
    {
      "id": "review",
      "name": "Send for Review",
      "score": 0.95
    }
  ]
}

​
Batch Operations

To execute the same action on multiple items:
  1. Query getWorkflowActions once to verify action is valid
  2. Execute changeWorkItemStatus for each item individually
  3. Collect results and display summary
Batch endpoint is not available; operations must be sequential.

​
Transaction Management

All workflow operations are atomic — either the entire action succeeds or it fails and is rolled back. Partial updates never occur.
Workflow operations on locked or checked-out documents may fail. Ensure the document is not locked by another user before attempting status changes.
Source Code
  • StatusChangeCommand.ts
  • WorkflowActionServlet.java
  • CommandFactory.ts
  • AppConfig.ts
  • AppConfigParser.ts