Creating Your Own Connection Interface

Follow this guide on building your own user interface to present connection options to your customer without using our premade widget.

Prerequisites:

Before getting started it is necessary to have an:

Account with Boss Insights. More information on creating accounts can be found at this link: Accounts . This will provide you with a link to the account domain that will follow the format of my-company.myintranetapps.com.
Embed Token. You will also need a token provided by Boss Insights. Please note that these tokens are consumed after use and will set a cookie. You will only need to use the token once and any further requests will not require the token. For instructions please visit: Embed Token

Embed tokens are only valid for one hour after they are generated.

Imagine your embed token as a ticket to an event, and the links where you are using the token as ticket booths. When you present your ticket/token, you will receive a wristband/cookie that allows you to access the event without having to show your ticket again for the next hour. In other words, you can skip providing the token when accessing future requests during that time.

Authorization:

Step 1: Get a List of Integrations

If you already have the integration keys, you may proceed to Step 2.

You may choose to connect to one or many integrations. To get a list of all integrations, please use the JSON/AJAX request below. Please use your account domain in replacement of accountDomain and your token in replacement of embedToken. Please see prerequisites for reference.

CODE

https://${accountDomain}/integrations-list.php?embed=${embedToken}

Please reference this table for category descriptions of above image.

Please take note of the Integration Key found on Line 6 for each separate integration you would like to add. This will be used to authorize later.

Category Line	Category Description
0	Name of the Integration.
1	Description of the Integration.
2	Path to logo.
3	Background colour for logo.
6	Integration key, used to connect the integration.
7	Integration supported. If you see YES, you can connect. If you see NO, more configuration is required.
8	Integration connection. A Boolean value showing whether integration is currently connected or not.
9	Connected company name. If the integration is connected, the company name will show here.
10	Categories that this integration belongs to. The first listed is the primary category for integration, any further listed are secondary. Categories are delimited by a comma. Please note that not every integration will be categorized. In the example provided the primary category for quickbooks is Accounting and the secondary is Finance.

Step 2: Build your own User Interface

You are now able to design and create your own interface. Please include buttons, links, or script to present your custom connection options seen in Step 3.

Step 3: Authorize the Connection

Your connection buttons should link to this for authorization:

CODE

https://${accountDomain}/dock/pre-auth.php?redirect=${redirect}&domain=${accountDomain}&service=${service}&embed=${embedToken}

If you have already used the embed token generated (e.g. in Step 1) then you do not need to use it again. In this case, please omit &embed=${embedToken} from the request above.

Please reference this table for variable names and their descriptions:

Variable Name	Description
accountDomain	The domain comes from the response you get from prerequisite. It is the domain name assigned to your business customer. Please see prerequisite for reference.
redirect	Where you would like the user to be redirected after they’ve authorized.
service	The integration you are trying to authorize connection to e.g. quickbooks. This is the integration key from Line 6 in Step 1.
embedToken	An embed token obtained from Boss Insights. Please see prerequisites. If you have already used the embed token generated (e.g. in Step 1) then you do not need to use it again. In this case, please omit `&embed=${embedToken}` from the request above.

Deauthorization:

If you would like to deauthorize a connection please follow this link Connections for more information.