jadu
Integrations Design Manual

Updated 7 months ago

Integrations Design Manual

Continuum Integrations are a highly technical feature, often linking together separate systems and software using technical terminology like port numbers, timeouts and access tokens. Great care should be taken to design the integration to help the user understand what information they must supply and where they can find it.

Integrations hub

The integrations hub lists all of the currently available integrations available within a given Continuum product using a Pulsar 'piano' layout, listing the integrations as tabs on the left and their configurations on the right.

Integration tab

The tabs content is marked up as a standard media object, using Pulsar's html.media() object.

{{
    html.media({
        'image': '/path/to/images/office365.png',
        'image_alt': 'Office365 logo',
        'title': 'Office 365',
        'description': 'Access Outlook calendars within your CMS'
    })
}}

Tab icon

Allows an integration to be branded to make them more recognisable, you should use authorised brand assets where possible, taking care not to break any brand guidelines.

  • Images should be 100 x 100px square (will be displayed at 50px square)
  • should have a transparent background
  • should be added to the repository, don't link to externally hosted assets

Instead of an image you could use a FontAwesome icon to illustrate the tab and define a specific colour value to match a company's brand, see the branding icons category.

{{
    html.media({ 
        'icon': 'youtube-square', 
        'icon_colour': '#e52d27', 
        'title': 'YouTube', 
        'description': 'Upload videos to your YouTube accounts' 
    })
}}

Tab title

The title should, ideally, be the name of the software being integrated.

e.g.

  • PayPal
  • YouTube
  • Office365

If a company name isn't widely known, or provides multiple services, you should make the title more descriptive as to the nature of the integration.

e.g.

  • Google Analytics
  • Google Drive
  • Google Maps
  • ESRI Maps

Some integrations won't relate to a specific company or software and should try and use the most obvious descriptive name.

e.g.

  • LDAP Authentication
  • Website Analytics
General guidance
Do Do not
Use title case, unless branding guidelines dictate otherwise (like YouTube) Add a trailing full-stop

Tab description

The description is a single line to provide extra information about what the integration does and can be used to clarify ambiguous titles.

Try to describe the integration in 10 words or fewer, the tab container has limited width and shouldn't break onto multiple lines.

A properly formed tab description should be able to complete the following sentence:

When enabled, this integration will allow you to [ .......... ]

e.g.

Title Description
LDAP Authentication Authenticate admins using your LDAP/AD server
Continuum CXM Allow users to sign into your website using their CXM credentials
Website Analytics Track visitors to your public website
General guidance
Do Do not
Use sentence case Add a trailing full-stop

Main integration user interface

An integration should use the 'masterswitch' layout pattern where possible, this provides a clear 'on/off' switch for an Administrator to enable or disable an integration in one easy step, and helps the person to understand whether an integration is currently active or not.

A brief description (one or two short paragraphs) should be put at the top of the settings view (above the masterswitch) to further explain this integration or to provide important information which may be needed to successfully set it up.

e.g. Inform the user how to find specific details on the external system they're integrating with.

You will find these details by signing into your Continuum CXM and navigating to Settings > System > Service APIs.

Permission to add service APIs will be required.

or

Add the tracking code from any analytics program like Google Analytics, Piwik, KISSMetrics, etc and it will be included in the footer of all pages on your public website.

Masterswitch control

The masterswitch pattern allows an entire UI to be disabled while the switch is in the 'off' position.

Disabling an integration should happen immediately and not require an extra 'save' or confirmation step, however after enabling the switch, the integration should not be activated until they have completed all required fields to configure the integration.

If disabling an integration is a potentially destructive action, you should use a confirmation modal to illustrate the impact of the action to the user.

Form fields

Because integrations are often highly technical in nature, you should use every opportunity to use help text to provide more context around a field

Be clear about what system a setting relates to, for example, if you're asking for a username, is that the person's username on System A, or System B?

Quite often you may need to allow an admin to configure server oriented variables, such as port numbers, timeouts and proxy addresses. You should provide sensible defaults for these where possible, giving the admin a higher likelihood of getting it right 'first time'. Choose your field type wisely, for example, if an integration only has a specific list of valid port numbers available, use a form.choice() helper instead of a free text input, reducing the opportunity for accidental errors.

If the admin needs to ask their sysadmin/network administrator for specific values, or to get ports unblocked, then it's useful to let them know upfront.

Tabbed integrations

For more complex integrations it may make sense to split the settings over multiple tabs.

The first tab should be active when the user enables the masterswitch, however you may need/want to disable the other tabs until some required information has been completed.

Use cases for this may include:

  1. User connects to the integrating system on the first tab
  2. Integration can now fetch data from the integrated system to allow further configuration on other tabs

.