This document is intended for developers who are using the TeamworkIQ API. It describes API concepts related to Process Roles. Before reading this document, you should read Process Roles, which summarizes the basic TeamworkIQ process role concepts.
Defining custom process roles
The process model JSON contains a
process_roles property, whose value is a JSON object, Within the object, the keys are the role numbers and the values are Role Definitions.
Anatomy of a process role
Every process role has:
- role number
Different role types have different additional properties..
Every process role has a role number, which must be unique within the process model. The process model uses the role number to refer to the role.
Role numbers must obey the following rules:
- Process Owner: role_number == 1001
- Custom process roles: 2001 <= role_no <= 3000.
Role types are JOB, USER or OWNER.
Role names are as follows:
- Process Owner Role: "Process Owner" (read-only)
- Job Role: Process author chooses a name
- User Role: The full name of the user (automatically set, and read-only)
The assignee properties of the role depend on the role type.
- Job Role:
- User Role:
For a Job Role, the client may set
assigned_to_users to an array of user numbers. The
assigned_to_users_actual property is read-only, but its value is automatically set to the value of
For a User Role, the client may set
assigned_to_user to an array of user numbers. The
assigned_to_user_actual property is read-only, but its value is automatically set to the value of
To update the assignees of a Job Role or User Role, it is necessary to update the role definition in the process model.
Job Roles and User Roles have a property called
accepted_by. This property specifies the user number of the user who has accepted the role.
There is no
accepted_by concept for Process Owners. All Process Owners are responsible for managing the process.