3.2 - 3.8 - REST API Designer - Process Variables

Process Variables Endpoints

The new Dynaform designer included inside ProcessMaker 3 needs variables to be created in a separate interface before being used and added into forms. This endpoint details the use of these variables inside the new interface.

Process variables:

Get Variables List: GET project/{prj_uid}/process-variables

Gets the list of the process variables in a project.

GET /api/1.0/{workspace}/project/{prj_uid}/process-variables

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID

Result:

Type	Description
array	Returns an array containing data about all variables in the process.

Example:

Response

Get Process Variable: GET project/{prj_uid}/process-variable/{var_uid}

Gets a process variable.

GET /api/1.0/{workspace}/project/{prj_uid}/process-variable/{var_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID
var_uid	String	Variable UID

Result:

Type	Description
object	Returns an object with data of the requested variable

Example:

Response

Create Process Variable: POST project/{prj_uid}/process-variable

Creates a process variable.

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}/process-variable

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID

Required Fields:

Name	Type	Description
var_name	String	Variable name
var_field_type	String	Variable type
var_label	String	Variable label

Optional Fields:

Name	Type	Description
var_field_size	Integer	Variable size
var_dbconnection	String	Database connection
var_sql	String	SQL query
var_null	String	Whether the variable will accept null values
var_default	String	Default values
var_accepted_values	String	Accepted values

Result:

Type	Description
object	Returns an object containing the information about the new variable.

Example:

Request

Response

Update Process Variable: PUT project/{prj_uid}/process-variable/{var_uid}

Updates a process variable.

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}/process-variable/{var_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID
var_uid	String	Variable UID

Optional Fields:

Name	Type	Description
var_name	String	Variable name
var_field_type	String	Variable type
var_label	String	Variable label
var_field_size	Integer	Variable size
var_dbconnection	String	Database connection
var_sql	String	SQL query
var_null	String	Whether the variable will accept null values
var_default	String	Default values
var_accepted_values	String	Accepted values

Result:

Type	Description
Empty	No return

Example:

Request

Response

Delete Process Variable: DELETE project/{prj_uid}/process-variable/{var_uid}

Deletes a process variable.

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}/process-variable/{var_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID
var_uid	String	Variable UID

Result:

Type	Description
empty	No return

Example:

Response

Execute Query: POST project/{prj_uid}/process-variable/{var_name}/execute-query

Executes an SQL query of a dependent field, such as a dropdown box, checkgroup or radiogroup, that uses an SQL query with one or more dynamic variables to populate its list of options.

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}/process-variable/{var_name}/execute-query

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is "workflow" by default.	http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/dropdownVar001/execute-query
prj_uid	Unique ID of the project. This can be found by running a case with the Debugger turned on and looking at the @@PROCESS system variable.	http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/dropdownVar001/execute-query
var_name	Name of the variable assigned to the dependent field that uses an SQL query to populate its list of options. It is not possible to use this endpoint with controls that do not have an associated variable. Remember that variable names are case sensitive and they can only contain letters, numbers and _ (underscores).	http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/dropdownVar001/execute-query

POST Parameters:

Name	Description
{
'dyn_uid': '406442383573140df944390011262710',	Required. The unique ID of the Dynaform that holds the dependent control associated with the specified variable.
'field_uid': 'dropdownVar001',	Required. The name of the variable that is associated with the dependent field.
'COUNTRY1': 'U%',	Required. The variable used in the SQL query of the dependent field. The name of this parameter will change according to the variable name. In this example, the variable used in the SQL query shown in the example below is named @@COUNTRY1, so the parameter name is 'COUNTRY1'. The string defined as its value will be used in the SQL query. The value is case insensitive. Note that at least one of the variables used in the dependent field must be present in the request body.
'app_uid': '37439823957314102c66d78026868117',	Optional. The unique ID of the case whose variable will be queried for the options in the suggest box.
'del_index': 0,	Optional. Delegation index of the case specified in the app_uid parameter, which counts tasks executed in the case starting from 1.
}

Result:

Example:

Query Options in Control: POST project/{prj_uid}/process-variable/{var_name}/execute-query-suggest

Queries the options in a suggest box, dropdown box, checkgroup or radiogroup, which uses an SQL query to populate its list of options (or uses a datasource "array variable" in version 3.0.1.8 or later).

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}/process-variable/{var_name}/execute-query-suggest

URL Parameters:

Name	Description	Example
workspace	Workspace name, which is "workflow" by default.	http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/country/execute-query-suggest
prj_uid	Unique ID of the project. This can be found by running a case with the Debugger turned on and looking at the @@PROCESS system variable.	http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/country/execute-query-suggest
var_name	Name of the variable with a suggest box, dropdown box, radiogroup or checkgroup, which uses an SQL query to populate its list of options (or uses a datasource which is "array variable" in version 3.0.1.8 or later). It is not possible to use this endpoint with controls that do not have an associated variable. Remember that variable names are case sensitive and they can only contain letters, numbers and _ (underscores).	http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/country/execute-query-suggest

POST Parameters:

Name	Description
{
'dyn_uid': '406442383573140df944390011262710',	Required. The unique ID of the Dynaform that holds the control associated with the specified variable.
"field_uid": "suggestVar001",	Required. The name of the variable that is associated with the suggest box, dropdown box, radiogroup or checkgroup.
"filter": "Adam",	Optional. A string that searches the displayed text of the options. The search is case insensitive and can find results anywhere within the text. If not included, then all options in the suggest box are returned.
"start": 10,	Optional. The number of the option where to start. The first option is 0, the second option is 1, etc. If not included, then starts at 0 by default.
"limit": 20	Optional. The maximum number of options to return, which is 10 by default.
"order_by": "ASC",	Optional. The sorting order that can be "ASC" or "DESC". If not included, the response will be retrieved in an ascending order.
"app_uid": "37439823957314102c66d78026868117",	Optional. The unique ID of a case whose variable will be queried for the options in the suggest box. This is only used if the datasource for the control associated with the specified variable is set to "array variable". Remember that this array variable must store its list of options in the following format: array( array('value', 'text-label'), array('value', 'text-label'), ... )
"del_index": 0,	Optional. Delegation index of the case specified in the app_uid parameter, which counts tasks executed in the case starting from 1.
"variable-name": "variable-value"	Optional. If the SQL statement for the control contains variable(s), then the name and value of the variable(s) should be included, so they will be inserted into the SQL statement when it is executed. For example, if the SQL statement for the control is: SELECT CLIENT_ID, CLIENT_NAME FROM CLIENTS WHERE SALES_AREA=@@selectArea OR COUNTRY=@@selectCountry Then, the POST parameters would be something like this: "selectArea": "MIDWEST", "selectCountry": "UK"
}

Result:

Example:

PHP Example: