This article explains how to setup a form field using the “Service” field type in Collect. A service field makes Application Programming Interface (API) requests over HTTPS. These requests can be either internal, which use EQuIS Authentication and access certain Collect reports, or external, such as accessing an API for weather data.
Collect Enterprise Setup for External Service
The following steps show an example of setting up a field to pull from an OpenWeatherMap API:
1.Open a template in the Collect dashboard in Enterprise.
2.Add a custom field and set the field Type to “Service”.
3.Click the Service Tab.
4.Set the Service Type to "Generic".
5.Set the Request Method to “Get”.
Note: The option “User EQuIS Authentication” is reserved for internal EQuIS Collect report services. See the Collect Enterprise Setup for Internal Service directions in the following section. |
|---|
6.(Optional) When Automatically Pull Service is checked, the service field in the Collect app will pull data automatically each time a field is populated, indicated by a "Loading" message in Collect Mobile.
7.(Optional) When Include In Data is checked, the data returned from the API will be included.
8.Click on the Formula column for the URL attribute and enter a formula that will ultimately result in a valid URL call to the report API. The URL should contain the protocol and the domain.
Example: ‘https://api.openweathermap.org’.
9.Click on the Formula column for the RequestURI attribute and enter a formula that will ultimately result in a valid URL call to the report API when combined to the URL. The RequestURI should contain the path and possibly the query string.
Example: ‘/data/2.5/weather?lat=43&lon=-82&APPID=REPLACE_WITH_YOUR_KEY&units=metric’.
10.Under Mobile Display Setup > Test URL, enter the link to the API. To setup an external service, make sure that a valid APPID key is provided in the URL, if required.
Example: API call from https://openweathermap.org/api will look like this: https://api.openweathermap.org/data/2.5/weather?lat=43&lon=-82&APPID=REPLACE_WITH_YOUR_KEY&units=metric.
11.Click View.
12.Select data that should display in Collect:
a.Click the + node next to “main”.
b.Click the check box next to each desired parameter.
c.Set a Display Name
8.Click Save.
9.Click OK.
10.The JSON (JavaScript Object Notation) formulas that appear in the Mobile Display Formulas may be used in other places in the form template:
a.Calculations on other fields.
b.Mappings from a form field to the format used. All data mapped back to fields in format need to use formulas in the “Data Mappings” tab to properly parse the JSON string pulled from a service.
Collect Enterprise Setup for Internal Service
The following steps show hot to set up a field to pull from an EQuIS Report:
1.Open a template in the Collect dashboard in Enterprise.
2.Add a custom field and set the field Type to “Service”.
3.Click the Service Tab.
4.Set the Service Type to “EQuIS Report”.
5.(Optional) When Automatically Pull Service is checked, the Service field in the Collect app will pull data automatically when a form record is created.
6.(Optional) When Include In Data is checked, the data returned from the API will be included.
7.Click the Choose a Report button and select a report. Users can choose which reports are displayed by clicking on the Report Chooser button in the upper right corner.
8.(Optional) Choose an Output Type from the drop down.
9.(Optional) Edit the Formula sections for any of the Report Parameters.
10.Click OK.
Use Service Field in Collect App
1.In the Collect app, tap the newly created service field and tap Pull from server.
2.Tap Save.
3.The service field will display the configured fields.
