Using ad hoc reports from 3rd party tooling via API tab

Overview

Ad hoc reports provide a great mechanism for users to write their own reports in OneAegis. Through ad hoc reports users can configure the columns (fields) and selection criteria and even schedule reports to run on a regular basis and deliver results via email. (Information on developing ad hoc reports can be found in other KB articles.)

However, in cases where you want to ingest data into another system on a regular basis manually running a report is not ideal, and even an email sent on a regular basis requires the ingesting system have a way to receive and parse emails, still not ideal. Enter the API tab on ad hoc reports.

Setting up the report for API use

Any ad hoc report is a candidate for API use. However, you must take some additional steps to setup security so we know who can run ad hoc reports via the API and what permissions they'll have.

Ad hoc reports are run by a user and that user needs to be a member of several groups to access the report. First, to access any ad hoc report via an API the authenticating user must be a member of the api-access-ExcelWebData group. Additionally, they must be a member of a report-specific group, or a member of api-access-ExcelWebData-*All if you want to allow them access to all ad hoc reports. To allow the user access to specific reports add them to the api-access-ExcelWebData-xxx report where xxx is the name of the ad hoc report. 

For those using SSO to login to OneAegis you need to also know the "native" password (not the SSO password) for the user to access the API. 

We will honor the permissions (or lack thereof) of the user requesting the report through the API when determining what data is visible. However, it is possible to provide a "Run As" user on the ad hoc report in which case we will adopt that user's permissions when running the report. Running a report as another user is part of the definition of the ad hoc report, it's not a choice that can be made when you request the ad hoc report. 

Calling the API

The API is a simple one, a GET request to the report's API URL will return the report in Excel (xlsx) format. Authentication is provided using Basic auth with the username in ClientID\Username format.

The report's API endpoint is available in the ad hoc report's API tab, but it will be in the following format: https://<clienturl>/api/ewd/<guid>/<name> where clienturl is the web address for your instance of OneAegis, guid is a report-specific identifier, and name is the name of the report. The name actually is an optional piece and does not need to match the report name in OneAegis, it's the guid that matters, name is there for human consumption to help you remember what report this represents, feel free to tweak/change/omit the name if it helps.

For example, you could issue the following Curl command to download an ad hoc report:

curl https://<clienturl>/api/ewd/b551cadb-5e6a-40c0-b207-e9e7ce35ab60/ReportName --user ClientId\\username:password --output report.xlsx

For more specific instructions on how to link an ad hoc report with Excel via the API see Ad-Hoc Reports: API - linking a report to Excel