Skip to main content

​
Introduction

This guide is aimed at helping you edit TimeEntries through API requests. For example, if you have another ‘source’ system that handle working times (e.g. a planner, a clock-in clock-out physical device, another time-tracking software, …), you might want to send its data to Lucca Timesheet to automatically fill in timesheets either partially or entirely. On following timesheet modes, you will be able to tag TimeEntries as ‘imported’ to prevent edition from unauthorized users (requires ‘Edit times’ right) :
  • Attendance schedule with clock-in clock-out system ;
  • Activity schedule. If you need to set TimeEntries as read-only on other modes, please contact your account manager or your consultant to discuss options.
If you need to do it the other way around, i.e. extracting TimeEntries from Lucca Timesheet to import them in another system (reporting, ERP, …), please see this other guide.

​
Two Different Approaches

Depending on your needs, TimeEntries can be modified two different ways:
  1. Manual CRUD requests /api/v3/timeentries : if you have precise requirements regarding TimeEntries lifecycle (when a TimeEntry should be deleted, edit a very specific TimeEntry and not another ‘look-a-like’) to match an existing business logic. [recommended]
  2. Smart update service /timmi-timesheet/services/time-entries : if you only want to send “what Alexander given timesheet should look like”, without caring what might it already be
While the smart update service might look appealing, we strongly recommend you to follow the manual CRUD requests approach if you have the resources to. By building the TimeEntries integration logic between your two systems on your end with manual CRUD requests, you will own decisions regarding :
  • What do you want to do if a user edit simultaneously the TimeEntries on Lucca Timesheet and on the other system? Where is the truth?
  • What do you want to do if a user deletes a TimeEntry in the source system, and recreates another quite like it with a slightly different duration? Do you want Lucca Timesheet to delete the original TimeEntry and recreate another? Or do you want to to edit the original to match the new duration?
If the answers to those questions does not matter to you when looking at what you need to do, then go for the smart update service.

​
Editing rights : matching the source and the user rights

The source property of the time-entry affects its access-rights. As a result, when creating new time-entries, make sure to pick the one that matches your integration purpose:
  • Manual source (timeSource=manual or creationSource=2) is for regular time-entries that employees should be able to edit themselves down the line. The idea here would be to “automatically suggest time-entries” to employees. The access operation “Add/Edit Times” is required to create or edit such time-entries.
  • Import source (timeSource=import or creationSource=3) is used for time-entries that regular employees should NOT be able to edit. It is most commonly used to import clocked-in times that can’t be tampered, except by administrators. Only users with “Edit imported or clocked-in times” right will be able to edit such time-entries through the user interface.
Recommendation : if you want employees to be able to add new time-entries themselves BUT not be able to edit those you imported, use the import source and do not give them the “Edit imported or clock-in times” operation. See the TimeEntry API reference.

​
Prerequisites

You will need:
  • (required) Your domain name {yourDomain}, eg: “https://myawesomecompany.ilucca.net”.
  • (required) An API key {apiKey} that has editing rights on the TimeEntries of the users concerned by your integration project.

​
Guide

​
Approach 1 - Manual CRUD Requests

You will need to track any change made to the source system for TimeEntries, and translate those changes into Lucca Timesheet TimeEntries requests.
  • A new TimeEntry has been created -> POST a new TimeEntry
  • A TimeEntry has been modified (duration, project, comment, …) -> PUT on the corresponding TimeEntry id
  • A TimeEntry has been deleted -> DELETE the corresponding TimeEntry id
You therefore need to store Lucca Timesheet created TimeEntries ids to be able to target the right TimeEntries when any modification occurs in the source system. See the API reference for /api/v3/timeentries POST, PUT, and DELETE endpoints.

​
Examples

Create new TimeEntries 
POST /api/v3/timeentries HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Body:
[
  {
    "ownerId": 90,
    "unit": 2,
    "startsAt": "2024-04-22T09:30:00",
    "duration": "03:45:00",
    "creationSource": 2,
    "axisSections": [
        {
            "id": 41
        },
        {
            "id": 127
        },
        {
            "id": 346
        },
        {
            "id": 347
        }
    ]
  }
  ...
]
Edit existing TimeEntries 
PUT /api/v3/timeentries HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Body:
[
  {
    "id": 55
    "startsAt": "2024-04-22T09:45:00",
    "duration": "03:30:00",
  },
  ...
]
Delete TimeEntries 
DELETE /api/v3/timeentries HTTP/1.1
Host: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Body:
[
  {
    "id": 55
  },
  ...
]

​
Approach 2 - Smart update service

You will need to track any change made to the source system TimeEntries, and send back to Lucca Timesheet ALL TimeEntries for the whole period, including those that weren’t modified. The service will automatically match and update Lucca Timesheet TimeEntries to meet what you sent. The service should be seen as an ‘erase and replace’ request. See the API reference for /timmi-timesheet/services/time-entries endpoint.

​
Examples

Let’s say Alexander already has 3 TimeEntries from 08:00 to 12:00 on each day from May 6th to 8th 
[
  {
    "id": 552281,
    "startsAt": "2024-05-06T08:00:00",
    "duration": "04:00:00",
    "ownerId": 45
  },
  {
    "id": 552282,
    "startsAt": "2024-05-07T08:00:00",
    "duration": "04:00:00",
    "ownerId": 45
  },
  {
    "id": 552283,
    "startsAt": "2024-05-08T08:00:00",
    "duration": "04:00:00",
    "ownerId": 45
  }
]
If he started earlier on May 6th, you need to send the corrected May 6th TimeEntry 
PUT /timmi-timesheet/services/time-entries?ownerId=45&startsOn=2024-05-06&endsOn=2024-05-06 HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Body:
[
  {
    "startsAt": "2024-05-06T07:00:00",
    "duration": "05:00:00",
    "ownerId": 45
  }
]
If he started earlier on May 6th, and also worked on May 7th afternoon: you need to send all May 6th and 7th TimeEntries, including the untouched May 7th morning one. 
PUT /timmi-timesheet/services/time-entries?ownerId=45&startsOn=2024-05-06&endsOn=2024-05-07 HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Body:
[
  {
    "startsAt": "2024-05-06T07:00:00",
    "duration": "05:00:00",
    "ownerId": 45
  },
  {
    "startsAt": "2024-05-07T08:00:00",
    "duration": "04:00:00",
    "ownerId": 45
  },
  {
    "startsAt": "2024-05-07T14:00:00",
    "duration": "03:00:00",
    "ownerId": 45
  }
]
If he started earlier on May 6th, and finished late on May 8th: you need to send all TimeEntries from May 6th to May 8th. Please note that although May 7th TimeEntry was not modified, you still need to send it in the payload. If you don’t, the service will clear May 7th TimeEntries, assuming there should not be any TimeEntry on this day anymore. 
PUT /timmi-timesheet/services/time-entries?ownerId=45&startsOn=2024-05-06&endsOn=2024-05-08 HTTP/1.1
Domain: {yourDomain}
Authorization: lucca application={apiKey}
Accept: application/json

Body:
[
  {
    "startsAt": "2024-05-06T07:00:00",
    "duration": "05:00:00",
    "ownerId": 45
  },
  {
    "startsAt": "2024-05-07T08:00:00",
    "duration": "04:00:00",
    "ownerId": 45
  },
  {
    "startsAt": "2024-05-08T08:00:00",
    "duration": "05:35:00",
    "ownerId": 45
  }
]

​
Going Further

If you are already importing TimeEntries through API requests, and do not need nor want your submitters to submit their own timesheets, you can submit their timesheets by API requests. Follow this guide.