Our automated change control system uses ETQ Reliance 2022 REST API to transition change requests through workflow states. Everything works fine until we try to move records from ‘Review’ to ‘Approved’ state - the API consistently returns validation errors.
The API call structure:
POST /api/v2/change-control/{id}/transition
{
"target_state": "Approved",
"approver_id": "USR-12345"
}
Error response: “State transition validation failed: Missing required fields for target state”
We’ve confirmed the approver_id is valid and the user has approval permissions. The state machine allows this transition in the workflow configuration. What mandatory fields does the ‘Approved’ state require that aren’t obvious? Is there something about linking approver records or specific workflow transition logic we’re missing?
Yes, approver linking is more complex than just an ID. You need to create or reference an approver record that includes the approval signature data. The approver object should have the user ID, approval timestamp, and digital signature if your instance requires it. Some workflows also require the approval to be linked to a specific approval step in the workflow definition, not just the user who approved it. Try querying an existing approved change record via the API to see the full approver structure.
The state machine validation in ETQ 2022 is quite strict about transition prerequisites. Beyond mandatory fields, you need to ensure all validation rules for the source state are satisfied before transitioning. For example, if the Review state requires certain attachments or linked records, those must be present before you can move to Approved. The error message is generic but the actual blocker could be missing data from an earlier state. Run a validation check endpoint if available before attempting the transition.
Each workflow state in ETQ has its own set of mandatory fields defined in the state configuration. When you transition to ‘Approved’, you likely need to include fields like approval_date, approval_comments, and possibly approval_method. These aren’t always documented in the API guide because they’re configured per instance. Check your workflow state configuration in the admin panel to see which fields are marked as required for the Approved state.
Another common issue - concurrent workflow instances. If your change control record has multiple approval paths or parallel approval steps, the API needs to know which specific approval step you’re completing. You might need to include a workflow_step_id or approval_sequence_number in your transition payload to indicate which approval in the workflow you’re satisfying.
I’ve implemented several change control integrations. One gotcha - the approver_id you’re sending might not be the right type of reference. ETQ distinguishes between user IDs and approver role IDs. Your workflow might require an approver_role_id that maps to a configured approval role (like ‘Quality Manager’ or ‘Engineering Lead’) rather than a specific user ID. Check if your workflow uses role-based approvals versus user-based approvals.