When working with the API you may have noticed that the way Fields are specified when adding or editing forms is a bit different between fields inside tables and outside of them. The way fields are provided inside tables differs in two big ways:
- Identify the fields inside tables by their Uids – ProcFormAdd and ProcFormEdit use the field name (via the “Field” key) to identify which field to fill. This works because field names are unique inside the process. But for tables we have switched to Uids, this reduces the potential for confusion and makes finding the correct field on the server side a lot faster.
- Allow multi-value values – for fields outside tables we provide the value using a string, this becomes a problem when working with multi-select fields because it requires special formats which are error prone. For fields inside tables we’ve moved to a more structured way of providing the value of the field via an array of objects. Multi-select fields are not supported inside tables at the time of writing but this structure should allow to add support easily.
These two are differences make the API easier to use and understand, but because we didn’t want to disrupt current API users these changes didn’t get implemented for fields outside tables. Due to that we have 2 ways to specify fields in the API which can be confusing.
This guide will clarify a bit the differences and more importantly will show how to work with fields inside tables. The example section contains a full example of how the data is sent.
ProcFormAdd basic structure
The basic argument list for ProcFormAdd is:
ProcFormAdd(
int processID,
string Process,
object Form,
bool WebhookEvaluate
)
The Form object contains a Fields key that is the list of fields to fill in:
"Fields" : [
{
"Field": <string>, // Field Name
"Value": <string> // Field Value
},
// ... more fields
]
If a field is a table field, instead of having a Value key it will have a Rows key:
"Fields" : [
{
"Field": <string>, // Field Name
"Rows": <array> // Array of rows to fill in
},
// ... more fields
]
Rows
The data structure for rows on a table field is very simple and the only difference is how to identify rows when working with a defined rows table. To identify the defined row a “TemplateDefinedRowID” must be provided, the value should be the ID of the defined row as received in ProcFields.
"Rows": [
{
"TemplateDefinedRowID": <int>, // Defined row ID from ProcFields
"Fields": [...]
},
// more rows
Deleting rows
To delete rows from free rows table you must exclude the row from the data payload sent to ProcFormEdit.
When working with tables it’s recommended that API users first fetch the form’s complete data using ProcForm and then modify the data inside the tables to ensure that untouched rows do not get deleted by mistake.
Fields inside row tables
Similarly to the Form, each row has a “Fields” key with a list of fields to fill in but the structure is different:
- Identify the field by Uid – as of this writing (RPM20) the fields are identified via their name outside tables but for fields inside tables we use Uids
- Provide the field Value with an array – each entry in the Values array will have a “Value” or “ID” key:
- Use “ID” for fields that options with IDs (This IDs are available via the ProcFields API endpoint for list fields, or for reference fields via the different endpoints based on the reference type – i.e. ProcFormList, AgentUsers, CustomerUsers, etc.)
- Use “Value” when the field has free text values (dates, text fields, number fields, etc)
"Fields": [
{
"Uid": <string>, // Field Uid, usually with this format "522_382"
"Values": [
{
"ID": <int>, // Use this if reference or list field
"Value": <string> // Use this if any other
},
// More values for fields (not used at the moment)
]
}
]
Example
This section shows a sample process (via ProcFields) and an example ProcFormAdd request to show a set of fields inside tables.
ProcFields
{
"Result": {
"Process": {
"ProcessID": 132,
"Signatures": {
"IsEnabled": false,
"Name": "Signatures",
"IsHandDrawn": false,
"ShowCompany": false,
"Instruction": ""
},
"NotificationFields": [],
"Fields": [
{
"Name": "Defined rows",
"Uid": "500_1366",
"Order": 1,
"IsRepeating": false,
"FieldType": 500,
"SubType": 46,
"FormatType": 18,
"LayoutFormat": {
"Width": "2"
},
"InternalFormat": {
"TotalsRow": 0
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false,
"Rows": [
{
"ID": 1893,
"Name": "",
"Order": 0,
"IsDefinition": true,
"IsLabelRow": false,
"IsShown": true,
"Fields": [
{
"Name": "Form Reference Field",
"Uid": "522_382",
"Order": 1,
"IsRepeating": false,
"FieldType": 522,
"SubType": 519,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"ProcessID": 73,
"Flags": 0,
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A customer",
"Uid": "522_383",
"Order": 2,
"IsRepeating": false,
"FieldType": 522,
"SubType": 5,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A text field",
"Uid": "500_1367",
"Order": 3,
"IsRepeating": false,
"FieldType": 500,
"SubType": 1,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"InternalFormat": {
"PatternEnabled": false,
"Pattern": "",
"Instruction": ""
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A date",
"Uid": "500_1368",
"Order": 4,
"IsRepeating": false,
"FieldType": 500,
"SubType": 3,
"FormatType": 3,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A date and time",
"Uid": "500_1369",
"Order": 5,
"IsRepeating": false,
"FieldType": 500,
"SubType": 28,
"FormatType": 25,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A list",
"Uid": "500_1370",
"Order": 6,
"IsRepeating": false,
"FieldType": 500,
"SubType": 5,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"Options": [
{
"Text": "Option 1",
"ID": 5460,
"IsHidden": false,
"IsLabel": false,
"CssClass": ""
},
{
"Text": "Option 2",
"ID": 5461,
"IsHidden": false,
"IsLabel": false,
"CssClass": ""
},
{
"Text": "Option 3",
"ID": 5462,
"IsHidden": false,
"IsLabel": false,
"CssClass": ""
}
],
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
}
]
},
{
"ID": 1894,
"Name": "Row Name",
"Order": 1,
"IsDefinition": false,
"IsLabelRow": false,
"IsShown": true,
"Fields": [
{
"Name": "Form Reference Field",
"Uid": "522_382",
"Order": 1,
"IsRepeating": false,
"FieldType": 522,
"SubType": 519,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"ProcessID": 73,
"Flags": 0,
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A customer",
"Uid": "522_383",
"Order": 2,
"IsRepeating": false,
"FieldType": 522,
"SubType": 5,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A text field",
"Uid": "500_1367",
"Order": 3,
"IsRepeating": false,
"FieldType": 500,
"SubType": 1,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"InternalFormat": {
"PatternEnabled": false,
"Pattern": "",
"Instruction": ""
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A date",
"Uid": "500_1368",
"Order": 4,
"IsRepeating": false,
"FieldType": 500,
"SubType": 3,
"FormatType": 3,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A date and time",
"Uid": "500_1369",
"Order": 5,
"IsRepeating": false,
"FieldType": 500,
"SubType": 28,
"FormatType": 25,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A list",
"Uid": "500_1370",
"Order": 6,
"IsRepeating": false,
"FieldType": 500,
"SubType": 5,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
}
]
},
{
"ID": 1895,
"Name": "Row Name1",
"Order": 2,
"IsDefinition": false,
"IsLabelRow": false,
"IsShown": true,
"Fields": [
{
"Name": "Form Reference Field",
"Uid": "522_382",
"Order": 1,
"IsRepeating": false,
"FieldType": 522,
"SubType": 519,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"ProcessID": 73,
"Flags": 0,
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A customer",
"Uid": "522_383",
"Order": 2,
"IsRepeating": false,
"FieldType": 522,
"SubType": 5,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A text field",
"Uid": "500_1367",
"Order": 3,
"IsRepeating": false,
"FieldType": 500,
"SubType": 1,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"InternalFormat": {
"PatternEnabled": false,
"Pattern": "",
"Instruction": ""
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A date",
"Uid": "500_1368",
"Order": 4,
"IsRepeating": false,
"FieldType": 500,
"SubType": 3,
"FormatType": 3,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A date and time",
"Uid": "500_1369",
"Order": 5,
"IsRepeating": false,
"FieldType": 500,
"SubType": 28,
"FormatType": 25,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A list",
"Uid": "500_1370",
"Order": 6,
"IsRepeating": false,
"FieldType": 500,
"SubType": 5,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"UserCanEdit": false,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
}
]
}
]
},
{
"Name": "Free rows",
"Uid": "500_1371",
"Order": 3,
"IsRepeating": false,
"FieldType": 500,
"SubType": 45,
"FormatType": 18,
"LayoutFormat": {
"Width": "2"
},
"InternalFormat": {
"TotalsRow": 0
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false,
"Rows": [
{
"ID": 1928,
"Name": "",
"Order": 0,
"IsDefinition": true,
"IsLabelRow": false,
"IsShown": true,
"Fields": [
{
"Name": "A reference field",
"Uid": "522_384",
"Order": 1,
"IsRepeating": false,
"FieldType": 522,
"SubType": 519,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"ProcessID": 73,
"Flags": 0,
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "Some text",
"Uid": "500_1372",
"Order": 2,
"IsRepeating": false,
"FieldType": 500,
"SubType": 1,
"FormatType": 7,
"LayoutFormat": {
"Width": "1"
},
"InternalFormat": {
"PatternEnabled": false,
"Pattern": "",
"Instruction": ""
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
},
{
"Name": "A yes no",
"Uid": "500_1373",
"Order": 3,
"IsRepeating": false,
"FieldType": 500,
"SubType": 4,
"FormatType": 4,
"LayoutFormat": {
"Width": "1"
},
"InternalFormat": {
"IsCheckbox": false
},
"UserCanEdit": true,
"IsRequiredForUser": false,
"Archived": false,
"EmailNotification": false
}
]
}
]
}
],
"FieldGroups": [],
"StatusLevels": [
{
"Text": "New",
"ID": 156,
"Order": 1,
"ShowSignature": false
}
],
"Folders": [],
"EmailNotification": [
{
"UserType": 1,
"Enabled": true,
"Watching": 2
},
{
"UserType": 3,
"Enabled": true,
"Watching": 2
},
{
"UserType": 8,
"Enabled": true,
"Watching": 2
}
],
"Approvals": [],
"MeasurementFieldControl": {
"FieldUID": "0_0",
"Values": ""
}
}
}
}
ProcFormAdd request
POST /RPM20/Api2.svc/ProcFormAdd HTTP/1.1
Host: secure.rpmtest.ca
RpmApiKey: &lt;key&gt;
{
"ProcessID": "132",
"Form": {
"Fields": [
{
"Uid": "500_1374",
"Value": "this is teh value"
},
{
"Field": "Defined rows",
"Uid": "500_1366",
"Rows": [
{
"TemplateDefinedRowID": 1894,
"Fields": [
{
"Uid": "522_382",
"Values": [
{
"ID": 1729
}
]
},
{
"Uid": "522_383",
"Values": [
{
"ID": 3
}
]
},
{
"Uid": "500_1367",
"Values": [
{
"Value": "This is the text"
}
]
},
{
"Uid": "500_1368",
"Values": [
{
"Value": "2017-08-28T20:49:00.000Z"
}
]
},
{
"Uid": "500_1369",
"Values": [
{
"Value": "2017-08-28T20:49:00.000Z"
}
]
},
{
"Uid": "500_1370",
"Values": [
{
"ID": 5462
}
]
}
]
}
]
},
{
"Field": "Free rows",
"Uid": "500_1371",
"Rows": [
{
"Fields": [
{
"Uid": "522_384",
"Values": [
{
"ID": 1762
}
]
},
{
"Uid": "500_1372",
"Values": [
{
"Value": "This is the text"
}
]
},
{
"Uid": "500_1373",
"Values": [
{
"Value": "Yes"
}
]
}
]
}
]
}
]
}
}
Conclusions
We’ve written this guide to clarify the differences of the data structure for fields inside tables against fields outside tables. Here are the main points:
- Providing data to ProcFormAdd and ProcFormEdit requires the user to send a list of fields along with their values to fill the form
- The data structure for fields inside tables is different than for fields directly on the form
- The structure for fields inside tables is a future proof form that will eventually make it to the fields outside tables
- When sending data for a defined rows table the data requires to identify the row to fill via the TemplateDefinedRowID key
- The value for fields outside tables is provided as a string and the value for fields inside tables is provided as an array of objects that vary depending on the type of field (some take an ID key and some string Value key)
RPM Developers Website - API Documentation and News 