Change control API approval workflow fails at manager review stage

QMS Arena QMS (by PTC)
, , , , , , , ,
1

Our automated change control approval workflow is getting stuck at the manager review stage when triggered via API. We can successfully create change requests and move them through initial review, but the transition to manager approval consistently fails with a state transition error.

API response:


POST /api/v2/change-control/CR-2025-089/approve
{"error": "Invalid state transition",
 "currentState": "technical-review",
 "requestedState": "manager-approval"}

Manual approvals through the UI work fine, but API calls fail. We’re using a service account with Change Manager role permissions. The workflow state machine seems to require intermediate steps that aren’t documented. We’ve verified role-based permissions are correct, but state transition validation keeps blocking the API call. Is there a specific service account configuration needed for programmatic workflow approvals?

2

Check your workflow configuration in Arena. The change control module has configurable state machines, and some organizations customize the approval flow. Your instance might require additional validation fields like approverComments or riskAssessment before allowing the manager-approval transition. Export your workflow configuration and review the transition rules for the technical-review to manager-approval path.

3

The change control workflow has hidden state requirements. Between technical-review and manager-approval, there’s an implicit ‘technical-approved’ state that must be set first. Try calling the technical approval endpoint before requesting manager approval.

4

Here’s the complete solution for change control API workflow approvals:

Workflow State Machine: Arena’s change control uses a strict state machine with role-gated transitions. The standard flow is: initiated → technical-review → technical-approved → manager-approval → approved → implementation

Your error occurs because you’re trying to jump from technical-review directly to manager-approval, skipping the technical-approved state. Each state requires approval from a specific role before advancing.

Role-Based Permissions: Service accounts need multiple permission layers:

  1. Functional role (Change Manager) - grants access to change records
  2. Workflow execution permission - allows API-driven state transitions
  3. Role impersonation rights - permits acting on behalf of required approver roles

Navigate to Admin > Service Accounts > [Your Account] > Advanced Permissions and enable ‘Impersonate Workflow Roles’.

State Transition Validation: The correct API call sequence is:


// Step 1: Technical approval
POST /api/v2/change-control/CR-2025-089/technical-approve
{"approverRole": "technical-reviewer", "comments": "Technical review complete"}

// Step 2: Manager approval
POST /api/v2/change-control/CR-2025-089/manager-approve
{"approverRole": "change-manager", "comments": "Management approval granted"}

Each transition endpoint validates the current state and required approver role.

Service Account Configuration: Your service account needs these specific settings:

  • Primary Role: Change Manager
  • Additional Roles: Technical Reviewer (to approve technical-review state)
  • Permissions: ‘Execute Workflow Transitions’, ‘Impersonate Approver Roles’
  • Workflow Access: Full access to change-control module workflows

The key issue is that service accounts can’t automatically bypass workflow gates even with manager-level roles. You must explicitly approve each stage using the role-specific endpoints.

Implementation Fix: Modify your automation to check current workflow state and call the appropriate approval endpoint:


current_state = get_change_request(cr_id)['workflowState']
if current_state == 'technical-review':
    technical_approve(cr_id)
if current_state == 'technical-approved':
    manager_approve(cr_id)

This respects the workflow state machine while maintaining automation. The UI works because human users are prompted to complete each step sequentially, but API calls must explicitly handle each transition.

5

I added the workflow transition permission but still getting the same error. Could the issue be related to the approval payload structure? What fields are required for the manager approval transition?