3.2 - 3.8 - REST API Designer - Activities

Activities Endpoints

The following REST endpoints are available to manage activities. Note that "activities" are either tasks or subprocesses.

Note: There is no endpoint to create a new activity.

Get Activity: GET project/{prj_uid}/activity/{act_uid}

Gets the properties of a specified activity (task or subprocess).

GET /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480
prj_uid	Unique ID (UID) of the project.	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480
act_uid	Unique ID of the activity (step or subprocess)	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480

Result:

If executed with success, the HTTP status code is set to 200 and the following object is returned with information about the activity:

Example:

If an error occurred, the status code is set to 400 or higher and an error object is returned, such as:

PHP Example:

Update Activity: PUT project/{prj_uid}/activity/{act_uid}

Updates the properties of a specified activity (task or subprocess).

Permission:

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

Structure:

PUT /api/1.0/{workspace}/project/{prj_uid}/activity/{act_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480
prj_uid	Unique ID (UID) of the project.	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480
act_uid	Unique ID of the activity (step or subprocess)	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480

PUT Parameters:

Element	Description
{	Start object.
"properties": {	Start properties object.
"tas_title": "Define Client",	The title of the task or subprocess.
"tas_description": "Enter info about client",	The description of the task or subprocess. The task/subprocess description is displayed when the user views the Case Summary.
"tas_priority_variable": "@@priority",	A variable that determines the priority of the task. If the variable contains 1, then the case is the highest priority. If it contains 3, then the case is normal priority, which is the default. If 5, then the case is lowest priority. If set to "" (empty string), then the case will have normal priority. Note that this property can only contain variables and not literal values, so it will not work correctly if set to "4".
"tas_derivation_screen_tpl": "routingScreen.html",	The filename of the template file displayed after routing the task. If none, then set to "" (empty screen).
"tas_assign_type": "BALANCED",	The type of assignment rule, which can be: "BALANCED" (Cyclical Assignment), "MANUAL", "EVALUATE" (Value Based Assignment), "REPORT_TO", "SELF_SERVICE", "SELF_SERVICE_EVALUATE" (Self Service Value Based Assignment), "MULTIPLE_INSTANCE" (Parallel Assignment in Enterprise E.), "MULTIPLE_INSTANCE_VALUE_BASED" (Parallel Value Based Assignment in Enterprise E.).
"tas_assign_variable": "@@nextAssigned"	The variable that holds the unique ID of the user to be assigned to a Value Based Assignment task. The default is "@@SYS_NEXT_USER_TO_BE_ASSIGNED". Remember that this user must also be in the list of users assigned to the task.
"tas_group_variable": "@@canClaimGroup",	The variable that contains the unique IDs of the groups and users which can claim a Self Service Value Based Assignment task. The default is "@@SYS_GROUP_TO_BE_ASSIGNED". Remember that these users/groups must also be in the list of users/groups assigned to the task.
"tas_selfservice_time": "5",	The amount of time of the timeout in a self service task. If none, then set to "" (empty string).
"tas_selfservice_timeout": 1,	Set to 1 for a self service timeout, meaning that a trigger will be executed if no one claims a case with a self-service task within the configured amount of time. If there is no timeout, then set to 0.
"tas_selfservice_time_unit": "DAYS",	The time units for calculating the timeout of a self service task, which can be "" (none), "MINUTES", "HOURS" or "DAYS".
"tas_selfservice_trigger_uid": "2840568655706c023962945046408021",	The unique ID of the trigger executed after the timeout of a self service task. If no trigger, then set to "" (empty string).
"tas_selfservice_execution": "ONCE",	If set to "ONCE", then the trigger of the self service timeout is executed once. If set to "EVERY_TIME", then the trigger is executed every time the cron.php script is run after the timeout.
"tas_transfer_fly": "FALSE",	If set to "TRUE", then users are allowed to change the task duration during runtime; whereas if set to "FALSE", the task duration is a fixed amount of predetermined time.
"tas_offline": "TRUE",	If set to "TRUE" the task will be enable for offline use in ProcessMaker Mobile.
"tas_auto_root": "TRUE",	If set to "TRUE" the task will be enable to be routed automatically as soon as the ProcessMaker Mobile app is back online.
"tas_duration": 14,	The number of time units before the task becomes overdue. The default is 1.
"tas_timeunit": "DAYS",	The time unit of the task duration, which can be: "DAYS", "HOURS" or "MINUTES".
"tas_type_day": "2",	If set to "1", then the task duration is counted by "Work Days", which is Monday through Friday, which is the default. If set to "2", then the time is counted by "Calendar Days" and the calendar being used is set in tas_calendar.
"tas_calendar": "1720244195706d204dbfde6080740114",	The unique ID of the calendar used to calculate the duration of the task. If set to "00000000000000000000000000000001", then the "Default Calendar" is used. If set to "" (empty string), then no calendar is used, so task time is calculated 24 hours of every day.
"tas_def_title": "Client @#name",	The title of the case, which can contain variables and is set when the case arrives at the task. It is displayed at the top of the screen next to the case number when a case is opened. If set to "" (empty string), then the title of the case displays the case number preceded by #.
"tas_def_description": "Info about client '@#name'",	The description of the case, which can contain variables and is set when the case arrives at the task. The description is displayed when the user views the Case Summary. If set to "" (empty string), then there is no case description.
"tas_send_last_email": "TRUE",	If set to "TRUE", then an email notification is sent to the next assigned user(s), meaning the users assigned to this task will receive a custom email message when the case arrives at this task. If set to "FALSE", then no email notification is sent for this task.
"tas_def_subject_message": "Your case @#caseNo",	The subject line of the email notification to be sent to the assigned user(s) of the task. It may contain variables.
"tas_def_message_type": "text",	If set to "text", then use plain text for the email notification sent to the assigned user(s). This text is entered directly in the "Activity Properties" dialog box and is available in the tas_def_message property. If set to "html", then the body of the email notification is defined by a template file set in the tas_def_message_template property.
"tas_def_message": "New case @#caseNo.\nRegards, @#mngr",	The text (body) of the email notification to sent to the assigned user(s) if the tas_def_message_type is set to "text". The text can contain variables.
"tas_def_message_template": "alert_message.html"	The filename of the template file that defines the body the email notification sent to the assigned user(s) of the task if the tas_def_message_typeproperty is set to "html".
"tas_email_server_uid": ""	The unique ID of the email server selected to send the task notifications.
"tas_receive_server_uid": "6270141605851bf3cb71eb2041564369",	The unique ID of the email server configured to send task notifications.
"tas_receive_last_email": "TRUE",	If set to "TRUE", the "Notify the assigned user to this task" option was checked and a notification will be sent to the current assigned user(s), meaning the user(s) assigned to this task will receive a custom email message when the case arrives to this task. If set to "FALSE", no email notification is sent.
"tas_receive_email_from_format": 0,	If the "Assigned User" option was selected in the notification configuration, the value will be 0. If the "Email Server Settings" option was selected, the value will be 1.
"tas_receive_message_type": "text",	The content type of the notification, that can be "text" or "template".
"tas_receive_message_template": "alert_message.html",	The template set in the notification configuration.
"tas_receive_subject_message": "New Case for @#USR_USERNAME",	Subject of the message.
"tas_receive_message": "New case assigned!",	Content of the notification.
}	End properties object.
}

All properties are optional, but certain properties have dependent properties, which must be set. For example, if tas_transfer_fly is set to "FALSE", then it is not necessary to set tas_duration, but if set to "TRUE", then tas_duration must be set. The easiest way to avoid problems is to first call GET project/{prj_uid}/activity/{act_uid} to get the list of properties for an activity and then set the properties that need to be changed.

Note: It is recommended to not include the tas_type property, because it will cause an error if set to "SUBPROCESS", and changing it from "NORMAL" to "ADHOC or vice versa will set inaccurate information.

Note: If the activity is a subprocess, only tas_title and tas_description are used. Currently there are no endpoints for getting and updating the other properties of subprocesses.

Result:

If the activity was successfully updated, then the HTTP status code is set to 200 and there is no response. If an error occurred, the status code is set to 400 or higher and an error object is returned, such as:

PHP Example:

Delete Activity: DELETE project/{prj_uid}/activity/{act_uid}

Deletes a specified activity (task or subprocess).

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}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480
prj_uid	Unique ID (UID) of the project.	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480
act_uid	Unique ID of the activity (step or subprocess)	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/activity/27487747556cbb168597107027360480

Result:

If the activity was successfully deleted, then the HTTP status code is set to 200 and there is no response. If an error occurred, the status code is set to 400 or higher and an error object is returned, such as:

Warning: This endpoint deletes the activity from the TASK or SUB_PROCESS table in the database, but it does NOT remove it from the BPMN_ACTIVITY table if the activity is from a BPMN process. The activity will still appear in the BPMN process map after being deleted.

PHP Example:

Get Starting Tasks: GET project/{prj_uid}/starting-tasks

Returns a list of the starting task(s) to which the logged-in user is assigned in a specified project (or process).

GET /api/1.0/{workspace}/project/{prj_uid}/starting-tasks

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/starting-tasks
prj_uid	Unique ID of the project (or process), which can be found by looking at the @@PROCESS system variable in the Debugger.	/api/1.0/workflow/project/84233230756cbb13a780d37064601378/starting-tasks

Result:

If successful, then the HTTP status code is set to 200 and an array of task objects is returned. If an error occurred, the status code is set to 400 or higher and an error object is returned, such as:

Note: This REST endpoint only returns tasks connected to a normal Start Event. It does not return sub-processes connected to Start Events or tasks connected to Start Timer Events.

Example:

Response:

PHP Example:

Search for the unique ID of the "Purchase Request" task: