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:

Name Description Type Value
prj_uid Project UID String "9541049475298f190420f51086854718" (string of 32 characters)
var_uid Variable UID String Alphanumeric string of 32 characters
var_name Variable name String Alphanumeric string up to 60 characters. Note.- If modifying the var_name field is not necessary, then it id not necessary to send it in the json request.
var_field_type Variable type String Alphanumeric string up to 32 characters. Accepted values: string, integer, boolean, float, datetime, date_of_birth and date
var_field_size Variable size Integer Integer up to 11 digits
var_label Variable label String Alphanumeric string up to 32 characters
var_dbconnection Database connection String Alphanumeric string up to 32 characters
var_sql SQL query String Alphanumeric string up to 512 characters
var_null Whether the variable will accept null values Tinyint 0.- No, 1.- Yes
var_default Default values String Alphanumeric string up to 32 characters
var_accepted_values Accepted values String Alphanumeric string up to 32 characters

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

200 (OK)
Content-Type: application/json
[
   {
      "var_uid": "4415812967531539f30a166211600459",
      "prj_uid": "812967531539f30a1662116004594415",
      "var_name": "text_name",
      "var_field_type": "string",
      "var_field_size": "15",
      "var_label": "Nombre:",
      "var_dbconnection": "",
      "var_sql": "",
      "var_null": "0",
      "var_default": "",
      "var_accepted_values": ""
   },
   {
      "var_uidv": "57820440553b1a6e4304938032532769",
      "prj_uid": "812967531539f30a1662116004594415",
      "var_name": "drp_country",
      "var_field_type": "string",//similar to data type
      "var_field_size": "20",
      "var_label": "Pais:",
      "var_dbconnection": "@DBCONNECTION",
      "var_sql": "select * from iso_country",
      "var_null": "0",
      "var_default": "",
      "var_accepted_values": ""
   }
]

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

 200 (OK)
 Content-Type: application/json
 {
     "var_uid": "4415812967531539f30a166211600459",
     "prj_uid": "812967531539f30a1662116004594415",
     "var_name": "text_name",
     "var_field_type": "string",
     "var_field_size": "15",
     "var_label": "Nombre:",
     "var_dbconnection": "",
     "var_sql": "",
     "var_null": "0",
     "var_default": "",
     "var_accepted_values": ""
 }

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

 Content-Type: application/json
 {
    "var_name": "drp_ciudad",
    "var_field_type": "string",
    "var_field_size": 120,
    "var_label": "Ciudad:",
    "var_dbconnection": "@DBCONNECTION",
    "var_sql": "select * from iso_city",
    "var_null": 0,
    "var_default": "",
    "var_accepted_values": ""
 }

Response

201 (Created)
{
   "var_uid":            "4415812967531539f30a166211600459",
   "var_name":           "drp_city",
   "var_field_type":     "string",
   "var_field_size":     120,
   "var_label":          "City:",
   "var_dbconnection":   "@DBCONNECTION",
   "var_sql":            "select * from iso_city",
   "var_null":            0,
   "var_default":         "",
   "var_accepted_values": ""
}

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

Content-Type: application/json
{
   "var_uid":"4415812967531539f30a166211600459"
   "var_name": "drp_ciudad",
   "var_field_type": "string",
   "var_field_size": 80,
   "var_label": "Ciudad:",
   "var_dbconnection": "@DBCONNECTION",
   "var_sql": "select * from iso_city",
   "var_null": 0,
   "var_default": "",
   "var_accepted_values": ""
}

Response

200 (OK)

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

200 (OK)

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:

If successful, returns an HTTP status code of 200 (OK) and an array of objects in the following format:

[ { "value": "value1", "text" : "text1" }, { "value": "value2", "text" : "text2" } ... ]

Where "value" is the ID of each option in the control and "text" is its displayed label.

If the {var_name} doesn't exist or if the control doesn't have a SQL query defined, then the HTTP status code will be set to 400 and the response will be NULL.

Example:

A dropdown box is associated with a variable named "selectCountry" and uses the following SQL query to populate its contents:

SELECT IC_UID, IC_NAME FROM ISO_COUNTRY WHERE IC_UID LIKE @@COUNTRY1 AND IC_UID <> @@COUNTRY2

Where @@COUNTRY1 and @@COUNTRY2 are variables associated to two different textboxes.

Request

The URL is http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/selectCountry/execute-query and the POST variables are:

{
        "dyn_uid": "61907528958ab229099c681078186062",
        "field_id": "dropdownVar001",
        "COUNTRY1": "U%",
        "COUNTRY2" : "US",
    "app_uid": "4029846195956990555d732058297161",
        "del_index": 1
}

Response

All the countries that start with the letter U will be displayed, except the United States.

200 (OK)
[
    {
        "value": "UA",
        "text": "Ukraine"
    },
    {
        "value": "UG",
        "text": "Uganda"
    },
    {
        "value": "UM",
        "text": "United States Minor Outlying Islands"
    },
    {
        "value": "UY",
        "text": "Uruguay"
    },
    {
        "value": "UZ",
        "text": "Uzbekistan"
    }
]

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:

If successful, returns an HTTP status code of 200 (OK) and an array of objects in the following format: [ { "value": "value1", "text" : "text1" }, { "value": "value2", "text" : "text2" } ... ]

Where "value" is the ID of each option in the control and "text" is its displayed label.

If the {var_name} doesn't exist or if the control doesn't have a defined sql query, then the HTTP status code will be set to 400 and the response will be NULL.

Example:

A suggest box is associated with a variable named "selectCountry" and it uses the following sql query to populate its contents:

SELECT IC_UID, IC_NAME FROM ISO_COUNTRY

Request

The URL is http://www.example.com/api/1.0/workflow/project/84233230756cbb13a780d37064601378/process-variable/selectCountry/execute-query-suggest and the POST variables are:

{
  "filter": "Nic",
  "limit": "10",
  "app_uid": null,
  "field_id": "selectCountry",
  "del_index": 0,
  "dyn_uid": "86759108558d01d35637f23017076271"
}

Response

200 (OK)
[
  {
    "value": "DM",
    "text":  "Dominica"
  },
  {
    "value": "DO",
    "text":  "Dominican Republic"
  },
  {
    "value": "NI",
    "text":  "Nicaragua"
  }
]

PHP Example:

Using the same "selectCountry" suggest control from the previous example, the following PHP code constructs the HTML code for a list of options in a <select> box.

$oToken = pmRestLogin('YOXQRMHAMMMKSOENEDENDFQDTJTGTUUS', '32667560556abe5142235e0090500305', 'mary', 'p@s5w0rD');
if (!isset($oToken) or !isset($oToken->access_token)) {
   die("Error: Can't access ProcessMaker REST");
}

$varName = 'selectCountry';
$dynaformId = '406442383573140df944390011262710';
$projectId = '798659366573140bc117490080056441';
$url = "/api/1.0/workflow/project/$projectId/process-variable/$varName/execute-query-suggest";
$aParams = array(
   "filter"   => "",
   "limit"    => '50',
   "dyn_uid"  => $dynaformId
);

$oRet = pmRestRequest("POST", $url, $aParams, $oToken->access_token);
if ($oRet->status == 200) {
  print '<p>Select Country:<br><select id="selectCountry">';
  foreach ($oRet->response as $oOption) {
    print "<option value=\"{$oOption->value}\">{$oOption->text}</option>\n";
  }
  print '</select>';
}