Creating and editing forms that contain Yes/no lists fields using the API

On the previous part, we showed how yes/no lists are structured in the JSON sent by the RPM API. On this part, we’ll show how to add forms and edit the values in a yes/no lists field.

ProcFormAdd

The API endpoint to add a form to a process is ProcFormAdd, we’ll add a new form to the process created on the previous part:

POST http://localhost/rpm/Api2.svc/ProcFormAdd HTTP/1.1
host: localhost

{
    "Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
    "ProcessID": "2781",
    "Form": {
        "Fields": [
            {
                "Field": "Yes/No List field",
                "Value": "{\"Values\":[{\"OptionID\":14321195,\"Value\":1,\"Comment\":\"Comment for this option\"},{\"OptionID\":14321196,\"Value\":2,\"Comment\":\"\"},{\"OptionID\":14321198,\"Value\":1,\"Comment\":\"\"}]}"
            }
        ]
    }
}

Note: The response from the request to ProcFormAdd will contain the internal FormID for the new form. This is useful if you need to be able to edit the form afterwards.

The field on the new form:
ProcFormAdd

ProcFormEdit

To edit a form, we use the ProcFormEdit API endpoint:

POST http://localhost/rpm/Api2.svc/ProcFormEdit HTTP/1.1
host: localhost

{
    "Key": "7c2c1037-b6fd-4b0a-b403-9ed39062ad76",
    "ProcessID": "2781",
    "Form": {
        "FormID": 221498,
        "Fields": [
            {
                "Field": "Yes/No List field",
                "Value": "{\"Values\":[{\"OptionID\":14321195,\"Value\":1,\"Comment\":\"Updated comment for this option\"},{\"OptionID\":14321196,\"Value\":1,\"Comment\":\"\"},{\"OptionID\":14321198,\"Value\":2,\"Comment\":\"\"}]}"
            }
        ]
    }
}

The field on the updated form:
ProcFormEdit

Posted in API Usage Examples

Reading Yes/no lists fields via the API

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:

example01 - 01-setup

  1. Value column labels determines the text to display for the yes and no answers
  2. Value column order determines which answer shows up first
  3. Value column format determines if the yes/no list should use check boxes instead of radio buttons
  4. Text value position determines if the option text shows before or between the yes and no answers
  5. Null column allows to enable and determine the display text for a “not applicable” answer
  6. 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:

  1. Value column labels “LabelYes” and “LabelNo”
  2. Value column order “OrderSwap” (true means Yes/No, false No/Yes)
  3. Value column format “RenderCheckbox”
  4. Text value position “TextMiddle”
  5. Null column “LabelNull” and “HideNull”
  6. 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
example01 - 06-form-edit

Displaying
example01 - 06-form

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”.

example02 - 01-setup-checkboxes

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
example02 - 02-form-edit

Displaying
example02 - 03-form-display

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:

example03 - 03-setup-comments

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
example03 - 02-form-edit

Displaying
example03 - 03-form-display

On the next article, we show how to add and edit forms that contain one of these yes/no list fields via the API.

Posted in API Usage Examples

New in 8.1: Rep access to comissions

When calling the Rep endpoint of the RPM API, you will get a new piece of information on the response: does this Rep have access to the sales commission values.

Look for it in the response like this:

{
    "Result": {
        ...
        "CommissionsHidden": false,
        ...
    }
}
Posted in Uncategorized

New API Error Format in 8.0

RPM 8.0 is bringing a change in the way errors in API results are structured.

On previous versions of RPM, when a call generated an error the response looked like this:

{
	"Result":{
		"Error":"Valid key required"
	}
}

The new syntax that you will be getting in 8.0 the value for the Error is an object.

{
	"Result":{
		"Error":{
			"Message":"Process not found"
		}
	}
}

This will allow us to provide you with more information on the error in the future. For now, any code that interacts with our API should take this into consideration and update the handling of error response.

Tagged with: , , ,
Posted in API News

Upcoming Change: Key goes First

On an upcoming update to RPM, the system will start requiring that the key be the first piece of data to be present in the request data.

Like this:

{
    "Key": "<Your API Key>",
    ... <"Rest of the Request Data>
}

The reason for this change is to optimize resource usage by not having to parse the entire request if the key is incorrect.

If you don’t do this already, we recommend that you do as it will not affect the way requests works at the moment and will ensure future compatibility when this requirement starts to be applied.

Posted in API News

Welcome to RPM’s Developers Site

Hi and Welcome,

Today We’re thrilled to launch this developers site. We plan to use it for documenting the current state of the REST API that comes with every RPM subscription as well as to keep developers informed of future changes that we have planned.

As we continue our progress in documenting all the available API endpoints, we will also start building sample applications and wrappers to show how to use them in different programming languages. If you have any questions, or requests please get in touch with us.

Posted in RPM