The following guide will introduce some of the details you need to take into consideration when interacting with yes/no lists via the RPM API.
Process Template
When setting up a yes/no list field, you can configure it in different ways:
- Value column labels determines the text to display for the yes and no answers
- Value column order determines which answer shows up first
- Value column format determines if the yes/no list should use check boxes instead of radio buttons
- Text value position determines if the option text shows before or between the yes and no answers
- Null column allows to enable and determine the display text for a “not applicable” answer
- Comments column allows to enable and determine the display text for a “comments” free-text answer
This guide will show a process template with a yes/no field setup with the options shown in the previous image.
Displaying a yes/no list field
When displaying an entire form, any of the fields could be a yes/no list. This section shows how to retrieve the data and how to interpret the data related to a yes/no list field.
The ProcFields API endpoint returns the setup information for a process. The following is an example based on a process setup with only one yes/no list field (as seen on the previous screenshot).
Sending the ProcFields request
Sending the request to the API:
POST http://localhost/rpm/Api2.svc/ProcFields HTTP/1.1
host: localhost
{
"Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
"ProcessID": "2781"
}
The response will look something like this:
{
"Result": {
"Process": {
"FieldGroups": [],
"Fields": [
{
"FormatType": 47,
"InternalFormat": {
"HideNull": false,
"LabelComment": "Leave a comment",
"LabelNo": "Nope",
"LabelNull": "Maybe",
"LabelYes": "Yep",
"Options": [
{
"OptionID": 14321195,
"Text": "Option 1"
},
{
"OptionID": 14321196,
"Text": "Option 2"
},
{
"OptionID": 14321197,
"Text": "Call me"
},
{
"OptionID": 14321198,
"Text": "Option 3"
}
],
"OrderSwap": false,
"RenderCheckbox": true,
"ShowComment": true,
"TextMiddle": true,
"TwoTables": false
},
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": 1,
"Width": "2"
},
"Name": "Yes/No List field",
"SubType": 41,
"Tuid": "500_7123449",
"UserCanEdit": true
},
{
"FormatType": 7,
"IsRepeating": false,
"IsRequiredForUser": false,
"LayoutFormat": {
"Order": -1,
"Width": "1"
},
"Name": "multi list",
"SubType": 10,
"Tuid": "500_7123652",
"UserCanEdit": true
}
],
"ProcessID": 2781
}
}
}
The ProcFields response
Looking at the “Fields” list in the response, notice that there’s only one field Named “Yes/No List field” whose “FormatType” is 47 (YesNoList). One attribute we are interested in is the “InternalFormat”:
"InternalFormat": {
"HideNull": false,
"LabelComment": "Leave a comment",
"LabelNo": "Nope",
"LabelNull": "Maybe",
"LabelYes": "Yep",
"Options": [
{
"OptionID": 14321195,
"Text": "Option 1"
},
{
"OptionID": 14321196,
"Text": "Option 2"
},
{
"OptionID": 14321197,
"Text": "Call me"
},
{
"OptionID": 14321198,
"Text": "Option 3"
}
],
"OrderSwap": false,
"RenderCheckbox": true,
"ShowComment": true,
"TextMiddle": true,
"TwoTables": false
}
Looking at the parsed Internal format you can see the same properties that we setup at the beginning but presented in a JSON format:
- Value column labels “LabelYes” and “LabelNo”
- Value column order “OrderSwap” (true means Yes/No, false No/Yes)
- Value column format “RenderCheckbox”
- Text value position “TextMiddle”
- Null column “LabelNull” and “HideNull”
- Comments column “LabelComment” and “ShowComment”
The options to display in the list are available via the “Options” list.
Retrieving form data
The ProcForm API endpoint, provides the data stored in one form.
Sending the ProcForm request
POST http://localhost/rpm/Api2.svc/ProcForm HTTP/1.1
host: localhost
{
"Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
"FormID": 221421
}
The response will look something like this:
{
"Result": {
"Form": {
"Actions": [],
"ApprovalResult": "",
"Fields": [
{
"Field": "Yes/No List field",
"Value": "{\"Values\":[{\"OptionID\":14321195,\"Value\":2,\"Comment\":\"\"},{\"OptionID\":14321196,\"Value\":1,\"Comment\":\"\"},{\"OptionID\":14321198,\"Value\":2,\"Comment\":\"\"}]}"
}
],
"Files": [],
"FormID": 221421,
"Modified": "2014-09-22",
"Notes": [],
"NotesForStaff": [],
"Number": "0003",
"Owner": "joaquin manager",
"Participants": [
{
"Name": "joaquin manager",
"Read": "2014-09-18",
"Role": "System Manager"
}
],
"Sets": [],
"Started": "2014-09-17",
"Status": "New",
"VerifiedList": []
},
"Process": "18209 - yes/no example",
"ProcessID": 2781
}
}
The ProcForm response
Looking at the “Fields” list in the response, the “Value” of the “Yes/No List field” will be a string-encoded JSON that contains the value for each option where the user chose something other than the Null option, after decoding the data it looks like this:
"Fields": [
{
"Values": [
{
"Comment": "",
"OptionID": 14321551,
"Value": 2
},
{
"Comment": "",
"OptionID": 14321552,
"Value": 1
},
{
"Comment": "",
"OptionID": 14321554,
"Value": 2
}
]
}
]
Each option contains a “Value” key that indicates which value was chosen:
- 1 means the user chose the “No” option
- 2 means the user chose the “Yes” option
Use the “OptionID” key to match with the option text available via the ProcFields API call.
This is the basic information necessary to display a yes/no list field. Inside RPM they are displayed in the following way:
Editing
Displaying
Notice that options that have the “N/A” option selected (in this example “Maybe”) are not shown on the view.
And that is the basics of how to interpret and handle the data received via the API:
- Use ProcFields to get the setup information on how to display a yes/no list fields
- Use ProcForm to get the actual data in the field when displaying a form
Other yes/no list configurations
Checkboxes
When the a yes/no list is setup to use checkboxes the Null option must be ignored as it’s not possible for the user to respond “not applicable”.
Note how the “Null column” section on the setup page has disappeared. In the response for ProcFields:
"InternalFormat": {
"HideNull": false,
"LabelComment": "Comments",
"LabelNo": "Nope",
"LabelNull": "Maybe",
"LabelYes": "Yep",
"Options": [ ... ],
"OrderSwap": false,
"RenderCheckbox": true,
"ShowComment": false,
"TextMiddle": true,
"TwoTables": false
}
Notice that “HideNull” is still false, but “RenderCheckbox” is now true.
Inside RPM they are displayed in the following way:
Editing
Displaying
Comment fields
Yes/no lists can be configured to show a comment field for every option available. Modifying the previous example, the setup setup section will look like the following:
After enabling the comments field option, the “InternalFormat” in the response for ProcField looks like:
"InternalFormat": {
"HideNull": false,
"LabelComment": "Leave a comment",
"LabelNo": "Nope",
"LabelNull": "Maybe",
"LabelYes": "Yep",
"Options": [ ... ],
"OrderSwap": false,
"RenderCheckbox": true,
"ShowComment": true,
"TextMiddle": true,
"TwoTables": false
}
Notice that “ShowComment” now is true and “LabelComment” indicates the text to put as a label.
Inside RPM they are displayed in the following way:
Editing
Displaying
On the next article, we show how to add and edit forms that contain one of these yes/no list fields via the API.
RPM Developers Website - API Documentation and News 