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
     
    Connections Administration area
    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.

  1. Enter a name and description for the application, then click “Next”
     
    Basic Information area
    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.
  2. Click the “New Extension” button
  3. Choose “ImportantToMe” in the “Service” dropdown
  4. Choose “com.ibm.itm.entry.custom” as the “Extension Point”
  5. Enter a unique name for this extension
  6. Choose “OrientMe” as the “Path”
     
    New extension page
    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.

  1. Enter a “Bubble Title”, which is the text that appears when you hover your mouse over the bubble.
  2. Choose “URL” as the “Bubble Handler”.
  3. Enter the “Bubble Handler URL”. For our example, we use the Verse homepage.
  4. Enter the “Icon” URL. (Note that you can also enter a base64 encoded data image here if you choose.)
  5. 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.
 
Bubble wizard
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.

  1. Click on the “Highlight” tab
  2. Deselect the “Show Highlight” option
     
    Bubble wizard highlight tab
    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.

  1. Click on the “Actions” tab
  2. Click the “+” button
  3. Enter the title, URL, icon and hover text. In our example, the first action we add is for Watson Workspace
  4. Then click “Save Action”
     
    Bubble wizard save
    Figure 6 – Adding a Watson Workspace action to the bubble

Next we follow the same procedure to add an action for Slack.
 
Adding a Slack action
Figure 7 – Adding the Slack action

And lastly we add an action for Microsoft Teams.
 
Adding a teams action
Figure 8 – Adding the Microsoft Teams action

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.
 
Finished application in registry
Figure 9 – The finished application in the app registry

The Outcome

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.
 
Custom bubble in ITM bar
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.
 
custom bubble with actions
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”,
“services”: [
“ImportantToMe”
],
“extensions”: [
{
“name”: “Social Quick Links”,
“type”: “com.ibm.itm.entry.custom”,
“payload”: {
“id”: “dbcabe9a-c279-4a65-abf4-4306b2da4001”,
“name”: “IBM Verse”,
“showHighlight”: false,
“show”: true,
“metadata”: {
“exId”: “dbcabe9a-c279-4a65-abf4-4306b2da4001”
},
“icon”: {
“url”: “http://i65.tinypic.com/nqo3zs.jpg”,
“alt”: “”
},
“handler”: {
“url”: “https://mail.notes.na.collabserv.com/”
},
“actions”: [
{
“type”: “Watson”,
“icon”: {
“data”: “http://i66.tinypic.com/33ygkeu.png”,
“type”: “png”
},
“label”: “Watson Workspace”,
“handler”: {
“url”: “https://workspace.ibm.com/”
},
“enabled”: true
},
{
“type”: “Slack”,
“icon”: {
“data”: “http://i63.tinypic.com/s65941.png”,
“type”: “png”
},
“label”: “Slack”,
“handler”: {
“url”: “https://slack.com/”
},
“enabled”: true
},
{
“type”: “Microsoft Teams”,
“icon”: {
“data”: “http://i64.tinypic.com/2hz0ft3.jpg”,
“type”: “png”
},
“label”: “Microsoft Teams”,
“handler”: {
“url”: “https://teams.microsoft.com/”
},
“enabled”: true
}
] },
“path”: “OrientMe”
}
] }

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.


Brian Gleeson
Advisory Software Engineer, IBM Collaboration Solutions

Join The Discussion

Your email address will not be published. Required fields are marked *