Back in February I posted an update to a blog article on IBM Connections Customizer which described a bunch of new enhancements that had been delivered around that time. In the intervening months, the Customizer development squad has been busy working on many other new features so it’s about time to publish the good news on all that cool stuff. This time however the plan is to provide a series of smaller news updates over the coming weeks, each focused on particular aspects of Customizer. Work starts here with this piece on Customizer’s latest selection filtering capabilities.

Audience Awareness for Apps

Last time around we talked about how Customizer enables you to target your application to a particular set of users within your organization. By default, a Customizer app is enabled for all users but there are various payload properties that can narrow the audience scope down to specific subsets of users. To recap, take the following Customizer JSON fragment which shows how to reduce the audience to just three users – Jane Doe, John Snow and Joe Schmoe in this example:

Listing 1. Customizer Application targeting Specific Users by Name

…
   "path":"communities",
   "payload":{
      "match":{
         "user-email":[
            "jane.doe@us.greenwell.com",
            "john.snow@us.greenwell.com",
            "joe.schmoe@ie.greenwell.com"
         ]
      }
   }
…

This technique effectively creates what’s known as a whitelist for the application – an explicit group of users who can consume the app. Last time around however there was no notion of a blacklist … which can of course be equally useful, albeit in the opposite direction, i.e. an explicit list of user who are excluded from the customization. The exclude keyword has been since been added to the Customizer JSON vocabulary to accommodate this use case. As the keyword implies, Customizer does not insert the include-files declared in the payload for anyone listed in the exclude clause.

The new exclude keyword can be applied wherever the match keyword is used today. They are mutually exclusively however, i.e. you cannot declare both match and exclude clauses in the payload of a given extension. In other words, if a user is listed not listed in a whitelist (match) they are automatically in the blacklist (an implicit exclude set), and vice-versa.

The list of selection criteria for the match/exclude operations has also been expanded. Up to recently these operations were confined to four operands: url, user-name, user-email and user-id.  Of these, the three user-centric criteria all worked in the same way – i.e. one or more literal strings that either identified specific user(s) or did not.  Whilst this is all well and good for simple use cases, there was no mechanism for wildcarding user selections or making more broad-based powerful choices … until now.

Smarter Selections

One limitation with the example shown in Listing 1 is that is does not scale well to handle large user lists. Suppose a Customizer application wishes to target all the employees of our fictitious Greenwell organization who are based outside of the USA. Obviously this could amount to far more users than is practical to include in a manually maintained list. This use case can now be handled very efficiently by combining the exclude blacklist property with a new condition keyword, as shown as follows in Listing 2:

Listing 2. Customizer Application excluding Users by Geography

… 
 "path": "communities",
   "payload":{
      "exclude":{ 
         "condition":{ 
            "keyword": "user-email",
            "regex": "@us.greenwell.com"
         }
     }
   }
…

In essence the new condition clause allows you to apply a regular expression against the data item identified in the keyword property value.  Out of the box, Customizer provides five keywords to handle popular criteria, namely: user-name, user-email, user-id, user-role and user-agent. By excluding all users whose email address contains “@us.greenwell.com”, Customizer has addressed the specified use case of targeting employees not based in the USA.

Another use case might be targeting all users of a particular browser – e.g. you wish to include a FireFox-specific version of a Customizer app. The fragment in Listing 3 shows how this can be achieved by applying a simple condition based on the user-agent keyword.

Listing 3. Conditionalizing Extensions based on the Browser Client

… 
"path":"communities",
"payload":{
   "match":{
      "condition":{
         "keyword": "user-agent",
         "regex": "Firefox"
      }
   }
}
…

NOTE: If the keyword string is not one of the pre-defined out-of-the-box values then Customizer treats it as a header name and will look for the nominated header and apply the regular expression to it, assuming it can be successfully resolved. This extends the filtering power of Customizer to act on totally arbitrary data items – i.e. a selection criterion that just may be very important to you!

Support for Groups

To round out the story around audiences and filters for Customizer apps we need to address the issue of groups. Whilst whitelists and blacklists are great for targeting an application at a precise set of users, inevitably this leads to a requirement to support re-usable lists of users (aka groups). In other words, typing in the same list of users over and over again gets old fast!

Suppose the list of three users shown in Listing 1 are a test group for the Customizer apps that you deploy within your organization. Your deployment strategy means that you soft-launch applications to this group of users first in order to get feedback before rolling it out to the wider organization. Ideally you could define a list containing those users and use it in your match/exclude clauses. This is now possible with the latest release of Customizer.

To check it out you first need to define one or more groups and to do this you need to use the IBM Connections App Registry. A user group is an extension point provided by the App Registry Connections service which can be consumed by apps from other services like Customizer, Communities, Files and so on. Listing 4 shows an application with a single extension that defines a group called “EarlyAdopters”. Observe that the canonical extension point name is com.ibm.connections.user.group. More extensions could be added to this application to define other groups.

Listing 4. Defining a User Group

{
   "name":"My Groups",
   "title":"Various User Groups in my Org",
   "description":"Use these as whitelists/blacklists in other extensions",
   "services":[
      "Connections"
   ],
   "extensions":[
      {
         "name":"EarlyAdopters",
         "type":"com.ibm.connections.user.group",
         "payload":{
            "user-email":[
               "jane.doe@us.greenwell.com",
               "john.snow@us.greenwell.com",
               "joe.schmoe@ie.greenwell.com"
            ]
         },
         "path":"EarlyAdopters"
      }
   ]
}

The example shown in Listing 1 can now be modified to use the “EarlyAdopters” group reference instead of the literal inline user-email list, as follows:

Listing 5. Customizer Application targeting a User Group

…
   "path":"communities",
   "payload":{
      "match":{
         "user-group": "EarlyAdopters"
      }
   }
…

Great – less typing, copying/pasting and app maintenance!  Even better – multiple groups may be applied to a match/exclude clause and groups may also be mixed with other user lists… in which case the union of all users become the target of the application.  Listing 6 shows an example of such an aggregation.

Listing 6. Customizer Application mixing multiple User Lists

…
   "path":"communities",
   "payload":{
      "match":{
          "user-group": [
             "SocialClub",
             "Contactors"
          ],
          "user-email":[
             "molly.randomer@greenwell.com",
             "billy.brolly@greenwell.com"
          ]
     }
   }
…

Summary

The goal of this article is to highlight some of the recent IBM Connections Customizer enhancements that help you to manage the scope of applications through whitelists, blacklists, smarter filtering capabilities and re-usable group references. More detail on any of the topics covered can be found in the documentation and samples provided in the IBM Connections Developer GitHub site.

Hopefully the sum of these parts amounts to easier deployments for you and less administration headaches overall. Watch this space for more news on cool Customizer stuff coming your way soon. Next instalment will focus on the latest Customizer assets made available by the Connections development community. Until then… happy customizing!