Improving access to Time Tracking data from the API
Description
We are customers of GitLab EES, in the process of migrating from Trac.
Here I am proposing a set of improvements over the current time tracking API. We believe those improvements are not only matching our use case, but could be used by others to have better integration of GitLab in their environment.
Our setup and workflow (i.e.: the problem)
Time tracking is central to our workflow, it is used to monitor our work time and overtime, calculate compensation, bill our clients, and more generally understand where we are spending our hours.
To do all that, we have an internal custom made CRM, that connect with Trac in two ways:
-
Via webhooks
- Anything posted in Trac that has a time field will trigger a webhook to our CMR, this generates an internal feed, and is used for statistics about our work time/overtime.
- Example of feed data: (the hidden part contains the ticket title, the project name, and the content of the comment made)
- Example of aggregated work time and overtime data from this feed:
- Via direct database access to Trac (which we want to remplace by clean API access from GitLab)
Proposal
There are three places where API improvement would be useful:
- webhook generated by objects adding or removing time should have a machine-readable field providing the value of the change
- the notes API should provide machine readable time
- Getting the list of issues, or the details of the issue, should also contain the estimated and spent time
Webhook proposal
Right now, when a slash command modifying the time spent is added to a note, two webhook are received, one of kind notes
, containing everything (i.e.: the note details, and the issue details), one of kind issues
containing the details of the issue only.
Both of them, only provided the new aggregated time value:
{
...
"total_time_spent": 72000,
"human_total_time_spent": "2d 4h",
...
}
But not the actual increment or decrement of time. We think this should be part of the notes
webhook, so that any tool listening to webhooks will receive the note payload, with the time tracking data added to it.
This could be represented as a new field in the webhook, like:
{
...
"time_change": -600,
...
}
Making the notes API more machine-friendly
Right now, the note API is returning time data only in a human readable way like so:
{
"id":1214,
"body":"added 1d of time spent",
"attachment":null,
"author":{...}
...
}
These forces any tools consuming the API to:
- Parse the body, assuming this sentence never change
- Convert the time into something more manipulable (i.e.: second most of the time)
To be more useful, the notes API could be returning slash command notes as a more structured data in addition to the human readable body.
For time tracking data it could be:
{
"id":1214,
"body":"added 1d of time spent",
"machine_readable_time_change": 3600
"attachment":null,
"author":{...}
...
}
This will allow easy, and robust processing of this API by scripts.
Time tracking data should be exposed sooner when getting issue
Right now to get the time tracking statistics you have to pinpoint specifics issue one by one. Time tracking data should be more first class and accessible in a GET /issues
command. (Same thing when getting a single issue)
This would allow to list/search issues, and getting at the same time the time tracking data. Which will be great for any report needs. Like getting all the issues tagged "bug", and aggregating the time spent on bugfixing.
If performance is the reason that this is not part of the current returned data, allowing to pass an option to enrich this would be quite fine I believe.
Finally
Thank you for reading this until here!