Home‎ > ‎Reports‎ > ‎

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.

Required Ticket Language: 
File a ticket from your site. Put "Enable Reports API" in the Short Description of Issue field. The Description box must contain "I have read the Cautions on the Reports API help page and understand the security and other concerns of using this feature."  

We can usually enable the feature on your demo site within 2 weeks of you filing the ticket, with your live site getting it the week after it hits your demo site.


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.

User Setup

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

Create a new user role, suggested name "API":
 * 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"
 * 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.

Individual Report Setup

* Edit the report and click "XML/XSL/Template" in the Additional Display Formats section.

* Expand the new "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.

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

Manual Testing

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

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

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

Filter Overrides in API Calls

This feature is in beta testing and subject to change. We do not expect to make breaking changes, but you have been warned.

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 new 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 supported in this first iteration of the feature.