Build your own Catalog

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:

1. The boolean enabled flag
2. The status field of an authorization (and the authorization'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:

1. Create a connection
2. Repair a connection
3. 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!