Introduction

The External IDs connector is a Docebo Connect connector that exposes the External IDs functionality directly within your Connect recipes. External IDs provide a way to store and manage different identifiers for entities that exist both in the Docebo platform and in external systems, improving performance during synchronization by mapping and storing the unique identifiers (UIDs) of Docebo entities alongside their corresponding UIDs in third-party systems.

The connector appears in Docebo Connect as Docebo Learn - External IDs and allows your integrations to register and manage integrations in the External IDs service, send commands to create and update mappings between Docebo entities and external entities and query mappings that have been created through those commands.

This article describes how to use the External IDs connector actions in Docebo Connect. It is intended for platform administrators and integration owners who design and maintain Docebo Connect projects, as well as technical users who need to understand how External IDs behave at the recipe level. You should already be familiar with the basic concepts of connectors, connections and recipes in Docebo Connect.

Before you start

Each integration that uses External IDs takes responsibility for a number of tasks: creating, updating, deleting and retrieving entities involved in the Docebo platform according to the integration's purpose; informing the External IDs service when an integration is activated or deactivated; asking External IDs to store metadata for synchronized Docebo entities; and setting the initial External IDs matching status for the Docebo entities involved when an integration is activated.

Role of the event bus

The event bus determines how integrations must react when a Docebo entity changes in the platform. Once an integration subscribes to platform events through the External IDs connector, mappings can be updated automatically when entities change. For example: if you map a Docebo user to an external user and that Docebo user is then deleted in the platform, the mapping between that user and the external entity is updated, allowing the integration to apply business logic such as deleting the corresponding external user.

Supported platform events

Integrations can choose which events to subscribe to when creating or updating an External IDs integration. The following platform events are supported:

Prerequisites

Before you use the External IDs connector, ensure that:

• Docebo Connect is active on your platform and you can access it from the Admin Menu > Docebo Connect > Manage entry.
• You have the permissions required to manage projects, connectors and recipes in Docebo Connect.
• You are familiar with the basic concepts of connectors, connections and recipes in Docebo Connect, as described in the Docebo Connect and Docebo Connect: Glossary of terms articles.

Accessing the External IDs connector in Docebo Connect

To access the External IDs connector, log in as a Superadmin and open the Admin Menu. Find Docebo Connect and press Manage. In your project, create or open a recipe. Add a step of type Actions in app and search for Docebo Learn - External IDs in the list of connectors. Select the existing connection for the Docebo platform when prompted.

You can then choose one of the connector actions described in the following sections.

Overview of connector actions

The Docebo Learn - External IDs connector supports four core actions:

• Create integration
• Update integration
• Run commands
• Query entities

Each action is described in detail below.

Create integration

The Create integration action registers a new integration in the External IDs service for the current platform domain. When you run this action, the External IDs service adds the integration to External IDs for the specific domain, creates a dedicated database for the domain if one does not yet exist, generates a unique integration UUID and a pre-shared key (PSK) for the integration and stores the salt and hashed PSK in the External IDs data store. The registered integration is activated by default and the action subscribes it to the selected events on the event bus.

Input fields

Output fields

Please note: You must store the uuid and psk values in a secure and retrievable location, such as a Docebo Connect lookup table or environment properties. The External IDs service does not expose an API to retrieve these values later, so they cannot be recovered if they are lost.

Update integration

The Update integration action updates an existing integration in the External IDs service. You can use it to change the integration name, activate or deactivate the integration and update the list of subscribed events.

Input fields

When you run Update integration, the integration configuration is updated with the provided values and the selected events are subscribed on the event bus for that integration.

Please note: If you deactivate an integration by changing its status to inactive, subsequent Run command executions for that integration will not have any effect until you reactivate it.

Run commands

The Run commands action sends commands to the External IDs command queue for a specific integration. Each command describes a mapping operation that associates a Docebo entity with a corresponding external entity, or that resets an existing mapping. Once the commands are queued, the External IDs consumer processes them and stores the resulting mappings.

Input fields

The exact combination of required fields depends on the command you select.

Supported commands

The table below lists the available commands and their required fields. All fields are mandatory, except where noted.

When you run Run commands, the specified commands are queued and processed and mappings are created, updated or reset according to the command semantics. The action output includes information about successful and failed items when you test the recipe in Docebo Connect.

Disclaimer: External IDs can map via any additional field defined by the integrator. That field could contain personally identifiable information (PII). Docebo does not take responsibility for which fields the integrator chooses to store in the service. Additionally, Docebo does not automatically delete or anonymize users in Docebo when they are deleted in a third-party system. To clean up any data in the service, the integrator must create the appropriate integration logic.

Query entities

The Query entities action invokes the query service in the External IDs infrastructure. You can use it to retrieve mappings and related metadata that were created through Run commands. This action lets your integration query and filter mappings based on time ranges, metadata and entity types.

Input fields

Entities and internal IDs

The entity fields represent the internal Docebo identifiers for the entities you want to query. For each entity type, you can specify lists of IDs as follows:

Time-based query filters

You can filter records based on when they were created, updated, deleted, matched or touched. The following filters are available:

• Created at from / Created at to
• Updated at from / Updated at to
• Deleted at from / Deleted at to
• Matched at from / Matched at to
• Last updated at from / Last updated at to
• Touched at from / Touched at to

These filters can be combined with metadata filters to restrict the result set.

Output fields

The Query entities action returns a list of mappings. Each item can contain the following fields, depending on the entity type and the command that created the mapping:

• integration_id
• external_id
• internal_id
• internal_uuid
• mapping_id
• user_id
• session_id
• course_id
• learning_plan_id
• created_at
• updated_at
• deleted_at
• matched_at
• last_updated_at
• metadata

When you run Query entities, the External IDs query service retrieves mappings that match the provided filters and results are paginated according to the Page and Page Size settings. You can then process the returned mappings in your recipes. This can be useful, for example, to synchronize data with a third-party system.

Best practices

• Run Create integration once for each external integration and securely store the generated uuid and psk values in a lookup table or environment properties.
• Use Update integration to change names, statuses or subscribed events rather than creating a new integration.
• Design Run commands steps so that mappings are idempotent where possible, especially when commands can be retried.
• Use Query entities with specific metadata and time filters to limit the amount of data returned and reduce processing time.