Home‎ > ‎Other Modules‎ > ‎Guided Navigation‎ > ‎

Guided Navigation API Calls

Purpose: Allow a LegalServer admin to, with custom coding, send information to an outside endpoint via API

Cost: This option is included with LegalServer.  For now, there is no charge for unlimited API calls.

Within Guided Navigation, you can add an element "Action: Perform an API Call". This functions similarly to the Generic Outgoing API Block (but is not exactly the same). When the element is loaded or submitted as part of a GN dialogue segment, it will automatically send an API call to the endpoint specified. 

Please note that there is no indication on the user side of the form that this block is present. You may wish to add an Instruction element to let users know that this API call will be made when the submit/continue button is clicked.

The big difference between the GN API Calls and the Generic outgoing API Block is that the Generic Outgoing API Block lets you set custom headers beyond those required for Authentication.

WARNING:  You must be sure you trust the outside service with your client's data.  

Configuration


There are some different customizations between the  big distinctions from the GOAPI block are:
  • Entering Logic: This controls whether this element of the GN Segment is utilized in the interview. It can always happen, or you can set certain expressions as a requirement for it to happen.
  • Run this action when segment is shown or submitted?: lets the user choose to run when the segment is displayed to the user or when the segment is submitted and the user clicks "Next".
  • URL: The service you are sending data to.
  • Method: either GET or POST. This is specified by the outside service's documentation.
  • Authentication: Rather than offer an HTTP Headers section in the Generic Outgoing API Block, this allows you to specify the exact authentication method directly. 
  • Perform request synchronously: For efficiency purposes, the API call is performed in the background by default. This allows you to move on to the next segment without waiting for a long API call to finish. If you want to wait for the next segment until the API call finishes and the response is processed, you will need to perform the request synchronously. This will process the response with JQ or case notes before moving on to the next segment. For example, if you want to chain API calls together (and pass variables for the second API call based on responses from the first), you will need to perform them synchronously. 
  • Parameters: defines what data you are sending. When you click "Add Parameter", you'll see three boxes. The first is the type of variable. The second is the parameter name. The third is the value to send. The type of variable can be either:
    • Literal Values: that you manually type in and are the same for every API Call. (Useful for API keys or static values).
    • LegalServer matter variables: Various matter values are available, including all custom matter fields. 
    • Data Structure: Allows you to create a heirarchy where you pass data within data -- { "note" : { "body": "This is the note body", "subject": "This is the note subject" } }
  • Path Parameter: is a checkbox to determine whether the parameter is available in the URL as a path parameter. In the url it should be show up as a bracketed version of the Param Name. For example. if the url is http://localhost:9999/anything/{case_id} then {case_id} will be replaced with the parameter named case_id that has the Path Parameter checked. 
  • Store Response in a Note?: save the response as a casenote. The entire case note will be stored in the format it was returned.  
    • Note Type: for the saved note
    • Note Subject: can be set specifically for this API call.
    • JSON params to pluck from response: this is a comma separated list of top level parameters to save in the case note. 
  • Set field based on response:  this is a powerful option that allows you to set matter fields as a result of the API call. 
    • Set with jq filters: This allows you to use highly customizable jq filters in parsing the JSON response of the API call. See jq documentation for detailed examples. This can work to set text, date, and boolean fields within LegalServer. 
    • Set with legacy simple expression: This is now a deprecated feature that would allow you to capture the top level values in a JSON response.
Especially when troubleshooting API issues, it is worth having "Store Response in a Note" set to true. 

jq Filters

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

Use Case

With the ability to use jq filters, you could easily set up a chained set of API calls that return data back into the case. One API call to confirm the client, one to confirm an option and the next to populate data. If each is set on a separate segment, it becomes a streamlined method for interacting with another integration.