> For the complete documentation index, see [llms.txt](https://help.steeple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.steeple.com/en/administration/synchroniser-annuaire-lucca.md).

# How do I synchronize my collaborator directory with Lucca?

### Overview

The Lucca integration synchronizes your Steeple Directory from your Lucca HRIS: account creations, profile updates, and departures follow your HR reference data. When you add an employee in Lucca, their account is created automatically in Steeple.

Synchronization is **automatic every night**. You can also launch it yourself at any time without waiting for the next run.

Setup takes place in two steps: create a Steeple application in Lucca to obtain access keys, then configure the connector in Steeple.

### Prerequisites

* Have the necessary rights in Lucca to create an OAuth application (see step 1).
* Stop provisioning your organization via SCIM: an HRIS connector and SCIM provisioning cannot coexist, and as long as SCIM is active the connector cannot be enabled.

### Step 1 — Create a Steeple application in Lucca

For Steeple to synchronize with Lucca, you must first create access keys on the Lucca side.

In Lucca, go to **Administration** > **Settings**, then, in the **Security**section, select **OAuth Applications**.

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-586982ca06494740b69d62b8c1c3609cb8a05ead%2Flucca-1-parametre-application.png?alt=media" alt="Menu Paramètres de Lucca : l&#x27;entrée Applications OAuth, dans la section Sécurité"><figcaption></figcaption></figure>

If this entry does not appear in your menu, you do not have the required permissions: contact your Lucca administrator.

Click on **Add an application**. A window opens, organized into four steps, after which Lucca displays the access keys.

#### 1. Technical contact

Enter the email address that will be used as the technical contact with Lucca.

#### 2. Information

* **Name** : the application name, for example “Steeple Connector”.
* **Scope of use** : select **Third-party publisher**.
* **Publisher name** : enter **Steeple**.

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-e77766900a7e4bd17642ffc59287deadb424001c%2Flucca-2-contact.png?alt=media" alt="Étape 2 Informations : nom de l&#x27;application, périmètre d&#x27;utilisation Éditeur tiers et nom de l&#x27;éditeur"><figcaption></figcaption></figure>

#### 3. Scopes

Scopes define the resources Steeple has access to. Select the following five:

* `employees.readonly` — employee essentials (last name, first name, email…)
* `employments.readonly` — contract start and end dates
* `job-positions.readonly` — position held and manager
* `departments.readonly` — the employee's department assignment
* `business-establishments.readonly` — the employee's establishment assignment

These scopes are **read-only** and do not grant access to information classified as critical by Lucca.

All five are required: Lucca rejects the access request if one of them is not declared on the application, and missing information (the contract dates, for example) prevents departure detection.

The list of available scopes is documented by Lucca: <https://developers.luccasoftware.com/api-reference/latest/oauth-scopes>

#### 4. Establishments

Select the establishments that the Steeple connector should cover.

#### After validation — Retrieve the access keys

Once these four steps are validated, Lucca confirms the application has been created and displays the two pieces of information needed to configure the Steeple side: the **Client ID** and the **Secret value**. Use the **Copy** buttons to retrieve them.

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-aa0560c4da49963c95287f24d4567895f0534289%2Flucca-3-cles-app.png?alt=media" alt="Fenêtre de confirmation Lucca affichant le Client ID et la Valeur du secret, avec un bouton Copier pour chacun"><figcaption></figcaption></figure>

Keep them in a safe place before leaving this page: **the secret value is never shown again**. The secret is valid for **3 years** — after that, you must generate a new one and enter it again in Steeple.

### Step 2 — Configure the connector in Steeple

Go to the**Administration**, **Integrations** (`/administration/integrations`section, then select **Lucca**. The page is organized into collapsible sections: click **Show** to open the one you are working on.

#### Connection

* **Address of your Lucca workspace** : the domain name displayed in your browser when you are on Lucca, for example `https://034-mon-entreprise.ilucca.net`. The address must start with `https` and point to a Lucca domain (`ilucca.net`, `ilucca.ch`, their `ilucca-test` and `ilucca-demo`, or `luccasoftware.com`).
* **Client ID** : the Client ID generated in step 1.
* **Secret value** : the secret value generated in step 1.

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-1dc7161a44f368e0b193009ddc9864c91c27d955%2Flucca-4-steeple-cles.png?alt=media" alt="Section Connexion : adresse de l&#x27;espace Lucca, Client ID et valeur du secret"><figcaption></figcaption></figure>

The credentials are never shown again. When making a later change, leave these fields blank to keep the ones already saved.

#### Who manages employee profiles?

This choice determines **who writes employee profiles**. It does not change the synchronization pace: whatever the choice, it remains automatic. Account creations and departures follow Lucca.

* **Your administrators** — accounts created from Lucca remain editable in Steeple. An existing profile is never overwritten, except for the contract end date, which always follows Lucca.
* **Shared** — accounts created from Lucca are maintained by Lucca. An existing profile is never overwritten, except for the contract end date.
* **Lucca** — all profiles linked to Lucca are maintained by Lucca.

Any information left blank in Steeple is filled in from Lucca, except email and employee number, which are used to log in.

An employee missing from the directory is never automatically deactivated, and employees outside the directory are never modified.

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-7ca0402ae595ad36294692764f0b3b24a9d7fdb9%2Flucca-5-steeple-modes.png?alt=media" alt="Section Qui gère les fiches des collaborateurs ? : les trois choix Vos administrateurs, Partagé et Lucca"><figcaption></figcaption></figure>

Assign profiles to **Lucca** requires confirmation: from the next synchronization onward, Lucca writes the profiles of all linked employees, changes entered in Steeple are overwritten, and switching back to another choice does not restore them.

#### Advanced options

* **Create dynamic Communities automatically** — departments and locations in the directory that do not yet have a community will be created during synchronization.
* **Send activation emails** — employees created by the connector receive an email to activate their account. Only accounts created once this option is enabled will receive one.
* **Do not synchronize the location** — the Lucca establishment is no longer used as the location on profiles.
* **Do not synchronize the birthday** — the birthday entered in Lucca is no longer used on profiles.

These two options leave the field as is: nothing is overwritten, and you remain free to fill it in in Steeple.

#### Setup

The **Setup** section brings together the connector's three actions.

1. **Save and verify the connection** — saves the configuration, then checks that Lucca responds with the entered credentials and reads your Directory. It creates no one. The connector becomes active once the verification succeeds.
2. **Test synchronization** — runs a full synchronization without writing anything to profiles: the report shows which employees would be created, updated, completed, or marked as leaving. Employees already present in Steeple are matched to their Lucca profile and attached to the connector, without their profile changing. On a large directory, the operation may take a few minutes.
3. **Synchronize now** — actually applies the synchronization: profiles, Communities, and departures are written to your employees. The first run creates your employees in Steeple; the test above shows exactly which ones. Lucca is then synchronized automatically every night.

Verification always comes first: as long as the connector is not active, the other two actions remain unavailable. **The test is required only before the first synchronization.** It creates your entire organization, and the test is what tells you in advance what it will do. Once that first run has passed, the test remains available but no longer conditions anything: you can change the configuration and synchronize right after.

Each action provides access to a link **View report**, which details how it runs. The link appears only once the run is finished: while it is running, there is nothing to read yet.

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-d5f93f01df869a55566d151da742a11e86832278%2Flucca-6-steeple-installation.png?alt=media" alt="Section Installation : vérification de la connexion, test de la synchronisation et synchronisation, chacun avec son rapport"><figcaption></figcaption></figure>

Changing the address of your Lucca workspace puts the connector back into pending verification: it is another Directory, and nothing that had been verified applies there. The whole sequence starts over — verify, then test, then synchronize — and the test becomes required again before the first synchronization on this new Directory. **Disconnect** the connector has the same effect: reconfiguring it starts over from verification, with a test again required before synchronizing.

### Run a synchronization on demand

The connector syncs every night. To avoid waiting for the next run, you can trigger it yourself from two places.

The button **Synchronize now** in the **Setup**section, described above.

Or, more directly, the entry **Synchronize with Lucca** in the **⋮** menu (three dots), to the right of the title **Collaborators** of the**Directory** (`/directory`).

<figure><img src="https://608007981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FByS0e17eM732OXdGGkme%2Fuploads%2Fgit-blob-021d6010c5d95a7ae5d8128174f082b5b663020e%2Flucca-7-steeple-sync-annuaire.png?alt=media" alt="Page Annuaire : le menu ⋮ ouvert à droite du titre Collaborateurs, avec l&#x27;entrée Synchroniser avec Lucca"><figcaption></figcaption></figure>

This button is visible only to organization administrators once the connector setup is complete.

In both cases, the synchronization applies profiles, Communities, and departures, and the report is available a few minutes later.

### View synchronization reports

The **Synchronization reports** appears after the first run. It shows the date of the last synchronization and gives access to the run history. Each report details what was done — or, for a test, what would have been done — and the reason for any error.

### Disconnect the connector

The button **Disconnect** removes the credentials and personal data from Lucca, and stops synchronization. Your employees and synchronization history are kept. It remains available on a connector that has not yet been activated: a secret value is already stored there, and it is the only way to retrieve it.

### What the assistant can do

The assistant can guide the user to the page **Integrations** via navigate\_to and explain how the connector works (who manages employee profiles, advanced options, nightly synchronization, reports). It can remind that the test is required only before the first synchronization, and that SCIM provisioning must be removed before activating the connector. For creating the OAuth application on the Lucca side, direct to Lucca documentation and to <https://help.steeple.com/>
