Integrations
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.
Integrations tab
The tabs content is marked up as a standard media object, using Pulsar’s html.media() object.
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
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 YouTubeYouTube.
Upload video to YouTube.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.
Office 365
Access Outlook calendars within your CMSOffice 365
Enable Office365 integrationA 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.
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:
- 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