3.2 - 3.8 - REST API Designer - Dynaforms

DynaForm Endpoints

The current methods implemented for the Dynaform resources in the ProcessMaker API designer are listed below:

Dynaform resources:

Note: (**) Defines only one value: copy_import or pmtable; if both variables are defined, an error will be shown.

Information about each method is written in the sections below:

Get Dynaform List: GET project/{prj_uid}/dynaforms

Gets the list of Dynaforms in a project.

GET /api/1.0/{workspace}/project/{prj_uid}/dynaforms

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID

Result:

Type	Description
array	Returns an array of Dynaforms objects

Example:

Response

Get Dynaform: GET project/{prj_uid}/dynaform/{dyn_uid}

Gets a single Dynaform from a project.

GET /api/1.0/{workspace}/project/{prj_uid}/dynaform/{dyn_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID
dyn_uid	String	Dynaform UID

Result:

Type	Description
object	Returns an array of Dynaform objects

Example:

Response

Get Field List in Grid: GET project/{prj_uid}/dynaform/{dyn_uid}/grid/{grd_name}/field-definitions

Gets the list of fields found in a specified grid.

GET /api/1.0/{workspace}/project/{prj_uid}/dynaform/{dyn_uid}/grid/{grd_name}/field-definitions

URL Parameters:

Name	Type	Description	Example
workspace	String	Workspace name.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definitions
prj_uid	String	Unique ID of the project, which can be found in the @@PROCESS system variable in the Debugger.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definitions
dyn_uid	String	Unique ID of the Dynaform that holds the grid, which can be found by clicking on the border of the DynaForm and looking at the id property.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definitions
grd_name	String	The name of the variable which is associated with the grid. Note that it is not possible to retrieve grids that aren't associated with a variable.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definitions

Result:

If successful, the HTTP status code is set to 200 and an array of objects is returned, which contain the attributes of the fields in the specified grid. The attributes vary according to the type of field. To learn more, see the Available Attributes of DynaForm controls and Editing DynaForm's JSON code.

Example:

Response

200 (OK)
[
  {
    "type":           "text",
    "variable":       "",
    "var_uid":        "",
    "dataType":       "",
    "protectedValue": false,
    "id":             "clientName",
    "name":           "clientName",
    "label":          "Client Name",
    "defaultValue":   "",
    "placeholder":    "",
    "hint":           "",
    "required":       false,
    "textTransform":  "none",
    ...
  }
  {
    "type":               "datetime",
    "variable":           "",
    "var_uid":            "",
    "dataType":           "",
    "protectedValue":     false,
    "id":                 "contractDate",
    "name":               "contractDate",
    "label":              "Contract Date",
    "placeholder":        "",
    "hint":               "",
    "required":           false,
    "mode":               "parent",
    "format":             "YYYY-MM-DD",
    "dayViewHeaderFormat":"MMMM YYYY",
    "extraFormats":       false,
    "stepping":           1,
    "minDate":            "",
    ...
  }
]

PHP Example:

The following code retrieves the field list for a grid whose variable is named "clientList", and prints a list of the attributes for each field in the grid.

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

$gridName = 'clientList';
$dynaformId = '406442383573140df944390011262710';
$projectId = '798659366573140bc117490080056441';
$url = "/api/1.0/workflow/project/$projectId/dynaform/$dynaformId/grid/$gridName/field-definitions";

$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
if ($oRet->status != 200) {
  print_r($oRet);
  die;
}

print "<pre>"; //if displaying in a web page
foreach($oRet->response as $oField) {
   print "{\n";
   foreach($oField as $key => $value) {
      print "  $key => $value\n";
   }
   print "}\n";
}

Get Field in Grid: GET project/{prj_uid}/dynaform/{dyn_uid}/grid/{grd_name}/field-definition/{fld_id}

Gets the attributes of a field in a grid.

GET /api/1.0/{workspace}/project/{prj_uid}/dynaform/{dyn_uid}/grid/{grd_name}/field-definition/{fld_id}

URL Parameters:

Name	Type	Description	Example
workspace	String	Workspace name.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definition/address
prj_uid	String	Unique ID of the project, which can be found in the @@PROCESS system variable in the Debugger.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definition/address
dyn_uid	String	Unique ID of the Dynaform that holds the grid, which can be found by clicking on the border of the DynaForm and looking at the id property.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definition/address
grd_name	String	The name of the variable which is associated with the grid. Note that it is not possible to retrieve grids that aren't associated with a variable.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definition/address
fld_id	String	The id of a field inside a grid.	/api/1.0/workflow/project/798659366573140bc117490080056441/ dynaform/406442383573140df944390011262710/grid/ clientList/field-definition/address

Result:

If successful, the HTTP status code is set to 200 and an object is returned, which contain the attributes of the grid field. The attributes vary according to the type of field. To learn more, see the Available Attributes of DynaForm controls and Editing DynaForm's JSON code.

Example:

Response

200 (OK)
{
  "type":             "text",
  "variable":         "",
  "var_uid":          "",
  "dataType":         "",
  "protectedValue":   false,
  "id":               "clientName",
  "name":             "clientName",
  "label":            "Client Name",
  "defaultValue":     "",
  "placeholder":      "",
  "hint":             "",
  "required":         false,
  "textTransform":    "none",
  "validate":         "",
  "validateMessage":  "",
  "maxLength":        1000,
  "formula":          "",
  "mode":             "parent",
  "operation":        "",
  "datasource":       "database",
  "dbConnection":     "workflow",
  "dbConnectionLabel":"PM Database",
  "sql":              "",
  "dataVariable":     "",
  "columnWidth":      "30",
  "width":            100,
  "title":            "Client Name"
}

PHP Example:

The following code prints out the attributes of a field with the ID "clientName" found in a grid whose variable is named "clientList".

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

$gridName = 'clientList';
$fieldId  = 'clientName';
$dynaformId = '406442383573140df944390011262710';
$projectId = '798659366573140bc117490080056441';
$url = "/api/1.0/workflow/project/$projectId/dynaform/$dynaformId/grid/$gridName/field-definition/$fieldId";

$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   print "<pre>"; //if in web page
   foreach($oRet->response as $key => $value) {
      "$key => $value\n";
   }
}

Create DynaForm: POST project/{prj_uid}/dynaform

Normal creation of a DynaForm.

POST /api/1.0/{workspace}/project/{prj_uid}/dynaform

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID

Required Fields:

Name	Type	Description
dyn_title	String	Dynaform title
dyn_type	String	Dynaform type, which is always "xmlform".
dyn_version	Integer	Dynaform version which is 1 for a classic Dynaform based on XML or 2 for a responsive Dynaform based on JSON.

Optional Fields:

Name	Type	Description
dyn_description	String	Dynaform description
dyn_content	String	The XML or JSON code for the Dynaform. This can be found either by exporting a Dynaform as a .json file or by copying the content from the DYNAFORM.DYN_CONTENT field in the database. If importing JSON, all the whitespace needs to be removed. TIP: If needing to edit a Dynaform's content, go to http://jsonviewer.stack.hu and paste the JSON code into the editing window. Then, click on Format to get an editable version of the JSON with spacing. When done editing, click on Remove white space to remove the spacing. Then, copy the JSON code into a text editor and search for each " and replace it with \" so that all the Dynaform's code will be contained in a single string.

Result:

Type	Description
object	Returns an object with the new dynaform information and the attribute: "dyn_uid"

If the dyn_content is included, then new unique IDs will be generated for the Dynaform and its variables when it is imported. If the dyn_title and dyn_description were specified, then they will be inserted in the Dynaform's code, replacing the original title and description.

Example:

Request

Response

PHP Example:

Create Dynaform from Copy/Import: POST project/{prj_uid}/dynaform

Creates a Dynaform using Copy/Import.

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}/dynaform

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID

Required Fields:

Name	Type	Description
dyn_title	String	Dynaform title
dyn_version	Integer	Dynaform version
copy_import	String	Dynaform data to Copy/Import
copy_import . prj_uid	String	Project UID
copy_import . dyn_uid	String	Dynaform UID

Optional Fields:

Name	Type	Description
dyn_description	String	Dynaform description
dyn_content	String	Dynaform content

Result:

Type	Description
object	Returns an object that contains information about the new Dynaform and the attribute: "dyn_uid"

Example:

Request

Response

Create Dynaform from PM Table: POST project/{prj_uid}/dynaform

Creates a Dynaform using the fields in a PM table.

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}/dynaform

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID

Required Fields:

Name	Type	Description
dyn_title	String	Dynaform title
dyn_version	Integer	Dynaform version
pmtable	object	PM Table data
pmtable . tab_uid	String	PM Table UID
pmtable . fields	object	Definition of the primary key to register in the PM Table

Optional Fields:

Name	Type	Description
dyn_description	String	Dynaform description
dyn_content	String	Dynaform content

Result:

Type	Description
object	Returns an object that contains information about the new Dynaform and the attribute: "dyn_uid"

Example:

Request

Response

Update Dynaform: PUT project/{prj_uid}/dynaform/{dyn_uid}

Updates a Dynaform in a project.

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}/dynaform/{dyn_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID
dyn_uid	String	Dynaform UID

Optional Fields:

Name	Type	Description
dyn_title	String	Dynaform title
dynaform_description	String	Dynaform description
dyn_type	String	Dynaform type
dyn_version	Integer	Dynaform version
dyn_content	String	Dynaform content

Result:

Type	Description
empty	No return

Example:

Request

Response

Delete Dynaform: DELETE project/{prj_uid}/dynaform/{dyn_uid}

Deletes a Dynaform in a project.

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}/dynaform/{dyn_uid}

Parameters:

Name	Type	Description
workspace	String	Workspace name
prj_uid	String	Project UID
dyn_uid	String	Dynaform UID

Result:

Type	Description
empty	No return

Example:

Response