API Service Fields in Collect
Copyright © 2018 EarthSoft, Inc • Modified: 12 Dec 2018
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.
The following steps show an example of setting up a field to pull from an OpenWeatherMap API:
1.Open a form template in the Collect dashboard in Enterprise.
2.Add a custom field and set the field Type to “Service”.
3.Click on the Service Tab.
4.(Optional) When Automatically pull service is checked, the Service field in the Collect app will pull data automatically when a form record is created.
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.
5.Under Get test result> 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.
7.Select data that should display in Collect:
a.Click the + node next to “main”
b.Click the checkbox next to each desired parameter.
c.Set a Display Name
8.To allow Collect to capture weather data as configured, but based on the field device’s current GPS coordinates, enter a formula in the Save Result section:
a.Under Save Result, click the URL button.
b.Add the following in the Formula text field (replacing the “&APPID” value with a valid key):
10.Click the Edit icon on the form field.
11.The JSON formulas that appear in the bottom of the editor 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 “Mappings” tab to properly parse the JSON string pulled from a service.
The reports services setup is like other API services with the exception that the “User EQuIS Authentication” needs to be selected for Collect reports.
1.Save a User Report which the Collect service field will call:
a.Publish the Collect API report(s) to the database.
b.Open the report in EQuIS Professional or Enterprise.
c.Select report parameters.
d.Save the selected parameters into a User Report.
e.In EQuIS Professional, open ST_USER_REPORT.
f.Note the ST_USER_REPORT.USER_REPORT_ID for the report just saved.
2.In the Collect dashboard in Enterprise, open a form template.
3.Add a custom field and set the field type to Service.
4.Click on the Service Tab.
5.Check the User EQuIS Authentication box.
6.Under Get test result> Test URL, enter the link to the API report. The report URL will look something like this:
where 1146251 is the ST_USER_REPORT.USER_REPORT_ID for the desired for the API report.
8.Select items to display in Collect:
a.For reference, the column headers for each column are listed under the “properties” node.
b.Expand the “data” node, then any of the row numbers (e.g., “0”) to find report output columns to include.
c.Click the checkbox next to each desired parameter.
d.Set a Display Name.
9.Under Save Result, click URL.
10.Enter a formula that will ultimately result in a valid URL call to the report API.
Note: Additional SQL statements may be appended on the end of the URL within the formula, which can filter the data returned by the report. For example, the following URL would return only rows where SYS_LOC_CODE equals a value that was entered on another form field called “Location”, and where FACILITY_ID=1:
CONCAT(‘https://[yourSiteName]/api/reports/[st_user_report.user_report_id]/data?where=sys_loc_code=''',[Location],''' and facility_id=1’)
12.Click the Edit icon on the form field.
13.The JSON formulas that appear in the bottom of the editor 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.
c.In the previous example, “JSON([Service1],'data’,0,2)” would return the VALUE_MAX column from the report.
1.In the Collect app, tap the newly created service field and tap Pull from server.
3.The service field will display the configured fields.