Connecting to the IBM social platform from a Domino Agent

We recently worked on a project that involved IBM Domino and IBM Connections. The idea was to 'replicate' some of the Connections data into an NSF, so users can access these data offline from the Notes client. Actually, the synchronization between Connections and the NSF happens on a Domino server, and the Notes clients are using the regular Notes replication capability to get the data down. So far, it sounds simple.

To access Connections data, we obviously wanted to use the IBM Social Business Toolkit SDK. I said obviously because I was at the origin of this SDK, during my time at IBM :-). It really makes things simpler, by handling all the plumbing for you.

Now, the Connections/NSF synchronization task should be triggered on a scheduled basis. For this, Domino offers at least 3 options:

• Use an agent
  This seems the obvious answer, although it is *not* the most performing one, as the classes are loaded every time the agent is executed, then discarded. On the other hand, it takes less than a second to get it bootstrapped. For a task that just happens from time to time, this is not a big deal.
  The other issue is with the SBT SDK, as it has never been run in an agent. At least by IBM. And it failed when I tried it.
• Use an Eclipse job within the HTTP server
  We explained this technique in a video. It is relatively simple to code, as it uses all the XPages capabilities (managed beans for the endpoints...)
  But it requires some extra permissions that should be set within the global java security files, or bypassed through a custom plug-in. I implemented a version this way, but I found it to complex to install for this basic project.
• Use DOTS
  Another great OpenNTF Project from my friend David. But the installation complexity is even worse than the Eclipse job. Moreover, even though parts of the project are now in Domino 9, this is not supported by IBM. I anticipated an extra effort to justify this choice, so I decided to not go this route.

Ok, I finally decided to go back to the agent option, and fix what should be fixed in the SDK. That was actually simple. See: https://github.com/OpenNTF/SocialSDK/issues/1604.

With that fix in, here are the steps to call a Connections API from an agent:

1- Create a Java agent in Designer.
No kinding...

2- Import the SDK libraries into the agent
Import the Java archives to get something similar to this:

Note that I used an older version of the SDK But I would advise you to use the most recent one.

3- Code your agent
If you already used the SDK prior to this, you might know that it uses some 'Endpoint' defined as managed beans. But managed beans do not exist in agent.
Fortunately, the SDK provides you other ways to define these endpoints, including extension points. But, in my case, to make it as simple as possible, I just created one programmatically:
    BasicEndpoint e = new ConnectionsBasicEndpoint();
    e.setUrl(getConnectionsUrl());
    e.setUser(getGlobalUserName());
    e.setPassword(getGlobalUserPassword());
    // For HTTPS access
    e.setForceTrustSSLCertificate(true);

Other endpoints types (oauth...) can be created the exact same way. In this example, I'm using basic authentication, with the URL, user name & password are stored in a configuration document.

Note the use of setForceTrustSSLCertificate. This allows the SDK to call HTTPS URLs without having to install the SSL certificates in the Domino server. Not fully secure, but this is ok for development or within a known intranet environment.

Then you can create the service your need with the desired endpoint as a parameter:

    BasicEndpoint e = ...;

    CommunityService cs = new CommunityService(e);

    CommunityList communities =  cs.getPublicCommunities()

For more information on the available services and API, have a look at the Playground. It contains many examples of working code.

4- Make sure that your agent can execute restricted operations (http calls in this case) and that it is signed with a user with the appropriate rights in the server security document.

To get the whole story in, I also bundled the code into an OSGi plug-in and called it directly from XPages, in the HTTP task. That made it far easier to develop and debug, particularly with the Domino Debug plugin, again from David.

If you also want to access the SDK from an XPages, then you should install the OSGi plug-ins, following the standard procedure. The jar files in the agents are not visible from XPages.