Search

Skip to end of metadata
Go to start of metadata

The API provides a mechanism to query the reporting data. This gives a flat report in CSV format you can use in other analysis tools such as Tableau, Power BI and others.

Prerequisites

  • The reports API functionality to be enabled for your organisaiton - contact your account manager about this
  • An API Key from the domain organisation or sub-organisation the reports will cover
  • A basic practical knowledge of APIs and coding

Procedure

Perform a GET request to the following URL:

https://reports.openathens.net/api/v1/example.org/report?type=<type>&from=<from>&to=<to>&by=<by>[&resource=<resource>][&scope=<scope>][&andBy=<andBy>][&granularity=<granularity>]

Where example.org is your OpenAthens API name and:

ParameterRequiredAccepted valuesDefault if omitted
typeY
  • RESOURCE_USAGE

(other report types will be added in the future)


fromY
  • YYYY-MM
  • YYYY-MM-dd
  • YYYY-MM-ddTHH:mm
YYYY-MM (default if no granularity is set)
toY
  • YYYY-MM
  • YYYY-MM-dd
  • YYYY-MM-ddTHH:mm
YYYY-MM (default if no granularity is set)
byY
  • RESOURCE
  • GROUPS
  • ATTRIBUTE:<reportable attribute's target name>
  • PERMISSION_SETS

resourceN

Specify a single resource by entityID

Can not be used with &by=RESOURCE

All resources
scopeN
  • THIS_ORGANISATION
  • ALL_ORGANISATIONS

All includes all the sub-organisations below the authenticated user

The organisation of the authenticated user
andByN
  • GROUPS
  • ATTRIBUTE:<reportable attribute's target name>
  • PERMISSION_SETS

Optional. Can only be used with &by=RESOURCE


granularityN
  • HOURLY
  • DAILY
  • MONTHLY

If Hourly: 'from' and 'to' date format should be YYYY-MM-ddTHH:mm

If Daily: 'from' and 'to' date format should be YYYY-MM-dd

If Monthly: 'from' and 'to' date format should be YYYY-MM

  • MONTHLY

Response codes

HTTP Response Code

Description

200

The request was successful

204No data
400Bad request - e.g. date out of range

401

The requester does not have permission to perform this operation

404Not found

Response payload

Since reports can take some time to run, the response is an application/vnd.eduserv.iam.reports.task-v1+json object containing a href to the task status. Your application will need to monitor this until the task completes (20s is a reasonable wait time to code).

Once the task is complete, the object will have a status of FINISHED and a percentComplete of 100, and a link to the report.  

Example

Request:
GET https://reports.openathens.net/api/v1/example.org/report?type=RESOURCE_USAGE&from=2020-01&to=2020-01&by=RESOURCE&scope=ALL_ORGANISATIONS
Authorization: OAApiKey <api-key>
Response:
HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json

{
    "percentComplete": 0,
    "status": "RUNNING",
    "links": [
        {
            "href": "https://reports.openathens.net/api/v1/example.org/task/a11b5fff-6170-38e3-b4bb-560bee3e6985",
            "rel": "SELF",
            "type": "application/vnd.eduserv.iam.reports.task-v1+json",
            "method": "get"
        }
    ],
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}

When finished the response will have updated to include a link to the report

Request:
GET https://reports.openathens.net/api/v1/example.org/task/a11b5fff-6170-38e3-b4bb-560bee3e6985
Authorization: OAApiKey <api-key>
Response:
HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json

{
    "percentComplete": 100,
    "status": "FINISHED",
    "links": [
        {
            "href": "https://reports.openathens.net/api/v1/athens/report/a11b5fff-6170-38e3-b4bb-560bee3e6985",
            "rel": "DOWN",
            "type": "application/vnd.eduserv.iam.reports.report-v1+json",
            "method": "get"
        }
    ],
    "id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}

Report format

The downloaded report will be a CSV file with the headings:

Domain,Organisation number,Organisation name,Date,<by>,[<andyby>,]Count

where:

  • Domain is your API name (as per the request). This will be constant for the report
  • Organisation number is the numeric identifier of the organisation (or sub-organisations where scope=ALL_ORGANISATIONS in the request). See below if you have more than one in the report.
  • Date is the month as YYYY-MM
  • <by> will be replaced by RESOURCE, GROUPS, PERMISSION_SETS, or ATTRIBUTE:<targetname> as per the request
  • <andBy> (where present) will similarly be replaced by the secondary breakdown identifier
  • Count will be the number of transfers

 Organisation numbers

All organisations and sub-organisations have a numeric identifier in the system whether or not they are marked as having a unique identifier - it's just not easy to see those identifiers in the interface for the ones who don't have the unique setting (most don't need it, and turning it on can affect access to content).

This numeric identifier is persistent and will allow you to link stats from the same sub-organisations even if their name changes.  

Notes

Reports have a monthly granularity

Reports are type: text/csv

You can specify <from> dates up to 12 months ago - for example if you are sending the API call in January 2020 (UTC), you can specify a <from> date as far back as 1 January 2019



  • No labels