Add Assignees to Workflow BP Records

PUT /ws/rest/service/v2/bp/record/wf/addassignees

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.

Notes:

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 already 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 in the Unifier General Administration Guide.
The Completion Policy must be All-Majority or All-Consensus.

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.