Customizing CRM Link

Options to change how CRM Link is launched

Apart from configuring how to access CRM data, the third argument to linkCRM can also be used to change the way in which CRM Link is launched.

Some common scenarios are covered below.

Specifying connection IDs

In the usage examples for CRM Link, we passed the context ID to the connectionID property in the options object. This effectively restricts a context to have a single CRM connection associated with it.

While this single connection per context mode is an easy way to setup and use CRM Link, you might want to manage multiple CRM connections per context or have finer control over the ID of the connections. This section will go into detail about how the connectionID option works.

The connectionID option can take any string as its value. If a CRM connection with that ID does not exist yet, CRM Link will prompt the user to authorize access to their CRM and a connection with that ID will be created.

If a CRM connection with that ID already exists, CRM Link will be re-launched for that connection, allowing your user to review and modify the configuration done by them previously. In this mode, the user completely bypasses the authorization step.

This means that you can allow multiple CRM connections per context by simply passing different connection IDs to the connectionID option.

If you do not pass a value for the connectionID option, CRM Link will always prompt the user to authorize access to their CRM and a randomly generated connection ID will be created and used. You can use this approach to also allow multiple connections per context.

However, a fairly common pattern is for the user to authorize access to their CRM instance and then navigate away to finish the mapping at a later time. It's a good idea to re-launch CRM Link by specifying a value to the connectionID option the next time such that they don't have to perform the authorization again.

You can obtain the list of existing CRM connections by querying the Xkit API.

Request

GET /api/platform/contexts/<contextID>/connections HTTP 1.1
Host: app.xkit.co
Authorization: Basic <credentials>

Response

200 OK
Content-Type: application/json

{
  "connections": [
    {
      "id": "fd219dbb-e744-4d19-bd0a-84883dd8e05c",
      "enabled": true,
      connector: {
        "name": "Sales Cloud (CRM Link)",
        "slug": "salesforce-sales-cloud-crm",
        "crm": true
      }
    },
    {
      "id": "e556ba7f-a93e-43ae-9f66-b0415e8538ae",
      "enabled": true,
      connector: {
        "name": "HubSpot (CRM Link)",
        "slug": "hubspot-crm",
        "crm": true
      }
    }
  ]
}

If you are using Xkit generated connection IDs instead of passing your own, you can use the connection IDs from this API to re-launch CRM Link appropriately.

Rendering by status of connection

We recommend calling linkCRM via a button click or other user interaction. It is a good idea to have a distinction between when CRM Link will be launched to create a new CRM connection and when CRM Link will be re-launched for an existing connection. This can be shown in the button title for example so that your application and user are aware of the interaction that is going to follow.

We have some recommendations on the rendering strategies you can use to accomplish this. The examples below are in React and make use of Xkit generated connection IDs.

Single connection per context

When you have a single connection per context, a recommended approach is to also have a single button for CRM Link.

You can query the API to know if a CRM connection already exists or if one needs to be created.

// Call your backend route to fetch list of connections
const { connections } = await fetch('/xkit/connections')

const launchCRMLink = async (connectionID) => {
  const { token } = await fetch('/xkit/token')
  try {
    await linkCRM('example.xkit.co', token, { connectionID })
    // CRM linked successfully
  } catch (error) {
    // CRM link failed, display an error to the user
  }
}

export default function App() {
  if (connections.length) {
    return (
      <button onClick={() => {
          launchCRMLink(connections[0].id)
      }}>
        Edit CRM Mapping
      </button>
    )
  } else {
    return (
      <button onClick={() => {
          launchCRMLink()
      }}>
        Connect CRM
      </button>
    )
  }
}

Multiple connections per context

When you have multiple connections per context, we recommend that you query the API for the list of connections and render a button for each connection listed which will re-launch CRM Link to reconfigure them; and an additional button with that will allow the user to create a new CRM connection.

// Call your backend route to fetch list of connections
const { connections } = await fetch('/xkit/connections')

const launchCRMLink = async (connectionID) => {
  const { token } = await fetch('/xkit/token')
  try {
    await linkCRM('example.xkit.co', token, { connectionID })
    // CRM linked successfully
  } catch (error) {
    // CRM link failed, display an error to the user
  }
}

export default function App() {
  return (
    <>
      {connections.map((connection) => (
        <button onClick={() => {
          launchCRMLink(connection.id)
        }}>
          Edit CRM Mapping
        </button>
      ))}
      <button onClick={() => {
        launchCRMLink()
      }}>
        Connect CRM
      </button>
    </>
  )
}

Preselecting a CRM

For various reasons, you might want a user to only link a particular CRM. For example, you may have gathered information on which CRM your user has, or maybe you have different buttons for linking different CRMs.

In such a scenario, you can launch CRM Link such that the user gets to link only that particular CRM.

Here's what that looks like. In this example, we've preselected Salesforce as the CRM:

Preselecting a CRM for linking

To preselect a CRM, pass the CRM slug to the preselectCRMSlug property of the options object.

You can find the CRM slug from the Xkit Developer Portal by navigating to the "CRMs" menu item, selecting the relevant CRM, navigating to the "Setup" tab and looking at the value for the URL Slug field.

URL Slug field in CRM settings

Here's an example of how you would call linkCRM with a CRM preselected.

await linkCRM('example.xkit.co', token, {
  objects: {
    // Mapping definition for CRM objects
  },
  preselectCRMSlug: 'salesforce-sales-cloud-crm'
})

Ready to build your CRM app?

Integrate every CRM with one build, request access to get started.