Generic Outgoing API Block

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

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

Add the Generic Outgoing API block to any matter form, and it will automatically send an API call to the endpoint specified when the containing process is saved. This is one of two ways to send an API call from within LegalServer. The other method is to use Guided Navigation to make an API call.  

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 to let users know that this API call will be made when the submit/continue button is clicked.

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

Generic Outgoing API Block Administrator Setup

To use this block, first identify the endpoint you will hit with the API call. You'll need to research what authentication is required, and you may have to sign up to get keys to use the outside API endpoint.

1. Add an Auxiliary Form with the Generic Outgoing API Block on it.
2. Configure the Generic Outgoing API Block

Here is an example configuration that will return a random taco recipe:

The Parameters to Send (and potentially other fields) are not available when you first add the block to a form. You will have to save the form first and then reopen the block to edit those fields. The form should offer a "Save and Stay on Page" button that will do that.

Notes on the Configuration Settings

• "Legacy Items" and "Advanced Features", each with a Show button, hide many of the lesser used options (effective 2024-11-01).
• API URL: The service you are sending data to.
• API Method: either GET or POST. This is specified by the outside service's documentation.
• POST content type: Typically this will be "application/json", but it could also be "application/x-www-form-urlencoded".
• Parameters: defines what data you are sending. This 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).
  • Data Structure: this allows you to indicate that there is an object within the API call.
  • 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. 
• HTTP Headers: allows you to add specific headers in a comma separated set of keys and values. This is a great place to store authentication settings.
• Client Certificate: for authentication purposes.
• Store Response in a Note?: save the response 
  • 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. 

Especially when troubleshooting API issues, it is worth having "Store Response in a Note" set to true. 

1. Add the Form to a Process and the Process to the Actions Menu
2. Run the Process
3. Look at the Case Notes to see what the outside API endpoint returned.
4. Celebrate.

OAuth

If you need to use OAuth authentication, please file a ticket to request those features be enabled. Once we've enabled it, the Generic Outgoing API Block gains the following configuration values:

You'll have to then populate these fields. The Token URL allows you to identify the URL to get the OAuth Token from. The Username and password fields both need to be entered with the parameter name and the value. So if you need to submit a username, it would be "username:my_user_name" and the same with the password. As of 2023-05-24, there is a third field for an additional token parameter to be sent in the same format.

To then parse the results, you'll need to enter in the value to get the token from. If the response looks like:

{ "access_token":"12345"}

You'll want to put "access_token" in the final field for the JSON path. 

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

Differences from Guided Navigation API Calls

There are a number of small differences between the two ways to send API calls from within LegalServer. Primarily, the Generic Outgoing API Block lets you set custom headers beyond those required for Authentication.