Assignment and Targeting
The concept of assignment and targeting is widely used throughout the API.
This can be either a static assignment (e.g., always assign to a specific user or department) or a dynamic assignment based on certain criteria (e.g., assign to the user executing a task, assign to the department of the executing user, etc.).
Static assignment can be configured with different assign_mode options to determine how users and departments are selected:
Assign Modes
null: No specific assignment mode. all: All users and departments are included. all_users: All users are included. all_group_accounts: All group accounts are included. any_of: Any of the specified users or departments can be selected. one_of: Exactly one of the specified users or departments must be selected. any_of_user: Any of the specified users can be selected. one_of_user: Exactly one of the specified users must be selected.
Available assign modes may vary depending on the entity and context. Please refer to the specific entity documentation for supported assign modes.
Supported entities
Entities that provide static assignment modes include: Survey, TaskAssignment, ChatConversation
Example: Adding and retrieving assigned users and departments
These entities share the same request structure for creating and updating, which typically includes assign_mode, user_ids, and department_ids fields.
{
"assign_mode": "any_of",
"user_ids": [1, 2, 3],
"department_ids": [4, 5]
}They can also be retrieved with the assigned users and departments included in the response utilising result-control.
Example request:
Example response:
Dynamic Assignment
Dynamic assignment can be done in supported actions via computed_targetable_type field based on various criteria:
For executing user/department (who finishes a task or submits a form etc.)
for_executing_department: Uses the department of the user who is executing the action as the target.for_executing_real_department: Uses the real department of the executing user, ignoring any proxy or delegation.for_executing_user: Uses the user who is executing the action as the target.for_executing_real_user: Uses the real user (not a proxy or delegate) who is executing the action.
task specific
from_task_assignment: Uses the assignment from the related task as the target.
workflow-node specific
from_workflow_node: Uses the related workflow node as the target.for_workflow_node_department: Uses the department associated with the workflow node as the target.for_workflow_node_executed_user_department: Uses the department of the user who executed the workflow node as the target.for_workflow_node_user: Uses the user associated with the workflow node as the target.for_workflow_node_executed_user: Uses the user who executed the workflow node as the target.
What is a workflow node?
It's possible to chain multiple actions. Let's say you have a form that triggers a task assignment action. The resulting task template also has a task assignment action. The new resulting task assignment can again have a task assignment action and so on. Each of the executed steps represent a workflow node.
The assignment resulting from the first workflow node (form submission in this case) can be used in the follow-up workflow nodes specifying a zero based index as config value:
entity select field specific
from_entity_select_fields_users: Uses users selected in entity select fields as the target.from_entity_select_fields_departments: Uses departments selected in entity select fields as the target.
Given you have a form or taskTemplate with entity select fields that allows the selection of users or departments, you can use those selections as target for an action.
Requires an array of field ids to be set in the config field computed_targetables_entity_select_field_ids, e.g.
See form field types (EntitySelect) and form field types (EntitiesSelect) for additional information on entity select fields.
system variable specific
for_system_variable_users: Uses users resolved from system variables as the target.for_system_variable_departments: Uses departments resolved from system variables as the target.
Needs an additional config field computed_targetables_system_variable with the system variable key that should be used to resolve the target users/departments, e.g.
Have a look at system variables to understand how system variables can be used to resolve dynamic data.
Note that in this case the system variable needs to resolve to a user or department or list of users or departments depending on the computed targetable type.
Examples resolving users in different contexts:
system.usersystem.temporaryUsertaskExecution.lastActivityUser
Given that any of the above users has an assigned role or department with additional attributes, you can also access those attributes in the manner of an assignment when the attribute is a field of type entity_select.
system.temporaryUser.role.additional_attributes.{$attributeSetKey}.{$attributeId}.resolved_valuesystem.temporaryUser.role.department.additional_attributes.{$attributeSetKey}.{$attributeId}.resolved_valuetaskExecution.last_activity_user.role.additional_attributes.{$attributeSetKey}.{$attributeId}.resolved_valuetaskExecution.last_activity_user.role.department.additional_attributes.{$attributeSetKey}.{$attributeId}.resolved_valuesystem.user.role.additional_attributes.{$attributeSetKey}.{$attributeId}.resolved_valuesystem.user.role.department.additional_attributes.{$attributeSetKey}.{$attributeId}.resolved_value
Given the action is linked to a form that has entity select fields with users or departments as options, those can also be used as value for computed_targetables_system_variable:
field.{$fieldId}.resolved_value
You may instead want to use the dedicated entity select field specific computed targetable types for better clarity in this case.
Supported actions:
Last updated