Motimate: 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}

Prior to generating a report with the Public API, make sure that a report template has already been generated in Generate Reports (see guide here), 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.