​
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.

​
About the creationSource / timeSource

When sending TimeEntries to Lucca Timesheet, you will need to set a timeSource or a creationSource depending on the endpoints used :

  • timeSource=manual or creationSource=2 for standard TimeEntries that users should be able to edit normally. [the default for any TimeEntry]
  • timeSource=import or creationSource=3 for read-only TimeEntries that only users with “Edit times” right should be able to edit through the user interface. (only for attendance-schedule-clock-in/clock-out or activity-schedule timesheet modes)
  • timeSource=timer or creationSource=4 for clocked-in / clocked-out TimeEntries that users should be able to adjust if necessary. After editing the TimeEntry, timeSource/creationSource will be set to manual/2.

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.