Motimate: Rapporten genereren met openbare API

Naast het delen van gegevens over cursusvoltooiing via Motimate xAPIondersteunen we ook het extraheren van Excel-bestanden uit Motimate Public API. Deze Excel-rapporten zijn gebaseerd op rapportsjablonen die eerder zijn gemaakt in het menu Rapporten genereren onder Insights in Motimate.

Hier is wat nuttige informatie voordat we beginnen:

De drie relevante Motimate Public API-functies zijn:

• GET /inzichten/leren/rapport_templates
   
• POST /insights/learnings/rapport_requests
   
• GET /inzichten/leren/rapport_aanvragen/{id}

Voordat je een rapport genereert met de Openbare API, moet je ervoor zorgen dat er al een rapportsjabloon is gegenereerd in Rapporten genereren(zie handleiding hier) en dat je weet van welk(e) sjabloon(s) je rapport(en) gaat genereren. Als dit klaar is, vereist het genereren van een rapport drie stappen:

Stap 1: Verkrijg een lijst met rapportsjablonen:

Opdracht: GET /insights/learnings/report_templates

Voorbeeld 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"
      }
    }
  ]
}

Noteer de sjabloon-id die u in de volgende stap moet gebruiken, in dit geval: abc86b82-029a-4b74-9690-4ab607f3eafe

Stap 2: Genereer een nieuw rapport op basis van de geselecteerde sjabloon

Opdracht: POST /insights/learnings/report_requests

Zorg er in dit voorbeeld voor dat u abc86b82-029a-4b74-9690-4ab607f3eafe als template_id opgeeft in dit verzoek.

Voorbeeld 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": "Testen voor openbaar API-doel",
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.06885+01:00"
    }
  }
}

Let op: een waarde voor url is nog niet beschikbaar. Afhankelijk van de hoeveelheid gegevens in het rapport, kan het enkele minuten duren om een rapport te genereren. In de volgende stap vraag je de url van je rapport op.

Stap 3: URL ophalen van Excel-rapportbestand

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

Zorg ervoor dat u de id voor gegevens gebruikt in het antwoord van stap 2, en niet de id voor sjabloon!

Voorbeeld 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": "Testen voor openbaar API-doel",
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.70689+01:00"
    }
  }
}

Mogelijk moet je dit verzoek elke 30 seconden opnieuw uitvoeren totdat je een antwoord krijgt met een waarde voor url. Hoe lang dit duurt, hangt af van hoeveel gegevens nodig zijn om het rapport te genereren.

In dit voorbeeld is de 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

Als je deze URL opent, worden je rapporten gedownload in een .xlxs Excel-bestand. Het is momenteel niet mogelijk om de gegevens in andere bestandsformaten te extraheren, zoals bijvoorbeeld .csv.

Let op: Het bestand verloopt na 10 minuten en moet voor die tijd worden gedownload.

ℹ️ Als een rapportsjabloon is gemaakt door een Groepsbeheerder, die slechts beperkte toegang heeft tot gegevens over geselecteerde Groepen en Gebruikers, blijft deze beperking van kracht bij gebruik van Motimate Public API.