Prerequisites
You should have a basic familiarity with Web Experience Factory, Rest Api's and Service builders. You should also know how to create and run models. To run these models you will need to follow the information provided in the wiki article Adding Security Certificates to a Deployment Server for Outbound Requests to configure your development environment.
Introduction to creating services to integrate with IBM Connections blogs and profiles status updates.
Being able to incorporate connection components in your portlets is easy to do using the rest Api's provided by connections and builders provided by Web Experience Factory. We will use these builders to create service provider builders following the standard Service Oriented Architecture. This article is part one of a two part sample. The second part is found here [Creating mobile and desktop UI for IBM Connections]
Sample description
In this sample we will show how to build service providers using rest services. The sample will describe step by step the builders that we use and why. We will also demonstrate a way to separate the connection server configuration from the builders to make it easier to switch from one server to another or one blog or status updates to another.
Here are some of the techniques illustrated in the sample code:
These samples illustrate how to use the REST Service Call Builder to access Atom feed data from Lotus Connection servers using Service Consumer/Provider architecture. The high level diagram below shows this architecture.
How to update Connections data using the Atom publishing API
Use of context Variables to pass non-input data from the Service Consumer to the Service Provider model (e.g. server connection URL’s).
Service Provider Models
The following section describes the Service Provider models used in the samples.
models\demo\social\data\BlogsProvider.model
models\demo\social\data\StatusUpdatesProvider.model
Common Context Variables
Each of the Service Provider models use a common set of context variables that are specified in each Service Operation Builder. Context Variables that are specified in the Consumer are pushed into the corresponding service model instance variables just before the operation is invoked. These are used in place of exposing extra inputs to each service operation. The following is a list of the common variables.
connectionURL – Used to push the base URL of the target Connections server to the provider model.
userName - Used to push the current user’s name from the consumer model to the provider model. Used for authentication purposes.
userPassword - Used to push the current user’s password from the consumer model to the provider model. Used for authentication purposes.
Blogs Provider Model
The blogs provider model defines a service that provides four services.
• The blog entries operation to return a list of blog entries from a specific blog.
• The blog entry operation to retrieve a specific blog entry .
• The blog entry comments operation to return a list of comments from a specific blog entry
• The blog add comment operation to add comments to a specific blog entry.
The blog entries rest service call data contains more data than we want to display so we will add a restructure handler to the project that can be used by the rest service builder. To do this we added the sample_restructure_blogs_feed.properties file to the /WEB-INF/config/rest_handlers folder. This file contains the information needed to perform the transformation. The class.name property /WEB-INF/work/source/com/ibm/wpf/samples/feed/RestructureBlogsFeed.java is the java class that implements the RestructureFeedData interface.
This class takes the data returned for the feed and removes entries to make the data structure much smaller and only contain the data we would like to provide within the user interface.
Here is the list of builders in the model lets go through them.
The Import to XML builder uses the /WEB-INF/demo/blogs/server_config.properties file to read the urls and user and log-on information and create variables for them to be used by later builders. This allows you to keep the information for the services separate from the builder and by updating this file the services are reconfigured.
Next we have Service Definition builder that defines the service name and makes it public so that it can be consumed by a service consumer model. We also turned on the testing support so we can test this service. After testing and before we deploy this service into a production environment we would turn off the testing support. This improves the performance of the generation of the model when run.
We then add the Rest Service Call and Service Operation builders for the operations that we want to add. The rest builder uses the variables that were added by the Import to XML builder to call and return the data from the connections server. The Get operations use the restructure feed we added to the project and return the data. For the blog entry and the blog entry comment the URL is not set in the builder but is set as an argument from the service consumer.
Note: If you leave the URL blank, the URL will become an input to the data service for the Rest Service Call. If the input is left blank and you require a result schema to be created, supply a URL value for the
Sample Data URL input. The Add operation posts the added data to the server and sets the input to ignore any results since there are none for this service call.
Status Update Provider Model
The status update provider model defines a service that provides two services.
The get status update operation to return a list of status updates from a specific profile.
The update status operation to add a new status update to a specific profile .
The results from these rest service call use the automatic handler which automatically converts the data from the server into a format that will be usable.
Here is the list of builders in the model lets go through them.
The Import to XML builder uses the /WEB-INF/demo/blogs/server_config.properties file to read the urls and user and log-on information and create variables for them to be used by later builders. This allows you to keep the information for the services separate from the builder and by updating this file the services are reconfigured.
Next we have Service Definition builder that defines the service name and makes it public so that it can be consumed by a service consumer model. We also turned on the testing support so we can test this service. After testing and before we deploy this service into a production environment we would turn off the testing support. This improves the performance of the generation of the model when run.
We then add the Rest Service Call for the status entries call operation that we want to add. The rest builder use the variables that were added by the Import to XML builder to call and return the data from the connections server.
In this service we want to post process the results from the update status service. This is different from the restructuring we did in the previous sample the restructuring of the data happens in the service call. But in this case we are not restructuring the data but the content of a field. So we added a Linked Java Object that will go through the results and remove spaces from the authors photo element. This java class is called from the service operation builder.
We then add a Schema builder that describes the schema that is used by the get status updates operation. This schema is designed to flatten the entry type to make dealing with entries easier.
We add a Service Operation builder that defines the operation for the service and it uses the previously define Linked Java Object to reformat the data that it provides into the schema we previously defined.
Next we add the Rest Service Call builder for the update service request. This request posts data to the server.
The data that is sent to this call is in the Atom format so we define a variable conforms to the atom specification by adding a Variable builder.
To get the data from the string that was sent to the operation we create a method using the Method builder that takes the string and places it into the content part of the status entry variable.
We then added the Action List builder that takes the data runs it through the method and then calls the service call that is referenced by the service operation.
The Service Operation builder is then added to add the operation to the service definition. This operation posts data to the server and sets the input to ignore any results since there are none for this service call.
Resources
For Adding Security Certificates to a Deployment Server for Outbound Requests
http://www-10.lotus.com/ldd/pfwiki.nsf/dx/adding-security-certificates-to-a-deployment-server-for-outbound-requests
For the complete documentation on connections rest api's see
http://www-10.lotus.com/ldd/lcwiki.nsf/dx/IBM_Connections_APIs_ic301
For information on Restructuring the Results of a REST Service Call
http://www-10.lotus.com/ldd/pfwiki.nsf/dx/Restructuring_the_Results_of_a_REST_Service_Call
For the service provider models
http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Creating_mobile_and_desktop_UI_for_IBM_Connections
Demo: creating multichannel application (mobile/desktop/tablet) that integrate with social media services like Lotus Connections, Facebook and Twitter