A the core of the process management functionality in RPM is the ability to save and update the data contained in forms. This same power is available via ProcFormAdd and ProcFormEdit API endpoints.
Both endpoints use the same JSON structure that allows to store data in the available fields in a process. This article will show you how to format the data for each kind of field to be able to successfully add and edit their values.
For each type of fields we’ll show the format returned by ProcFields and then how to send the data to ProcFormAdd and ProcFormEdit.
Single select list fields
ProcFields
{
"FormatType": 7,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "single",
"Options": [
{
"Text": "Option 1"
},
{
"Text": "Option 2"
},
{
"Text": "Option 3"
}
],
"SubType": 5,
"Tuid": "500_7125305",
"UserCanEdit": true
}
ProcFormAdd
The following request shows how to fill in a single select field while starting a new form:
POST http://localhost/rpm/Api2.svc/ProcFormAdd HTTP/1.1
host: localhost
{
"Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
"ProcessID": 2818,
"Form": {
"Fields" : [
{
"Field": "single",
"Value": "Option 1"
}
]
}
}
ProcFormEdit
When editing a form, you can use a request very similar to ProcFormAdd:
POST http://localhost/rpm/Api2.svc/ProcFormEdit HTTP/1.1
host: localhost
{
"Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
"ProcessID": 2818,
"Form": {
"FormID" : 221594,
"Fields" : [
{
"Field": "single",
"Value": "Option 1"
}
]
}
}
Submitting an invalid option will leave the field without value so sending the correct value is important.
Note: the data sent for ProcFormAdd and ProcFormEdit are basically the same aside from ProcFormEdit requiring the FormID to identify which form to edit. The next sections will show only the ProcFormAdd to keep things short.
Multi select list fields
ProcFields
{
"FormatType": 7,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "multi select",
"Options": [
{
"Text": "Option 1"
},
{
"Text": "Option 2"
},
{
"Text": "Option 3"
}
],
"SubType": 10,
"Tuid": "500_7125310",
"UserCanEdit": true
}
ProcFormAdd
The following request shows how to fill in a multi select field while starting a new form:
POST http://localhost/rpm/Api2.svc/ProcFormAdd HTTP/1.1
host: localhost
{
"Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
"ProcessID": 2818,
"Form": {
"Fields" : [
{
"Field": "multi select",
"Value": "Option 1, Option 2"
}
]
}
}
For multi select fields, send the options to “select” via a comma separated list.
Single value fields
We’re including in this section the following field types as they all behave similarly:
- Text
- Date
- Date time
- Money
- Decimal
- Quantity
- Percent
For all these fields, the only difference is the formatting of the data to be sent. Here is the list of Fields as received from ProcFields:
ProcFields
"Fields": [
{
"FormatType": 7,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Text",
"SubType": 1,
"Tuid": "500_7125316",
"UserCanEdit": true
},
{
"FormatType": 7,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": 2,
"Width": "1"
},
"Name": "Text (paragraph)",
"SubType": 11,
"Tuid": "500_7125317",
"UserCanEdit": true
},
{
"FormatType": 7,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": 3,
"Width": "1"
},
"Name": "Text (Link)",
"SubType": 12,
"Tuid": "500_7125318",
"UserCanEdit": true
},
{
"FormatType": 3,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Date",
"SubType": 3,
"Tuid": "500_7125319",
"UserCanEdit": true
},
{
"FormatType": 27,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Date and time",
"SubType": 28,
"Tuid": "500_7125386",
"UserCanEdit": true
},
{
"FormatType": 2,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": 6,
"Width": "1"
},
"Name": "Money ($1,000.95)",
"SubType": 7,
"Tuid": "500_7125321",
"UserCanEdit": true
},
{
"FormatType": 26,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Money (1,000.9490)",
"SubType": 16,
"Tuid": "500_7125322",
"UserCanEdit": true
},
{
"FormatType": 29,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Decimal",
"SubType": 22,
"Tuid": "500_7125323",
"UserCanEdit": true
},
{
"FormatType": 20,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Quantity",
"SubType": 14,
"Tuid": "500_7125324",
"UserCanEdit": true
},
{
"FormatType": 21,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "Percent",
"SubType": 17,
"Tuid": "500_7125325",
"UserCanEdit": true
}
]
ProcFormAdd
The following request shows how to fill each of the fields described before:
POST http://localhost/rpm/Api2.svc/ProcFormAdd HTTP/1.1
host: localhost
{
"Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
"ProcessID": 2818,
"Form": {
"Fields" : [
{
"Field": "Text",
"Value": "Anything can be put in this field, no length limitation"
},
{
"Field": "Text (paragrahp)",
"Value": "Anything can be put in this field, no length limitation"
},
{
"Field": "Text (Link)",
"Value": "http://google.ca"
},
{
"Field": "Date",
"Value": "2014-09-30"
},
{
"Field": "Date and time",
"Value": "2014-09-30T18:58"
},
{
"Field": "Money ($1,000.95)",
"Value": 129.3245
},
{
"Field": "Money (1,000.9490)",
"Value": 345.1234
},
{
"Field": "Decimal",
"Value": 123.321
},
{
"Field": "Quantity",
"Value": 4321.1234
},
{
"Field": "Percent",
"Value": 0.52
}
]
}
}
- Text fields – they all can be filled in with any string. Link fields (“SubType”: 12) don’t impose limitation on the data but it is recommended to submit a valir URL.
- Date and Date and time fields – RPM expects dates in ISO 8601 format.
- Decimal fields (money, decimal) – these fields all expect a decimal numeric value. They can receive as many decimal but will only show in RPM as configured (2 or 4 decimal).
- Quantity – these fields expect whole numbers and will be left empty if not a whole number.
- Percent – percentage fields expect percentage expressed as a decimal between 0 and 1 (use 0.95 to represent 95%). Numbers greater than 1 are allowed.
And that concludes this guide, in summary:
- To be able to submit a request to ProcFormAdd or ProcFormEdit, it’s necessary to do a request to ProcFields to get a list of available fields.
- The JSON format to add a new form and to edit a form are very similar.
- The JSON format to set a value for a field is the same for every field type. What changes is the formatting of the data to be sent.
RPM Developers Website - API Documentation and News 