Skip to main content

Integrations

Supported products
  • Central CMS
  • Central Forms
  • Central Connect

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.

Screenshot showing integrations hub example

Integrations tab

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

Office365 logo

Office 365

Access Outlook calendars within your CMS
{{
html.media({
'image': '/views/patterns/integrations/img/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
tip

Most of the time it will be necessary for us to create a new icon based on a product's brand assets, you should aim to find the most appropriate branding which would suit the square nature of the tab icon, avoid small wordmarks which would be unreadable at 50px, and aim to use as much of the available space as possible without extra padding.

The Pulsar team will be more than happy to assist in creating tab icons.

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.

Tab title

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

  • 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.

  • 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.

  • LDAP Authentication
  • Website Analytics

YouTube

Upload video to YouTube

Do use title case, unless branding guidelines doctate otherwise (like YouTube)

YouTube.

Upload video to YouTube.

Don’t use 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.

Office365 logo

Office 365

Access Outlook calendars within your CMS
Do explain what the integration will enable the users to do
Office365 logo

Office 365

Enable Office365 integration
Don’t simply explain what the integration process is

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

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

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.

Screenshot showing the layout of an integration

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.

Do keep the label consistent to indicate state
Don’t change the label to indicate the action that will be performed
Do use the label 'Enable Integration'
Don’t use product/service names

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.

Seconds
How long the system should wait for a response, usually 600 seconds (10 minutes)
Do use units of measure, and explain what the setting actually means
Don’t expect people to know what any of this means

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?

Find your personal token at https://github.com/settings/tokens
Do be clear about which system/software a value originates from, and where to find it
Don’t be ambiguous

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.

Screenshot showing the layout of a tabbed integration

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:

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