Timesheet APIs - migration guide - 01/01/2020

Introduction

One of your scripts uses an API token that grants access to either the /api/v3/timeentries or the /timmi/services/reporting/... API. 

From January, 1st 2021, the time-entries API will enforce paging and thus will never return more than 1 000 results per request.

From the same date, the reporting APIs will be switched off. You are expected to use the new reporting APIs that are already released as well as documented.

If you have a script that uses one of these two APIs, please update it. The following guide will help you achieve that.

Paging time-entries

How to control paging?

Paging is controlled through the paging query parameter.

This parameter takes two arguments separated with a coma ",":

  • offset: the index of the first item to retrieve in the collection. The first item has a 0 (zero) index.
  • limit: the total number of items to retrieve from the starting index. Value cannot be greater than 1000.

For instance, to retrieve 25 time-entries from the 12th one :

GET /api/v3/timeentries?fields=id&paging=12,25 HTTP/1.1

You may want to sort items when requesting pages. This can be achieved through the orderBy query parameter that also takes two arguments separated by a coma ",":

  • fieldName: the name of the property on which items should be sorted.
  • direction: either asc (ascending) or desc (descending)

For instance, to sort time-entries on ascending start date-time:

GET /api/v3/timeentries?fields=id&orderby=startsAt,asc HTTP/1.1

How to get the total items count?

The total items count can be retrieved through the collection.count field. You can then know how many pages you must request.

GET /api/v3/timeentries?ownerId=12&fields=id,collection.count HTTP/1.1
Response:
{
"data": {
"count": 2
"items": [{"id":1},{"id":2}]
}
}

How to retrieve more than 1000 items?

Retrieve the first 1000 items and retrieve the collection count.

If the collection count is greater than 1000, then you need to retrieve more pages where the offset is equal to (pageCount+1)*1000.

 

Using the new reporting APIs

The new reporting feature supports custom report templates. These templates are no longer already existing, and you have to first create them.

In brief, you will thus have to:

  • Create your custom report-template POST /timmi-timesheet/api/report-templates
  • Use it as the template for your report POST /timmi-timesheet/api/reports

These APIs are documented here.

Creating a new report template

First, choose a report-blueprint. Each report-blueprint corresponds to a coherent set of resources:

  •  Times: work duration, time off, overtime, etc...
  • Activities: time spent on each task
  • Accounts: pay items accounted for.
  • Warnings: warnings triggered on timesheets.
  • Timesheets
  • Comments

Report-blueprints dictate the available columns, or data fields for your report-template.

To create a report-template that matches the old "standard report":

POST /timmi-timesheet/api/report-templates HTTP/1.1
Authorization: lucca application={token}
Content: application/json
Accept: application/json

{
"name": "My awesome standard report",
"blueprintId": "times",
"periodicity": "none",
"defaultPeriod": "lastMonth",
"columns": [
{"kind": "ownerName"},
{"kind": "ownerDepartment"},
{"kind": "ownerEmployeeNumber"},
{"kind": "ownerLegalEntity"},
{"kind": "theoreticalWorkingTime"},
{"kind": "attendanceTime"},
{"kind": "leavesDuration"},
{"kind": "overUnderTime"},
{"kind": "breaksDuration"},
{"kind": "actualTimeLeavesDuration"}
],
"filters": [],
"total": {"kind": "none"},
"onlyShowTotals": false,
"isPublic": false,
"establishments": [],
"collaborators": []
}

The server response will give you the actual id of your new report-template, which you will need to create a report from said template.

Creating a new report from a report-template

You will need:

  • the report-template id, "12" in this example
  • the start date of your report, "2020-09-01" in this example
  • the end date of your report (included), "2020-09-30" in this example

You can then send the following request:

POST /timmi-timesheet/api/reports HTTP/1.1
Authorization: lucca application={token}
Content: application/json
Accept: application/json

{
"templateId":"12",
"startsOn":"2020-09-01",
"endsOn":"2020-09-30"
}

The server sends a response immediately, but your report data will only be ready when the report status is "done". You can send periodic GET requests on the report to retrieve its status.

Once the server has finished processing the report (its status is then "done"), you can retrieve the data through the /timmi-timesheet/api/reports/{reportId}/header-rows (to retrieve columns names) and /timmi-timesheet/api/reports/{reportId}/body-rows (to retrieve the actual data) APIs.

The body-rows API enforces paging through both take and offset query parameters:

GET /timmi-timesheet/api/reports/{reportId}/body-rows?offset={pageStartIndex}&take={pageLength} HTTP/1.1
Authorization: lucca application={token}
Content: application/json
Accept: application/json

Page content

Was this article helpful?
0 out of 0 found this helpful