How It Works
Versori Embedded is broken down into the following key concepts:
- Hubs
- Integrations
- End Users
- Activations
Hubs
A Hub is the entrypoint into Versori Embedded, all other entities are encapsulated by a Hub. Typically most users will only require a single Hub, however using multiple is possible.
Primary Connector
Each Hub is created with a Primary Connector, this is a Connector that represents your own application for which the integration hub is built around.
When defining your Primary Connector, if there are multiple Authentication Methods available, you will also choose which method should be used by your End Users.
Secondary Connectors
Secondary Connectors are in planning stages and are not yet available, however the concept allows defining multiple Connectors which may be used by your End Users, but is not specifically related to a single Integration. This allows for more complex deployments where your application may have multiple APIs which cannot be onboarded into Versori as a single Connector.
If this functionality is required, please reach out to support to discuss your requirements.
Integrations
An Integration is implemented as a Board which defines workflows and data transformations between your Primary Connector (and if applicable, any Secondary Connectors) and other external Connectors. However, these Boards are different to regular boards created through Versori Integrate in that Connections do not need to be defined before deploying the Integration. Instead these Boards use Connection Templates, which define how an End User should connect to the Connector.
Connection Templates
Every Connector within a Versori Embedded Integration may either be pre-connected with a regular Connection, or declared as a Connection Template. When an End User activates an Integration, they must provide connection details for each Connection Template in that Integration.
When a Connection Template is created, if the connector supports multiple Authentication Methods, you also must choose which method should be used by your End Users. When building your embedded integration hub in your own application, you may choose to override this method when creating a Connection for an End User.
End Users
An End User is a user of your application who has access to your integration hub and can activate integrations. End
Users are created with an externalId
which is unique to the Hub in which they belong.
It is recommended to use the same user ID which you assign to your users in your own application, however this is not mandatory.
When an End User is created, their connection details for the Primary Connector must also be defined, and optionally any Secondary Connectors which are available to them. An End User must exist before the first Activation can be created.
All API endpoints which reference an End User (either by path or query parameters) may reference that user by Versori’s
own End User id
field, or by their externalId
which is determined by you. Additionally, all endpoints which are
designed to be consumed by End Users (prefixed with /embed/:hub_id/users/:user_id
) may be called referencing an End
User which may not yet exist, and the API will respond like the End User is not connected. This allows for rendering the
UI elements of your integration hub before the user actually exists within Versori.
Activations
An Activation maintains the state that an End User has activated an Integration. In order to create an Activation, the End User must provide connection details for each Connection Template in that Integration. This may be achieved by referencing an existing Connection which the End User has already created, or by creating a new one.