Credit: IBM
New release on IBM Connections Cloud
Martin Donnelly
Published on December 13, 2017/Updated: January 15, 2018
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": "com.ibm.customizer.ui",
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 github.com/ibmcnxdev 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:
- Share your repo with IBM. (Add “ibmcndev” as a collaborator. Use the Settings >
Collaborators menu option in the GitHub web UI.) - IBM (
ibmcnxdev) then creates a fork of your repository
under github.com/ibmcnxdev and grants you read access by default. - 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. - IBM merges your pull request once acceptance criteria are met.
- Upon merge, all the files in the repository are automatically pushed
to IBM Customizer in the cloud via a webhook. - 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 github.com/ibmcnxdev.
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:
https://www.ibm.com/developerworks/collaboration/library/intro-customizer-video-2/index.html
Figure 1. The IBM Connections Developers Organization on
GitHub
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
60050207 22716730 10034583
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.com/ibmcnxdev
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 github.com/ibmcnxdev 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 github.ibm.com
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 github.ibm.com. 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 OpenCode4Connections.org.
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 ibmcndev@us.ibm.com 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.
Questions?
Time to get cracking with some customizations!
Downloadable resources
Related topics
Credit: IBM
