Link Connection Widget

The Link Connection Widget is used if you want to present your end users with an easy way to connect applications and sync data including Accounting, Payroll and Commerce.

To sync business information from your customers' connected apps (e.g. Quickbooks, Salesforce, Stripe) you need to:

1. Provision an account to store your customers' data 

2. Display a menu of applications or data types to connect to and then get your customers' permission to access data via the Link Connection Widget.

3. Use the API to pull the business information you need

If you don’t want to use the Link Connection Widget and would prefer to build your own connection UI see Connector API below.

Provision an Account

Before a customer can begin to share information a customer account needs to be provisioned to hold data synchronized for that specific business customer. To create a new account you need to make a POST request to the account administration API.

As part of the account creation, you will specify a secret password/key which you will need to store and reference in subsequent steps. You will also need to specify a subdomain, which should be generated with a reasonable degree of uniqueness because the account creation request will fail if the provided subdomain is already in use. The response from successfully creating an account will contain account_domain, subdomain and account_key fields that you should store for subsequent reference.

Link Connection Widget

The Link Connection widget will list all supported Apps (by name or data type) and handle credential validation, multi-factor authentication, and error handling for each app that we support. The Link connection widget works across all modern browsers and platforms including mobile (iOS, Android) and web) and automatically handles many implementation details.

Example integration flow for connecting to a end-user applications to access business data:

Consent and Connect

To connect a customer's business application software you first need to get their permission to access their account by connecting the App. Once the App is connected you can make subsequent API calls to gather data.

Embedding

To embed the Link widget into your web application you need to include a reference to a JavaScript file and create an HTML DIV tag within your page to render the widget within. This DIV tag will contain the application listing.

The container DIV tag:

<div class="DockLink_AppList"></div>

The link widget does not use HTML iframes as many of the APIs we connect to use OAuth to authenticate the end user which is not compatible with frames

In order to access data you need to decide what type of data you want your user to provide and then display to them a list of app connection options that deliver the data. Platform types and example data sets include:

• Accounting (tag: accounting)

  • Financial ratios and probabilities

  • Financial statements

  • AR/AP

• Commerce (tag: commerce)

  • Subscriptions (inc recurring payments)

  • Purchases

  • Payment methods

  • Customers

  • Shipments

  • Sales

When embedding the link connection widget a set of platforms can be provided to limit the list to the types of information required.

The widget embed script:

<script type="text/javascript" src="https://example.myintranetapps.com/dock/link/2022-09-08/link.js"></script>
<script>
  var widget = new DockLink({
    container: document.getElementsByClassName('DockLink_AppList')[0],
    name: "Example Financial Institution",
    brand: {accent:'#FF0000'},
    domain: "{{ ACCOUNT_DOMAIN }}",
    cancel: "https://example.com/user-cancelled.html",
    redirect: "https://example.com/connection-complete.html",
    platforms: ['accounting','commerce'],
    filteredIntegrationsList: ['accounting_app1', 'accounting_app2', 'commerce_app2'],
    token: "{{ EMBED_TOKEN }}"
  });

  widget.render();
</script>

Content Security Policy (CSP) issues? JS/CSS not loading? See Browser Security

• The domain of the src="https://example.myintranetapps.com/dock/link/2022-09-08/link.js" attribute should be changed to your domain. (Replace example.myintranetapps.com with your domain).

• When you provision an account, the Administration API response contains an account_domain value that should be used here for the domain parameter. (Replace {{ ACCOUNT_DOMAIN }} with the newly provisioned account’s account_domain value.)

• You will need to generate an embed token.

The following configuration values can be set when initializing the widget:

Pull business information

After a connection has been established you can make API calls to the common data model and call upon different business data objects as shown in our examples.

Browser Security

Do not embed the widget within a html iframe, many integrations utilize OAuth and based on OAuth specs will block loading when requested from within a frame.

CORS Access

If you get errors in your browser about Access-Control-Allow-Origin you need to add the domain name you will be embedding the widget from to the allowed list of URLs. In the admin portal go to the “Embed” menu and then add the URL for your app and click save, the URL will then be added to a list that is allowed to embed the widget

Content Security Policy (CSP)

Embedding the link widget will result in external resources being loaded in to your page. These resources will come from your Boss Insights domain e.g. example.myintranet.apps , if you use a content security policy (CSP) header within your application you will want to add this domain to the list of allowed domains that can reference resources. Depending on widget configuration additional scripts, frames, images and stylesheets may be loaded.

Framing

The widget should not be embedded within a frame, many integrations utilize OAuth, the spec for which recommends blocking attempts to load inside of a frame.

If you see browser console errors related to framing ensure you are not loading the widget within a frameset.

Connector API

If you want to build your own user interface to present connection options to your customer without using our premade widget you can manage this process yourself. Please see our Creating Your Own Connection Interface page to get started.

You’ll need to redirect your users' browser to a specific URL to connect an application.

Please contact our support if you require additional assistance.