Changements des APIs Timmi Timesheet (01/01/2021) - Guide de migration

Avant de commencer

Vous disposez aujourd’hui d’une clé d’API qui dispose d’un accès aux temps saisis dans Timmi Timesheet ou à l’ancien module de reporting.

À partir du 1er janvier 2021, l’API /api/v3/timeentries permettant de récupérer les temps saisis paginera dorénavant les résultats et ne retournera jamais plus de 1 000 éléments en une seule requête.

À partir de la même date, l’API /timmi/services/reporting permettant de récupérer les données des anciens rapports ne sera plus supportée. Les nouvelles APIs de reporting ici documentées et déjà disponibles prendront le relais.

Si jamais vous avez des scripts qui consomment une de ces APIs, nous vous recommandons de les adapter afin de prendre cette nouvelle contrainte en compte. Pour vous faciliter le travail, vous trouverez ci-dessous un guide de migration.

Gérer la pagination des Time-Entries

Comment paginer un appel à l'API ?

La pagination sur cette API passe par le paramètre de query paging qui prend deux arguments offset et limit séparés par une virgule :

  • offset : l'index du premier élément à retourner, le premier élément a l'index zéro.
  • limit : le nombre d'éléments à retourner (maximum : 1000).

Par exemple, pour récupérer 50 éléments à partir du vingt-sixième (inclu) :

GET /api/v3/timeentries?paging=25,50 HTTP/1.1

Il est recommandé de passer également par un ordonnancement des éléments via le paramètre de query orderby qui prend lui aussi deux arguments :

  • fieldName : le nom de la propriété sur laquelle ordonner les éléments (attention, toutes les propriétés ne sont pas forcément ordonnançables) ;
  • sortDirection : asc pour un ordre croissant, et desc pour un ordre décroissant

Par exemple, pour récupérer les cinquante time-entries les plus récentes de l'utilisateur d'identifiant 16 :

GET /api/v3/timeentries?orderby=startsAt,desc&paging=0,50&fields=id,startsat,collection.count HTTP/1.1

Comment savoir combien d'éléments satisfont votre query ?

Vous pouvez récupérer le nombre total d'éléments satisfaisant la query via le field collection.count.

Par exemple, en récupérant les deux premières time-entries de l'utilisateur d'identifiant 16 :

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

 On peut dès lors constater que l'utilisateur a déjà créé 15 000 time-entries.

Comment récupérer plus de 1 000 éléments ?

Afin de récupérer plus de 1 000 éléments, il vous faudra dorénavant passer plusieurs requêtes, éventuellement en parallèle. En règle générale, vous pouvez :

  1. passer une première requête en demandant le field collection.count ;
  2. constater si le nombre d'éléments retourné est inférieur au collection.count, auquel cas il manque des éléments ;
  3. passer des requêtes subséquentes pour récupérer les suivantes.

 

Utiliser les nouvelles APIs de reporting

Contrairement aux anciennes APIs de reporting, il n'existe plus de modèles de rapport déjà créés.

Vous aurez donc à :

  1. Créer le modèle de votre choix via l'API des /timmi-timesheet/api/report-templates qui vous permet entre autres de définir les colonnes du rapport et leur agencement.
  2. Générer ensuite des rapports à partir de ce modèle via l'API /timmi-timesheet/api/reports.

La référence complète des APIs est disponible ici

 

Créer un modèle de rapport

Timmi Timesheet manipule un grand nombre d'objets. La première étape de la création d'un modèle de rapport est donc de choisir le type des objets sur lesquels vous voulez générer un rapport. Les différents objets disponibles correspondent aux ReportBlueprints exposés sur l'API /timmi-timesheet/api/report-blueprints/{blueprintId}.

 

Par exemple, pour créer l'équivalent du rapport standard de l'ancien module de reporting :

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

{
"name": "Rapport standard",
"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": []
}

Vous obtiendrez en réponse le ReportTemplate ainsi créé, et plus particulièrement son Id, dont vous aurez besoin pour générer un rapport.

 

Générer un rapport

Une fois munis de l'Id du ReportTemplate que vous voulez utiliser pour générer votre rapport entre deux dates, il vous suffira d'émettre la requête HTTP suivante :

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

{
"templateId":"{reportTemplateId}",
"startsOn":"{startDate}",
"endsOn":"{endDate}"
}

Tant que le rapport est en cours de calcul, le status du Report ainsi créé renvoyé par le serveur sera égal à pending. Une fois terminé, le statut passera à done. Dès lors, les données du Report peuvent être récupérées par la requête suivante :

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

Cette requête est paginée et prend donc deux paramètres de query :

  • offset : l'index de la première ligne du tableau à récupérer (par défaut : 0)
  • take : le nombre de lignes à retourner (maximum : 1000)

Contenu de la page

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 0 sur 0