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 differences between the GN API Calls and the Generic outgoing API Block are:
  1. The Generic Outgoing API Block allows for data structures to be passed as part of the API call.
  2. The Generic Outgoing API Block lets you set custom headers beyond those required for Authentication.
  3. The GN API Call allows you to store results from the API call in specific fields and not just as a note. 
WARNING:  You must be sure you trust the outside service with your client's data.  

Configuration


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: 
  • 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. 
  • 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 reponse 
    • 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.