Substitution REST APIs

This section lists out details of all the REST APIs used to substitute an user. For more information about user substitution, see Working with BPMN User Substitution.

Add substitute

Request Type

POST

Request URL

https://<Host Name>:<Port>/bpmn/runtime/substitutes

Sample URL: https://localhost:9443/bpmn/runtime/substitutes

Details & Parameters

This request will add new substitution record. If the existing substitution is disabled, it will be enabled after this update request.

Parameter	Optional/Required	Description
assignee	Optional	The username of the user who is going to be unavailable. If this value is not specified, the user who is logged in at the time of request will be considered.
substitute	Required	The username of the substitute user for the assignee.
startTime	Optional	The time stamp for when the substitution should start, in ISO format. If the value is not specified, the current time stamp is considered.
endTime	Optional	The time stamp for when the substitution should end, in ISO format. If the value is not specified, the substitution is considered as valid forever.
taskList	Optional	Task IDs for bulk task reassignment (existing tasks that should be reassigned to the substitute user). If values are provided for this parameter, bulk task reassignment will be done only for the tasks specified here.

Request Body

{
"assignee":"assigneeUserName",
"substitute" : "SubstituteUsername",
"startTime" : "20160101T12:00:00Z",
"endTime" : "20170101T12:00:00Z",
“taskList” : [‘id1’, ‘id2’, ‘id3’]
}

Response

Success: 201 created with location header.
Error: 405 if substitution feature is not enabled, 400 if there are incorrect parameters.

Update substitution record

Request Type

PUT

Request URL

https://<Host Name>:<Port>/bpmn/runtime/substitutes/{user}

Sample URL: https://localhost:9443/bpmn/runtime/substitutes/{user}

Details & Parameters

This request will update an existing substitution record of the user identified by the {user}.

If any of the following parameters are not provided, the existing value will be retained.

Parameter	Optional/Required	Description
substitute	Optional	The username of the substitute user for the assignee.
startTime	Optional	The time stamp for when the substitution should start, in ISO format.
endTime	Optional	The time stamp for when the substitution should end, in ISO format.
taskList	Optional	If values are provided for this parameter, bulk task reassignment will be done only for the tasks specified here.

Request Body

{
"substitute" : "SubstituteUsername",
"startTime" : "20160101T12:00:00Z",
"endTime" : "20170101T12:00:00Z",
“taskList” : [‘id1’, ‘id2’, ‘id3’]
}

Response

Success: 200 OK.
Error: 405 if substitution feature is not enabled, 400 if there are incorrect parameters.

Change substitute

Request Type

PUT

Request URL

https://<Host Name>:<Port>/bpmn/runtime/substitutes/{user}/substitute

Sample URL: https://localhost:9443/bpmn/runtime/substitutes/{user}/substitute

Details & Parameters

This request will change the existing substitute record of the user identified by {user}.

Parameter	Optional/Required	Description
substitute	Required	Specify the new substitute.

Request Body

{
"substitute" : "username"
}

Response

Success: 200 OK.
Error: 405 if substitution feature is not enabled, 400 if there are incorrect parameters.

Get substitute information

Request Type	GET
Request URL	https://<Host Name>:<Port>/bpmn/runtime/substitutes/{user} Sample URL: https://localhost:9443/bpmn/runtime/substitutes/{user}
Details & Parameters	This request will return the substitute record of the user identified by {user}. No request parameters.
Response Body	{ “assignee” : “user” "substitute" : "SubstituteUsername", "startTime" : "20160101T12:00:00Z", "endTime" : "20170101T12:00:00Z", “taskList” : [‘id1’, ‘id2’, ‘id3’] }
Response	Success: 200 OK. Error: 405 if substitution feature is not enabled, 400 if there is no such substitution record available.

Query substitutes

Request Type

GET

Request URL

https://<Host Name>:<Port>/bpmn/runtime/substitutes

Sample URL: https://localhost:9443/bpmn/runtime/substitutes?substitute=user&enabled=true

Details & Parameters

This request will return the query result of the substitution records based on substitute, assignee and enabled or disabled parameters and pagination parameters.

The following parameters are allowed.

Parameter	Description
Query Parameters
substitute	Records with this user as a substitute.
assignee	The record where this user is the assignee.
enabled	true/false
Pagination Parameters
start	Starting of the record count. The default value is 0
size	The size of the result set. The default value is 10.
order	Set as "asc" for ascending or "desc" for descending. The default value is "asc".
sort	Specify which field the sorting should be based on. The default sort field is "startTime".

Response Body

{  
   "size":2,
   "order":"asc",
   "total":3,
   "sort":"startTime",
   "start":0,
   "substituteInfoList":[  
      {  
         "substitute":"vinod",
         "startTime":1468261800000,
         "endTime":1468348200000,
         "enabled":true,
         "assignee":"admin"
      },
      {  
         "substitute":"vinod",
         "startTime":1468261800000,
         "endTime":1469730600000,
         "enabled":true,
         "assignee":"waruna"
      }
   ]
}

Response

Success: 200 OK.
Error: 405 if substitution feature is not enabled.

Disable a substitution

Request Type	POST
Request URL	https://<Host Name>:<Port>/bpmn/runtime/substitutes/{user}/disable Sample URL: https://localhost:9443//bpmn/runtime/substitutes/{user}/disable
Details & Parameters	This request will disable/enable the substitution record of the user identified by {user}.
Request Body	{ “action” : true/false }
Response	Success: 200 OK. Error: 405 if substitution feature is not enabled, 400 if there are incorrect parameters.

Check if substitution feature is enabled

Request Type	GET
Request URL	https://<Host Name>:<Port>/bpmn/runtime/substitutes/configs/enabled Sample URL: https://localhost:9443/bpmn/runtime/substitutes/configs/enabled
Details & Parameters	This will return true if the substitution feature is enabled, else it will return as false. No request parameters.
Response Body	{ “enabled” : true/false }
Response	Success: 200 OK. Error: 405 if substitution feature is not enabled, 400 if there are incorrect parameters.