Using IBM WebSphere Portlet Factory to integrate IBM Lotus Connections with IBM WebSphere Portal

In this article, you learn how the REST Service Call builder in IBM® WebSphere® Portlet Factory can be used to access, display, and manipulate the data from the five IBM Lotus® Connections services.

Share:

Angela Self, Senior IT Specialist, IBM

Angela Self is a Senior IT Specialist with IBM WebSphere Portal Technical Sales. Angela has been working with IBM for 7 years and loving every minute of it. Angela started as a Java Services Consultant and then became a WebSphere consultant with Software Group Services. After a long stint in Services, Angela switched to Tech Sales support and is now an IT Specialist in Chicago, IL.



Luis Benitez, Consulting IT Specialist, IBM

Luis Benitez is a Consulting IT Specialist with IBM TechWorks. Luis leads the Lotus Connections community within IBM and has been working on early adopter customer deployments of Lotus Connections since January 2007. Luis joined IBM TechWorks in early 2008, and prior to that he worked as a consultant for IBM Software Services for Lotus. You can reach Luis at Luis_Benitez@us.ibm.com.



29 July 2008

Also available in Russian Japanese

IBM WebSphere Portlet Factory is a powerful and flexible development tool that allows developers to rapidly create, build, customize, and deploy portlets to IBM WebSphere Portal. IBM Lotus Connections, a social software offering, can easily be extended and integrated into your existing applications through a set of REST APIs; as a result, it is a perfect fit for the rapid development paradigm provided by IBM WebSphere Portlet Factory.

While Lotus Connections ships with a portlet to allow integration with WebSphere Portal, you might need to go beyond what is provided in the standard product.

After reading this article, you should be able to create custom solutions using such advanced capabilities as inter-portlet communication and granular access control to the various Lotus Connections services. This article describes a simple way to build portlets and integrate Lotus Connections into WebSphere Portal. The focus of this particular article and subsequent example is the Dogear service in Lotus Connections. Dogear, if you are not already familiar with it, is a social bookmarking tool.

It is assumed that you have experience deploying portlets in WebSphere Portal and have already reviewed the WebSphere Portlet Factory wiki and the Lotus Connections examples.

“What is REST?”, “What is a builder?”, and finally, “What is a REST builder?”

What is REST? Representational State Transfer (REST) is an inherently lightweight and intuitive environment that allows customers to create, update, query, and manage information of any REST-enabled applications (such as Lotus Connections) from their own custom applications. The simplicity in the API comes from the fact that the REST API is HTTP-based, allowing you to easily make requests to the five Lotus Connections services through a simple and straightforward URL using POST, PUT, and DELETE methods with the service data encapsulated in an HTML form or an XML Atom document.

But what is a builder? At the core of IBM WebSphere Portlet Factory designer is a set of software automation components called builders. These builders capture design intelligence through easy-to-use, wizard-like user interfaces and then automate the creation of code. The use of builders greatly speeds up the development process, thereby masking the complexities of the underlying APIs, and producing portlets that are truly SOA compliant.

This concept brings us to a REST builder: the further simplification of the REST API contained inside a form-based WebSphere Portlet Factory builder. The REST Service Call builder (its formal name) invokes the REST service, which returns an Atom feed. As a result, the builder generates a default XML Schema Definition (XSD) based on introspecting the resulting feed.


Creating a Dogear cooperative portlet

A cooperative portlet is a portlet that interacts with another portlet on the same page or another page in the same WebSphere Portal instance. In this example, you create two portlets. One portlet displays a search window that allows users to search the Dogear service for bookmark tags that match their search criteria. The second portlet displays the list of resulting bookmark links. You use WebSphere Portlet Factory to do this operation. If you haven't done so yet, study the sample tutorial on how to create a portlet that is provided with WebSphere Portlet Factory.

This section explains how to create two portlets that fetch data from Lotus Connections through its REST API using WebSphere Portlet Factory.

NOTE: These examples were created using WebSphere Portlet Factory v6.0.2.3 and Lotus Connections 2.0.

Create the source portlet

First, create the portlet that is the source in this cooperative scenario. The source portlet displays a search window to the users along with a Submit button. When the users click the Submit button, the search query is sent to the target portlet over a property broker wire. The property broker is a service that exists in WebSphere Portal that allows you to link portlets together and send messages between them. The wire is configured by a portal administrator to complete this linking.

Before you begin, make sure that you are in the WebSphere Portlet Factory perspective. If you are not in this perspective, select Window - Open Perspective - Other - WebSphere Portlet Factory.

To create the WebSphere Portlet Factory project, follow these steps:

  1. Click File - New - WebSphere Portlet Factory Project.
  2. Name the project Dogear, and click Next.
  3. Click Next in the Add Feature Sets window.
  4. Click Next in the Java Settings window.
  5. In the Deployment Configuration window, select both the Application Server and Portal Server to which you would like to deploy. If you need to create one of each, you can click the Add button as appropriate. Click Finish.
    NOTE: These servers must be up and running.
  6. When asked “Would you like to deploy your project now?” answer Yes.

You now have an empty Project. Next you need to create a new model. Model is a WebSphere Portlet Factory term; you can almost think of it as the application that you will create. This model defines a set of builders that are responsible for generating the application code for the behavior, structure, and presentation of your portlet application.

To create the model, follow these steps:

  1. Right-click the newly created project, and then select New - WebSphere Portlet Factory Model.
  2. Select Dogear in the Choose Project window, and then click Next.
  3. Select Main and Page from the Select Model window, and click Next. The Main and Page builder creates a simple main() method that immediately directs the user to the Default page.
  4. In the Page Settings window, select Simple Page and click Next.
  5. In the Save New Model window, name the model as DogearSource and click Finish.

Your model has now been created with a very simple default page. Next, you modify the page to create a search form:

  1. In the Project Explorer view, shown in figure 1, double-click DogearSource.model. Next, double-click page1 in the Outline to open the page that is rendered to users.

    Figure 1.Project Explorer view
    Project Explorer view
  2. In the Page Contents section, paste the code shown in listing 1.

    Listing 1. HTML for the search page
    <html>
         <body>
            <!-- As a best practice, change the form name to a unique name -->
            <form name="searchForm" method="post">
                <div align="center">
         <span name="searchTag"></span>
         <span name="searchButton" class="searchButton"></span>
                </div>
            </form>
        </body>
    </html>
  3. Save the model. Your default page now contains a search field and a Search button.

Next, you complete simple steps to turn this application into a portlet application. Follow these steps:

  1. In the Outline section, click the icon showing a plus sign (+) to add a builder to the model.
  2. Under Category, select Portal Integration and then Portlet Adapter under Builder Type.
  3. Name the portlet WPFDogearSource.
  4. Set the Title of the portlet to WPF Dogear Source.
  5. Save the model.

At this point, you configure the portlet to be the source in a cooperative scenario. First, you need to add a variable to represent the search string by doing the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Variables and then Variable under Builder Type.
  3. Click OK.
  4. Set the Name to searchQuery.
  5. Set the Type to String.
  6. Set the Initial Value to Portal.
  7. Save the model.

Next, you add support to send the property broker events, as shown in figure 2, by doing the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Portal Integration, and then select Cooperative Source Portlet under Builder Type.
  3. Click OK.
  4. Set the Name to ProcessProperty.
  5. Set the Type to Property Broker Action. This setting means that the inter-portlet communication occurs when an action is performed, such as a button being clicked.
  6. Set the Output Type Name to linkTextType.
  7. Set the Caption to linkText.
  8. Set the Name in Output Definitions to linkText.
  9. Save the model.
Figure 2. Cooperative Portlet Source window
Cooperative Portlet Source window

Next, you add a text input control at the named tag searchTag on page1. The value for this text field is the variable that you created earlier. Folow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Page Controls, and then select Text Input under Builder Type.
  3. Click OK.
  4. Name the text field searchTag.
  5. Set the Page to page1.
  6. Set the Tag to searchTag.
  7. Set the Text to ${Variables/searchQuery}. NOTE: You can also click on the ellipsis (...) button to find the variable name through a user interface.
  8. Save the model.

Define what happens when the Submit button is clicked. First, you take the value entered by the user in the search window and store it in the variable named searchQuery. Then you send this value to the Property Broker so that it is later available to the target portlet through the wiring capability. See figure 3.

Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Flow Control and then Action List under Builder Type.
  3. Click OK.
  4. Set the Name to dogearSearch.
  5. Under Action List, set the first action to:
    Assignment!Variables/searchQuery=${Inputs/searchTag}
  6. Set the next action to:
    pbAction_ProcessProperty (pbAction_ProcessProperty,${Variables/searchQuery})
  7. Save the model.
Figure 3. Defining the Submit button actions
Defining the Submit button actions

Finally, configure the Submit button to initiate the action that you defined in the previous set of steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Page Controls, and then select Button under Builder Type.
  3. Click OK.
  4. Name the button searchButton.
  5. Set the Page to page1.
  6. Set the Label to Submit.
  7. Set the Action to dogearSearch.
  8. In Input Mappings, add one mapping with Name set to ACTION_NAME and Value set to pbAction_ProcessProperty.
  9. Save the model.

At this point, you have successfully created the source portlet. To test it, right-click DogearSource.model and select Run As - Run under WebSphere Portlet Factory Model. If everything is set correctly, a browser opens with a search window and a search button.

The next sections guide you through the process of creating the target portlet that is responsible for performing the search using the REST API of the Lotus Connections Dogear service, parsing the results, and then rendering them in the portlet.

Create the data provider

Before you can create the target portlet, you need to tell WebSphere Portlet Factory how to call the Lotus Connections APIs. This section explains how to create a data provider.

A data provider abstracts how data is retrieved from Dogear. In this case, you use the Lotus Connections Dogear REST APIs to retrieve this data. This abstraction allows you to change the data retrieval mechanism later without affecting the presentation layer of your application.

The following steps outline the process used to configure WebSphere Portlet Factory to call the Lotus Connections Dogear REST APIs.

To create the data provider model, follow these steps:

  1. Right-click the project, and select New - WebSphere Portlet Factory Model.
  2. Select Dogear in the Choose Project window, and then click Next.
  3. Select Empty from the Select Model window, and then click Next.
  4. In the Save New Model window, name the model DogearProvider and click Finish.

Next, define the interactions with the Dogear REST APIs. You can define the Dogear service that can be consumed by other models and applications by doing the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services. and then select Service Definition under Builder Type.
  3. Click OK.
  4. Set the Name to dogearSearch.
  5. Make sure that Make Service Public is selected.
  6. Save the model.

Add the REST Service Call builder by doing the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Data Integration, and then select REST Service Call under Builder Type.
  3. Click OK.
  4. Set the Name to dogear.
  5. Set the URL to http://connections.acme.com/dogear/atom (or as appropriate).
  6. In the Parameters section add the following parameters as shown in figure 4 and leave each of the Values blank:
    • search
    • page
    • ps
    • lang (set the Value to en)
    Figure 4. Parameters for the builder
    Parameters for the builder
  7. Under Results Schema, do the following:
    • Make sure that Auto Create Schema, Restructure Feed Data, and Cache Schema are selected.
    • Set the Sample Data URL to http://connections.acme.com/dogear/atom (or as appropriate), and create one Sample Data Parameter called lang and set a value of en.
  8. Click Apply. This step performs a call to your Dogear server and retrieves a sample of the resulting XML. Using this sample, WebSphere Portlet Factory automatically generates a result schema.
  9. Save the model.

To add a service operation to abstract to a REST call, follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services, and then select Service Operation under Builder Type.
  3. Click OK.
  4. Set the Data Service to dogearSearch.
  5. Name the operation doSearch.
  6. Specify DataServices/dogear/execute as the Action to Call.
  7. Set both Input Structure Handling and Result Structure Handling to Use structure from called action.
  8. Click Apply.
  9. Save the model.

Add a rich data definition to further describe the fields retrieved from the Dogear service. This definition allows you to easily hide particular fields from view. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services, and then select Service Operation under Builder Type.
  3. Click OK.
  4. Choose dogear as the schema from the list of options.
  5. Under Data Definition Editor, make sure that Container Element is set to entry.
  6. For each field listed, make sure that the Data Type is set to string except for author and category.
  7. Click the Create Data Definition File button, and save the file to:
    /WEB-INF/data_definitions/dogear.xml
  8. Save the model.

Create the target portlet

This section describes how to create a portlet that receives information from another portlet and uses the data provider that you created in the previous section to call the REST APIs on Lotus Connections Dogear.

Note that because you have abstracted the data retrieval from Lotus Connections, you could theoretically change the provider to use a JDBC connection instead of a REST API call to get data from Lotus Connections Dogear without changing anything on the portlet side.

To create the target portlet model, follow these steps:

  1. Right-click the project and select New - WebSphere Portlet Factory Model.
  2. Select Dogear in the Choose Project window, and then click Next.
  3. Select Main and Page from the Select Model window, and then click Next.
  4. In the Page Settings window, select Simple Page and click Next.
  5. In the Save New Model window, name the model as DogearTarget and click Finish.

Next, you complete a simple step to turn this application into a portlet application by doing the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Portal Integration, and then select Portlet Adapter under Builder Type.
  3. Name the portlet WPFDogearTarget.
  4. Set the Title of the portlet to WPF Dogear Target.
  5. Save the model.

Now you can configure your portlet to be the target in a cooperative scenario.

To add a variable to hold the input string from the source portlet, follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Variables, and then select Variable under Builder Type.
  3. Click OK.
  4. Set the Name to receivedProperty.
  5. Set the Type to String.
  6. Save the model.

Add the property broker cooperative target capabilities to your portlet application. This addition reacts to the query string sent from the source portlet when a wire is created between the two portlets.

Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Portal Integration, and then select Cooperative Target Portlet under Builder Type.
  3. Click OK.
  4. Set the Event Name to ProcessProperty.
  5. Set the Input Name to linkText.
  6. Set the Input Type Name to linkTextType.
  7. Set the Caption to Link Text.
  8. Set the Caption under Output Definitions to Received Text.
  9. Save the model.

Next, create the page to render the results from Lotus Connections:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Pages, and then select Page under Builder Type.
  3. Click OK.
  4. Set the Name to TargetPage.
  5. Set the Page Contents to the code shown in listing 2.

    Listing 2. HTML code template for the target portlet
    <html>
      <body>
          <!-- As a best practice, change the form name to a unique name -->
          <div align="center" class="bookmarks">
             <span name="allTags"/>
    	   <div class="bookmarkList"  >
    	     <span name="searchResults"></span>
               </div>
               <div>
    	     <span name="pagingTag"></span>
               </div>
          </div>
      </body>
    </html>
  6. Save the model.

Render the results in the correct location on your page by using the Data Page builder to map data to named HTML tags created on the previous page. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Page Modifiers, and then select Data Page under Builder Type.
  3. Click OK.
  4. Set the Name to search.
  5. Set the Variable to DataServices/dogear/doSearch/results/feed/entries.
  6. Set the Page in Model to TargetPage.
  7. Set the Page Type to View Only.
  8. Set the Location for New Tags to searchResults.
  9. Save the model.

Next, you create the builders to call the Lotus Connections APIs. First, create the handler to perform an action when a new property is received on the property broker wire. The action is to get the search query from the wire, assign it to a temporary variable, call the Lotus Connections APIs, and then redirect users to the target page that renders the results. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Flow Control, and then select Event Handler under Builder Type.
  3. Click OK.
  4. Set the Name to handleNewProperty.
  5. Set the Event Name to ProcessProperty.
  6. In Arguments, set the Name to linkText and the Data Type to String.
  7. Under Actions, create the following three actions:
    NOTE: The SystemOut Actions are optional because they are for debugging purposes only.

    Assignment!Variables/receivedProperty=${Arguments/linkText}
    DataServices/dogear/doSearch
    TargetPage
  8. Save the model.

Next, you create a service consumer to call the service that was defined (DogearProvider) in the previous section. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services, and then select Service Consumer under Builder Type.
  3. Click OK.
  4. Set the Name to dogear.
  5. Set the Provider Model to DogearProvider.
  6. Make sure that Override Inputs is selected.
  7. Set the Input Value as follows (the page and ps values allow you to add paging support later):
    dogearRestInputs.Parameters.search to ${Variables/receivedProperty}
    dogearRestInputs.Parameters.page to 1
    dogearRestInputs.Parameters.ps to 10
  8. Set the Rich Data Definition File to:
    /WEB-INF/data_definitions/dogear.xml
  9. Save the model.

At this point, you have completed the development of two portlets. One portlet allows users to enter a search string. A second portlet receives this search string and performs a search on Dogear on all public bookmarks using the REST APIs. It's also worth noting that you have yet to write a single line of Java™ code. That's the great thing about WebSphere Portlet Factory. As long as you can follow this recipe, you can create portlets that leverage the Lotus Connections API without having to learn Java, XML, REST, or portlet development.

After the portlet WAR has been built and deployed, you can now configure the portlets on a particular page and wire them together. To wire the portlets, follow this procedure:

  1. Log into WebSphere Portal Server as the portal administrator.
  2. Go to the page where the portlets have been configured.
  3. Next to the page's title, select Edit Page Layout.
  4. Click the Wires tab.
  5. Specify the following settings:
    • In the Source Portlet field, enter WPF Dogear Source.
    • In the Sending field, enter linkText.
    • In the Target Page field, enter <page name>.
    • In the Target Portlet field, enter WPF Dogear Target.
    • In the Receiving field, enter Received Text,Link Text.
    • In the Wire Type field, enter Public.
  6. Click the plus-sign (+) button to add the wire.
  7. Click Done.

Go back to the WebSphere Portal page, and enter a search string in the source portlet. When you click Submit, an action is called on the Dogear Service and the Lotus Connections REST APIs are used to parse the resulting Atom feed to return the results into a good-looking portlet such as the one shown in figure 5.

Figure 5. The resulting portlet
The resulting portlet

NOTE: This portlet works only with Lotus Connections 2.0 and later, where Dogear has been configured to allow anonymous access. For an example of a portlet that uses the user's credentials, take a look at the WebSphere Portlet Factory Wiki and its Lotus Connections integration examples.

This example gives you the basis for further development. You can now take the resulting Atom feed and do several things:

  • Filter it based on the user's role (show only links from users in the same department or geography, for example)
  • Hyperlink-enable the bookmarks
  • Add paging support to show more than 10 bookmarks at a time
  • Add translation support
  • Integrate with your enterprise search engine

Because Lotus Connections is built on top of services, you can even recreate the user interface that meets your needs and integrates with your existing environment on your own with WebSphere Portlet Factory. With WebSphere Portlet Factory, the possibilities are endless, and it can all be done with little code.


Achieving granular access control in Dogear

Lotus Connections, by its very nature, was designed with minimal access control. As a result, anyone who chooses to share information across the five services is aware of the fact that what they choose to blog about, to comment on, and to bookmark is immediately visible to their entire social network. It would seem impractical to impose limitations on a tool whose sole purpose is to facilitate open communication and collaboration without boundaries.

We do not condone any attempts to structure unstructured content, but we recognize that sometimes you might have to help solve a business use case like the one described next.

An IBM customer, Company XYZ, is a large retail establishment that runs a vendor portal that supports multiple vendors. In an effort to attract additional vendors and to keep the ones they already have happy, Company XYZ has decided to add a social networking capability to its portal environment: specifically, a service for bookmarking and tagging. The challenge, however, with using Lotus Connections in this case is that no vendor is allowed to see the bookmarks created by another vendor. Because Dogear was designed to be deployed as an open system without any standard access controls, using a standard installation of Lotus Connections does not work in this case. We need to develop a custom portlet that uses WebSphere Portlet Factory.

The next section explains how to create a custom Dogear portlet that can be profiled or personalized, depending on the logged-in vendor, to display only the bookmarks for that particular vendor. As a result, there is no risk of cross-vendor bookmark contamination.

NOTE: These examples were created with WebSphere Portlet Factory v6.0.2.3 and Lotus Connections 2.0.

Create the community

Before stepping through the development process you must first understand how the access control requirements can be achieved. For this understanding, you rely heavily on the Lotus Connections Communities service. The Communities service is unique in that it is the one service that has the ability to create a private or moderated membership list. Because there is a bookmark component to a community, allowing members to share bookmarks among themselves, this service is the implementation of Dogear that is of importance to this example.

Communities components (such as the bookmark feature) can be retrieved through a REST call by knowing that particular communityUuid. Because a portlet can accept a configuration parameter (and be personalized) a communityUuid parameter can be developed into the portlet to affect what results are displayed.

Additionally, the customization of the Lotus Connections Dogear bookmarklet (a small JavaScript™ program that is stored as a URL in a browser bookmark) gives you the ability to bookmark content just to the Communities service. Because the Communities and the Bookmarklet both recognize the membership to a community, you can bookmark content only to a community to which you belong. As a result, if a private community is set up ahead of time, you can guarantee that each vendor can see only the content tagged and bookmarked by their peers.

Create the Communities data provider

As mentioned earlier, a data provider abstracts how data is retrieved from a service, in this case Lotus Connections Communities. With the creation of the next model, you use the Lotus Connections Communities REST APIs to retrieve a particular community based on a communityUuid and then return the bookmarking aspect to that community. The communityUuid is then used as a configuration parameter to personalize the portlet results. This value is set by the portal administrator when placing this portlet on the page. (The communityUuid can be seen in the URL when you access a given community in Lotus Connections, as shown in figure 6.)

Figure 6. Identifying the communityUuid
Identifying the communityUuid

The following steps outline the process to configure WebSphere Portlet Factory to call the Lotus Connections Communities REST APIs. First, you create the Data Provider model:

  1. Right-click the project, and select New - WebSphere Portlet Factory Model.
  2. Select Dogear in the Choose Project window, and click Next.
  3. Select Empty from the Select Model window, and click Next.
  4. In the Save New Model window, name the model CommunitiesProvider and click Finish.

You now have an empty model.

Next, you define the Community Service Definition builder that creates a new data service. See figure 7. This data service can be made public so that it can be consumed by other models acting as Service Consumer models. Follow these steps:

  1. In the Outline section of your workbench, click the plus-sign icon to add a new builder to the Model.
  2. Under Category, select Services, and then select Service Definition under Builder Type.
  3. Click OK.
  4. Set the Name to communities.
  5. Make sure Make Service Public is selected.
  6. Save the model.
Figure 7. Service Definition builder
Service Definition builder

Next, you add a REST Service Call builder that allows you to integrate with REST-style calls to the Lotus Connections Communities service. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Data Integration, and then select REST Service Call under Builder Type.
  3. Click OK.
  4. Set the Name to getAllBookmarks.
  5. Set the URL to:
    http://www.acme.com/communities/service/atom/community/bookmarks
    (or as appropriate)
  6. In the Parameters section of the builder, add the following parameters. Leave each value blank for now as shown in figure 8:

    • communityUuid. This value is profiled in the consuming portlet. Profiling in WebSphere Portlet Factory is used to generate different portlet variations depending on the value.
    • Tag. This value is optional and allows you to filter community or bookmark results based on a particular tag value, communityUuid. This value is profiled in the consuming portlet.
    Figure 8. The parameters of the builder
    The parameters of the builder
  7. Under the Results Schema section of the builder, do the following:
    • Make sure that Auto Create Schema, Restructure Feed Data, and Cache Schema are selected.
    • Set the Sample Data URL to:
      http://www.acme.com/communities/service/atom/community/bookmarks
      (or as appropriate)
    • Create two Sample Data Parameters. One is called communityUuid with a default value of 35FG091E0E92932F37764EE3F30442000007, and one is called tag with a default value of vendor_1. The values should be specific to your environment. Thus, you need to enter a communityUuid that exists in your Communities deployment and a tag that already exists.
  8. Click Apply. This action performs a call to your Communities server and retrieves a sample of the resulting XML. Using this sample, WebSphere Portlet Factory automatically generates a result schema.
  9. Save the model.

Next, add a Service Operation builder to add an operation to the data service that can call any data service or method (in this case, it calls the REST service that you just created) and transform the results. See figure 9. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services, and then select Service Operation under Builder Type.
  3. Click OK.
  4. Set the Data Service to dogearSearch.
  5. Name the operation getAllMyBookmarks.
  6. Specify DataServices/getAllBookmarks/execute as the Action to Call. This specification instantiates the REST Call builder that were created in the previous step.
  7. Set both Input Structure Handling and Result Structure Handling to Use structure from called action.
  8. Click Apply.
  9. Save the model.
Figure 9. Adding a Service Operation builder
Adding a Service Operation builder

Next, add a rich data definition to describe the fields retrieved from the preceding sample call. This addition allows you to show or hide the resulting fields. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services, and then select Service Operation under Builder Type.
  3. Click OK.
  4. Choose communities as the schema from the list of options.
  5. Under Data Definition Editor, make sure that Container Element is set to entry. This setting allows you to manipulate information about each bookmark entry that is returned (there could be more than one).
  6. For each field listed, make sure that the Data Type is set to string.
  7. Click the Create Data Definition File button, and save the file to:
    /WEB-INF/data_definitions/communities.xml
  8. Save the model.

You can now test your data provider model, CommunitiesProvider, by selecting Run Active Model as was done in previous examples. If you receive the results that you expected, you are ready to move on to the next step.

Create the access-controlled bookmark portlet

The bookmark portlet displays all bookmarks for a particular vendor’s community based on the communityUuid value set on the portlet instance by the portal administrator.

To create the Data Consumer model (the source portlet), follow these steps:

  1. Right-click the project, and select New - WebSphere Portlet Factory Model.
  2. Select Dogear in the Choose Project window, and click Next.
  3. Select Empty from the Select Model window, and click Next.
  4. In the Save New Model window, name the model as CommunitiesPortlet and click Finish.

Next, import the Provider model. This model makes the services created in the provider available to you as the consumer. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Model Construction, and then select Imported Model under Builder Type.
  3. Name the Builder Connections Data, and point it to your Provider model as shown in figure 10.
Figure 10. Importing a model
Importing a model

Now, create two variables to represent the communityUuid and the tags being searched. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Variables, and then select Variable under Builder Type. Do this step twice, creating one called tags and one named communityUuid. Each variable is of type String.

Create a new Profile for the communityUuid variable. Profiling is a concept in WebSphere Portlet Factory that allows you to define variations on the application based on certain values. In this example, you change the results displayed in this portlet based on the value of the communityUuid set when the portlet administrator selects Edit Shared Settings.

To create a new profile for communityUuid, follow these steps:

  1. With the Variable communityUuid open, click the profiler icon next to the field for Initial Value.
  2. Select the option Create Profile Set.
  3. Name the Profile Set connections.communities.Edit. Select <none> as the Profile Set to duplicate. See figure 11.

    Figure 11. New Profile Set window
    New Profile Set window
  4. Set ${Profile/connections.communities.Edit/communityUuid} as the Profile Values for Default. Click OK. As a result, the value for the communityUuid is determined by Edit Shared Settings. See figure 12.

    Figure 12. The Profile Input window
    The Profile Input window

Next, create a Service Consumer builder to consume the service operations of your data provider. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Services, and then select Service Consumer under Builder Type.
  3. Name the Builder CommunitiesData, and point it to your provider model.
  4. Select CommunitiesProvider as the Provider Model, and select Add All Provider Operations and Override Inputs. By overriding the inputs, you can specify the communityUuid as the input parameter to this service call. See figure 13.

    Figure 13. The Service Consumer window
    The Service Consumer window
  5. Within the same builder, select the operation getAllMyBookmarks. In the section for Inputs make sure that communityUuid and tag are set to the variables that you created earlier. See figure 14.

    Figure 14. Input names and values
    nput names and values
  6. Set the value of the rich data definition file to the schema that you created earlier under /WEB-INF/samples/data_definitions/communities.xml.
  7. Save this builder.

Next, create a new page named BookmarkPage by doing the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Pages, and then select Page under Builder Type.
  3. Name this builder BookmarkPage.

Next, create a Data Page Builder to map the results from your service or data provider calls to the page that you created. Do the following:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Page Modifiers, and then select Data Page under Builder Type. Name this builder searchBookmarks.
  3. Set the variable as Variables/CommunitiesDataGetAllMyBookmarksResults to represent the feed coming back from your getAllMyBookmarks service call.
  4. From the list of options, select BookmarkPage as the Page Type.
  5. For the Location for New Tags, select searchResults. This value exists as a <span> tag in your BookmarkPage by default. Set all other settings as shown in figure 15.

    Figure 15. Properties setting
    Properties setting

Next, create a Rich Data Definition builder to add rich data definition to the resulting fields.

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Page Modifiers, and then select Rich Data Definition under Builder Type. Name this builder CommunitiesDataGetAllBookmarks.

You can then experiment with the resulting fields to have them formatted the way you like.

Now you create the Action builder for the method main. This is the method that is called when the portlet is loaded initially. Follow these steps:

  1. In the Outline section, click the plus-sign icon to add a builder to the model.
  2. Under Category, select Flow Control, and then select Action List under Builder Type. Name this builder main (use all lowercase letters).
  3. In the ActionList, set the first several actions as shown in figure 16 to make the initial connection.
    Figure 16. Setting actions
    Setting actions
  4. For the next ActionList, select the following action to getAllBookmarks from a community: DataServices/CommunitiesData/getAllMyBookmarks.
  5. For the final action, display the page BookmarkPage.

Finally, you add a Portlet Adapter builder to turn this into a portlet. Name the Portlet DogearBookmarks as shown in figure 17.

Figure 17. The Portlet Adapter builder
The Portlet Adapter builder

After the portlet WAR is built, you can deploy the portlet and configure its default communityUuid. Follow these steps:

  1. Log in as the portal administrator and place the DogearBookmarks portlet on your page.
  2. Go to the page where the portlet has been deployed, and next to the portlet's title (in the skin) select Edit Shared Settings.
  3. In the window that displays, fill in the communityUuid of the community that represents the vendor community who has access to this particular page or portlet.
  4. Save your changes.

At this point, you have completed the development of a Dogear portlet that allows granular access control. Go back to the portlet page, and log in as different users with different vendor access rights. You should see the Dogear results changing accordingly.

To reiterate an earlier point, note that you have yet to write a single line of Java code.

Also, realize that as you choose to "Dogear This!" from your browser, you are given the option to bookmark documents only in the communities in which you are a member.

This example gives you the basis for further development. You can now take the resulting Atom feed and do several more things:

  • Return and format a tag cloud for that community's bookmarks
  • Enable the tag cloud to provide "click to action" by selecting a tag and changing the resulting Dogear results
  • Enable a target portlet to display the article selected or perhaps even a thumbnail of that article

Conclusion

In this article, you learned how to build portlets using WebSphere Portlet Factory. This article provides step-by-step instructions on how to build portlets that access data from Lotus Connections Communities and Dogear services. You also learned how to create a Data Provider model that leverages the REST API builders in WebSphere Portlet Factory to manipulate the data of all five Lotus Connections services. Now, you have the power to build customizations that include such advanced capabilities as inter-portlet communication and granular access control to the various Lotus Connections services.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, WebSphere
ArticleID=324588
ArticleTitle=Using IBM WebSphere Portlet Factory to integrate IBM Lotus Connections with IBM WebSphere Portal
publish-date=07292008