How to Generate Reports using Public API

In addition to sharing course completion data via Motimate xAPI,  we also support extraction of Excel-files from Motimate Public API. These Excel-reports are based upon Report templates that have previously been created in the Generate Reports feature under Insights in Motimate.

Here is some useful information before we get started:

The three relevant Motimate Public API functions are:

• GET /insights/learnings/report_templates
• POST /insights/learnings/report_requests
• GET /insights/learnings/report_requests/{id}

Technical Documentation: Motimate Public API

Prior to generating a report with the Public API, make sure that a report template has already been generated in Generate Reports, and you know from which template(s) you will be generating report(s). Provided this is ready, the process with generating a report will require three steps:

Step 1: Get a list of report templates:

Command: GET /insights/learnings/report_templates

Example Response:

{
  "data": [
    {
      **"id": "abc86b82-029a-4b74-9690-4ab607f3eafe"**,
      "name": "Report Test",
      "description": "Testing for Public API purpose",
      "last_status": "uploading",
      "last_generated_at": null,
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-01T15:41:26.98349+01:00",
      "user": {
        "name": "John Doe"
      }
    }
  ]
}

Make note of the template id which you will need to use in the next step, in this case: abc86b82-029a-4b74-9690-4ab607f3eafe

Step 2: Generate a new report based selected template

Command: POST /insights/learnings/report_requests

In this example, make sure to submit abc86b82-029a-4b74-9690-4ab607f3eafe as template_id in this request.

Example Response:

{
  "data": {
    **"id": "abc23922-940d-4d6d-a6f0-ecaed00810c4"**,
    "status": "started",
    "created_at": "2022-03-03T08:48:46.051Z",
    "updated_at": "2022-03-03T08:48:46.051Z",
    "url": null,
    "template": {
      "id": "abc86b82-029a-4b74-9690-4ab607f3eafe",
      "name": "Report Test",
      "description": "Testing for Public API purpose",
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.06885+01:00"
    }
  }
}

Please note that a value for url is not yet available. Depending on how much data goes into the report, it may take several minutes to generate a report. You’ll be requesting the url of your report in the next step.

Step 3: Get URL of Excel report file

Command: GET /insights/learnings/report_requests/{id}

Make sure to use the id for data in the response from step 2, and not the id for template!

Example Response:

{
  "data": {
    "id": "abc23922-940d-4d6d-a6f0-ecaed00810c4",
    "status": "done",
    "created_at": "2022-03-03T08:48:46.051Z",
    "updated_at": "2022-03-03T08:48:46.839Z",
    **"url": "<https://motimate-reports-production.s3.eu-west-1.amazonaws.com/abc883af5017bcb49a6b99e71b01a0660b8f5204/report-test_1646297326.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABCAYLEQ6WVKO52OZP5X%2F20220303%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220303T085426Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc3806250e855b83fc121ea181764cc6df64481c63371004a27229acbaf98de>"**,
    "template": {
      "id": "abc86b82-029a-4b74-9690-4ab607f3eafe",
      "name": "Report Test",
      "description": "Testing for Public API purpose",
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.70689+01:00"
    }
  }
}

You may need to run this request on a recurring basis every 30 seconds until you get a response which include a value for url. How long this take depends on how much data is required to generate the report.

In this example the url is https://motimate-reports-production.s3.eu-west-1.amazonaws.com/abc883af5017bcb49a6b99e71b01a0660b8f5204/report-test_1646297326.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABCAYLEQ6WVKO52OZP5X%2F20220303%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220303T085426Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc3806250e855b83fc121ea181764cc6df64481c63371004a27229acbaf98de

Accessing this URL will download your reports in a .xlxs Excel file. It is currently not possible to extract the data in any other file formats, such as for instance .csv.

Please note: The file will expire after 10 minutes, and must be downloaded before that.

ℹ️ If a report template has been created by a Group Admin, who only has limited access to data on selected Groups and Users, this restriction will still be inn effect when using Motimate Public API.