Setting up the Lucca integration

Deel can also connect to Lucca using the dedicated integration that leverages the SFTP protocol. This article explains how to prepare Lucca to send data to Deel and how to connect to it using the integration.

The Lucca integration is organized in plugins, where each plugin is responsible for the sync of a specific part of the data. To be able to sync employee data from Lucca, configurations must be done on both Lucca and Deel.

In this article

• Before you begin
• Set up the Lucca FTP
• Set up employee sync
• Set up one-time payment (OTP) sync
• Set up paid-time off (PTO) sync
• Set up recurring payments sync
• Syncing data from Lucca

Before you begin

To configure the Lucca integration, make sure to have:

• A user with an admin role on Lucca
• The admin user setting up the integration must have Lucca's language set to English
• A user with an admin role on Deel
• Access to the following Lucca products:
  • Core HR
  • Pagga Compensation
  • Timmi Absences (For PTO sync)

Set up the Lucca FTP

To set up an FTP on Lucca, follow the instructions from the Lucca Help Center.

Make sure to store the credentials and FTP server information, as they are needed to complete the setup.

Set up employee sync

The employee sync is the most important plugin, as it is responsible for the sync of employee data and is the foundation for other plugins to work.

Employee sync Lucca configuration

This section explains how to set up the employee sync on Lucca. To sync employees from Lucca, 3 exports are required.

• Employee data
• Establishment data
• Compensation data

Step 1. Create the employee sync export

The first part of configuring the employee data consists in creating an export.

To create an export:

1. Log in to your Lucca instance as an admin and go to Solutions > Core HR.

2. Go to Export, then click Create an export setup.

3. On the Create an export configuration dialog:

a. Select the relevant establishment.

b. Name the export so that you can differentiate from other exports. For example, Employee data or Establishment data.

c. Enter Deel as the name of the synchronized software.

d. Click Save.

Step 2. Configure the employee sync export settings

After the export is generated, users are taken to the export’s Configuration settings. Here’s how to configure them:

1. In the Generation of the export section, set the generation mode to Automatic.

Set the frequency and the hours at which the report must be generated.

3. In the Shipping policy section, set the file to be sent by FTP.

4. Select the FTP where you want to send the file, then click Save changes.

Step 3. Configure the employee sync file template

After configuring the export settings, a file template must be created.

To create a file template:

1. From the export page, go to the File templates tab, and click Add a file.

2. On the Create a file template dialog, set the template format according to the appropriate structure, then click Next.

3. In the File settings section of the File templates tab, configure the additional settings, then click Save.

Structure of the employee sync template files

Employee data template structure

 

Establishment data template structure

 

Step 4. Edit the employee sync file structure

After configuring the template file settings, the file structure must be edited.

To edit the file structure:

1. In the File templates tab, click Editing the file structure, then click Validate.

2. Pair header values to body values based on the structure of the employee sync export files.

 

Structure of the employee sync export files

Employee data file structure

The employee data file must have the following structure:

 

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file to compare the structure.

employeeNumber;addressLine1;zip;firstName;lastName;country;city;jobTitle;jobEffectiveDate;workEmail;startDate;fte;employmentType;employmentEffectiveDate;localisation;bankName;bankSWIFTCode;bankIBAN;bankAccountType;payGroupId;contractEndDate
1;65, Rue Victor Hugo, 75001 Paris;75001;Jessica;Berry Allen;GB;Paris;Business Developer;02/01/2020;email@deel.com;02/01/2020;1;Full Time;02/01/2020;Paris;BNP Paribas;BOUSFRPPXXX;FR7640618802760004015133137;Other;LUCCA_UK;20/02/2029

 

Establishment data file structure

The establishment data file must have the following structure:

 

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file to compare the structure.

 

companyId;companyName
LUCCA_FRANCE;France

Step 5. Create a compensation export for employee sync

After creating the employee data and establishment data exports, it's time to create a compensation data export. 

To create an export:

1. Log in to your Lucca instance as an admin and go to Solutions > Pagga Compensation.

2. Go to Exports, then click New configuration.

3. On the Add an export configuration dialog:

a. Name the export so that you can recognize that it’s related to compensation data. For example, Employee compensation data.

b. Choose Generic format as the format.

c. Click Save.

Step 6. Configure the compensation export scope

After the export is created, users are taken to the export’s Configuration settings. Here’s how to configure them:

1. From the export settings, go to the Scope of export tab.

2. Set the scope as follows:

    a. Select the relevant establishments to be exported.

    b. In the Population to be included in the export section, select Employee(s) without an assigned occupation category and All occupation categories.

    c. In the Selection of the variable pay natures to be exported, leave all options unselected.

    d. In the Selection of the fixed pay natures to be exported (only in turn-around file), select the pay natures that correspond to the salary categories that match the language of your establishment. For example, Salaire de base and Base salary for a combination of US and FR establishments.

3. In the Options section:

    a. Leave the option Display the comments associated with the FRIs and payroll variables in the turn-around file selected.

    b. Unselect the option Check the existence of the FRI for employees with an active contract over the period.

4. Click Save the configuration.

Step 7. Configure the compensation export format

After the scope is configured, the export format must be configured.

To configure the export format:

1. From the export settings, go to the Data and export format tab.

2. Set the export format as follows, then click Save the configuration.

Setting	Option
Selection and position of the fields to display in the export	- Col. 1: Employee (employee number) - Col. 2: Establishment (code)
Name and extension of the file	compensation_$[configName]_$[exportDate]_$[exportPeriod]
Output file type	CSV file
Date format	yyyy/MM/dd
Decimal separator	Comma
Field separator	Semicolon
Using quotation marks ("") to force the text forma in the generated file	true
Character encoding	ANSI

 

Step 8. Configure compensation automated exports

After the export format is configured, the automated exports must be configured.

To configure the automated exports:

1. From the export settings, go to the Automated exports tab.

2. Set automated exports as Enabled.

3. Set the FTP export as Enabled, then click Configure.

4. On the Configure the FTP server dialog:

a. Set the Selection of file types to Turn-around file only.

b. In Endpoint choice, select the FTP server where to send the export.

5. Click Save.

6. Click Save the configuration.

After configuring the automated exports, all the settings in Lucca are configured and it’s time to set up the integration on Deel.

If you want, you can download a sample file to compare.

Employee sync Deel configuration

This section explains how to set up the Lucca integration on Deel.

Step 1. Connect to Lucca

To connect to Lucca:

1. Go to the Hub > Apps and search for Lucca in the App Store.

2. On the integration page, click Connect Lucca.

3. Enter the information of the Lucca FTP server.

4. Choose the prefixes for the Lucca export files. We recommend leaving the pre-filled values.

5. When done, click Connect & go to settings.

Step 2. Configure the sync

Once the integration is connected, the sync can be enabled.

To enable the sync:

1. In the Plugins and settings section, locate the People data sync plugin and click Enable.

2. On the People sync configuration step, map the entities and groups to be synced, then click Continue.

3. On the Sync entities step, configure the sync schedule, then click Continue.

4. On the Data/item mapping step, confirm that the field mapping is correct or edit it as needed, then click Continue.

    a. (Optional) If you have included country-specific fields, you can map them from the Country-specific items section.

5. On the Notification settings step, add notification recipients, then click Continue.

6. On the Review & confirm step, review your settings, then click Continue.

7. (Optional) Repeat the configuration for each entity by clicking on the enabled plugin and then Add entity.

Set up one-time payment (OTP) sync

The Lucca integration can also sync one-time payments (OTPs). This section explains how to set up the OTP sync on Deel.

OTP sync Lucca configuration

This section explains how to set up the OTP sync on Lucca. To sync OTP information from Lucca, 2 exports are required: are required:

• OTP data
• OTP types

Step 1. Create the OTP data export

The first part of setting the OTP data sync consists in creating an export.

To create an export:

1. Log in to your Lucca instance as an admin and go to Solutions > Pagga compensation.

2. Go to Exports, then click New configuration.

3. On the Add an export configuration dialog:

    a. Name the export so that you can recognize that it’s related to OTP data. For example, OTP payment data or OTP types data.

    b. Choose Generic format as the format.

    c. Click Save.

Step 2. Configure the OTP data export scope

After the OTP data export is created, users are taken to the export’s settings. Here’s how to configure them:

1. From the export settings, go to the Scope of export tab.

2. Set the scope as follows:

    a. Select the relevant establishments to be exported.

    b. In the Population to be included in the export section, select all occupation categories as well as employees without an assigned occupation category.

    c. In the Selection of the variable pay natures to be exported, select all payroll variable natures.

    d. In the Selection of the fixed pay natures to be exported (only in turn-around file), leave all options unselected.

3. In the Options section, unselect all the available options.

4. Click Save the configuration.

Step 3. Configure the OTP data export format

After the scope is configured, the export format must be configured.

To configure the export format:

1. From the export settings, go to the Data and export format tab.

2. Set the export formats according to the appropriate settings then click Save the configuration.

Settings of the OTP export files

OTP data file settings

 

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file to compare the structure.

EmployeeNumber;Amount;NatureCode;PayPeriodEnd
1;2000,00;P1280;2024-11-30

 

OTP types file settings

 

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file  to compare the structure.

NatureCode;NatureName
P1280;Commissions

 

Step 4. Configure the OTP data automated exports

After the export format is configured, the automated exports must be configured.

To configure the automated exports for payments:

1. From the export settings, go to the Automated exports tab.

2. Set automated exports as Enabled.

3. Set the FTP export as Enabled, then click Configure.

4. On the Configure the FTP server dialog:

    a. Set the Selection of file types to The export file(s) only.

    b. In Endpoint choice, select the FTP server where to send the export.

5. Click Save.

6. Click Save the configuration again.

 

OTP sync Deel configuration

This section explains how to set up the OTP sync on Deel.

Enable the One Time Payment plugin

To enable the one-time payment sync:

1. In the Plugins and settings tab, locate the Global Payroll - One Time Payment plugin and click Enable.

2. On the Global Payroll - One Time Payment page, click Configure next to the entity you want to configure OTP sync for.

3. On the Match Lucca to Deel one time payment types page, map the OTP types, then click Confirm.

4. On the Enable the sync dialog, review the entities to be synced, then click Enable sync.

Set up paid-time off (PTO) sync

This section explains how to set up the PTO sync on Lucca.

PTO sync Lucca configuration

To sync PTO information from Lucca, 2 exports are required.

• PTO data
• PTO types

Step 1. Create the PTO export

The first part of setting up the PTO sync consists in creating an export.

To create an export:

1. Log in to your Lucca instance as an admin and go to Solutions > Timmi Absences.
2. Go to Exports, then click Create an export configuration.
3. On the Create an export configuration dialog:
   1. On the Template tab, select Generic template, then click Next.
   2. When asked How do you want to export the data?, select Full export, then click Next.
   3. Select the establishments you want to export data for, then click Create.

Step 2. Configure the PTO export general settings

After the PTO export is created, users are taken to the export’s general settings. Here’s how to configure them:

1. Give the export a name, then click Save.
2. Set FTP uploading to Activated, select the FTP server where to send the export, then click Save.
3. Set Automation to Activated, then do the following:
   1. Set the Type of recurrence to By day of the week.
   2. Set the recurrence to Every day.
   3. Set the time for the export to be triggered.
   4. Set the users to be notified if the error fails, then click Save.

Step 3. Configure the PTO export file

After configuring the PTO export general settings, users must configure the export file.

To configure the export files:

1. Go to the Files tab.

2. Rename absences.csv so that the name corresponds to the prefix set when connecting the Lucca integration:

• • For PTO data, leave the file name as absences.csv.
  • For PTO types, rename the file to pto_types.csv.

3. Click Edit structure and edit the structure of the file. For details on the structure of each file, see Structure of the PTO export files.

    a. On the File structure page:

        i. In the Header section, click Add a line.

        ii. Click Add cell.

    b. In the Header - Define cell content section:

        i. In the Define cell content section, click Add a field.

        ii. Expand the File section, select Constant, then click Add.

        iii. In the Fields formatting section, select Custom value as the input value.

        iv. In the value field, enter the first value.

        v. Click Save.

        vi. Hover on the cell you just added, then click the + button.

        vii. Repeat from step 3.1.2 for all the header values needed.

    c. In the Body section:

        i. Delete all the existing cells.

        ii. Click Add cell.

    d. In the Body - Define cell content section:

        i. In the Define cell content section, click Add a field.

        ii. On the Add a field dialog, select the field, then click Add.

        iii. (Optional) Where applicable, in the Fields formatting section, enter the field formatting pattern.

        iv. Click Save.

        v. Repeat from step 3.3.2 for all the body values needed.

Structure of the PTO export files

PTO data file structure

The PTO data file must have the following structure:

 

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file to compare the structure.

employeeProviderId;start;end;typeId;durationDays
1;29/11/2024;29/11/2024;66;1

 

PTO types file structure

The PTO types file must have the following structure:

 

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file to compare the structure.

typeId;typeName
1524;Vacation
66; Wedding

PTO sync Deel configuration

This section explains how to set up the PTO sync on Deel.

Enable the time off plugin

To enable the time off plug in:

1. In the Plugins and settings tab, locate the Global Payroll - Time Off plugin and click Enable.

2. On the Global Payroll - Time Off page, click Configure next to the entity you want to configure PTO sync for.

3. On the Match Lucca to Deel time off types page, map the PTO types, then click Confirm.

4. On the Enable the sync dialog, review the entities to be synced, then click Enable sync.

Set up recurring payments sync

The Lucca integration can also sync recurring payments. This section explains how to set up recurring payments sync on Deel.

Recurring payments sync Lucca configuration

The recurring payments sync needs a separate export setup with only recurring payments included in the export.

Step 1. Create a compensation export for recurring payments

The first part of setting up the compensation data sync consists in creating an export.

To create an export:

1. Log in to your Lucca instance as an admin and go to Solutions > Pagga Compensation.

2. Go to Exports, then click New configuration.

3. On the Add an export configuration dialog:

    a. Name the export so that you can recognize that it’s related to recurring payments data. For example, Recurring payments data.

    b. Choose Generic format as the format.

    c. Click Save.

Step 2. Configure the recurring payment export scope

After the export is created, users are taken to the export’s settings. Here’s how to configure them:

1. From the export settings, go to the Scope of export tab.

2. Set the scope as follows:

    a. Select the relevant establishments to be exported.

    b. In the Population to be included in the export section, select Employee(s) without an assigned occupation category and All occupation categories.

    c. In the Selection of the variable pay natures to be exported, leave all options unselected.

    d. In the Selection of the fixed pay natures to be exported (only in turn-around file), select all FRI's except the ones related to salary. Keep those that make sense for allowances, such as Travel Allowance, Referral Bonus, and so on.

3. In the Options section:

    a. Leave the option Display the comments associated with the FRIs and payroll variables in the turn-around file selected.

    b. Unselect the option Check the existence of the FRI for employees with an active contract over the period.

4. Click Save the configuration.

Step 4. Configure recurring payments automated exports

After the export format is configured, the automated exports must be configured.

To configure the automated exports:

1. From the export settings, go to the Automated exports tab.

2. Set automated exports as Enabled.

3. Set the FTP export as Enabled, then click Configure.

4. On the Configure the FTP server dialog:

    a. Set the Selection of file types to Turn-around file only.

    b. In Endpoint choice, select the FTP server where to send the export.

5. Click Save.

6. Click Save the configuration.

After configuring the automated exports, all the settings in Lucca are configured and it’s time to set up the integration on Deel.

Following is a sample CSV file exported using the appropriate structure. Or, if you prefer, you can download the sample file to compare the structure.

 

Recurring payments sync Deel configuration

This section explains how to set up the recurring payments sync on Deel.

Enable the recurring payment plugin

To enable the recurring payment plugin:

1. In the Plugins and settings tab, locate the Global Payroll - Recurring Payment plugin and click Enable.

2. On the Global Payroll - Recurring Payment page, click Configure next to the entity you want to configure recurring payments for.

3. On the Match Lucca to Deel recurring payment types page, map the recurring payment types, then click Confirm.

4. On the Enable the sync dialog, review the entities to be synced, then click Enable sync.

Syncing data from Lucca

The data will sync automatically at the time you configured while setting up the integration, but you can always do a manual sync by clicking the Sync Lucca button in the integration.