Summary
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
- type
- name
- assignee/s
Different role types have different additional properties..
Role number
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 type
Role types are JOB, USER or OWNER.
Role name
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)
Assignee/s
The assignee properties of the role depend on the role type.
- Job Role:
assigned_to_users,assigned_to_users_actual - User Role:
assigned_to_user,assigned_to_user_actual
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 assigned_to_users.
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 assigned_to_user.
To update the assignees of a Job Role or User Role, it is necessary to update the role definition in the process model.
Other properties
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.