Reports API

Purpose: Enable an external program to retrieve report results via a special user and URL.

Cost: There is no charge for this module.

Enabling: This module must be enabled by LegalServer staff. To see if your site already has it enabled, try the steps in "Individual Report Setup" below. If you come away sad, see the next paragraph.

Required Ticket Language to Get the Module Enabled: 

File a ticket from your site (Help menu > Support Request). Put "Enable Reports API" in the Short Description of Issue field.

We can usually enable the feature on your demo site within a week of you filing the ticket, with your live site getting it the week after it hits your demo site. If you have a more urgent need to get this enabled, put that in your ticket, along with a description of the pony you will send staff.

In this Article:

• Cautions
• User Setup
• Authentication
• Individual Report Setup
• Manual Testing
• Filter Overrides in API Calls
• Reporting on Reports API
• Errors
• Notes and Known Issues

Cautions

This feature allows pulling data from your database, potentially a lot of data, with the usual security concerns that entails, and with potential impact on your site's performance.

• Build reports that minimize exposure of confidential information.
• Practice good security protocols with access to the API user account, especially if you are giving this access to external vendors/programmers.
• Build reports with sane filters. Do not build a report that pulls all time information or all case information or all case notes, for example.
• Wherever you store the potentially large amount of data retrieved by this method, that system and any backups you make of it should be treated as a particularly high security priority.  
• If you permit a third party vendor to use this API, ensure that you understand how the vendor stores and protects this data, and what happens to the data when your relationship ends.  
• We reserve the option to disable this feature if use of it negatively affects server or site performance.
• Long running reports will be long running API calls. If a report is timing out when you run it as a user, it will likely timeout when you call it via API. The program you are using to make the API call may have a default timeout that is shorter than the LS one. 
• Reports API calls support API access tokens (as of 2022-10-07). 

User Setup

If your site does not already have an API user and user role:

Create a new user role, suggested name "API" or "API Role for Outside Contractor", etc.:

• Give this role the "Reports - API Access" and "Login" permissions.
• Depending on what you plan to retrieve and other settings, this role may need permissions like "View All Cases" and "View Other Users Time".

Create a new user:

• Suggested username "api_user" and name "API User", or "api_user_contractor", etc.
• Set Login Active to Yes, Current to No, and Contact Active to No.
• Select the user role created above.
• Select an Office and a Program (any value)
• Enter an email address (a single @ character is fine)
• All other fields can be any choice or left blank if not required.
• Set a strong password, and do not require it be changed on next login.
• If your site expires passwords, this user's password will need to be periodically reset as well.

Authentication

Reports API calls have historically used basic authentication using a username and password of a user. The Reports API also accepts the use of Bearer Tokens. 

Individual Report Setup

• Edit the report and click "API/XML/XSL/Template" in the Additional Display Formats section.
• Expand the new "API/XML/XSL/Template Settings" section and check "Allow remote retrieval of results via API" in the API Output box:

Not shown above is the URL for the report that includes the generated API Key. Also not shown is the "Regenerate API Key" button to change the key if you need to block access to the report via the original key.

If you want a JSON output instead of an XML output, change the "Data Source, Document Source" dropdown to "Report Output JSON - JSON output of only the data shown in the report". This is not a perfect JSON example -- true false values are rendered as "t" or "f" instead of using True and False. There is a ticket open to fix that. 

Click the "Apply XML Settings" button in the new section, then "Save Changes" at the top of the report.

WARNING: If you are Restricting Access to LegalServer by IP Address, turn on the "Allow Restricting Individual Reports from Being Accessed from External IPs" in Site Settings, and then enable the "Disallow Access from External IP Range" option on the Report, the IP filters will also apply to the Reports API call.  

Manual Testing

Paste the URL shown in the API Output on a report into a browser. Enter the credentials. Review the results.

We recommended pasting the URL into a private/incognito window, which should avoid logging yourself out.

Or call the URL from outside LegalServer with curl, for example:

curl -u 'api_user:password' 'https://yoursiteabbreviation.legalserver.org/modules/report/api_export.php?load=101&api_key=V3ryL0ngG3n3r4aTedK3Y'

With appropriate substitutions for the API user login name, password, repot ID, and API Key from that report.

Filter Overrides in API Calls

The filter overrides feature may see format changes as we add complexity. We do not expect to make breaking changes, but you have been warned. Updates will be noted in our weekly release notes.

You can adjust your API calls to apply different filter values than the underlying report.

Edit the XML Output box on a report and observe the checkbox "Allow API Calls to Override Filters".

In this example, the report has filters on 7 fields, including a filters on Last Name and Number of People Helped (18 and Over):

Note the API URL shown. It tells you how you could change your API call to filter instead on the last name Smith and number helped 5, without needing to change the filters on the underlying report.

Note as well that not all field types are currently supported.

There is a query parameter "display_hidden_columns" that defaults to true (existing behavior). If you set this as false, the report will filter out any hidden columns in the report as returned in the API call.  This query parameter can also be controlled in the UI so that the report creator can determine the behavior of hidden fields.

Reporting on Reports API

There is a new Report API Loads example report that summarizes all recent Report API calls and who has used them.

Errors

Reports API calls timeout after 30 seconds. If you are seeking a large dataset, try adjusting your filters.

If the server is experiencing High Processor Load from all of the existing UI use, that can cause the Reports API to return an error indicating High Processor Load currently exists.

Notes and Known Issues

Using the Age in Days formatting option on a date column does not work with the API (Ref: LS-116160)