Should produce a set of query parameters like:
{
"ethnicity": "Hispanic",
"Test": "Test",
"Address": {
"street": "123 Main Street",
"city": "Houston",
"state": "TX",
"zip": "77002"
}
}
Modify Parameters for NYC Data Format
NYC Open Data API calls require addresses to be full spelled out. This will look at the street address parameters lines and expand any abbreviations to the full word. The list includes:
AVE becomes AVENUE
BLVD becomes BOULEVARD
CIR becomes CIRCLE
CT becomes COURT
DR becomes DRIVE
EXPY becomes EXPRESSWAY
FWY becomes FREEWAY
HWY becomes HIGHWAY
LN becomes LANE
PKWY becomes PARKWAY
PL becomes PLACE
RD becomes ROAD
SQ becomes SQUARE
ST becomes STREET
TER becomes TERRACE
TPKE becomes TURNPIKE
For example with the jq filters, with a JSON API response of
{ "_internal": { "starttime": "2021-03-09T15:28:54.391312", "steps": 1, "steps_offset": 0, "tracker": 1 }, "nav": { "current": null, "hidden": false, "progressive": true }
Using a jq filter of ._internal.starttime and saving into a date field will let you see "03/09/2021".
Using a jq filter of ._internal.starttime and saving into a text field will let you see "2021-03-09T15:30:26.768303".
Using a jq filter of ._internal.starttime | length and saving into a number or text field will let you see "26" (as the length of the date when considered a string).
Using a jq filter of .nav.hidden and saving into a boolean field will let you see "No".
To explore jq filters further, please look at the jq documentation and to test jq filters look to jqplay.org. JQplay can also be run locally in a docker container. LegalServer uses jq version 1.5.
Updating Multiple Records
GN API calls can use jq to update multiple service/phase records on a case when there is multiple records to parse through in the API response. Think of the situation where you want to track all of the housing violations on the property and those all come back as a long API response. There is a limit on creating too many service records at one time using this API call. The standard limit is 250. If that is insufficient for your use case, please reach out to Support.
See Third Party Integrations: New York City Housing API (video) for an example of this in use.
For this to work, there are a few steps that need to be set up.
In the Service Type lookup, identify the specific service type that you want to update via the API call. Be sure to select "Create in Guided Navigation API? as true for any of those records.
Create the Dynamic Service Processes and Profiles. You will want to tie a create process to the new profile that will show all the fields you are getting back from the API call. In addition, be sure to grab the create process ID number. If you edit the create process, look in the URL and grab the number that follows edit_process/edit/. If you use this number in the API call's response, you'll be able to control which process it goes towards.
Setup your Guided Navigation API call. Be sure to check the box "Update Case from Response". There are three sections that then appear. For this feature, you'll need to use the second one "Create or Update service with jq filters.
If you want to create new service records each time you run the Guided Navigation API call, do not check the box for "Update existing service". If you want to update existing records based on a unique identifier in the source, you will need to identify it in the "Record Identifier query" as a jq filter. The filter should be for the specific unique identifer.
For example, if you are using the New York City Housing Data APIs to get details on housing violations, the data is returned in an array, you'd need to specify .[].violationid.
You'll need to specify which Service Type to save these records to. Only the ones you have identified in the Service Type lookup for GN will show up.
Then you've got the option to Add fields to the set. From the dropdown, you can pick the destination field. For the JQ filter, you'll want to provide a filter that will take you to the array, then a pipe, and then use the jq map() function on the specific key.
Using the same example, if you wanted to map the violationid mentioned above into a field, you'd need to use a jq filter of . | map(.violationid). The first . returns the array. The pipe passes it to the function that maps the specific keys from each housing violation record. You can read more about the map() function in the jq documentation.
To disable creating Service records, you will need to delete the rows that map the variables. Unchecking the Update Case from response is not sufficient (see LS-91120).
If Store the response as a Case Note is also selected, the case note response will be pre-appended by a statement indicating either the success or failure of the JQ processing. This occurs whether you are plucking out specific JSON parameters or just storing the entire response. Success example:
4 service record(s) created and 0 records(s) updated (limit: 250)
Failure example:
jq error: Unable to create or update service record(s) (jq: error: contactdescription/0 is not defined at <top-level>, line 1:
. | map(contactdescription)
jq: 1 compile error)
A few notes about mapping variables:
You likely will want to map something to Title field as that is what gives you a clickable link in the listview and reports.
You will get errors if you try mapping something to the Database ID or Type fields.
If you want to map a literal value that is the same on each service, you can use a filter of . | map(166) or something similar. This would be useful for the creation process field.
You can concatenate literals values (numbers or text) and values received. For example if .[].number returns a number, you can add to it by saying . | map(73 + .number). If you want the text value of a number or if you want to concatenate it with text, you may have to convert it to string.
If you want to map to a lookup (both custom lookups and system lookups), you have to map the numeric ID value of the lookup option, not the text value of the lookup. You can get the numeric values from the lookup table by clicking on the value in the lookup table. The numeric id in the URL is the value to map. Then you'd need to use a filter like . | map(if (.violationid) == "1234" then 1 elif (.violationid) == "4567" then 2 else 3 end).
Always take a sample of the API response and test all your jq filters against it in jqplay.org.