In recent years, content management has played an increasingly important role in the business world. The ability to manage and deliver Web content to potential customers quickly and efficiently is one of the keys to the success of modern companies. IBM Lotus Workplace Web Content Management is a key component of the Lotus Workplace solution, which helps customer manage their corporate content from initial creation to final Web presentation. It provides a sophisticated content management system for Web sites that can be used by both nontechnical and technical users. Currently, there are two editions available: Java and Domino. In this article, we refer to the Java edition of Lotus Workplace Web Content Management.

Lotus Workplace Web Content Management 2.0 provides new features to extend its functionality, one of which is the Lotus Workplace Web Content Management API. With this API, users can easily retrieve content or create content in their own Web applications, thus managing their enterprise Web content more conveniently and flexibly.

In this article, we demonstrate how to use the Lotus Workplace Web Content Management API to build a Java application. This article includes three parts. First, we walk you through the configuration of the Lotus Workplace Web Content Management API, then we discuss the basic interfaces of the Lotus Workplace Web Content Management API. In the end, we deliver an example to help you quickly build a Web application using the Lotus Workplace Web Content Management API with sample files that you can download from the Sandbox. This article assumes that you are an experienced Lotus Workplace Web Content Management user with Java application development experience.

Lotus Workplace Web Content Management API

Lotus Workplace Web Content Management 2.0 introduces API externalization, which gives you the ability to build solutions for migrating/importing content from competing products, doing advanced rendering, and batch processing of content. This is just one of several new features in release 2.0. For more Lotus Workplace Web Content Management 2.0 features and enhancements, refer to the Lotus Workplace Web Content Management, Java edition Release Notes.

You can access the following Lotus Workplace Web Content Management functions using the API:

• Several search iterators of object IDs, such as find object of given type by name and find content by workflow stage
• Content search which is similar to the Menu Component search, but uses object parameters as IDs
• Object retrieval via object IDs
• The ability to create/delete/save the following objects: content, sites, site areas, and three library components
• JSP Component

For more details, refer to the Lotus Workplace Web Content Management InfoCenter and JavaDoc. The JavaDoc is located under the WebApp\api-javadocs directory on your Lotus Workplace Web Content Management server.

Back to top

Lotus Workplace Web Content Management API configuration

The default installation process for Lotus Workplace Web Content Management places the Lotus Workplace Web Content Management Java classes in the WEB-INF\lib directory of the Lotus Workplace Web Content Management WAR file. In this location, the classes are not made available to other applications, even those on the same Java virtual machine. To make the Lotus Workplace Web Content Management code (specifically the API) available to other applications, a classloader needs to be created in WebSphere Application Server that loads related Lotus Workplace Web Content Management classes.

Follow these steps to configure the Lotus Workplace Web Content Management API:

1. Move all the ilwwcm-*.jar files from the WEB-INF\lib directory into a new directory somewhere outside the WEB-INF directory. An ideal location for the new directory is directly under the ilwwcm.war directory. You must move (not copy) the ilwwcm-*.jar files. Otherwise, an error will occur.
2. In the WebSphere Application Server administrative console, under the Environment - Shared Library area, create a new Shared Library named lib, for example. In this Shared Library, add all of the JAR files you have moved into the new directory to the Classpath section as shown in the following screen.
   Figure 1. Shared Library
   
   

   As the figure above shows, the path must be the full path for each JAR file. For example, if you have moved all the JAR files to the ilwwcm.war\lib directory, then the value of Classpath section should look like the following:

   C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-api.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-commons-properties.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-commons-utils.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-commons-version.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-commons-xmlpersistency.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-framework.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-javacontentextension.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-search-core.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-server.jar C:/IBM/WebSphere/AppServer/installedApps/Lotus Workplace Web Content Management/ Lotus Workplace Web Content ManagementV2.ear/ilwwcm.war/lib/ilwwcm-syndication-core.jar

   
   

   You can copy and paste the preceding block of code and modify it according to your own configuration.

3. Under Servers - Application Servers - [your server], select Classloader from the list and create a new classloader with PARENT_FIRST as the mode. Then select the created classloader and click the libraries link. Add the shared library you created in the preceding steps to the libraries section. The following figure shows this step.
   Figure 2. Classloader configuration
   
   
4. After you complete these steps, restart WebSphere Application Server on which Lotus Workplace Web Content Management is installed.

Back to top

Core class and interfaces of Lotus Workplace Web Content Management API

This section describes the core class and interfaces of the Lotus Workplace Web Content Management API. We walk you through the basic objects and components of Lotus Workplace Web Content Management, and then connect these objects and components with the corresponding application programming interfaces.

NOTE: There is only one class provided in the API, the WCM_API class. The rest are all interfaces.

WCM_API class

WCM_API class is the start point of using the Lotus Workplace Web Content Management API. It provides a method to get repository.

Workspace and repository interfaces

When you use Lotus Workplace Web Content Management to develop a Web site, you act as a registered user. All activities you perform are associated with the user. This user must have enough authority to perform certain functions. In the Lotus Workplace Web Content Management API, this is represented by a Workspace object. The Workspace is the heart of the API. Objects are created, saved, deleted, and searched for in the Workspace object. A Workspace is basically an interface to Lotus Workplace Web Content Management that is associated with a user. Using a Workspace object, the user can perform operations as that user.

A Workspace represents a view of the Lotus Workplace Web Content Management repository for a particular user. Most of the important functions are provided within the Workspace interface. Operations available in the Workspace include:

• Searching for a document. The Lotus Workplace Web Content Management API provides two kinds of search methods. One is to search for documents by providing a detailed search criterion. The criterion includes template ID, siteArea ID, category ID, and keyword. The other mechanism is to search for documents by several provided findby methods. These findby methods include findbyName, findbyType, findContentByCategory, and so on.
• Creating new objects of editable types, such as content, site, component, and so on.
• Rendering given context or rendering a given component using specified context.
• Saving and deleting editable objects.

To get a Workspace object, the user must request one from the repository singleton. It is the entry point into the Lotus Workplace Web Content Management repository. It provides two methods to get the Workspace object. One is for anonymous users, and the other is for registered users. For example, to get a Workspace object for a registered user, use the following call:

WCM_API.getRepository().getWorkspace(user name,password);

If the user is not recognized as a Lotus Workplace Web Content Management user, or cannot be authenticated, an OperationFailedException is thrown. Only Lotus Workplace Web Content Management users, including external LDAP users (who require special configuration), are recognized.

Document, document type, and document ID interfaces

A document represents an object or an entity in the repository. It is the parent interface of most other entity interfaces, such as content, category, site, and so on. Usually, we only use its subinterfaces.

Each entity in the repository has a unique identifier, called Document ID, that uniquely represents this entity. Different entities can have the same name, but they must have different IDs. Document ID is represented in the API by the DocumentID interface.

As for document type, it represents a kind of document. The document type can be content, category, site, or all the components. In the Lotus Workplace Web Content Management API, DocumentType and DocumentTypes interfaces handle document types. The DocumentTypes interface maintains a list of all available document types, where a DocumentType object is an individual document type.

Content components, library components, content component container, and content interfaces

In Lotus Workplace Web Content Management, there are two kinds of components: content components and library components. Content components are components stored in content, site, or site area, while library components are static components directly stored in the component library. Content components and library components can both be retrieved by the page design. However, when you retrieve library components in a page design, the components being retrieved are known at all times because they are directly referenced. As for content components, the actual component being rendered is dependent on the current content or site, which means they are looked up dynamically when content is rendered. Refer to the Lotus Workplace Web Content Management InfoCenter for more information.

There is a ContentComponent interface in Lotus Workplace Web Content Management that represents content components. The Lotus Workplace Web Content Management API provides some of the content components, excluding JSPComponent and Federated content components.

For library components, the Lotus Workplace Web Content Management API provides a LibraryComponent interface to represent all the library components. Also, there are LibraryFileComponent, LibraryHTMLComponent, and LibraryImageComponent interfaces that represent File component, HTML component, and Image component respectively. However, other library components, such as Navigator component and Menu component, do not have corresponding interfaces in the API.

ContentComponents can be added to Site, SiteArea, and Content objects. The ContentComponentContainer interface provides basic functions such as the updating and retrieving of content components from their container.

Content objects store values that can be referenced in other Lotus Workplace Web Content Management objects. These values include ID information, profiling, security, and components. Content is represented by the Content interface.

RenderingContext interface

In Lotus Workplace Web Content Management, it is a basic requirement to render content or components in a Web page. Due to the dynamic presentation feature, when rendering components, we first need to get the context for rendering. The RenderingContext interface represents the context of rendering that contains information required to present a renderable object. The contained information includes the current content, page design and site, the servlet path and the application path, the rendered content, and so on.

Back to top

Installation of the sample application

In this section, we use a sample application to demonstrate how to use the Lotus Workplace Web Content Management API. Download the sample application from the Sandbox, install it on your WebSphere Application Server, and complete the configuration described earlier in this article. The installation steps are as follows:

1. Install the API Testing application, for example, using the context root APISample. This sample application must be installed on the same application server as Lotus Workplace Web Content Management because Lotus Workplace Web Content Management offers a local interface only.

   NOTE: You cannot have an application using the API remotely, for instance, from a remote WebSphere Application Server or a stand-alone application.

2. Create a site and site area. Also create a simple workflow that has a publish action in its contained stage.
3. Create a content template that has the created workflow as its default workflow. Add an HTML component named body to this template. This step is very important because in our sample code, we will create new content that has this HTML component.
4. Modify the com\ibm\sgl\test\api\config.properties file according to the configuration of your own server. This config.properties file is very important for our sample application. For example, because the API requires a user name and password to be specified for all access to the repository, these values will be stored in the config.properties file. The WAR file has Administrator set as the user, but this should be changed for security reasons. It is always a good idea to work with Lotus Workplace Web Content Management with a user other than the administrator. Set the user name and password to an existing user who is a member of the UI Access Group.
5. Also in the config.properties file, there is a setting called Webappurl, which refers to the Lotus Workplace Web Content Management context. The provided WAR file has this set as: Webappurl=http://localhost:9080/API/connect as an example, but you must change it to match your environment.
6. One of the tests will import files on the file system to create a Library File component. The files to be imported are stored in the compressed file SampleImport.zip. Decompress this zip file to the root of the C: drive on the server machine. They will be correctly located by the API Sample application. The zip will decompress creating the directory C:/APISample/ImportFile. If these files are placed in another location, the source directory entries in the properties file com\ibm\sgl\test\api\config.properties should be altered. Whenever you modify the config.properties file, you must close and reopen the APISample application.
7. Start your Web browser and go to http://<server>:<port>/APISample/SampleServlet. This loads the introduction page and provides access to others.

Sample application

In this section, we highlight the most important code fragments from our sample application to show how to use the Lotus Workplace Web Content Management API. The API Sample application currently runs the following tasks:

1. Create a new content document.
2. Import files to create File Library components.
3. Render content in a Web page.
4. Search content.
5. Delete existing content.

Refer to the description in the sample application for more detail.

In the ConfigUtil.java file, the core Workspace object is constructed.

// ============
/**
  * Create a Workspace object with user name and password stored in the resource file
  * and store this Workspace object.
  *
  */
 private void createWorkspace() {
        String userName = m_resources.getString("username");
        String userPassword = m_resources.getString("password");
        try {
	// get the Workspace object with provided user name and password
            s_workspace =
                WCM_API.getRepository().getWorkspace(userName, userPassword);
        } catch (ServiceNotAvailableException e) {
            e.printStackTrace()
        } catch (OperationFailedException e) {
            e.printStackTrace();
        }
}
// ============

In the CreateContentText.java file, the createContent(), getbyID(), and save() methods of the Workspace interface are used to create new content from a specified template, to save the new content, and to publish it.

// ======
try {
// create new content with provided template ID
content = workspace.createContent(workspace.createDocumentId(publishingTemplateId));
  siteArea = (SiteArea) workspace.getById(workspace.createDocumentId(siteAreaId));
  siteAreaChildren = siteArea.getChildren();
  DocumentId lastSiteAreaChildId = null;
  
  while (siteAreaChildren.hasNext()){
    lastSiteAreaChildId = (DocumentId) siteAreaChildren.next();
  }
  
// add the newly created content to the end of this site area
  siteArea.addContent(content.getId());
  content.setName(contentTitle);
  content.setDescription(contentDescription);

// add an HTML component to this content
  if (content.hasComponent("body")){
bodyComponent = (HTMLComponent) content.getComponent("body");
    bodyComponent.setHTML(body);
  } else{
    output.append("HTMLComponent body not found");
  }

// save the content
  String[] saveErrors = workspace.save(content);
  output.append("<br><br>Content save attempted<br>");
  if (saveErrors.length > 0) {
    output.append("The following errors occurred on content save<br>");
    for (int i=0; i < saveErrors.length; i++) {
       output.append(saveErrors[i]+"<br>");
    }
  } else {
    output.append("No errors reported on content save<br>");
  }
  saveErrors = workspace.save(siteArea);
  output.append("<br><br>Site area save attempted<br>");
  if (saveErrors.length > 0) {
    output.append("The following errors occurred on site area save<br>");
    for (int i=0; i < saveErrors.length; i++) {
       output.append(saveErrors[i]+"<br>");
    }
  } else {
     output.append("No errors reported on site area save<br>");
  }

// publish the content
  while (!content.isPublished()){
    content.nextWorkflowStage();
    index++;
    if (index > 50) {
      output.append("Content failed to publish in runPost");
      break;
    }
  }
  output.append("Test complete in runPost");
  } catch (Exception e) {
   output.append(HTML.getStackTrace(e) + " in runPost");
  }
// ======

In the RenderContentTest.java file, createRenderContext() and render() methods of the Workspace interface are used to present the new content on a Web page with the appropriate components.

//=======
try {
SiteArea siteArea =
(SiteArea) workspace.getById(workspace.createDocumentId(siteAreaId));
  Content content =
        (Content) workspace.getById(workspace.createDocumentId(contentId));
  Map parametermap = new HashMap();
// create a rendering context 
  RenderingContext context =
        workspace.createRenderingContext(request, response, parametermap);

// set proper design page and content to be rendered
  context.setPresentationTemplateOverride(presentationTemplateName);
  context.setRenderedContent(content, siteArea);
 
// render selected content in Web page
  output.append(workspace.render(context));
  } catch (Exception e) {
	…..
  }
//=======

In the SearchTest.java file, the contentSearch() method of the Workspace interface is used. Please refer to the Java source code for details.

Back to top

Conclusion

This article provides configuration steps for using the Lotus Workplace Web Content Management API to deliver a flexible Web application. It provides a sample application for reference. This article can assist you in configuration and development with the Lotus Workplace Web Content Management API.

Resources

• Download the sample application from the Sandbox.
  
  
• Use Lotus Workplace Web Content Management to build a multilingual Web site. Read the article, "Implementing a globalization solution with IBM Lotus Workplace Web Content Management."
  
  
• Learn more about how Lotus Workplace Web Content Management can benefit you from the tutorial, "Streamline your Web content management: How Lotus Workplace Web Content Management gives you control."
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Lotus Workplace Web Content Management API
• Lotus Workplace Web Content Management API configuration
• Core class and interfaces of Lotus Workplace Web Content Management API
• Installation of the sample application
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Lotus on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers