Changements des APIs Timmi Temps (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 Temps 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

Si vous souhaitez générer des rapports de manière programmatique, ce guide est fait pour vous.

La première étape est de créer un modèle de rapport, qui est l'objet qui va dicter la structure et le contenu des rapports qui seront ensuite générés à partir de lui.

Le plus simple, pour cela, est de :

1. Créer manuellement le modèle de rapport qui vous convient depuis l'interface avec votre propre compte.

2. Une fois satisfait, en copier le paramétrage, et en créer un nouveau via l'API en s'authentifiant cette fois avec la clé d'API.

Récupérer l'identifiant du modèle créé à la main

Rendez-vous sur cette URL (remplacer {yourDomain} par le nom de votre propre domaine) :

https://{yourDomain}.ilucca.net/timmi-timesheet/api/report-templates

Notez la valeur de la propriété "id" du modèle qui vous intéresse.

Une fois l'identifiant ainsi récupéré, rendez-vous sur cette URL afin de récupérer tout le paramétrage du modèle en question (remplacer {templateId} par l'identifiant en question) :

https://{yourDomain}.ilucca.net/timmi-timesheet/api/report-templates/{templateId}

Copiez l'intégralité du JSON de la réponse du serveur.

Créer un nouveau modèle via la clé d'API

Forgez enfin une nouvelle requête HTTP de la manière suivante ({apiKey} correspond à la valeur de la clé d'API qui sera utilisée par le script appelé à générer des rapports à partir de ce modèle) :

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

Payload:
{copiedTemplateJSON}

Response:
{
  "id": 45,
  ...
}

Notez l'identifiant du modèle ainsi créé. Vous pouvez à présent supprimer le modèle que vous aviez créé manuellement au travers de l'interface.

Afin de générer des rapports à partir de ce modèle créé via la clé d'API, un guide a été rédigé ici : https://lucca.readme.io/docs/create-and-download-a-new-report

Le {templateId} évoqué par le guide correspond à l'identifiant du modèle que vous aurez créé en forgeant la requête POST au-dessus.