Change control workflow triggered by custom server script fails

QMS Qualio
, , , , , , , ,
1

We’ve implemented a custom server-side script that’s supposed to automatically update change control workflow status based on specific approval conditions. The script executes without errors in the logs, but the workflow status remains unchanged.

The trigger is configured to fire on approval completion, and we’re using the Qualio API endpoint for status transitions. We’ve verified API permissions for the service account, but wondering if there’s something specific about payload structure or event timing that we’re missing.

const response = await qualioAPI.post('/change-controls/transition', {
  id: changeControlId,
  targetStatus: 'implementation',
  triggeredBy: 'automated_script'
});

Anyone experienced similar issues with programmatic workflow updates in qual-2022.2?

2

Your payload structure looks incomplete. You need to include the current status as well, not just the target. Qualio validates the transition path. Try adding currentStatus: 'pending_approval' to your payload. Without it, the API can’t verify the transition is valid according to your workflow configuration.

3

Had the exact same issue last month. The problem is multi-faceted and requires addressing all three key areas:

API Permissions: Your service account needs both API access AND specific permissions for the target workflow state. Go to Admin > User Roles and verify the account has ‘Change Control State Manager’ permission. This is separate from general API access and specifically controls workflow transitions.

Event Trigger Configuration: The ‘approval completion’ event in qual-2022.2 has a known timing issue. Switch your trigger to ‘post-approval-validated’ event instead. This ensures all approval validations complete before your script fires, preventing race conditions.

Payload Structure: Your current payload is missing critical fields. Here’s the corrected version:

const response = await qualioAPI.post('/change-controls/transition', {
  id: changeControlId,
  currentStatus: 'pending_approval',
  targetStatus: 'implementation',
  transitionReason: 'Automated approval completion',
  triggeredBy: 'automated_script',
  validateOnly: false
});

The currentStatus field is mandatory for Qualio to validate the transition path. The transitionReason is required for audit trail compliance. Also add error handling to catch validation failures:

if (response.status === 200 && response.data.warnings) {
  console.warn('Transition warnings:', response.data.warnings);
}

After making these three changes, our workflow automation worked flawlessly. The key is ensuring all three areas - permissions, trigger timing, and payload completeness - are correctly configured.

4

Check the API response body even when status is 200. Sometimes Qualio returns success but includes warnings that explain why the action didn’t complete. We discovered our transitions were silently failing because we hadn’t included required custom field values in the payload. The API accepted the request but didn’t execute the transition due to validation rules.

5

Are you using async/await properly? If your script continues executing before the API call completes, you might not be catching errors. Also, make sure you’re not hitting rate limits - Qualio throttles API calls and will queue or reject requests if you exceed the limit. We had workflows that looked like they weren’t updating but were actually queued.

6

I’ve seen this before. The service account might have API access but not the specific workflow transition permissions. Check if your account has the ‘Workflow State Manager’ role assigned in addition to API access. That’s a common gotcha with programmatic status changes.

7

Also worth checking the event trigger configuration. In qual-2022.2, the ‘approval completion’ event fires before certain validation checks complete. We had to switch to using the ‘post-approval-validation’ event instead, which fires after all approval validations are done. This ensures the change control is in the right state to accept the transition. The timing difference is only a few seconds, but it matters for workflow integrity.