Add Assignees to Workflow BP Records
PUT /ws/rest/service/v2/bp/record/wf/addassignees
Available: 23.12 and later
Purpose
Add existing project/shell users as assignees to a list of existing in-flight workflow BP records of a project/shell with an Active, View-Only, or On-Hold status.
The system updates the BP Record Audit Log to reflect changes made using this REST service.
Note:
- Users who have already accepted a task as Assignees cannot be added to the corresponding workflow BP records using this REST service. Including them causes the request to fail.
- You can use this REST service for workflows with a Completion Policy of All-Majority and All-Consensus; you can use it for a Single Completion Policy only if the Assignee of the specified record has not accepted the task.
Prerequisites
- You must be an active user and a member of the company and the applicable project/shell.
- You must have Workflow Business Process Permissions (Get, Update) in the User Administration to use this API. Otherwise, contact your company administrator to update your Integration permission settings for Workflow Business Processes as outlined in Updating Permissions for Integration Users.
Request Format
The request parameters are specified as a JSON Map {} - structure:
{ "options":{}, "data":[{}] }
In the options JSON map:
{"project_number": "<value>", "bpname": "<value>","email_notification" : "<yes/no>"}
In the data list:
[ {"record_numbers": <List of record numbers>, "add_assignees" : <List of usernames>} ]
The data list size is restricted to one.
Request Parameters
The following parameters can be included in the request:
| Request Parameter | Required? | Data Type | Description |
|---|---|---|---|
project_number
|
No | String |
A valid 'Active' Unifier Shell number. For example, RE00000. If no value is specified, it is considered as Company. |
bpname
|
Yes | String | A Business Process name of a Workflow BP. For example, Action Items. |
email_notification
|
No | Boolean | Specify if an email notification is to be sent. Values include: Yes or No (default). |
record_numbers
|
Yes | List | Record numbers of a Workflow BP. For example, ["AI-000734", "AI-000735"]. |
add_assignees
|
Yes | List | A list of user names (login name) to be added as assignees to the current step of the workflow record. For example, ["testuser1", "coadmin"]. |
Recommendations
When submitting the request, you can specify in the array up to 1000 records and 10 assignees.
Sample Request
{
"options": {
"project_number" : "RE00000",
"bpname" : "Action Items",
"email_notification" : "yes"
},
"data" : [
{
"record_numbers" : ["AI-000734", "AI-000735"],
"add_assignees" : ["testuser1", "coadmin"]
}
]
}
Response Format
A JSON object is returned in the following format.
{
"data": [{"record_id" : "<Internal record ID for the specified BP record>"}],
"message": [ "<list of messages>"],
"status": <integer value>,
"rest_audit_id": <ID from the REST audit table matching this request>
}
A successful response displays a status code 200.
A failed response displays a message with a status code 3010.
Sample Success Response
{
"data": [ ],
"message": [ "success" ],
"status": 200,
"rest_audit_id": 720
}
Sample Failed Response 1
{
"data": [],
"message": ["Business Process Name is not correct."],
"status": 17002,
"rest_audit_id": 721
}
Sample Failed Response 2
{
"data": [],
"message": [
"AI-000734 specified is in Initiation step.",
"AI-000735 is terminated, cannot add assignee.",
"testuser1 is not an active member of RE00000."
],
"status": 3010,
"rest_audit_id": 722
}
Supported Validation Messages and Status Codes
The following validation messages and status codes display in the response when incorrect values are provided in the request:
| Field Name | Use-case Scenario | Status Code | Error Message |
|---|---|---|---|
| project_number | Project number was not specified for a shell-level BP. | 1361 | Project number is required |
| project_number | Specified project number is invalid (only applies to shell-level BPs). | 602 | Project/Shell Number is not correct. |
| project_number | Specified project number is not active (only applies to shell-level BPs). | 17022 | Update cannot be performed when project/shell status is Inactive or View-Only or On-Hold. |
| bpname | BP name was omitted. | 603 | Business Process Name is required. |
| bpname | Comma-separated list of BP names specified. | 17001 | Cannot support multiple business processes. |
| bpname | Specified BP name is invalid. | 17002 | Business Process Name is not correct. |
| bpname | Specified BP name is not a Workflow BP. | 17003 | Business Process is not a workflow BP. |
| bpname | Specified BP name is not active. | 3006 | Business Process is not Active. |
| email_notification | email_notification is specified but value is empty or incorrect. | 17021 | Invalid email notification, provide either 'yes' or 'no' value. |
| record_numbers | Record number was omitted. | 17004 | Record number is required. |
| record_numbers | Specified record number is invalid. | <record number> is not correct. | |
| record_numbers | Specified record is in Initiation step. | <record number> is in Initiation step, cannot add assignee. | |
| record_numbers | Specified record is terminated. | <record number> is terminated, cannot add assignee. | |
| record_numbers | Completion Policy is Single for specified record number and record has been accepted by an assignee. | <record number> has already been accepted, cannot add assignee. | |
| record_numbers | Specified record is closed. | <record number> is closed, cannot add assignee. | |
| add_assignees | add_assignees was omitted. | 17020 | Add assignees is required. |
| add_assignees | add_assignees is specified but value is blank. | 17016 | User name is required for add assignees. |
| add_assignees | Specified user is not active in the project/shell or company. | <user name> is not an active member of <project number>/company. |