# Integration with Lucca

### **Overview**

This guide walks you through the steps required to integrate Lucca with MangoApps. It includes setup instructions, roles needed, security information, testing tips, and rollout best practices to ensure a successful implementation.

<figure><img src="/files/kPpBnTREqSQsUCrz8BTu" alt="" width="375"><figcaption></figcaption></figure>

This integration supports automatic user provisioning and de-provisioning, along with user profile synchronization. Once configured, MangoApps will regularly pull data from Lucca based on the configured mappings.

***

### **Required Roles**

To complete this integration, the following roles are required:

* **Lucca Administrator**: Must have admin access to the Lucca instance to generate API keys and configure permissions.
* **MangoApps Administrator**: Must have admin access to the MangoApps Admin Portal to set up and manage the integration.

***

### **Lucca Side Setup**

This section outlines how to prepare your Lucca account for integration with MangoApps.

**Sign in to Lucca** and go to the **Home** page.

Locate your **Lucca domain** from the browser URL. For example, if your URL is `https://merge.ilucca-demo.net/home`, your domain is `merge.ilucca-demo.net`.

***

#### **Generate an API Key**

Click the **gear icon** (top-right corner), then select **API Keys**.

<figure><img src="/files/v0Tb4Ign96MpVg8r6Gt2" alt="" width="250"><figcaption></figcaption></figure>

Click **Generate a new API Key**.

<figure><img src="/files/eFD0zbVxEslVpiuuXdoj" alt="" width="563"><figcaption></figcaption></figure>

Name your key and assign these permissions:

* `consult/create/modify users` (required)
* `consult leaves` (optional)
* `make absence requests` (optional)
* Provide a **technical contact email**.
* In **API key usage**, choose **Third-party publisher**.
* Click **Generate a new API key**.

<figure><img src="/files/qYAxSDNpbh7eD6pM2yeJ" alt="" width="563"><figcaption></figcaption></figure>

***

#### **Configure Role Permissions** for the API Key

Click the **Role Administration** link after key generation.

<figure><img src="/files/3pQSxE5hc6gXhBWSYRDe" alt="" width="563"><figcaption></figcaption></figure>

Under the **Co-workers** tab, add these permissions:

* `see future employees` (required)
* `see former employees` (required)
* `view employee jobs` (optional)
* `view employee managers` (optional)
* `view employee qualification` (optional)

<figure><img src="/files/v4bKIjpMXZ1F8qJuDRTD" alt="" width="563"><figcaption></figcaption></figure>

**Save** the role configuration.

Copy the newly generated **API Key** for use in MangoApps.

<figure><img src="/files/yUr0pmoDKua0A5XUX3oa" alt="" width="563"><figcaption></figcaption></figure>

***

### **MangoApps Side Setup**

This section outlines the steps to configure MangoApps with your Lucca integration.

Go to the **Admin Portal** in MangoApps and navigate to **Partner Integrations**. Click the **Add Integration** button in the top right corner of the screen.

<figure><img src="/files/BsQXx0DHKyVcDEx3kAFe" alt="" width="563"><figcaption></figcaption></figure>

Select **Lucca** from the list integrations list.

<figure><img src="/files/L0ZbyI5cFnQeF5UMSJ7q" alt="" width="563"><figcaption></figcaption></figure>

Click **"I am an admin"** to proceed.

<figure><img src="/files/5FH5DuEx9FIr8QfQFVIq" alt="" width="410"><figcaption></figcaption></figure>

Review the **read-only accesses** MangoApps requests from Lucca and click **Next**.

<figure><img src="/files/KaXyIZdyR6hHSYw4K1zN" alt="" width="322"><figcaption></figcaption></figure>

Enter your **Lucca domain** in the domain field.

<figure><img src="/files/obV3s8jJGd4yeW8BYNpm" alt="" width="326"><figcaption></figcaption></figure>

Enter the **API Key** copied from Lucca and click **Next** to complete the setup.

<figure><img src="/files/devruDEmtPjcjQtoGeQs" alt="" width="329"><figcaption></figcaption></figure>

{% hint style="warning" %}
Once setup is complete, MangoApps will initiate the first sync. During this time, user mapping configuration will be **unavailable** until the sync finishes.
{% endhint %}

***

#### Configure User Mapping

After the initial sync, click **Configure User Mapping**.

<figure><img src="/files/cZtMLOa02ARq0bUlWhET" alt=""><figcaption></figcaption></figure>

In the pop-up menu, review and match Lucca fields to MangoApps profile fields.

<figure><img src="/files/ndZ5JBSjhDJeGPZWt6Pt" alt="" width="355"><figcaption></figcaption></figure>

{% hint style="success" %}
Click **Reset to System Default** if you wish to start over from the default configuration.
{% endhint %}

If additional fields are needed, create custom profile fields in [**Admin Portal > Modules > People > Full Profile**](https://guides.mangoapps.com/admin-guide/module-settings/people/full-profile/managing-profile-fields#adding-a-new-custom-field)**.**

**Save** your mapping once complete.

***

### **Testing Considerations**

Before going live, validate the integration:

* Ensure that user data is syncing accurately.
* Check that required fields are mapped correctly.
* Test the de-provisioning flow by deactivating a user in Lucca and confirming their status updates in MangoApps after the next hourly sync.
* Review optional data sync (leaves, job roles) if those permissions were enabled.

***

### **Security Considerations**

This integration maintains strong security by:

* Using API Keys for secure, scoped access.
* Requiring admin permissions on both platforms to initiate the setup.
* Supporting read-only access review prior to activation.
* Automatically syncing user status to minimize manual user management.

Ensure that the technical contact listed in Lucca receives key lifecycle notifications.

***

### **End User Experience**

End users will benefit from:

* Seamless onboarding: Users are automatically created and updated in MangoApps based on Lucca data.
* Consistent profiles: Profile fields reflect the most current data from Lucca.
* No additional login steps: This is a backend sync, so no user action is needed.

If a user is deactivated in Lucca, they will automatically lose access in MangoApps after the next sync.

***

### **Rollout Recommendations**

To ensure a smooth deployment:

1. **Pilot the integration** with a small user group.
2. Confirm mappings and test sync outcomes.
3. Train admins on how to update user mappings and custom fields.
4. Communicate changes to end users (if needed), especially around automatic de-provisioning.
5. Monitor syncs post-rollout using MangoApps Admin tools to ensure everything runs smoothly.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guides.mangoapps.com/integrations-guide/hris-partner-integrations/integration-with-lucca.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.