3.1 - 3.8 - REST API Administration - PM Tables

PM Tables

The following REST endpoints are used to manage PM tables in ProcessMaker:

Permissions:

These endpoints need the following permission:

PM Tables:

Available methods:

PM Tables List: GET /pmtable

Get a list of the PM tables in the workspace. It does not include any Report Tables.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

GET /api/1.0/{workspace}/pmtable

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable

Result:

If successful, the HTTP status is set to 200 (OK) and an array of PM Table objects is returned:

For example:

PHP Example:

Print out the PM Tables and the fields in each table.

Get PM Table Structure: GET /pmtable/{pmt_uid}

Get the structure from a specified PM Table, including a list of its fields and their properties.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

GET /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997
pmt_uid	Unique ID of the PM Table	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997

Result:

If successful, the HTTP status is set to 200 (OK) and a PM Table object is returned, such as:

PHP Example:

Print out the number of records in a PM Table and list the fields in the PM Table.

Get PM Table Data: GET /pmtable/{pmt_uid}/data

Get the data (records) from a PM table.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

GET /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data
pmt_uid	Unique ID of the PM Table.	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data

Optional Parameters:

Name	Description	Example
filter	Value that will be search in all the PMTable's fields.	/api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data?filter=555655656
q={where:spec}	string	This is a generic way to search via the filterType "where" (only this one is supported) and where spec is the specification of the filter, for example for a where filter, this is a logical condition that the results must match. For example, GET /api/1.0/workflow/pmtable/33532851355ef56860e8297082884997/data?q={"where":{"name":"Felix","lastname":"Mondaca"}} will return the row of the PM Table that has the values: "Felix", "Mondaca" in the fields "name" and "lastname", respectively .

Result:

If successful, the HTTP status is set to 200 (OK) and an object is returned with the rows of data in the PM Table and the number of rows.

For example:

Note: The field names are automatically converted to lowercase.

Note: Integers, floating-point numbers (real numbers) and boolean values are converted to strings. In the above example, the id is an integer and the has_contract is a boolean in MySQL. Also, the __index__ field is automatically created by MySQL to index the PM Table.

PHP Example:

Print out the records in a PM Table in an HTML table. First get the structure of the PM Table with GET /api/1.0/workflow/pmtable/{pmt_uid} in order to print out the label (description) of each field in the headers of the HTML table. Then, get the records with GET /api/1.0/workflow/pmtable/{pmt_uid}/data and print out each record as a record in the HTML table.

Querying Filter (Where)

A filter of type WHERE can be applied to this endpoint to narrow the endpoint response.

GET /api/1.0/{workspace}/pmtable/{pmt_uid}/data?q={"where":{"property":"value"}}

If wanting to search for multiple properties, separate them with a "," (comma).

GET /api/1.0/{workspace}/pmtable/{pmt_uid}/data?q={"where":{"property":"value","property2":"value2",...}}

Filter Parameters:

Name	Type	Description	Example
property	String	The name of a property (field) in the PM Table. The field name is case insensitive.	/api/1.0/workflow312Of/pmtable/16470336958222eae1e9918043923507/data?q={"where":{"name":"Travis Grady"}}
value	String	Value to be searched. The value is case insensitive.	/api/1.0/workflow312Of/pmtable/16470336958222eae1e9918043923507/data?q={"where":{"name":"Travis Grady"}}

Value Parameter

Inside the value parameter the following comparison operators can be used:

Operator	Description	Example
Not Equal	The "NOT EQUAL" operator returns all the records that are NOT the equal to the comparison value.	/api/1.0/workflow312Of/pmtable/16470336958222eae1e9918043923507/data?q={"where":{"name":{"neq":"Travis Grady"}}}
Like	The "LIKE" comparison operator enables to match the value using SQL regular expressions. The "%" sign is used to define missing letters, both before and after the value.	/api/1.0/workflow312Of/pmtable/16470336958222eae1e9918043923507/data?q={"where":{"name":{"like":"H%"}}}
nLike	The "NOT LIKE" comparison operator enables to return all the results where the records values are NOT like the comparison value.	/api/1.0/workflow312Of/pmtable/16470336958222eae1e9918043923507/data?q={"where":{"Phone":{"nlike":"%667%"}}}

Note: The URL may not contain spaces. If needing to include a space, then it needs to be URL encoded as %20. rawurlencode() in PHP and encode​URIComponent() in JavaScript can be used to replace spaces in the URL.

Example:
If successful, then the HTTP status code is set to 200 and there is a status object.

Create PM Table: POST /pmtable

Create a new PM Table.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

POST /api/1.0/{workspace}/pmtable

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable

POST Fields:

Name	Description
{	Start object.
"pmt_tab_name",	The name of the PM Table, which only consists of ASCII letters, numbers and underscores ("_"). It will automatically be converted to UPPERCASE. It is strongly recommended that it begin with "PMT_".
"pmt_tab_dsc",	Optional. Description of the PM Table.
"fields"	An array of field objects.
[	Start the array.
{	Start object defining field.
"fld_name",	The field name, which should only contain ASCII letters, numbers and underscores ("_"). It will automatically be converted to UPPERCASE. It is recommended that it be in UPPERCASE.
"fld_label,	The field's label.
"fld_type",	The field type, which can be: BIGINT: An integer of 8 bytes between -9223372036854775808 and 9223372036854775807. BOOLEAN: A binary value of either 1 (true) or 0 (false), but this stored as an INTEGER in the database. CHAR: A string of a characters between 0 and 255 in length. The number of characters stored in the database is fixed. If the field size is 100, then 100 characters are stored in the database, even if the value in the field has fewer characters. DATE: A date in the 'YYYY-MM-DD' format. The supported range is '1000-01-01' to '9999-12-31'. DATETIME: A datetime in the 'YYYY-MM-DD HH:MM:SS' format. The supported range is '1000-01-01 00:00:00' to '9999-12-31 23:59:59'. DECIMAL: A decimal number, which has exactly 2 decimal digits. This is the recommended type when using currency. DOUBLE: A decimal number of 8 bytes. The supported range is -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308. FLOAT: A decimal number of 4 bytes. The supported range is -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38. INTEGER: An integer of 4 bytes between -2147483648 and 2147483647. LONGVARCHAR: A string of a variable number of characters, between 0 and 16,777,215 characters long. This is a synonym for a MEDIUMTEXT field. REAL: A synonym for DOUBLE (unless the REAL_AS_FLOAT SQL mode is enabled). SMALLINT: An integer of 2 bytes between -32768 and 32767. TIME: The time in 'HH:MM:SS' format. TIMESTAMP: A synonym for DATETIME. TINYINT: An integer of 1 byte between -128 and 127. VARCHAR: A string of a variable number of characters, between 0 and 255 characters in length before MySQL 5.0.3 and between 0 and 65,535 characters in MySQL 5.0.3 and later.
"fld_size",	The field size is required for CHAR and VARCHAR fields, where it sets the maximum number of allowed characters. The field size is optional for BOOLEAN, TINYINT, SMALLINT, INTEGER and BIGINT fields, where it sets the maximum number of allowed digits. It is also optional for FLOAT, REAL and DECIMAL fields, where it sets the maximum number of digits before the decimal point. The number of decimal digits cannot be specified, although it is automatically set to 2 in DECIMAL fields. For example, setting fld_size to 4 allows numbers between -9999.X and 9999.X with the number of decimals determined by the maximum for the data type. The fld_size should NOT be included in DOUBLE, DATE, TIME, DATETIME, TIMESTAMP and LONGVARCHAR fields or it will cause a 400 error with no response object. Likewise, a 400 error will be caused if the fld_size is set to a value larger than the allowed size, such as 50 for an INTEGER.
"fld_null",	Optional. Set to 1 if this field may have a value of NULL, meaning "no data". Otherwise, set to 0, meaning that the field must have a value. If not included, then set to 1 by default.
"fld_autoincrement",	Optional. Set to 1 if this field will be auto-incremented, meaning that the value will be automatically inserted as the maximum existing value in the field plus 1. This option is recommended for ID fields. Otherwise set to 0, which is the default.
"fld_key"	Optional. Set to 1 if this field should be a primary key field, meaning that its value will be unique and it will used to index the table. Otherwise set to 0, which is the default if not included.
}	End of object defining the field.
...	Any additional field objects.
]	End array of field objects.
}	End object.

Result:

If the table is created, then the HTTP status code is set to 201 (Created) and a object is returned with information about the new PM Table. See the JSON example below.

JSON example:

Request:

Response:

PHP example:

Note: If using PHP, the POST variables will need to be passed through the http_build_query() which will cause problems with fields which include the fld_size. The ProcessMaker source code needs to be changed to avoid an error.

Add PM Table Data: POST /pmtable/{pmt_uid}/data

Add a new record to a PM Table.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

POST /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

Name	Description	Example
workspace	Workspace name	/api/1.0/workflow/pmtable/22815673755f209dd749c90081062413/data
pmt_uid	Unique ID of PM Table	/api/1.0/workflow/pmtable/22815673755f209dd749c90081062413/data

POST Fields:

The following object where the member variables have the same names as the fields in the PM Table and their values will be inserted in a new record in the PM Table.

Result:

If successful, the HTTP status is set to 201 (Created) and the new record which has been inserted in the PM Table is returned, with the field names in lowercase.

PHP example:

Note: Remember that ProcessMaker's MySQL database stores character data in the UTF-8 character set, so any strings should be converted to UTF-8 if they are in another character set, using a function such as iconv() in PHP.

Update PM Table Structure: PUT /pmtable/{pmt_uid}

Update the structure of a PM table.

Consideration:

• Must send the whole new structure of the table. If the table would have field A, B, C and the update sends A, B, D then C column is removed and D column is added.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

PUT /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID

Optional Fields:

Name	Type	Description
pmt_tab_dsc	String	PM Table description
fields	Array

Result:

Type	Description
empty	No return

Example:
Request

Response

Update PM Table Data: PUT /pmtable/{pmt_uid}/data

Update the data of an existing record in a PM table.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

PUT /api/1.0/{workspace}/pmtable/{pmt_uid}/data

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID

PUT Fields:

An object where the member variables have the same names as the fields in the PM Table and their values will be inserted in an existing record in the PM Table.

Result:

Type	Description
empty	No return

Example:
Request

Response

Delete PM Table: DELETE /pmtable/{pmt_uid}

Delete a specified PM table and all its data.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

DELETE /api/1.0/{workspace}/pmtable/{pmt_uid}

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID

Result:

Type	Description
empty	No return

Example
Response

Delete PM Table Data: DELETE /pmtable/{pmt_uid}/data/...

Delete a record from a PM table, by specifying its primary key(s). The PM Table can have up to 3 primary key fields.

Permission:

Users must have the PM_SETUP_PM_TABLES permission assigned to their role to have access to the endpoint information

Structure:

DELETE /api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}

(/api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}/{key2}/{value2})

(/api/1.0/{workspace}/pmtable/{pmt_uid}/data/{key1}/{value1}/{key2}/{value2}/{key3}/{value3})

URL Parameters:

Name	Type	Description
workspace	String	Workspace name
pmt_uid	String	PM Table UID
key1/key2/key3	String	Name of the PM Table primary key field (depending on the number of key fields in the table)
value1/value2/value3	String	Value of the PM Table primary key field (depending on the number of key fields in the table)

Result:

Type	Description
empty	No return

Example:
Response