Introduction

Case Manager Client is an iWidget-based mashup application for business analysts who create and customize solution layouts. Also, Case Manager Client is an environment where case workers can collaborate and process cases. Based on IBM Dojo technology, Case Manager Client provides a widgets application with a set of spaces and pages that are configured to work together, enabling case workers to manage cases and process work items. A business analyst designs the views and in-baskets for the Case Manager Client in the Case Manager Builder. Business analysts can then use the provided spaces and pages, or they can further customize the Case Manager Client by adding additional pages or widgets.

Widgets are portable, reusable components that are used in pages to manage content and process work items. IBM Case Manager provides three default spaces and associated pages that make up the Case Manager Client application: Solution space, Step pages space and Case Pages space. The Solution space is a mashup space that case workers use for interacting with a solution. It is the main IBM Case Manager space, and contains the Work page with the In-baskets and Toolbar widgets, and the Cases page with the Case Search-related widgets. By default, the Cases page contains the widgets laid out as shown in Figure 1. The Command widget is required for each page, but is hidden from case workers.

You use the Search widget to provide case workers with a way to search for cases based on selected properties.

The Search widget provides a basic search and an advanced search. Case workers can use the basic search to find cases by the case ID or by the date that the case was created. They can use the advanced search to find cases within a specific case type or to narrow the search based on various properties. The Search widget only collects search criteria and builds the search statement, and then provides all of the information to the Case List widget by firing an event. It is the Case List widget's responsibility to execute the search and display the search result. The Search widget is wired with the Case List widget automatically; the Search widget sends an event with required information as payload. The payload includes the searched properties definition, the summary properties definition defined in Case Builder, the query statement, and other useful information. After receiving the event, the Case List widget executes the search and displays the result.

Figure 2 shows the relationship between the Search Widget and Case List Widget in IBM Case Manager Client.

If the Search widget doesn't satisfy your requirements or describe the business scenario, you can develop a custom search widget to provide additional functionality. After wiring with the Case List widget, the custom search widget will work with the Case List widget by sending the required event and payload information.

For example, assume an insurance company needs an application to manage all its insurance policies. The insurance agent must be able to search through policies to find one that meets their needs. Generally the agent searches for a specific insurance policy by the insured name or policy number. If the agent uses the basic Search widget, the agent will have to open the advanced search dialog first, then add search criteria in user-specified properties. To improve efficiency and usability, you could build a custom search widget named Insurance Search widget. In the Insurance Search widget, the following general properties are listed in the panel:

• The insured name
• The number
• The date that the insurance policy was created
• Its current state

The result is a search widget that is tailored to the specific solution needs. An agent can use this custom widget to find an insurance policy quickly and accurately.

The next sections describe how to build a custom search widget. You will first learn about the IBM Case Manager REST APIs, which will be used by the custom widget. Then you'll see how to build the actual widget.

Back to top

Introducing the REST APIs

Before learning how to develop a custom search widget, first take a look at the IBM Case Manager REST APIs that will be used in the Search widget. The Search widget uses the following two services:

• CMIS
• Case REST service

The Content Management Interoperability Services (CMIS) provide standard methods for interacting with Enterprise Content Management repositories in a vendor and product agnostic manner. CMIS accepts HTTP requests from Case Manager Client. CMIS connects to the FileNet P8 Content Engine (CE) using the IIOP protocol to perform operations for the requests. CMIS then sends HTTP responses to the Case Manager Client with the result.

The Case REST service supports the REST framework. The Case REST service uses the FileNet P8 Process Engine (PE) Java API and the CE Java API to handle case solution requests from the IBM Case Manager components, notably those from Case Builder and Case Manager Client.

In the Search widget, Case REST is used for getting the list of view definitions of a particular case type. The Search widget needs the search view of the specified case type to construct the search panel, and send the summary view for the case type to the Case List widget to determine what case properties to display.

CMIS is used for retrieving all the properties for a case type. At the same time, querying is a feature for a CMIS repository. It is the Search widget's responsibility to build the query statement, and then the query statement with other useful information will be sent to the Case List widget by event. The Case List widget will execute the query by CMIS, and then display the search result.

Back to top

Creating a custom search widget

This section shows how to develop and deploy a custom search widget to communicate with the Case List widget. The custom search widget contains a series of searchable properties that are defined in the FileNet P8 Content Engine object store. Then it collects useful information which is used for the Case List widget to execute the search and display the result.

To create a custom search widget, You will need to complete the following tasks:

1. Retrieve the view definitions using the Case REST APIs
2. Retrieve the property definitions using CMIS
3. Restrict the search to one solution
4. Build the query statement
5. Create the widget definition
6. Build the publish event that will be received by the Case List widget
7. Create the JavaScript
8. Deploy the custom search widget
9. Wire the search widget and the Case List widget together

These tasks are described in detail in the following sections.

Retrieve the view definitions using the Case REST APIs

The business analyst defines three lists of view definitions: CaseSummaryView, CaseDataView and CaseSearchView. The widget uses the Case Summary view to communicate the properties that should be displayed in the Case List widget, and it uses the Search view to define the properties that are available and their display order for building a search. Listing 1 shows the code for invoking Case REST to get the view definitions.

			
getViewDefinitions: function(){
	var self = this;

	return this.caseService.getViewDefinitions({
		caseTypeName: this._getCaseType(),
		TargetObjectStore: this._getObjectStore()
	}).addCallbacks(dojo.hitch(this, function(result){
		var fields = result.value.CaseSummaryView ? result.value.CaseSummaryView
		 .Fields : [];
		dojo.forEach(fields, function(property) {
			self.summaryProperties.push({
				symbolicName: property.Name,
			});
		});
		self.summaryProperties.sort();
		
		var fields = result.value.CaseSearchView ? result.value.CaseSearchView
		 .Fields : [];
		dojo.forEach(fields, function(property) {
			self.searchProperties.push({
				symbolicName: property.Name,
			});
		});
		self.searchProperties.sort();
		return self.searchProperties;
	}), dojo.hitch(this, function(){
		//err back
	}));	 
},
			

A sample response returned by Case REST is displayed in Listing 2:

			
{
"CaseDataView": 
{
	"Fields": 
	[
	  { "FieldType": "property", "Name": "caseName" },
	  { "FieldType": "property", "Name": "accountNumber" },
	  { "FieldType": "group", "Label": "Home Address", "OpenState": false,
		"Fields": 
		[ 
		  {"FieldType": "property", "Name": "StreetAddressLine1"},
		  {"FieldType": "property", "Name": "StreetAddressLine2"},
		  {"FieldType": "property", "Name": "City"},
		  {"FieldType": "property", "Name": "State"},
		  {"FieldType": "property", "Name": "ZIPCode"},
		] 
	  }
	]
},
"CaseSummaryView": 
{
	"Fields": 
	[
	  { "FieldType": "property", "Name": "caseName" },		
	  { "FieldType": "property", "Name": "customerName" },
	  { "FieldType": "property", "Name": "requestedLoanAmount" },
	  { "FieldType": "property", "Name": "percentageDown" },
	  { "FieldType": "property", "Name": "FicoScore" }
	]
},
"CaseSearchView": 
{
	"Fields": 
	[
	  { "FieldType": "property", "Name": "caseName" },		
	  { "FieldType": "property", "Name": "customerName" },
	  { "FieldType": "property", "Name": "accountNumber" },
	  { "FieldType": "property", "Name": "requestedLoanAmount" }
	]     
}

			

Retrieve the property definitions using CMIS

The view definition provided by Case REST is not the full definition of each case property. You can only get the name and type for each property. Other useful information, such as property's symbolic name, which is used for building query statement, is provided through the CMIS API. Additionally, if a search requires access to case properties that aren't defined in the search view, you would need to use the CMIS API to get a complete list of properties for the case type. Listing 3 shows the code for invoking CMIS to get all the properties and filter out the searchable ones.

			
_showDefaultPane: function() {
		//show the widgets description.
		var caseTypeProperties = this.getCaseTypeProperties().addCallbacks(
				dojo.hitch(this, "_getCaseTypeProperties"),
				dojo.hitch(this, function(err) {
					console.log(err.toString());
					return err;
				}));
	},

getCaseTypeProperties: function() {
		var caseTypeName = this._getCaseType();
		var	targetObjectStore = this._getObjectStore();
		return this.CMISService.getPropertyDefinitions(targetObjectStore, 
		 caseTypeName).addCallbacks(dojo.hitch(this, function(result){
			return result;
		}), dojo.hitch(this, function(){
			//err back
		}));	
	},

This would be useful if the solution has been deployed successfully by the business analyst before developing the custom search widget. In this situation, you can get the searchable properties information through CMIS and then hard code them in the widget. The useful property information includes symbolic name and property type. In the sample code, it picks up several typical property types and hard codes the properties, so you can focus on how to retrieve the search view properties by REST APIs and how to construct the payload that will be fired to the Case List widget.

Restrict the search to one solution

The business analyst can deploy several solutions in one content engine, so it is very important to restrict the search to one solution. In the content engine, the case structure is represented as a case folder, so you must invoke CMIS to fetch the target solution folder ID first, and then insert it as search criteria in the query statement. Listing 4 shows the code for invoking CMIS to get the target solution folder id.

			
_onClickSearchButton: function() {
		this.solutionName = this._getSolutionName();
		this.objectStore = this._getObjectStore();
		var _sql = this._solutionIDSQL;
		_sql = _sql.replace("@solutionName", this.solutionName);
		
		var self = this;
		return this.CMISService.queryRaw(this.objectStore, _sql).
		 addCallbacks(dojo.hitch(this, function(result){
			self._onSolutionIDQueryDone(result);
		}), dojo.hitch(this, function(){
			//err back
		}));	
	},

_onSolutionIDQueryDone: function(feed) {
		if(!feed.entries){
			var resourceBundle = ecmwdgt.getResourceBundle("common");
			var msg = dojo.string.substitute(resourceBundle.
			 SolutionIDNotFound, [this.solutionName, this.objectStore]);
			
			ecmwdgt.getBean("messageDialog", {
						icon: "ERROR",
						message: msg
			}).show();
			return;
		}
		var entry = feed.entries[0];
		this.currentSolutionID = entry.getCMISProperty("This").value[0];
	},

The query statement built in the function is: SELECT This FROM CmAcmDeployedSolution where cmis:name = ' SampleSolutionName'.

The required solution folder ID in the response is this property value, Listing 5 shows the script of the query response.

			
<cmisra:object>
	<cmis:properties>
		<cmis:propertyId queryName="This" displayName="This" localName="This" 
		 propertyDefinitionId="This">                    
		 <cmis:value>ido_F391D3A8-972F-4D23-ADC0-D03E148E5AFF:
		 idt_616EA2CB-2F81-4AE7-8E9E-A787A0B224AF:
		  idx_23807F89-D34F-4C4D-9838-DBF7886067B7</cmis:value>
		</cmis:propertyId>
	</cmis:properties>
	<p8ext:ClassDisplayName>Deployed Solution</p8ext:ClassDisplayName>
</cmisra:object>
			

Build the query statement

This section describes how to build a query statement that is used for searching cases based on the search criteria. The syntax for queries is similar to SQL query syntax. Case Manager Client supports the following six property types: ID, String, DateTime, Integer, Decimal and Boolean. Each type can be a single value or multi-valued. The following table shows a listing of query expressions that represent a reasonable CMIS query for each single property type and supported operators.

If the property is multi-valued, then the query expression is like: ANY cmis:creationDate IN (TIMESTAMP'2010-12-09T16:00:00.000Z').

Additionally, the custom widget developer should pay attention to the following issues:

• Add the solution folder id expression to the query statement: CmAcmParentSolution = 'do_F391D3A8-972F-4D23-ADC0-D03E148E5AFF:idt_616EA2CB-2F81-4AE7-8E9E-A787A0B224AF:idx_23807F89-D34F-4C4D-9838-DBF7886067B7'.
• The value of the DateTime property should be Timestamp. But generally, it is not possible to get accurate time values from user input. For example, let's say the widget only accepts a date value and you enter a value of 2010-12-10. The widget developer must convert the query expression to: cmis:creationDate >= TIMESTAMP'2010-12-10T00:00:00.000Z' AND cmis:creationDate < TIMESTAMP'2010-12-11T00:00:00.000Z'
• For String type property, if the operator of query expression is LIKE, then there are four characters that must be escaped by a preceding backslash \. Those characters are: '%', '_', '\' and '''. If the operator is equal, not equal, or IN, then the character '\' must be escaped to '\\'.
• The FROM clause identifies which virtual tables the query will run against. So if the search is a cross-type search, the FROM clause should be CmAcmCaseFolder. If you identify a specific case type, the FROM clause is the case type symbolic name.

The whole query statement will be similar to the following: SELECT * FROM CmAcmCaseFolder WHERE CmAcmParentSolution = 'ido_F391D3A8-972F-4D23-ADC0-D03E148E5AFF:idt_616EA2CB-2F81-4AE7-8E9E-A787A0B224AF:idx_23807F89-D34F-4C4D-9838-DBF7886067B7' AND ETEProperty4 = 3.14

Create the widget definition

You create the widget definition as an XML file. In the widget definition file, define the following items:

• An iScope parameter that specifies the name of the IScope class that is to be instantiated by the Mashup application.
• A resource URI element that identifies the JavaScript file that contains the logic for the custom widget.
• A title element that identifies the widget name that is displayed in the Mashup widget title bar.
• A description element that identifies the widget outline.
• An attributes element that specifies the attributes of the widget.
• An event element and eventDescription element that identify the event that the widget uses.

Listing 6 shows the basic XML definition file of a custom search widget. The name of the widget is CustomSearch. You can also add translated title or description content as child elements of the title or description element for globalization.

			
<cmisra:object>
	<cmis:properties>
		<cmis:propertyId queryName="This" displayName="This" localName="This" 
		 propertyDefinitionId="This">                    
		 <cmis:value>ido_F391D3A8-972F-4D23-ADC0-D03E148E5AFF:
		 idt_616EA2CB-2F81-4AE7-8E9E-A787A0B224AF:
		  idx_23807F89-D34F-4C4D-9838-DBF7886067B7</cmis:value>
		</cmis:propertyId>
	</cmis:properties>
	<p8ext:ClassDisplayName>Deployed Solution</p8ext:ClassDisplayName>
</cmisra:object>	
<iw:iwidget id="com.ibm.im.ecmwidgets.sample.CustomSearchWidget" 
   xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" 
   iScope="com.ibm.im.ecmwidgets.sample.CustomSearchWidget"
 allowInstanceContent="true" supportedModes="view" mode="view" lang="en">
   
  <iw:resource uri="common/CMISService.js" />  
  <iw:resource uri="common/CaseService.js" />   
  <iw:resource uri="customSearchWidget.js" />  

  <iw:itemSet id="idescriptor">
	<iw:item id="title" lang="en" value="Custom Search">
		<!--@customSearch.title@-->
		<iw:alt lang="en" value="Custom Search"/> 
	</iw:item>
	<iw:item id="description" lang="en" value="A widget that supports custom search">
		<!--@slideshow.description@-->
		<iw:alt lang="en" value="A widget that supports custom search"/> 
	</iw:item>
  </iw:itemSet> 
   
  <iw:itemSet id="attributes" >
    <iw:item id="version" value="1.0"/>
  </iw:itemSet>

  <iw:event eventDescName="desc_search" published="true" 
     id="com.ibm.ecmwidgets.acm.SearchCases"/>	
	<iw:eventDescription  id="desc_search" payloadType="CaseSearch">
		<iw:alt description="The user executed a search for cases. 
		This event is automatically wired to the Case List widget." 
		lang="en" title="Search cases"/>	
	</iw:eventDescription>

 <iw:content mode="view">
        <![CDATA[
		<div id="_IWID_viewModeContent" class="ecmwdgt ecmwdgtViewModeContent">
		</div>
      	]]>
 </iw:content>
</iw:iwidget>
			

Build the publish event that will be received by the Case List widget

The introduction section described the mechanism for displaying the search results in the Case List widget. The Search widget sends an event with required information as payload. The following section introduces the payload in detail. The custom search widget fires an event 'com.ibm.ecmwidgets.acm.SearchCases' with the CaseSearch payload to the Case List widget. The CaseSearch payload type represents the search criteria that a case worked enters in the search widget. The CaseSearch payload type uses the iWidget syntax shown in Listing 7.

			
<cmisra:object>
<iw:payloadDef name="CaseSearch">
    <iw:payloadDef name="CaseType" type="string" defaultValue="" description=""/>
    <iw:payloadDef name="ObjectStore" type="string" defaultValue="" description=""/>
    <iw:payloadDef name="SortingProperties" type="any" defaultValue="" description=""/>
    <iw:payloadDef name="SystemProperties" type="any" defaultValue="" description=""/>
    <iw:payloadDef name="SummaryProperties" type="any" defaultValue="" description=""/>
    <iw:payloadDef name="SearchProperties" type="any" defaultValue="" description=""/>
    <iw:payloadDef name="QuerySQL" type="string" defaultValue="" description=""/>
</iw:payloadDef>

			

The CaseSearch payload type includes the following properties shown in Table 2.

The sample of the payload is shown in Listing 8.

			
{"CaseSearch":
{"CaseType": "ETECase1",
"ObjectStore: "ATOS",
"QuerySQL": "SELECT * FROM ETECase1 WHERE (CmAcmCaseState = 2)",
"SystemProperties": [
{"displayName": "Case State", "symbolicName": "CmAcmCaseState", "type": "string"},
	...
 ],
"SummaryProperties": [
{"displayName": "ETEProperty1", "symbolicName": "ETEProperty1", "type": "property"},
	...
 ],
"SortingProperties": [
{"displayName": "Case ID", "symbolicName": "CmAcmCaseIdentifier", "type": "string"},
	...
 ],
"SearchProperties": [
{"displayName": "Case State", "symbolicName": "CmAcmCaseState", "type": "string"},
	...
 ]}}

			

Create the JavaScript

In the example JavaScript code in Listing 9 shows the custom search widget implements onLoad and onview methods to handle onLoad and onview events.

			
onLoad: function() {
	//get this widget's viewModeContentNodeId.
	this.viewModeContentNodeId = "_" + this.iContext.widgetId + "_viewModeContent";

	this.CMISService = new com.ibm.im.ecmwidgets.sample.common.CMISService();
	this.caseService = new com.ibm.im.ecmwidgets.sample.common.CaseService();

	this.summaryProperties = [];
	this.searchProperties = [];
},

onview: function() {
	//show the default user interface, which is the widget description.
	this._showDefaultPane();
},

			

Deploy the custom search widget

There are three main steps to deploy a customized widget. There are a number of different mechanisms for deploying widgets, such as uploading a WAR file in IBM InfoSphere® MashupHub. This section will focus on the approach by which the widgets in the IBM Case Manager are deployed. The following steps show to do this.

1. Package the widgets in a WAR file. The WAR should contain following files:
   • Widgets definition XML file
   • Widgets resource files(Javascript files, pictures and CSS files)
2. Deploy the WAR file on WebSphere® Application Server via the WebSphere Application Server admin console:
   
   1. Log in to the WebSphere Application Server admin console and navigate to Applications-->Application Types-->WebSphere enterprise applications.
   2. Click the Install button to deploy the Custom Search widget WAR and follow the install wizard.
   3. Fill out the application name and set the context to CustomSearch on the wizard.
   4. Start up the CustomSearch application upon deployment completion. Verify the widget package deployment by confirming the widget definition file at the following URL. You should be able to see the XML content.
      http://hostname:port/CustomSearch/customSearchWidget/customSearchWidget.xml
3. Register the widget in MashupHUB.

Open the InfoSphere MashupHUB window and upload the widget. Refer to the Resources section to learn about uploading a widget or an OpenSocial gadget to the Catalog in the IBM Mashup Center v3.0 Information Center, including detailed steps on how to deploy a widget. There are several ways to upload widgets, one of which is shown in Figure 3. You select the URL method to upload the widget.

A widget registration window will appear as shown in Figure 4, where you will enter the following URL (http://hostname:port/CustomSearch/customSearchWidget/customSearchWidget.xml) that was used for testing the Custom Search application in step 2 shown previously.

The customized search widget will be added in the MashupHub when you complete the steps wizard. You will be able to see the custom search widget in the widget palette after you log in to the IBM Case Manager Client.

Wire the search widget and the Case List widget together

After you successfully deploy the custom search widget, complete the following steps:

1. Add the custom search widget and the Case List widget to a page.
2. Wire the custom search widget and the Case List widget together. Figure 5 shows the event wiring panel where you can see the result of wiring two widgets together using the com.ibm.ecmwidgets.acm.SearchCases event.

After wiring two widgets together, you can use the custom search widget to collect search criteria, and use the Case List widget to display the search result. The Cases page displays the custom widget and the Case List widget side by side, as shown in Figure 6.

Back to top

Conclusion

The Case Manager Client enables customers to integrate a custom widget with its out-of-the-box widgets to create a customized Mashup application. You can implement the customized functions in a custom widget, and the custom widget can work together with Case Manager Client to use the events that are exposed in following the events contract. So Case Manager Client can be easily enhanced by integrating the custom widgets to meet the requirements for a solution. This article described how to develop a custom search widget to work together with the Case List widget in support of your special solution requirements.

Back to top

Download

Information about download methods

Resources

Learn

• Use an RSS feed to request notification for the upcoming articles in this series. (Find out more about RSS feeds of developerWorks content.)
  
  
• Learn more about IBM Case Manager in the IBM Case Manager Information Center.
  
  
• Learn more about Uploading a widget or OpenSocial gadget to the Catalog.
  
  
• Get more information about mashups in the IBM Mashup Center Information Center.
  
  
• In the ECM Zone on developerWorks, get the resources you need to advance your skills with IBM Enterprise Content Management products.
  
  
• Learn more about Information Management at the developerWorks Information Management zone. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Follow developerWorks on Twitter.
  
  

Get products and technologies

• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  
• Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out the developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

XiaoLing Cui is a software engineer on the IBM Case Management development team.

Hong Dong Zhao is a software engineer in IBM China Software Development Lab (CSDL). He works on IBM Case Management development team.

Wei Wang joined IBM in 2004. Currently he works on IBM Case Manager as a developer. He previously worked as a developer for FileNet.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Introducing the REST APIs
• Creating a custom search widget
• Conclusion
• Download
• Resources
• About the authors
• Comments

Dig deeper into Information Management on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers