IBM Connections Customizer is available! What's New?

New release on IBM Connections Cloud

The formal release of IBM Connections Customizer on IBM Connections Cloud took place on Friday, December 8th 2017. This means that any tenant organization of IBM Connections Cloud on the North America or Europe data centres can now sign up for this new production offering and use it to modify the out-of-the-box IBM Connections user experience.

The production release of Customizer follows a lengthy pilot program which kicked off in July and ran for six months. Many customers and business partners engaged with the technology during the pilot phase and gave invaluable feedback in terms of feature requests, bug reports, use cases, and so on. As a result, several things have changed for the better in the production release.

What’s New in Customizer?

Customizer applications are now deployed in IBM Connections Cloud differently. Take the following simple sample:

Listing 1. Hello World Customizer App
1  {
2   "services": [
3     "Customizer"
4   ],
5   "name": "Simple Customizer Sample",
6   "title": "My First Customizer App",
7   "description": "Perform a modification to the Connections Homepage",
8   "extensions": [
9     {
10 	  "name": "Hello World Extension",
11      "type": "",
12 	  "path": "homepage",
13       "payload": {
14         "include-files": [
15           "helloWorld/helloWorld.user.js"
16         ],
17         "include-repo": {
18           "name": "global-samples"
19         }
20       }
21     }
22   ]
23  }

A new include-repo property features prominently in the JSON design markup for all production apps (see lines 17-19 above). This property identifies the location of the files that Customizer injects into the http response to perform a UI modification. The include-repo is a reference to a repository that exists in one of two possible GitHub organizations, namely:

IBM has a private organization that it uses to provide its own samples and other Customizer offerings like the Visual Update for IBM Connections. To the majority of users however, it is the public IBM Connections Developer organization that is of more interest. Any repository created there can be referenced as an include-repo in a Customizer app by any tenant organization … so how does that work?

Working with Repositories

To inject your own include-files into a Customizer app, you need a GitHub repository on the public organization. Typically, developers have their own repositories that they use to manage the source code for an app. In the case of Customizer, this would be a repo containing JavaScript, CSS, and possibly other web artifacts. To get this code into IBM Connections Cloud, this repo needs to be shared with IBM. The step by step procedure is as follows:

  1. Share your repo with IBM. (Add "ibmcndev" as a collaborator. Use the Settings > Collaborators menu option in the GitHub web UI.)
  2. IBM (ibmcnxdev) then creates a fork of your repository under and grants you read access by default.
  3. You can continue to work on your extension in your original repo, but once you are ready to deliver to IBM Cloud, you must issue a pull request to IBM.
  4. IBM merges your pull request once acceptance criteria are met.
  5. Upon merge, all the files in the repository are automatically pushed to IBM Customizer in the cloud via a webhook.
  6. Repeat starting at step 3 for extension updates.

Step 3 requires you to issue a Pull Request across forks (in GitHub parlance). The key thing to remember is that your original repo that contains the latest changes is always the “head fork”, while the “base fork” must refer to the repo on

Step 4 involves an initial lightweight summary review by IBM which looks at various aspects of the proposed customization, primarily from a performance, security, and documentation standpoint. However, ultimate responsibility for the quality and behavior of the app remains that of the customer who creates or adopts the customization. The review process by IBM provides no guarantee whatsoever of protection against adverse security or performance impacts.

If you are familiar with GitHub and have a GitHub account, the process described here should be easy to follow. If not, you can start learning about GitHub here using this quick 10 minute guide. Once you know the rudiments, creating a GitHub account is straightforward and free for public and open-source projects. A walkthrough of the repository process used by Customizer is provided in this short video on developerWorks:

Figure 1. The IBM Connections Developers Organization on GitHub
GitHub screen shot
GitHub screen shot

Restricting Access to Include-Files

As mentioned earlier, the contents of any repository in both GitHub organizations are, by default at least, available for use in Customizer apps by any IBM Cloud tenant. This is a very flexible and convenient model, but may not always be the desired solution for every situation. Some tenants may prefer to keep the include-files for Customizer apps private to themselves, or restrict usage to a subset of tenants. Different solutions exist to address these needs:

1. Access Control Lists for Tenant Organizations Access Control Lists
(ACLs) are used to manage access to a particular object. IBM Connections Customizer provides a very simple implementation of an ACL which can control which tenant organizations are allowed to load include files from your repos. All you need to do is provide an acl.ids file at the root of your project and populate it with the IBM Connections Cloud ids of the tenant organizations to whom you wish to grant access.

Listing 2. Sample acl.ids file

This is basically a whitelist for tenant access. Once you create an acl.ids file in your repository, only those tenant organizations listed in the file are allowed to use it; all others are denied access. If no acl.ids file exists, all tenants can potentially leverage the repo in their Customizer apps.

2. Private GitHub Repositories on

GitHub users on a paid GitHub plan have the option of creating private repositories. Private repositories can still be shared with the IBM Connections Developers organization. The private repository will appear in the list of projects under but only administrators of ibmcnxdev will be able to see the contents. The repo files have no visibility to regular users or to the general public. Even though read access of the source files is restricted via the repository, you will also need to add an acl.ids file should you also wish to prevent runtime access from other tenant organizations.

3. Private Repositories on

If you have privacy needs that are not satisfied by the previous two options, you can request a private repository for your organization’s include-files on In this situation, the JSON definition would typically not contain any include-repo reference, as Customizer will resolve the include-files location based on the tenant’s organization id.

From Pilot to Production

The IBM Connections Customizer production release is the first piece of IBM Connections Pink to ship in the cloud. The Customizer pilot program was accessed from the classic IBM Connections UI by following the Admin > Manage Organization > Organization Extensions menu path. Now that Customizer has graduated to the Pink platform, the access path has changed slightly. If you follow the same path as before you will notice a new Apps Manager link on the classic apps workspace. By clicking this link, you move to the App Registry for IBM Connections Pink, and you can create Customizer apps there.

If you used the pilot program to create Customizer apps and you want to move these to the Pink platform, you need to copy the JSON definitions to the Pink App Registry. This is a simple copy/paste operation, described in this document and also demonstrated in a short video available here.

What Else is New?

A new open source developer organization has been formed to support app development for IBM Connections Pink components such as Customizer, Orient Me, Important to Me, and so forth. It is known as

An IBM Connections Customizer Contest was organized by OpenCode4Connections to promote adoption of the technology during the pilot phase. Many excellent projects were submitted as part of the competition, and you can view these on the OpenCode4Connections GitHub site. Over the next couple of weeks, these projects will all become available on the IBM Customizer public repository and thus be available for use by any cloud tenant via Customizer apps. Watch this space!

Get Started

In summary, IBM Connections Customizer is here and ready to be enjoyed by all. Registering to use the service is simple: just send mail to with your name, organization name, and organization id (as described here). There are lots of samples, videos, and documentation available to jump start you with Customizer app development.


Time to get cracking with some customizations!

Downloadable resources

Related topics

ArticleTitle=IBM Connections Customizer is available! What's New?