Working with table fields via the API

Working with table fields via the API can be a bit confusing, we’ve written a guide to show the basics of table fields:

Working with Table Fields via the API

Posted in Uncategorized

An introduction to RPM Webhooks

We’ve published a quick introduction guide to RPM Webhooks in the upcoming RPM v12. If your organization is interested in automating some actions every time a form is created, edited, trashed/restored or archived/unarchived then take a look at thew new webhooks feature.

The guide can be found on the sidebar in most pages, for your convenience here’s a direct link too:

RPM Webhooks guide

Posted in Uncategorized

Worksheets being removed in RPM 11

In the next version of RPM we’re preparing a big change to a little used feature: Worksheets are being removed altogether from the service, including API access.

This means that the JSON structure for Forms is changing, and also the following API endpoints are being removed:

  • ProcFormWorksheetTableDataEdit
  • ProcFormWorksheetAdd
  • ProcFormWorksheetTableAdd
  • ProcFormWorksheet
Posted in Uncategorized

Getting more fields in ProcForms

The ProcForms API endpoint returns a list of forms for a given process. The fields returned for each form are based on the View ID provided. If the ViewID is not provided, the user’s default view is used.

Views in RPM

Views in RPM are used to show a list of forms in a process. The user has the freedom to select the visible fields and the order they’re in.

actions-view1

Clicking the “Edit view” button shows all the configurations possible in views, including the fields to show (highlighted in red):

actions-view2

Getting the View ID

RPM provides a section where it lists all the available views and the necessary IDs in ProcForms. To get to it go to the “Setup” section, click on the API button on the sidebar.

actions-view3

In the API page, there’s a “List of view IDs” link on the sidebar:

actions-view4

This page contains a list of all available views on a process. The user can select the process in the picker on the top left. Each row shown is one of the available views:

actions-view5

Using this information

With this information, the ProcForms endpoint can be called to provide the necessary data:

POST http://localhost/rpm/Api2.svc/ProcForms HTTP/1.1
RpmApiKey: 59a9a351-612d-4233-b610-134a7bca88b6

{
    "ProcessID": 1,
    "ViewID": 905
}

The response of this request looks something like this:

{
    "Result": {
        "Process": "Work Permits",
        "ProcessID": 1,
        "View": "Work information",
        "Columns": [
            "Number",
            "Start Date",
            "Short Description",
            "Complete Description"
        ],
        "Forms": [
            {
                "FormID": 3,
                "Values": [
                    "0003",
                    "3/4/2015 12:00:00 AM",
                    "Pipeline inspection in section C",
                    "Small leaks have been reported recently in section C pipelines, the works shall do a visual inspection to find any other leaks or rusted junctions and sections where new leaks could happen.\r\n\r\nAlso should look for any possible sources for these leaks (other than rusting)."
                ]
            },
            {
                "FormID": 2,
                "Values": [
                    "0002",
                    "3/6/2015 12:00:00 AM",
                    "Weekly Workshop Cleanup",
                    "Follow workshop cleanup checklist"
                ]
            },
            {
                "FormID": 1,
                "Values": [
                    "0001",
                    "3/19/2015 12:00:00 AM",
                    "Pump replacement at location ZZRP-1024",
                    "Replace the sump pump for the downstream reservoir"
                ]
            }
        ]
    }
}

Sending the same request without providing the ViewID will generate different results:

POST http://localhost/rpm/Api2.svc/ProcForms HTTP/1.1
host: localhost
RpmApiKey: 59a9a351-612d-4233-b610-134a7bca88b6

{
    "ProcessID": 1
}

In this case, the results contain the fields included in the user’s default view:

{
    "Result": {
        "Process": "Work Permits",
        "ProcessID": 1,
        "View": "All",
        "Columns": [
            "Number",
            "Owner",
            "Action due for me",
            "Started",
            "Started by",
            "Modified",
            "Modified by",
            "Files"
        ],
        "Forms": [
            {
                "FormID": 3,
                "Values": [
                    "0003",
                    "RPM Support",
                    "False",
                    "3/2/2015 2:47:41 PM",
                    "RPM Support",
                    "3/2/2015 2:47:41 PM",
                    "RPM Support",
                    ""
                ]
            },
            {
                "FormID": 2,
                "Values": [
                    "0002",
                    "RPM Support",
                    "False",
                    "3/2/2015 2:44:47 PM",
                    "RPM Support",
                    "3/2/2015 2:44:47 PM",
                    "RPM Support",
                    ""
                ]
            },
            {
                "FormID": 1,
                "Values": [
                    "0001",
                    "RPM Support",
                    "False",
                    "3/2/2015 2:43:46 PM",
                    "RPM Support",
                    "3/2/2015 2:43:46 PM",
                    "RPM Support",
                    ""
                ]
            }
        ]
    }
}
Posted in API Usage Examples

RPM 10 can now receive the API key as a request header

Back in 2013 we introduced a requirement that API keys had to be sent as the first attribute of the JSON payload, this was meant to allow some optimization when processing the request. This introduced a problem with JSON libraries that don’t allow custom property ordering. The JSON RFC also makes it clear that these keys are unordered.

Starting in RPM 10 we now check for the key in the header section of the HTTP request

Old:

POST http://localhost/rpm/Api2.svc/ProcFields HTTP/1.1

{
    "Key": ffffffff-ffff-ffff-ffff-ffffffffffff,
    "ProcessID": 502
} 

New:

POST http://localhost/rpm/Api2.svc/ProcFields HTTP/1.1
RpmApiKey: ffffffff-ffff-ffff-ffff-ffffffffffff

{
    "ProcessID": 502
}

For backwards compatibility we still allow the key to be passed as the first property in the JSON body. If a key is found in the header then any key in the body is ignored. Still, passing keys in the body should be considered temporary and we expect all API users to switch to the header key method. Eventually a future version of the API will no longer accept keys in the body.

Posted in API News, API Usage Examples

API primer: getting the coordinates of the options in a location list field

Location list fields are a special kind of list field where each option is associated to a set of geographic coordinate system coordinates.

When working with this kind of field via the API, the coordinates can be found inside the “InternalFormat” for the field and can be matched to the option via the ID.

Looking at the ProcFields response:

{
    "Result": {
        "Process": {
            "ProcessID": 502,
            "Fields": [
                {
                    "Name": "A Location List",
                    "Uid": "500_7610",
                    ...
                    "Options": [
                        {
                            "Text": "Headquarters",
                            "ID": 9386,
                            "IsHidden": false
                        },
                        {
                            "Text": "Field office",
                            "ID": 9387,
                            "IsHidden": false
                        }
                    ],
                    "InternalFormat": {
                        "Values": [
                            {
                                "Value": "51.0500\u00b0 N, 114.0667\u00b0 W",
                                "ID": 9386
                            },
                            {
                                "Value": "53.54438900,-113.49092669",
                                "ID": 9387
                            }
                        ]
                    },
                    ...
                }
            ],
            ...
        }
    }
}
Posted in API Usage Examples

Mastering ProcFormAdd and ProcFormEdit

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
            }
        ]
    }
}

Some things to note:

  • 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.
Posted in Uncategorized