Overview

The Link widget allows you to embed functionality from the Boss Insights platform in to your own software application.

The widget operates in two modes:

  1. Link Connection - you want to present your end users with an easy way to connect applications and sync data

  2. Link Page Element - you want to present forms, dashboards, insights, ratios, workflows and other page elements to gather data or inform your end users OR you want to present these to your own team

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

To present forms, insights and ratios (collectively known as page elements) you need to:

  1. Provision an account to store your customers data

  2. Request an embed token from the API

  3. Display a specific page element via the Link Page Element Widget

  4. Either use the API to pull captured information OR display pre-built dashboard elements within your own software application UI.

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.

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 customers 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 in to 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>
HTML

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: ['accouting_app1', 'accouting_app2', 'commerce_app2']
    auth: {basic: '{{ AUTH_BASIC }}'}
  });

  widget.render();
</script>
JS
  • 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 used here for the domain parameter. (Replace {{ ACCOUNT_DOMAIN }} with the newly provisioned account’s account_domain value.)

  • When you provision an account, you must create a password for the new account and keep track of it. For the auth parameter here, you should replace {{ AUTH_BASIC }} with the result of calling base64Encode("admin:password") in whichever programming language you use - JSPythonPHPJava. For example, if the password created when provisioning an account was “hello123”, you would replace {{ AUTH_BASIC }} with the result of base64Encode("admin:hello123").

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

parameter

required

type

definition

container

yes

htmlElement

The HTMLElement that the widget should render within

name

no

string

The name of your company that you want displayed within the widget

brand

no

Object

An object containing accent color and logo

domain

yes

string

The account domain of the business account to gather and share data with.

cancel

no

string

The URL a user is redirected to if they cancel the connection process

redirect

yes

string

The URL a user is redirected to once a connection is complete

platforms

no

array

An array of platforms that will be displayed in the widget, accounting and commerce are supported

filteredIntegrationsList

no

array

An array of the apps to filter which apps should be displayed in the widget. The widget will only display the apps listed in the array

auth

yes

Object

Authentication/Access information to allow an account connection to be made.

search

no

bool

Whether to show an app search

dataSecurity

no

string

URL to a security policy

terms

no

string

URL to a terms and privacy policy

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

The Link Page Element widget can display portions of the Boss Insights platform within your own software, either to your end users or in a back office portal your team accesses, e.g. as a provider of financial capital to small business I may embed the consent form for gathering tax records from my end users, then using another embed show my credit approval team specific ratios or document downloads based on information gathered.

Before a page element can be embedded an embed token must be requested via API, this token provides authorization to the Link Page Element widget.

Embedding

To embed the Link Page Element widget in to 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 page element.

The container DIV tag:

<div id="link_page_element"></div>
HTML

We recommend styling this containing element with CSS to set the width and height

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.getElementById('link_page_element'),
    domain: "ACCOUNT_DOMAIN",
    token: "EMBED_TOKEN",
    app: "company/forms",
    options:{
      key: "taxstatus"
    },
    onSuccess: function (data) {
      console.log('calling onSuccess callback with this data: ', data);
    },
    onError: function (data) {
      console.log('calling onError callback with this data: ', data);
    },
    onEvent: function (data) {
      console.log('calling onEvent callback with this data: ', data);
    }
  });

  widget.render();
</script>
JS
  • 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 request an embed token, the API response contains an account_domain value that should replace ACCOUNT_DOMAIN , the response also includes a token value, use it to replace EMBED_TOKEN.

After embedding the widget you may receive warnings in your browsers developer console, see the Browser Security section to understand some issues that can impact embedded widgets

The app parameter dictates the type of element that will be embedded, while options relate to the app and will vary depending on the app chosen.

Events

When an end user interacts with a widget certain events will be raised to your code to handle or ignore. the onEvent callback function you define will be provided with the event type and other properties depending on the event. For example when embedding a form for an end user to fill out an event will be raised when they have successfully submitted the form - you can then take appropriate actions via your javascript function such as updating progress indicators or redirecting the users browser to the next step in your software.

Note the onSuccess and onError callback functions are optional, if omitted the onEvent callback will be used.

Example Configurations

The following examples show some typical use cases for the Link Page Element widget. Each example requires a different type of Embed Token.

Example 1: Access your own account for a back office dashboard

<script type="text/javascript" src="https://example.myintranetapps.com/dock/link/2022-09-08/link.js"></script>
<script>
  var widget = new DockLink({
    container: document.getElementById('link_page_element'),
        
    domain: "ACCOUNT_DOMAIN", // your domain
    token: "EMBED_TOKEN", // token to access your own account
    app: "dashboard/insights-dashboard",
    options: {
      accountKey: '632364a5a046f7.42267761' // key of customer account
    },
		
  });

  widget.render();
</script>
JS

Example 2: Access a customer account so an end-user can fill in a form

<script type="text/javascript" src="https://example.myintranetapps.com/dock/link/2022-09-08/link.js"></script>
<script>
  var widget = new DockLink({
    container: document.getElementById('link_page_element'),
        
    domain: "ACCOUNT_DOMAIN", // customer domain
    token: "EMBED_TOKEN", // token to access a customer account
    app: "company/forms",
    options: {
      key: 'taxstatus' // the form to display
    },
		
  });

  widget.render();
</script>
JS

Example 3: Access your own account and review a customer’s form

<script type="text/javascript" src="https://example.myintranetapps.com/dock/link/2022-09-08/link.js"></script>
<script>
  var widget = new DockLink({
    container: document.getElementById('link_page_element'),
        
    domain: "ACCOUNT_DOMAIN", // your domain
    token: "EMBED_TOKEN", // token to access your own account and view a customer’s pages
    app: "company/forms",
    options: {
      key: 'taxstatus' // the form to display
    },
		
  });

  widget.render();
</script>
JS

Browser Security

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.