3.2 - 3.8 - REST API Designer - Ad Hoc Assignee

Ad Hoc Assignee Endpoints

The following endpoints can be used to manage ad hoc assignees of tasks:

Note: If these GET endpoints are called for a subprocess, they will return an empty array, because users and groups can't be assigned to subprocesses.

Get Ad Hoc Assignees for Task: GET /project/{prj_uid}/activity/{act_uid}/adhoc-assignee

Gets the list of ad hoc assignees of a task.

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-assignee?filter={string}&start={number}&limit={number}

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/assignee
start={number}	Optional. The initial position of the assignees in the list, where 0 is the first assignee, 1 is the second, etc.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee?start=1&limit=10
limit={number}	Optional. The maximum number of assignees returned.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee?start=11&limit=10
filter={string}	Optional. A search term to filter the list of assignees. It is a case-insensitive search inside the first name, last name and username of users and the names of groups. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee?filter=product%20manager

Result:

If successful, returns an HTTP status code of 200 (OK) and returns a JSON string containing an array of assignee objects, such as:

Element	Description
[	Start array.
{	Start first assignee object.
"ada_uid": "8f30daa78a440ab308727ca33381a545",	Unique ID of the user or group assigned to task on an ad hoc basis.
"ada_name": "James",	First name of the user or the name of the group.
"ada_lastname": "Johnson",	Assignee's last name. If a group, then "" (empty string).
"ada_username": "james",	Assignee's username. If a group, then "" (empty string).
"ada_type": "user"	Type of assignee, which can be "user" or "group".
}	End first assignee object.
...	Any additional assignee objects.
]	End array.

Example:

Response

Get Page of Ad Hoc Assignees of Task: GET /project/{prj_uid}/activity/{act_uid}/adhoc-assignee/paged

Gets a page of the users and groups assigned to a task on an ad hoc basis.

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-assignee/paged?filter={string}&start={number}&limit={number}

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/paged
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/paged
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/paged
start={number}	Optional. The initial position of the assignees in the list, where 0 is the first assignee, 1 is the second, etc.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee/paged?start=1&limit=10
limit={number}	Optional. The maximum number of assignees returned.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/paged?start=11&limit=10
filter={string}	Optional. A search term to filter the list of assignees. It is a case-insensitive search inside the first name, last name and username of users and the names of groups. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/paged?filter=product%20manager

Result:

If successful, returns an HTTP status code of 200 and returns a JSON string containing an array of assignee objects, such as:

Element	Description
{	Start page object.
"total": 3,	Total number of ad hoc assignees for the task.
"start": 0,	Index number of the first ad hoc assignee returned.
"limit": 0,	The maximum number of ad hoc assignees that will be returned.
"filter": "",	A search string that filters ad hoc assignees who are returned.
"data": [	An array of the available ad hoc assignees.
{	Start first assignee object.
"ada_uid": "8f30daa78a440ab308727ca33381a545",	Unique ID of the ad hoc assignee (user or group)
"ada_name": "James",	First name of the user or group, with its number of members in parentheses.
"ada_lastname": "Johnson",	User's last name. If a group, then "" (empty string).
"ada_username": "james",	Username of the user or the name of a group, with the number of members in parentheses.
"ada_type": "user"	Type of assignee, which can be "user" or "group".
}	End first assignee object.
...	Any additional assignee objects.
]	End array.
}	End page object.

Note: If this endpoint is called for a subprocess, it will return zero assignees.

Example:

Response

PHP Example:
Get the list of users for a task and then randomly chose one of them to reassign a case to:

Get Available Ad hoc Assignees of Task: GET /project/{prj_uid}/activity/{act_uid}/adhoc-available-assignee

Gets the list of the available users and groups who may be assigned on an ad hoc basis to a task.

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-available-assignee?filter={string}&start={number}&limit={number}

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/available-assignee
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee
start={number}	Optional. The initial position of the assignees in the list, where 0 is the first assignee, 1 is the second, etc.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee?start=1&limit=10
limit={number}	Optional. The maximum number of assignees returned.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee?start=11&limit=10
filter={string}	Optional. A search term to filter the list of assignees. It is a case-insensitive search inside the first name, last name and username of users and the names of groups. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee?filter=product%20manager

Result:

If successful, returns an HTTP status code of 200 and returns a JSON string containing an array of assignee objects, such as:

Element	Description
[	Start array.
{	Start first assignee object.
"ada_uid": "8f30daa78a440ab308727ca33381a545",	The unique ID of a user or group which is available to be assigned on an ad hoc basis.
"ada_name": "James",	First name of the user or group, with its number of users in parentheses.
"ada_lastname": "Johnson",	Last name of a user. If a group, then "" (empty string).
"ada_username": "james",	Username of the user or the name of a group, with the number of users in parentheses.
"aad_type": "user"	Type of assignee, which can be "user" or "group".
}	End first assignee object.
...	Any additional assignee objects.
]	End array.

Example:

Response

Get Page of Available Ad Hoc Assignees for Task: GET /project/{prj_uid}/activity/{act_uid}/adhoc-available-assignee/paged

Gets a page of the available users and groups that may be assigned to a task on an ad hoc basis.

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-available-assignee/paged?filter={string}&start={number}&limit={number}

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee/paged
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee/paged
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee/paged
start={number}	Optional. The initial position of the assignees in the list, where 0 is the first assignee, 1 is the second, etc.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee/ paged?start=1&limit=10
limit={number}	Optional. The maximum number of assignees returned.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/activity/679814870573f92e6509f59003354333/adhoc-available-assignee/ paged?start=11&limit=10
filter={string}	Optional. A search term to filter the list of assignees. It is a case-insensitive search inside the first name, last name and username of users and the names of groups. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-available-assignee/ paged?filter=product%20manager

Result:

If successful, returns an HTTP status code of 200 and returns a JSON string containing an array of assignee objects, such as:

Element	Description
{	Start page object.
"total": 3,	Total number of available ad hoc assignees of the task.
"start": 0,	Index number of the first ad hoc assignee returned.
"limit": 0,	The maximum number of ad hoc assignees that will be returned.
"filter": "",	A search string that filters ad hoc assignees who are returned.
"data": [	An array of the available ad hoc assignees.
{	Start first assignee object.
"ada_uid": "8f30daa78a440ab308727ca33381a545",	Unique ID of the ad hoc assignee (user or group)
"ada_name": "James",	First name of the user or group, with its number of members in parentheses.
"ada_lastname": "Johnson",	User's last name. If a group, then "" (empty string).
"ada_username": "james",	Username of the user or the name of a group, with its number of members in parentheses.
"ada_type": "user"	Type of assignee, which can be "user" or "group".
}	End first assignee object.
...	Any additional assignee objects.
]	End array.
}	End page object.

Note: If this endpoint is called for a subprocess, it will return all the users and groups in the workspace.

Example:

Response

PHP Example:
Get the list of users of a task and then choose one of them at random to assign to the task on an ad hoc basis:

Get ad hoc Assignee to Task: GET /project/{prj_uid}/activity/{act_uid}/adhoc-assignee/{ada_uid}

Gets a single ad hoc user or group assigned to a task.

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-assignee/{ada_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee/11609821854ca4355344560009542371
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee/11609821854ca4355344560009542371
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee/11609821854ca4355344560009542371
ass_uid	Unique ID of the assignee (user or group).	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/ adhoc-assignee/11609821854ca4355344560009542371

Result:

If successful, returns an HTTP status code of 200 and returns a JSON string containing an assignee object, such as:

Element	Description
{	Start assignee object.
"ada_uid": "8f30daa78a440ab308727ca33381a545",	Start array.
"ada_name": "James",	First name of the user or group.
"ada_lastname": "Johnson",	Assignee's last name. If a group, then "" (empty string).
"ada_username": "james",	Assignee's username. If a group, then "" (empty string).
"ada_type": "user"	Type of assignee, which can be "user" or "group".
}	End assignee object.

Example:

Response

Get All ad hoc Users for Task: GET /project/{prj_uid}/activity/{act_uid}/adhoc-assignee/all

Gets the list of all the users and groups assigned on an ad hoc basis to a task (including users that are within groups). Note that the endpoint will remove any duplicates, so users who are assigned multiple times will only be listed once.

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-assignee/all?filter=john&start=0&limit=50

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/all
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/all
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/all
start={number}	Optional. The initial position of the assignees in the list, where 0 is the first assignee, 1 is the second, etc.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/ all?start=1&limit=10
limit={number}	Optional. The maximum number of assignees returned.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/ all?start=11&limit=10
filter={string}	Optional. A search term to filter the list of assignees. It is a case-insensitive search inside the first name, last name and username of users and the names of groups. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3.	http://example.com/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/ all?filter=product%20manager

Result:

If successful, returns an HTTP status code of 200 and returns a JSON string containing an array of assignee objects, such as:

Element	Description
[	Start array.
{	Start first assignee object.
"ada_uid": "8f30daa78a440ab308727ca33381a545",	Unique ID of a user or group assigned to task on an ad hoc basis.
"ada_name": "James",	First name of the user or group.
"ada_lastname": "Johnson",	Assignee's last name. If a group, then "" (empty string).
"ada_username": "james",	Assignee's username. If a group, then "" (empty string).
"ada_type": "user"	Type of assignee, which can be "user" or "group".
}	End first assignee object.
...	Any additional assignee objects.
]	End array.

Example:

Response

Ad hoc Assign to Task: POST /project/{prj_uid}/activity/{act_uid}/adhoc-assignee

Assigns a user or group to a task on an ad hoc basis.

Permission:

Users must have the PM_FACTORY permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-assignee

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/activity/679814870573f92e6509f59003354333/adhoc-assignee
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/activity/679814870573f92e6509f59003354333/adhoc-assignee
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/activity/679814870573f92e6509f59003354333/adhoc-assignee

POST Parameters:

Element	Description
{
"ada_uid": "8f30daa78a440ab308727ca33381a545",	The unique ID of the user or group to assign.
"ada_type": "user",	Type of assignee, which can be "user" or "group".
"ada_name": "James",	Optional. First name of the user or the name of the group.
"ada_lastname": "Johnson",	Optional. Assignee's last name. If a group, then "" (empty string).
"ada_username": "james"	Optional. Username of the user or the name of the group.
}

Result:

If successful, returns an HTTP status code of 201 (Created) and there is no response; otherwise, the status code is 400 and an error object like the following is returned:

{
  "error": {
    "code":    400,
    "message": "Bad Request: This ID: 679814870573f92e6509f59003354333 is already assigned to task: 5296539325780572339ce51048356524"
  }
}

Example:

Request

Response

PHP Example:

Remove ad hoc Assignee from Task: DELETE /project/{prj_uid}/activity/{act_uid}/adhoc-assignee/{ada_uid}

Remove an ad hoc assignee (user or group) from a task.

Permission:

Users must have the PM_FACTORY permission assigned to their role to perform this action.

Structure:

DELETE /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}/adhoc-assignee/{ada_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is workflow by default.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/11609821854ca4355344560009542371
prj_uid	Unique ID of the project (process), which can be found by looking at the @@PROCESS variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/11609821854ca4355344560009542371
act_uid	Unique ID of the task, which can be found by looking at the @@TASK variable in the Debugger while running a case.	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/11609821854ca4355344560009542371
ass_uid	Unique ID of the ad hoc assignee (user or group).	/api/1.0/workflow/project/276544696573f9457cd0983094962709/ activity/679814870573f92e6509f59003354333/adhoc-assignee/11609821854ca4355344560009542371

Result:

If successful, returns an HTTP status code of 200 (OK) and there is no response. If the user isn't assigned to the task, it returns:

Example:

Response

PHP Example: