Fetching raw statistics data via the API
This function is in beta and may change. Documentation may sometimes lag behind any changes.
As well as a mechanism to return aggregated reports, an API call can also be used to retrieve raw data. This gives a flat report in CSV format you can use in analysis tools such as Tableau, Power BI and others.
Prerequisites
The optional reports API functionality to be enabled for your organisation - your account manager will be happy to discuss pricing with you
An API key from each organisation and sub-organisation you will be querying
The key will need either the reports API permission (recommended) or the full access permission.
Request
As with the other reports, this is a two step operation.
Perform a GET request to the following URL:
https://reports.openathens.net/api/v1/example.org/rawreport?date=<date>
Where example.org
is your OpenAthens API name and date
is the requested date (format yyyy-MM-dd
between yesterday and 30 days ago)
Response payload
The response will be an application/vnd.eduserv.iam.reports.task-v1+json
object.
If the job completes in under 5 seconds, it will have a status of FINISHED and a href to the report - see downloading below.
If the job is still running after 5 seconds, it will return a status of RUNNING and a href back to the task status.
Your application will need to allow for both types of response. 20s is a reasonable wait time to code if you get a running response.
Example - still running
GET https://reports.openathens.net/api/v1/example.org/rawreport?date=2023-05-22
Authorization: OAApiKey <api-key>
Response: HTTP/1/1 200 OK
Content-Type: application/vnd.eduserv.iam.reports.task-v1+json
{
"percentComplete": 40,
"status": "RUNNING",
"links": [
{
"href": "https://reports.openathens.net/api/v1/example.org/rawtask/a11b5fff-6170-38e3-b4bb-560bee3e6985",
"rel": "SELF",
"type": "application/vnd.eduserv.iam.reports.task-v1+json",
"method": "get"
}
],
"id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}
Example - finished
GET https://reports.openathens.net/api/v1/example.org/rawtask/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/rawreport/a11b5fff-6170-38e3-b4bb-560bee3e6985",
"rel": "DOWN",
"type": "application/vnd.eduserv.iam.reports.report-v1+json",
"method": "get"
}
],
"id": "a11b5fff-6170-38e3-b4bb-560bee3e6985"
}
Downloading the linked report
Depending on your method you may optionally add a filename parameter to the download URL, e.g. https://reports.openathens.net/api/v1/athens/rawreport/a11b5fff-6170-38e3-b4bb-560bee3e6985?filename=rawstats_2023-06-20.csv
.
Report format
The reports can be very large, so they’re downloaded as a zipped CSV file (MIME types application/gzip and text/csv). Not all fields will have data for all actions:
Heading | Comment |
---|---|
date | UTC Timestamp e.g. |
action | What happened (see next table) |
status | The status of the action e.g. |
account.authsystemname | Local connector name e.g. |
account.authsystemid | Local connector ID e.g. |
account.permissionsets | Permission set names connected to the user e.g. |
account.organisation | The parent organisation of the account e.g. |
account.accountid | The ID of the account e.g. |
account.type | e.g. |
account.status | The status of the account e.g. |
account.expiry | OpenAthens account expiry date e.g. |
location.isp | The user's ISP (where identifiable) e.g. |
request.countrycode | The ISO country code of the user's location e.g. |
request.useragent | The user agent string from the user’s browser e.g. |
request.ipaddress | The IP address the user was at e.g. |
attribute.resourceid | The entityID of the resource e.g. |
attribute.federationctx | A federation identifier e.g. Custom SAML resources appear as your own OpenAthens API name |
attribute.resourcetitle | The resource title (at the time) e.g. |
Plus all fields marked as reportable in your Schema editor as attribute.attributename … |
Actions
Action | Comment |
---|---|
AUTHENTICATE | An OpenAthens account has authenticated |
LOCAL_AUTHENTICATE | A local account has authenticated |
FEDERATED_TRANSFER | An OpenAthens accounts has been sent to a resource |
LOCAL_FEDERATED_TRANSFER | A local account has been sent to a resource |
Anything to watch out for?
Changes to the reportable state of attributes in your schema will only affect items recorded after the change is saved.
The report will only cover the organisation where the API key sits, so if you have sub-organisations you will need an API key from each.
All times and dates are UTC.
Location data
This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com