Build your own Catalog
A fully customized experience
If you want full control over how users interact with the Integration Catalog beyond what's available in the embedded catalog, you can use our libraries or APIs to fully customize the experience.
Building a Custom Catalog with xkit.js
xkit.js exposes all of the functions you need to build a fully custom catalog experience.
xkit-catalog.js (our embedded catalog) is an open source implementation of a catalog which itself uses only the public APIs exposed by xkit.js. It is a good starting point for anyone looking to implement their own catalog.
Overview
A custom catalog should include 3 components:
- A list of available connectors
- Details about a specific connector
- Actions to take for a specific connector
We'll address these components and how to use xkit.js to build them.
List of available connectors
Most integration catalogs which contain more than one connector will have some way for a user to view the available connectors. With xkit.js, you can retrieve the available connectors by calling the listConnectors
function.
listConnectors
returns a list of Connector objects with enough information to render both descriptive information and current status. An example is below:
const connectors = await xkit.listConnectors()
console.log(connectors)
// [
// {
// name: "Slack",
// slug: "slack",
// short_description: "Connect to slack for great success",
// mark_url: "https://example.com/slack.png",
// connection: {
// enabled: true,
// authorization: {
// status: active
// }
// }
// }
// ]
Connector Details
A catalog may also provide more detail about a specific connector and its status. That can be retrieved using getConnectionOrConnector
which returns the user's connector, if it exists, along with the details of the connector. The difference between this call and listConnectors
is that it includes the longer description
field (specified in the developer portal) and about
field for more details about the connector.
Connection Status
The status of a connection can be interpreted by two elements:
- The boolean
enabled
flag - The
status
field of anauthorization
(and theauthorization
's existence)
If a connection is not enabled
, that means that the user has either never installed it, or they have installed it and subsequently removed it. enabled
does not tell you about the status of the connection itself, only if a user has ever installed the connector.
If an authorization
does not exist, that means that we have no completed authorizations for a user. This typically only happens with an enabled
flag of false
. If the authorization
status is active
, that means that we have an active connection. Any other authorization
status paired with an enabled
value of true
means we are in some kind of errored state - the user has installed the connector, but the authorization is not correct.
If you are using the npm package, xkit.js
exposes a helper, connectionStatus
which you can import from @xkit-co/xkit.js/lib/api/connection
to return 3 enum values to help determine status.
Actions a user can take
Within a catalog, a user can take three actions:
- Create a connection
- Repair a connection
- Remove a connection
Create connection
To establish a new connection, use the addConnection
function on xkit.js. It takes a connectorSlug
as its first parameter (and required). It returns a promise, which, when resolved, will contain the active and enabled connection. In the case of an error, it will throw an Error
which has a descriptive message to be displayed to the user.
const slackConnection = await xkit.addConnection("slack")
addConnection
should be used when installing a new connector, or when a connector has been previously been removed by the user.
Repair a connection
If a connection is in an errored state (see Connection Status above), you should use reconnect
to repair it. It takes the existing Connection
object as its only parameter. Otherwise, it behaves like connect
.
let slackConnection = await xkit.getConnectionOrConnector("slack")
if (slackConnection.enabled && (!slackConnection.authorization || slackConnection.authorization.status !== "active")) {
slackConnection = await xkit.reconnect(slackConnection)
}
Remove a connection
If a user no longer wants to use a particular integration, they can remove it with a call to removeConnection
. Like connect
, it takes the string connectorSlug
as its only parameter. It returns a promise which will resolve when the the connection is removed.
await xkit.removeConnection("slack")
Further Support
If you're building a custom catalog and need additional help or support, or features that you don't see listed in our SDK, please contact us!
Updated about 3 years ago