Important To Me Customization Wizard
If you havenâ€™t discovered it by now, the Important-To-Me (or ITM) bar is part of the OrientMe experience in IBM Connections. It can be used to keep your most important contacts close to hand, as well as your most important communities, giving you quick access to their content within OrientMe. The ITM bar has some built-in customization features, allowing users to control what contacts & communities are shown and also allowing organization administrators to customize the ITM bar for their organization.
One such customization is the ability to add a completely custom ITM bubble to the bar. Each individual contact or community on the ITM bar is referred to as a bubble. Connections users have control of the favorite bubbles that they want to always appear on their ITM bar, but administrators can also add bubbles to the bar that are visible to all users in the org. This can be useful to highlight upcoming events, highlight important employees or highlight important communities within the organization, for a limited time or permanently on the ITM bar.
In this blog post, we are going to look at an example use case for this and describe how an org admin can make it happen with ease. The admin doesnâ€™t need to know or write any code, instead they just follow the steps of a configuration wizard to build a custom ITM bubble and deploy it to the ITM bar org-wide. So letâ€™s get started.
The Use Case
To help demonstrate this customization feature of the ITM bar, weâ€™ve imagined a use case for a company called Greenwell. They use a number of collaboration tools within the company, and so they want to add a bubble to the ITM bar providing quick links to access all of them. This quick-link bubble will incorporate links to IBM Verse, Watson Workspace, Slack and Microsoft Teams, all of which are used by Greenwell employees around the world.
The Creation Process
In order to create the desired feature for the Greenwell org in IBM Connections, an organization administrator needs to use the App Registry to create a new application. To access the App Registry they must:
- Open the administration area of IBM Connections Cloud
- Click the â€śOrganization Extensionsâ€ť menu option
- Click the â€śNew Apps Managerâ€ť link
Figure 1 â€“ App Registry
From there the administrator can begin the process for creating their custom bubble applications, by clicking the â€śNew Appâ€ť button and following the steps below.
- Enter a name and description for the application, then click â€śNextâ€ť
Figure 2 â€“ Basic Application Information
Under the covers of the user interface, the app registry is already generating the JSON data that defines your application. Ultimately your customization application is stored as JSON data inside the app registry, but by using the ITM bubble wizard you need not write, edit or even look at the JSON representation of your application. We will review the resulting generated JSON at the end of the creation process, but for now letâ€™s focus on creating the application. The next step is to add an extension to the application.
- Click the â€śNew Extensionâ€ť button
- Choose â€śImportantToMeâ€ť in the â€śServiceâ€ť dropdown
- Choose â€ścom.ibm.itm.entry.customâ€ť as the â€śExtension Pointâ€ť
- Enter a unique name for this extension
- Choose â€śOrientMeâ€ť as the â€śPathâ€ť
Figure 3 â€“ New Extension page
The service specifies that we want to create a customization for ImportantToMe in Connections. The path property specifies that this customization will apply to the ITM bar loaded by OrientMe. And the extension point specifies that we want to create a custom entry for the ITM bar.
When you select â€ścom.ibm.itm.entry.customâ€ť as the extension point, you may notice an additional button appears on the page, the â€śLaunch Wizardâ€ť button. Once you have entered all of the details listed above, you can click the â€śLaunch Wizardâ€ť button to open the â€śImportantToMe Custom Bubble Wizardâ€ť. This tool is designed to guide you through the process of creating your custom ITM bubble. Behind the scenes this tool will generate the necessary JSON data for your custom bubble, based on the data you enter.
- Enter a â€śBubble Titleâ€ť, which is the text that appears when you hover your mouse over the bubble.
- Choose â€śURLâ€ť as the â€śBubble Handlerâ€ť.
- Enter the â€śBubble Handler URLâ€ť. For our example, we use the Verse homepage.
- Enter the â€śIconâ€ť URL. (Note that you can also enter a base64 encoded data image here if you choose.)
- The â€śExpiresâ€ť property allows you to set a date when this bubble will expire. After that date, the bubble would no longer appear on the ITM bar. For our example we will leave the Expires field blank, so the bubble never expires.
As you follow the steps, you will see on the right hand side of the wizard that there is a preview of the bubble that you are building. This is a helpful visual representation to confirm that you are creating exactly what you want.
Figure 4 â€“ ImportantToMe Custom Bubble Wizard, General tab
After entering the General information for our bubble, we can move on to the other tabs in the wizard.
- Click on the â€śHighlightâ€ť tab
- Deselect the â€śShow Highlightâ€ť option
Figure 5 â€“ ImportantToMe Custom Bubble Wizard, Highlight tab
For this example, we wonâ€™t be using the â€śHighlightâ€ť. By default the highlight appears as a red circle on the top right of the bubble. It can be visually customized using the â€śHighlight iconâ€ť and â€śStyleâ€ť fields. Also you can customize the text that appears when hovering over the highlight. But since we are deselecting â€śShow highlightâ€ť, the highlight icon will be hidden from view for this example, as you can see in the preview area of figure 5 as compared to figure 4.
Next we will add our custom actions to the bubble. The actions appear as miniature bubbles on top of the main bubble, whenever a user hovers their mouse over the bubble. The default example of this is for people that appear on the ITM bar. When you hover over a person on the ITM bar, their bubble shows three actions, â€śinfoâ€ť, â€śchatâ€ť and â€śmailâ€ť. Clicking on each of these actions then triggers some associated action. For example, the mail action will open a new mail in your mail client addressed to the person in question. For our example, we will be adding three custom actions that open up a different social collaboration tool when you click on each of them.
- Click on the â€śActionsâ€ť tab
- Click the â€ś+â€ť button
- Enter the title, URL, icon and hover text. In our example, the first action we add is for Watson Workspace
- Then click â€śSave Actionâ€ť
Figure 6 â€“ Adding a Watson Workspace action to the bubble
Then you need to click the â€śSaveâ€ť button, which will add your custom ITM bubble extension into your application. And finally click the â€śSaveâ€ť button once more to save the application itself into the app registry.
Figure 9 â€“ The finished application in the app registry
To see the result of the bubble we have created, any user logged into the Greenwell organization will see the custom bubble in the ITM bar on the OrientMe homepage, as in the image below.
Figure 10 â€“ Custom Bubble appearing on the ITM bar
And once you hover the mouse over the bubble, the title text of the bubble and the custom actions appear. Clicking on any of the actions will open the associated URL in a new browser tab.
Figure 11 â€“ Custom bubble with actions showing on mouse hover
Throughout the process of creating the custom bubble, the administrator never had to deal with any of the JSON data that is typical when creating applications in the app registry. But as previously stated, behind the scenes the JSON data is automatically generated and this is what is saved into the app registry in our example.
“name”: “Social Collab Tools”,
“title”: “Social Collab Tools”,
“description”: “A custom ITM bubble for quick access to social collaboration tools”,
“name”: “Social Quick Links”,
“name”: “IBM Verse”,
“label”: “Watson Workspace”,
“type”: “Microsoft Teams”,
“label”: “Microsoft Teams”,
Instead of working with JSON, the administrator merely followed the steps, filled in the form values, visually inspected the preview and saved their work. And if they ever need to change the bubble, they can re-open the wizard to make some alterations. All in all an easy to follow process for creating a Connections customization.
Advisory Software Engineer, IBM Collaboration Solutions