How to Download Reports

​

Introduction

This guide is aimed at helping you generate Timesheet reports directly through API requests.

​

Prerequisites

You will need:

• (required) Your domain name {yourDomain}, eg: “https://myawesomecompany.ilucca.net”.
• (required) An API key {apiKey} that has report generation rights.

​

Guide

A report can only be generated from an existing report-template, referenced by its unique identifier templateId, for which your API key must have access to.

If an existing report-template is publicly available, you can generate a report from it.

But in most cases, you will need to create a dedicated report-template for your API key.

​

1. Create a report-template

As the resource is not yet documented, the easiest way is to create a new report-template through Timmi Timesheet user interface, then copy-paste the generated payload to make your POST request /report-templates with your API key.

For example :

POST /timmi-timesheet/api/report-templates HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: application/json

{
  "id": 0,
  "blueprintId": "times",
  "name": "Rapport sur les temps",
  "columns": [
    {
      "kind": "ownerName",
      "name": "Nom complet",
      "description": "",
      "category": "owner",
      "isRequired": true,
      "isPeriodic": false,
      "isDefault": true
    },
    {
      "kind": "ownerDepartment",
      "name": "Département",
      "description": "",
      "category": "owner",
      "isRequired": false,
      "isPeriodic": false,
      "isDefault": true
    },
    {
      "kind": "attendanceTime",
      "name": "Temps de travail",
      "description": "",
      "category": "time",
      "isRequired": true,
      "isPeriodic": true,
      "isDefault": true
    },
    {
      "kind": "leavesDuration",
      "name": "Absences",
      "description": "",
      "category": "time",
      "isRequired": false,
      "isPeriodic": true,
      "isDefault": true
    },
    {
      "kind": "theoreticalWorkingTime",
      "name": "Temps théorique",
      "description": "",
      "category": "time",
      "isRequired": false,
      "isPeriodic": true,
      "isDefault": true
    },
    {
      "kind": "overUnderTime",
      "name": "Écart",
      "description": "",
      "category": "time",
      "isRequired": false,
      "isPeriodic": true,
      "isDefault": true
    }
  ],
  "periodicity": "quarterly",
  "defaultPeriod": "thisYear",
  "total": {
    "kind": "manager",
    "name": "Par manager"
  },
  "onlyShowTotals": false,
  "isPublic": false,
  "collaborators": [],
  "filters": [
    {
      "kind": "ownerLegalEntityId",
      "name": "Établissements",
      "category": "owner",
      "values": [
        1
      ]
    },
    {
      "kind": "timesheetStatuteId",
      "name": "Réglementaires",
      "category": "timesheet",
      "values": [
        4,
        16
      ]
    }
  ]
}

The created report-template {id} will be answered in reponse.

​

2. Generate a new report from this report-template

You can now generate a report through /timmi-timesheet/api/reports with :

• The report-template {id} you just created.
• The start date of the report to generate {reportStartDate}. If left null, default date from the report-template is applied.
• The end date of the report to generate {reportEndDate}. If left null, default date from the report-template is applied.

These will be used as parameters in the following request:

POST /timmi-timesheet/api/reports HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Content-Type: application/json

{
  "templateId": {templateId},
  "startsOn": {reportStartDate},
  "endsOn": {reportEndDate}
}

Which response should look like:

{
  "id": 1,
  "status": "pending",
  ...
}

This response contains, among other things:

• the identifier (integer) id of the created report, to be kept carefully as the {reportId}
• the status (string) status of the generation of its content, which is an enum:

ReportStatus:
  type: string
  enum:
    - "pending"
    - "done"
    - "error"

​

Background process

The generation of a report content is a background process. As long as this process is not complete, the report status stays pending. Once the report is complete, its status is set to done. May an error be encountered while generating its content, then its status is set to error.

The report content can only be viewed and downloaded once it is done. The generation of the report is an asynchronous process. In practice, when the POST request is received, the server immediately responds with a 200 OK if successful, otherwise an error code is displayed.

​

3. Track report background building progress

The next request should be repeated at regular intervals (say, every 10 seconds) until the response indicates a done status (rather than pending).

If request is met with an error, the status error will be returned. In this case, it will be necessary to try creating a new report and if the error occurs again, please contact our support.

Here, {reportId} should be equal to the identifier of report recovered in response to the previous POST:

GET /timmi-timesheet/api/reports/{reportId} HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Response:
{
  ...,
  "status": "done"
}

​

4. Download the finalized report data

Once the content of the report is generated (status done), it can be downloaded in a CSV file:

GET /timmi-timesheet/api/reports/{reportId}/download-csv HTTP/1.1

Or in Excel format:

GET /timmi-timesheet/api/reports/{reportId}/download-excel HTTP/1.1

Reports expire after 24h, and will be deleted as soon as another report from any report-template is generated.