REST API authorization for process instances

The authorization roles and action policies that are associated with each process instance determine the implemented authorization roles and action policies. You can enable users to take actions by assigning them to the roles or policies.

For all APIs that support action policies, you can change the default association with the tw_admins group to another group. For more information about roles, see Authorization roles.

Process Instance Variable Resource (PUT)

PUT /rest/bpm/wle/v1/process/{instanceId}/variable/{name}

Action policy: ACTION_UPDATE_INSTANCE_VARIABLE

Table 1. Process Instance Variable Resource PUT method
Eligible roles Enabled for task states Preconditions API Documentation
  • Business Automation Workflow administrator
  • Process application administrator

If a team is not defined for process application administrators, you can authorize more users by assigning one or more groups to the ACTION_UPDATE_INSTANCE_VARIABLE action policy.

If a team is defined for process application administrators, the action policy is ignored. If the user set up a such a team, the only way to authorize more users is to add them to that team.

Any None For more information about the API to update a variable value in a BPD instance, see Process Instance Variable Resource (PUT).

Process Instance Resource (GET)

GET /rest/bpm/wle/v1/process/{instanceId} [?parts={string}][&taskLimit={integer}][&taskOffset={integer}]
Table 2. Process Instance Resource (GET)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Instance owner
  • Performance metrics user
  • For any task within the process:
    • Task team manager
    • Task owner
    • Task potential owner
    • Collaborator
Any None For more information about the API to retrieve the details of a process instance, see Process Instance Resource (GET).

Process Resource - POST (start)

POST /rest/bpm/wle/v1/process?action={string}&bpdId={string} [&snapshotId={string}][&branchId={string}][&processAppId={string}][&params={string}][&parts={string}]
Table 3. Process Resource - POST (start)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Process instance owner
  • For any task within the process:
    • Task team manager
    • Task owner
    • Task potential owner (if the task owner is not set)
    • Collaborator
  • Process starters (any exposed to start)
Any The snapshot is not archived and not deactivated. For more information about the API to start a BPD instance, see Process Resource - POST (start).

Process Resource - POST (sendMessage)

POST /rest/bpm/wle/v1/process?action={string}&message={string}

Action policy: ACTION_SEND_MESSAGE

Table 4. Process Resource - POST (sendMessage)
Eligible roles Enabled for task states Preconditions API documentation
By default, any role is eligible. Restricted by action policy ACTION_SEND_MESSAGE Any None For more information about the API to send a message to the event manager, see Process Resource - POST (sendMessage).

Process Instance Resource - PUT (evaluate a JavaScript expression)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}&script={string} or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}&script={string}
Table 5. Process Instance Resource - PUT (evaluate a JavaScript expression)
Eligible roles Enabled for task states Preconditions API documentation
Any authenticated user (see the precondition) Any In the 99Local.xml file, the <enable-javascript-execution> must be set to true. Its default value is false. For more information about the API to running a JavaScript expression, see Process Instance Resource - PUT (evaluate a JavaScript expression).

Process Instance Resource - PUT (suspend)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}] or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}]

Action policy: ACTION_SUSPEND_INSTANCE

Table 6. Process Instance Resource - PUT (suspend)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Any authenticated user, except if the role is restricted by action policy ACTION_SUSPEND_INSTANCE. By default, users with the tw_admins role are eligible.
Active None For more information about the API to suspend a process instance, see Process Instance Resource - PUT (suspend, resume, terminate, or retry).

Process Instance Resource - PUT (resume)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}] or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}]

Action policy: ACTION_RESUME_INSTANCE

Table 7. Process Instance Resource - PUT (resume)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Any authenticated user, except if the role is restricted by action policy ACTION_RESUME_INSTANCE. By default, users with the tw_admins role are eligible.
Suspended None For more information about the API to resume a process instance, see Process Instance Resource - PUT (suspend, resume, terminate, or retry).

Process Instance Resource - PUT (retry)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}] or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}]

Action policy: ACTION_RETRY_INSTANCE

Table 8. Process Instance Resource - PUT (retry)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Any authenticated user, except if the role is restricted by action policy ACTION_RETRY_INSTANCE. By default, users with the tw_admins role are eligible.
Failed None For more information about the API to retry a process instance, see Process Instance Resource - PUT (suspend, resume, terminate, or retry).

Process Instance Resource - PUT (terminate)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}] or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}]

Action policy: ACTION_ABORT_INSTANCE

Table 9. Process Instance Resource - PUT (terminate)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Any authenticated user, except if the role is restricted by action policy ACTION_ABORT_INSTANCE. By default, users with the tw_admins role are eligible.
Suspended, Failed, or Terminated None For more information about the API to terminate a process instance, see Process Instance Resource - PUT (suspend, resume, terminate, or retry).

Process Instance Resource - PUT (delete)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}] or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}[&parts={string}]

Action policy: ACTION_DELETE_INSTANCE

Table 10. Process Instance Resource - PUT (delete)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Any authenticated user, except if the role is restricted by action policy ACTION_DELETE_INSTANCE. By default, users with the tw_admins role are eligible.
Suspended, Failed, or Terminated None For more information about the API to delete a process instance, see Process Instance Resource - PUT (suspend, resume, terminate, or retry).

Process Instance Resource - PUT (update document)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}&docId={string}&docType={string}[&data={string}][&docUrl={string}][&parts={string}]

Action policy: ACTION_UPDATE_DOCUMENT

Table 11. Process Instance Resource - PUT (update document)
Eligible roles Enabled for BPD instance execution status Preconditions API documentation
  • Instance owner
  • Owner of any task in the instance
  • A member of the group that is assigned to the task, or a manager of the task team, or a collaborator of the task
  • The user that follows the instance
  • The user that is tagged in the instance
  • Process application administrator
  • The user is a member of the team to which the BPD is exposed through Performance Metrics
BPD instance is active, failed or suspended or Allow content operations for the completed process has been checked in BPD in the designer when the instance is completed or terminated. None For more information about the API to update a process instance, see Process Instance Resource - PUT (update document).

Process Instance Resource - PUT (update due date)

PUT /rest/bpm/wle/v1/process/{instanceId}?action={string}&dueDate={string}[&parts={string}] or POST /rest/bpm/wle/v1/process/{instanceId}?action={string}&dueDate={string}[&parts={string}]

Action policy: ACTION_CHANGE_INSTANCE_DUEDATE

Table 12. Process Instance Resource - PUT (update due date)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Instance owner
  • Any authenticated user, except if the role is restricted by action policy ACTION_CHANGE_INSTANCE_DUEDATE. By default, users with the tw_admins role are eligible.
Active or Suspended None For more information about the API to update a process instance, see Process Instance Resource - PUT (update due date).

Process Instance Resource - POST (add document)

POST /rest/bpm/wle/v1/process/{instanceId}?action={string}&docType={string}&name={string}[&data={string}][&docUrl={string}][&hideInPortal={boolean}][&parts={string}]

Action policy: ACTION_ADD_DOCUMENT

Table 13. Process Instance Resource - POST (add document)
Eligible roles Enabled for BPD instance execution status Preconditions API documentation
  • Instance owner
  • Owner of any task in the instance
  • A member of the group that is assigned to the task, or a manager of the task team, or a collaborator of the task
  • The user that follows the instance
  • The user that is tagged in the instance
  • Process application administrator
  • The user is a member of the team to which the BPD is exposed through Performance Metrics
BPD instance is active, failed or suspended or Allow content operations for the completed process has been checked in BPD in the designer when the instance is completed or terminated. Allow locally managed documents is enabled if the instance uses BPM managed folders For more information about the API to update a process instance, see Process Instance Resource - POST (add document).

Process Instance Resource - POST (comment)

POST /rest/bpm/wle/v1/process/{instanceId}?action={string}&comment={string}[&origCommentId={string}][&parts={string}]

Action policy: ACTION_ADD_COMMENT

Table 14. Process Instance Resource - POST (comment)
Eligible roles Enabled for task states Preconditions API documentation
  • Any authenticated user, except if the role is restricted by action policy ACTION_ADD_COMMENT. By default, any user is eligible.
Any None For more information about the API to add a comment to a process instance, see Process Instance Resource - POST (comment).

Process Instance Resource - POST (fire timer)

POST /rest/bpm/wle/v1/process/{instanceId}?action={string}&timerTokenId={string}[&parts={string}]

Action policy: ACTION_FIRE_TIMER

Table 15. Process Instance Resource - POST (fire timer)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Users who are enabled by action policy ACTION_FIRE_TIMER and authorized to retrieve instance details. By default, any user.
Active None For more information about the API to trigger a timer manually, see Process Instance Resource - POST (fire timer).

Process Instance Resource - POST (delete token)

POST /rest/bpm/wle/v1/process/{instanceId}?action={string}&tokenId={string}[&parts={string}][&resume={boolean}]

Action policy: ACTION_DELETE_TOKEN

Table 16. Process Instance Resource - POST (delete token)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Users who are enabled by action policy ACTION_DELETE_TOKEN and authorized to retrieve instance details. By default, any user.
Any None For more information about the API to delete a token, see Process Instance Resource - POST (delete token).

Process Instance Task Summary Resource

/rest/bpm/wle/v1/process/{instanceId}/taskSummary/{status}
Table 17. Process Instance Task Summary Resource
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Instance owner
  • Task team manager
  • Task owner
  • Task potential owner (if the task owner is not set)
  • Collaborator
Any None For more information about the API to list process instance tasks, see Process Instance Task Summary Resource.

Process Resource - GET (bulk instance details)

GET /rest/bpm/wle/v1/process?action={string}&instanceIds={string}[&parts={string}]
Table 18. Process Resource - GET (bulk instance details)
Eligible roles Enabled for task states Preconditions API documentation
  • Business Automation Workflow administrator
  • Process application administrator
  • Instance owner
  • Performance team
  • Task team manager
  • Task owner
  • Task potential owner (if the task owner is not set)
  • Collaborator
Any None For more information about the API to retrieve information about process instances, see Process Resource - GET (bulk instance details).

Process Actions Resource - GET

GET /rest/bpm/wle/v1/process/actions?instanceIds={string}[&actions={string}]
Table 19. Process Actions Resource - GET)
Eligible roles Enabled for task states Preconditions API documentation
Any authenticated user Any None For more information about the API to retrieve actions for process instances, see Process Actions Resource - GET.