Building a Custom Search Widget from IBM Case Manager …€¦ · • Set up a Model object to perform case search in ... to the standard UI features, IBM Case Manager Page widgets

Building a Custom Search Widget from IBM Case Manager 5.1.1 to IBM Case Manager 5.2.x

By Johnson Liu Software Development Engineer, IBM Case ManagerRevision 5

With special thanks to

Ming Liang GuoYajie YangLauren MayesAnuradha Shenoy

AbstractThis guide is presented to guide an application developer through the

development steps of a custom widget in IBM Case Manager v5.2.x with some commentary about a custom widget in IBM Case Manager v5.1.1. This guide contains custom widget best practices for IBM Case Manager v.5.2.x.

You will:

• Understand how custom widgets in IBM Case Manager 5.1.1.x work• Understand how to create an Eclipse workspace for IBM Case Manager

5.2.x custom widget development• Develop and convert the catalog and widget definition files• Set up and separate your custom widget content pane• Load and create a Dijit (Dojo widget)• Set up a Model object to perform case search in IBM Case Manager• Package a custom widget for deployment in IBM Case Manager• Deploy and set up a custom widget in IBM Case Manager• Update and uninstall a custom widget in IBM Case Manager

© Copyright IBM Corp 2014 1

Table of ContentsAbstract............................................................................................................................11. IBM Case Manager 5.2 Custom Widget Best Practices...............................................42. Reviewing the code and logic of the custom search widget in IBM Case Manager 5.1.1.................................................................................................................................53. Setting up the custom widget development environment.............................................84. Developing your catalog and definition JSON Files....................................................105. Setting up your Dijit HTML content pane....................................................................176. Adding Dojo AMD style loading and creating a content pane with case search.........187. Creating the model object and broadcasting the payload...........................................238. Setting Up Your Build.xml files for packaging.............................................................259. Creating your custom widget deployment compressed file........................................2710. Deploying and registering the IBM Case Manager 5.2 custom search widget using the IBM Case Manager configuration tool......................................................................2811. Adding the custom search widget to IBM Case Manager 5.2...................................3112. Updating a custom widget in IBM Case Manager 5.2...............................................3113. Uninstalling a custom widget in IBM Case Manager V5.2........................................3314. Known Limitations....................................................................................................3615. References...............................................................................................................36


Upgrading from IBM Case Manager V5.1.1 to V5.2

IBM Case Manager V5.1.1 used Business Space powered by WebSphere as thewidget platform for the Case Manager Client application. In V5.1.1, custom widgets were created using REST API calls with iWidget or Dojo.

In IBM Case Manager V5.2, the Case Manager Client application is deployed as a plugin on IBM Content Navigator. When you create custom widgets in V5.2, you use the Model API with IBM Content Navigator and Dojo 1.8. This combination allows for a more uniform user interface, better functionality, and an improved deployment and removal process.

If you created a custom widget to use with IBM Case Manager V5.1.1, you must update and convert the custom widget to the new framework in order to use it with IBM Case Manager V5.2.

These steps to convert a custom widget are based on an example of a custom search widget that was created for IBM Case Manager V5.1.1. The custom search widget provides capabilities beyond the search widget that is provided with IBM Case Manager. The details for creating this widget are explained in the following article:

http://www.ibm.com/developerworks/data/library/techarticle/dm-1106casemanagerclient/index.html




1. IBM Case Manager 5.2 Custom Widget Best Practices

IBM Case Manager Page widgets are essentially Dojo based widgets also knownas dijits that run inside of a Dojo based Page container framework. A normal Dojo dijit is a widget that is part of Dojo's User Interface (UI) library. In addition to the standard UI features, IBM Case Manager Page widgets offer two things:- Events that can be used for wiring- Widget settings

These two features allow the Business Analyst to dynamically adjust page and widget behavior with little to none programming skills.

The following guidelines should be kept in mind when creating a Page widget:

UI dijit

• First create a normal Dojo dijit which is responsible for rendering the user interface and handling user interaction to collect user input.

• Ideally, this dijit should be a designed as a reusable component that takesin a context and renders itself.

• The UI dijit should not access any IBM Case Manager Page Container related APIs, which will limit its usage to only the IBM Case Manager Case Client.

• Separating the UI dijit from the Page widget layer will allow you to reuse this dijit in a custom application or plug-in built on top of IBM Content Navigator.

• The dijit could also be reused in a non-ECM environment if it doesn’t use any ECM related API.

• The dijit should also expose necessary dojo methods/events to allow interested parties (the page widget wrapper or other custom widgets) to exchange data or get notified by user interaction.

Page widget

• After the dijit corresponding to the user interface is ready, you will need to create a Page widget wrapper that extends this UI dijit and converts it into an IBM Case Manager Page widget.

• The page widget wrapper should be the place where the page container related code resides.

• The page widget wrapper accepts widget settings from the page containerand passes them to the underlying dijit.

• It should also connect to Dojo events exposed on the dijit to be notified of user actions.


Event Listener (Optional)

As an optional separation, you could separate the event handling logic from the page widget when the event handling gets too complex. For e.g. if you have complex logic to pre-process or post-process the event data, you can create a separate event listener object which holds the event handler implementations. The page widget could then delegate the event handling logic to the event listener object.

Terms of use

When developing or extending custom widgets in IBM Case Manager, avoid referencing the IBM Case Manager Case Client JavaScript code base directly or copying the Case Client JavaScript code. It is recommended to follow the IBM Case Manager JavaScript API and utilize public functions there. Private functionsfrom the IBM Case Manager Case Client code can change between releases and will cause maintainability and functionality issues for your custom widgets.

When using public functions in your custom widgets, you can create your customwidget as a subclass to the IBM Case Manager out of the box page widgets. Only public methods can be overwritten within the subclass and as needed, call the parent class inherited function accordingly. You may overwrite the the method if full customization is needed.


2. Reviewing the code and logic of the custom search widget in IBM Case Manager 5.1.1

The following diagram shows the basic logic of the custom search widget construction:

The original IBM Case Manager V5.1.1 Custom Search widget contains some hard-coded values. As a result, you must update the widget for your new specificsolution and case type. It is important to understand these customizations in case your Solution Administrator makes a new custom property or wants the custom search widget to specifically search on different case properties.

a. In customSearchWidget.js in your WAR file, make sure to customize the _showSearchableProperties function and add the fields that you want to show in the user interface portion of the custom search widget. In the code snippet below, the bolded values are specific to the Credit Card Dispute Management solution associated with the DeveloperWorks sample for the custom search widget in IBM Case Manager 5.1. Note that CustomerName and AssignedDate are by default in the Credit Card Dispute Management solution. AssignedToUseris a custom property that was added by the Solution Administrator.

_showSearchableProperties: function(properties) {var propertiesDef = this._getPropertiesDefinition(properties);

var markup = '';markup += '<div>' +

'<table><tbody>'+ '<tr>'+ '<td><label for="CustomerName">Customer Name:</label></td><td><input value="" id="CustomerName" type="text" style="width: 150px"></td>' +

'</tr>'+ '<tr>'+ '<td><label for="Assigned Date">AssignedDate begins:</label></td><td><input value="" id="AssignedDate" type="text" style="width: 150px"></td>' + '</tr>' + '<tr>' + '<td><label for="AssignedToUser">AssignedToUser equals:</label></td><td><input value="" id="AssignedToUser" type="text"


style="width: 150px"></td>'+ '</tr>'+ '</tbody></table>'+ '</div>';markup += '<br/>' +

' <input type="button" id="customSearchButton" value="Search" />' +' <br/>' +' </div>' +'</div>';

document.getElementById(this.viewModeContentNodeId).innerHTML += markup;

var customSearch_searchButton = document.getElementById("customSearchButton");dojo.connect(customSearch_searchButton, "onclick", this, dojo.hitch(this, "_onClickSearchButton"));

},

b. Make sure to customize the _getSearchedProperties function and add in the properties that are specific to your solution. These will be added together for a SQL query later on. In the code snippet below, bolded values are specific to the Credit Card Dispute Management solution that are associated with the DeveloperWorks sample for the custom search widget in IBM Case Manager 5.1.

_getSearchedProperties: function() {var payloads = [];var Customer_Name = document.getElementById("CustomerName");if(Customer_Name.value) {

var payload = {symbolicName: 'CustomerName',displayName: "Customer Name",operator: "LIKE",

propertyType: "string",value: Customer_Name.value

};payloads.push(payload);

}var AssignedToUser = document.getElementById("AssignedToUser");if(AssignedToUser.value) {

var payload = {symbolicName: "AssignedToUser",displayName: "AssignedToUser Integer",operator: "LIKE",

propertyType: "string",value: AssignedToUser.value


}var Assigned_Date = document.getElementById("AssignedDate");if(Assigned_Date.value) {

var payload = {symbolicName: '"AssignedDate"',displayName: "Assigned Date",operator: "eq",

propertyType: "dateTimeBegin",value: Assigned_Date.value


}return payloads;

},

c. Make sure to also customize the _getSQL function to search by a specific case type. The rendition of the custom search widget uses the Investigate Fraud


case type. To use another case type, update the query below. In the code snippet that follows, bold values are specific to the Credit Card Dispute Management solution that is associated with the DeveloperWorks sample for thecustom search widget in IBM Case Manager 5.1. In the _getSQL function below,if(searchProperties !== "undefined") has been added to check for empty searches, making the function more robust. Also, two else if statements were added at the end to format the SQL appropriately.

_getSQL: function(searchProperties) {var sql = "SELECT * FROM CCDMT_InvestigateFraud ";sql += "WHERE ";sql += this._getSolutionConstraint();

if(searchProperties !== "undefined"){

if(searchProperties && searchProperties.length > 0) {for(var i = 0; i < searchProperties.length; i++) {

sql += " AND ";var property = searchProperties[i];sql += " " + property.symbolicName + ""; if(property.propertyType == "string")

sql += " LIKE '%" + this._encodeLiteralByOperator(property.value, property.operator) + "%'";

else if(property.propertyType == "integer")sql += " = " + property.value + "";

else if (property.propertyType == "dateTimeBegin")sql += " >= TIMESTAMP '" + property.value + "T00:00:00.000'" + "

";else if (property.propertyType == "dateTimeEnd")

sql += " <= TIMESTAMP '" + property.value + "T23:59:59.000'";

}}

}console.log(sql);return sql;

},

d. The _getSolutionName and _getCaseType functions are also customized withthe name of the specific solution. Note that these are hard coded for a Credit Card Dispute Management solution with the name Credit_Card_Dispute_Management and with the solution prefix of CCDMT.

In the code snippet below, bold values are specific to the Credit Card Dispute Management solution that were added in after using the DeveloperWorks sample for the custom search widget in IBM Case Manager 5.1.

_getSolutionName: function() {return "Credit_Card_Dispute_Management";

},

_getCaseType: function() {return "CCDMT_InvestigateFraud";

}

e. Setting up the Search Payload in IBM Case Manager V5.1.1


After retrieving the values from each text box to search on and putting that into a payload variable, the function _getSearchPayload() calls _getSearchedProperties() to construct the search payload. There were no additional customizations to be done to _getSearchPayload, but it is important tonote how this custom search widget accomplishes get search payload versus theupcoming IBM Case Manager V5.2 custom search widget.

_getSearchPayload: function() {var searchProperties = this._getSearchedProperties();var searchPayload = {

CaseType: this._getCaseType(), ObjectStore: this._getObjectStore(), SortingProperties: this.SORTING_PROPERTIES, SystemProperties: this.SYSTEM_PROPERTIES, SearchProperties: searchProperties, SummaryProperties: this._getPropertiesDefinition(this.summaryProperties), QuerySQL: this._getSQL(searchProperties) };

return searchPayload;},

f. Firing the broadcast event in IBM Case Manager V5.1.1

Sending the search payload results is done using iContext. There were no further customizations required for this broadcast statement. However, it is important to note that this is using Business Space to broadcast the event and payload out. In the upcoming IBM Case Manager 5.2 custom search widget, you use a different method to broadcast an event and a payload.

this.iContext.iEvents.fireEvent("com.ibm.ecmwidgets.acm.SearchCases", "searchDefinition", searchPayload);

3. Setting up the custom widget development environment

In this section, we will use Eclipse to set up the IBM Case Manager 5.2 custom widget development environment. Specifically, this example uses the Eclipse IDE for Java EE Developers package with the JavaScript editor plug-in. The Navigator API plug-in jar can be obtained by finding your navigatorapi.jar file on your development environment. It is detailed in the IBM Content Navigator Redbook, which can be found at the following link: http://www.redbooks.ibm.com/redbooks/pdfs/sg248055.pdf

More details about setting up your development environment and custom widget setup can be found in the following article: https://www.ibm.com/developerworks/mydeveloperworks/blogs/e8206aad-10e2-4c49-b00c-fee572815374/resource/ACM_LP/ICM52CustomWidgets.pdf


https://www.ibm.com/developerworks/mydeveloperworks/blogs/e8206aad-10e2-4c49-b00c-fee572815374/resource/ACM_LP/ICM52CustomWidgets.pdf

https://www.ibm.com/developerworks/mydeveloperworks/blogs/e8206aad-10e2-4c49-b00c-fee572815374/resource/ACM_LP/ICM52CustomWidgets.pdf

http://www.redbooks.ibm.com/redbooks/pdfs/sg248055.pdf

You can obtain the workspace files from the article below. The steps below are meant to illustrate the flow of how to construct a standalone custom search widget.

The code for that article is here:https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=e8206aad-10e2-4c49-b00c-fee572815374#fullpageWidgetId=Wf2c4e43b120c_4ac7_80ae_2695b8e6d46d&file=046c4fb2-b3d1-4783-acfe-6a34b28d5538

It is important to note that there are 3 main folders, ICMRegistry, ICMCustomPlugin, and ICMCustomWidgets. ICMRegistry is the file that provides a simple widget definition JSON file and a catalog JSON file. The ICMCustomWidget folder contains the IBM Case Manager Custom Search Widget code and is the location where you will construct the custom search widget. The ICMCustomPlugin folder is where you construct the jar file needed to create a plugin for IBM Content Navigator.

1. Start Eclipse and create your workspace. 2. Create a Java Project:

a) In your development, environment, click File > New > Project > Java Project.

b) In this example, give the project name as “csw” (for “Custom Search Widget”). Leave the rest of the options as default.

c) Click Finish to create the project.

3. Using the Widget_Workspace folder provided in the assets of this article, findthe folder ICMRegistry. Right-click the ICMRegistry folder and select Copy. The ICMRegistry folder contains your widget definition JSON file and the catalog JSON file.

4. Navigate back to Eclipse and paste the ICMRegistry folder into your project. Validate that your csw Java project resembles the screenshot below.

5. Navigate back to the Widgets_Workspace folder. Locate the


https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=e8206aad-10e2-4c49-b00c-fee572815374#fullpageWidgetId=Wf2c4e43b120c_4ac7_80ae_2695b8e6d46d&file=046c4fb2-b3d1-4783-acfe-6a34b28d5538



ICMCustomPlugin folder. Copy and paste the ICMCustomPlugin folder file intoyour Eclipse project csw.

6. Navigate back to the Widgets_Workspace folder. Copy and paste ICMCustomWidgets folder into your Eclipse project csw.

7. Navigate back to the Widgets_Workspace folder. Copy and paste the Build folder into your Eclipse project csw.

8. Enable line numbers under Window > Preferences > General > Editors > Text Editor > Show Line Numbers

4. Developing your catalog and definition JSON Files

The next step is to develop your catalog and widget definition JSON files. These files are needed to define your custom widget properties and define any event broadcasting or handling within your custom widget.

In IBM Case Manager 5.1.1, the catalog and widget definition files were in XML format. In order to do a conversion, make sure to map the values between the XML files to the new JSON files.

1. Within Eclipse, open the ICMRegistry folder and double-click the file Catalog.json to open it.

2. Note that the Name, Description, and other fields are not filled in.

Starting with the Name and Description fields near the top of Catalog.json, enter a value for the name of this custom widget package into the name field. Likewise, enter a description into the description fields.

See the following example: "Name":"Custom Search Widget Package", "Description":"IBM Case Manager Custom Search Widget Package",

3. Add in the value for Categories, which are the category values for this specific custom widget package that you will see in the palette bar on the left in Page Designer.

Enter values for the id and title for the Categories section.

See the following example:


4. Add the values for the Widgets section in the Catalog.json file. Enter values for the id and title fields.


"Widgets":[{

"id":"CustomSearchWidget", "title":"Simple Custom Search Widget",

5. Add the value for the category. Make sure to give your category the same name that you provided for the category section in the previous step.


6. Add the description value for the widget.


"Widgets":[{

"id":"CustomSearchWidget", "title":"Simple Custom Search Widget", "category":"CustomWidgets", "description":"This widget shows payload from Search Widget",

7. Enter the value for the widget definition file. Since it is already created in theICMRegistry folder, enter the file name of the widget definition file, CustomSearchWidget.json.



8. Enter the value for the preview, icon, and previewThumbnail images for thecustom widget. The image files are already imported into the ICMRegistry folder.

In your Eclipse navigation pane on the left, expand the images folder under ICMRegistry and enter the path names for the corresponding preview, icon, and previewThumbnail images.



9. For the Catalog.json file, define the runtimeClassName. Because the ICMCustomWidget folder with the widget source code is already imported, find the main runtimeClassName.

In your Eclipse navigation pane on the left, expand ICMCustomWidgets > WebContent > icm > custom > pgwidget > customSearchWidget > CustomSearchWidget.js

This is the path to define in the runtimeClassName field in the Catalog.json file.


10. Double click the widget definition JSON file, CustomSearchWidget.json to open it in the Eclipse navigation pane on the left. You may notice that the first part of the file looks similar to the end of the Catalog.json file.

11. Using the same values you entered for the Catalog.json file, fill in the fields for the name, description, and so on for the CustomSearchWidget.json file.



12. For the properties section in your CustomSearchWidget.json file, you can enter one or more properties to be displayed in the settings window of your custom widget in Page Designer.

Set a PreferredHeight property for sizing of the custom widget. Hide this property and set it to be invisible. This step describes one way to set a property to make it invisible to the user.

Set the id, disabled, required, visibility, and title fields.



13. Define the next property as a custom string that is visible to the user.

Set the values for id, defaultValue, required, visiblity, and title.


14. Define the events section of the custom widget. This section determines whether to handle or broadcast an event and sets the function name to handle the event if applicable.

In this example, set the id to icm.SearchCases as the event id to broadcast. You can also handle this event.

15. Set the title and description. These are not specific like icm.SearchCases, so provide your own title and description to those fields.


16. Set the functionName and direction fields. Because the widget is broadcasting an event to another widget, set direction to broadcast. You can also set it to subscribed if you want to handle an event published from another widget. Set the functionName to handleICM_SearchCasesEvent as that is the function name in the .js file.

The following example shows the updated events section of your CustomSearchWidget.json file:


17. Save all of your changes to the two JSON files in Eclipse.


5. Setting up your Dijit HTML content pane

The next step is to set up your Dijit HTML content pane for the custom widget. The content pane is where you can add div tags or set up HTML and JavaScript code to display when your widget renders.

This HTML content pane is connected to the Dijit content pane class where the implementation to retrieve the solution attributes to display them on the content pane is. You can find this code in CustomWidgetContentPane.js.

1. In your Eclipse project navigation pane on the left, navigate to CustomWidgetContentPane.html under ICMCustomWidgets > WebContent > icm > custom > pgwidget > customSearchWidget > dijit > templates.

2. Double click to open the CustomWidgetContentPane.html file.

3. We will be dynamically populating our custom search widget in this HTML file. This has already been added for you.

4. Add a submit button to detect that the user wants to search on the user defined values for the variables. We will add this button underneath the div tag labeled fieldsNode.


5. Make sure to save CustomSearchWidget.html and close the file. Leave Eclipse open.


6. Adding Dojo AMD style loading and creating a content pane with case searchThe next step is to add Dojo functionality to retrieve the user defined values for searching. You can also declare Dojo AMD style loading in CustomSearchWidget.js. In this section, you retrieve the user defined values from the content pane and use them for case search.

For the CustomWidgetContentPane class, it is a standard Dojo dijit, which is responsible for rendering the user interface of the custom search widget. It calls an event stub method when users click the submit button. And the CustomSearchWidget will connect to that method and construct the page widget event and send it out. The event construction logic will be wrapped into the CustomWidgetContentPaneEventListener class, for the purpose of separating the complex logic from the page widget wrapper class. In this way, it is possible to reuse the CustomWidgetContentPane dijit in other Content Navigator plugin where the case manager page container doesn't exist. Note: For this example, you need to make sure the ICM model is loaded and initialized properly if you want to run it outside of ICM page environment.

1. In your Eclipse project navigation pane on the left, navigate to CustomSearchWidget.js under ICMCustomWidgets > WebContent > icm > custom > pgwidget > customSearchWidget.

2. Double click on CustomSearchWidget.js to open it.

3. Define other JS files using Dojo AMD. Notice that the Dojo libraries have already been loaded like dojo/dom-attr and dojo/query. You also have other IBM Case Manager JS files that are referenced, such as icm/util/SearchPayload and icm/base/BasePageWidget.


In your Eclipse project navigation pane on the left, note the path for CustomWidgetContentPaneEventListener.js and CustomWidgetContentPane.js.

4. Define these files in the CustomSearchWidget.js file so that you can call the functions in those classes, if necessary.

Fill in the last two empty quotes in CustomSearchWidget.js file in the define header.


5. Add the two JS file definitions into the function method at the top.


It is also possible to build the search payload using SearchTemplate instead of the ceQuery. This change can be performed inside of CustomSearchWidget.js (event handler class) without modifying the content pane dijit. This demonstrates the benefit of separating the UI dijit from the business logic. Here is the following code to switch between the two ways of payload construction. The commented code on line 32 is how to generate a search template while the code on line 31 is


how to generate a ceQuery payload.

6. In order to dynamically load the solution attributes into the custom search widget, a Model API call must be made. By using the IBM Case Manager JavaScript API Reference (http://pic.dhe.ibm.com/infocenter/casemgmt/v5r2m0/topic/com.ibm.casemgmt.development.doc/jsdoc/index.html), icm.model.Solution contains a function namedretrieveAttributeDefinitions(callback) that gives the necessary information to display for the user to search upon the case properties of the solution.

Add this call into CustomWidgetContentPane.js in the createSearchFields function.


solution.retrieveAttributeDefinitions(lang.hitch(this, this._buildSearchFields));

7. After performing the Model API call with retrieveAttributeDefintions(callback), we push these attribute definitions into the next function in CustomWidgetContentPane.js named _buildSearchFields(attrs). We are handling simple data types in this function.

We can write output directly to the content pane's inner HTML. Here we are outputting what the attribute's id and name. See the following example:

var fields = [];

fields.push("<table>"); array.forEach(attrs, function(attr) { // if(attr.hidden || attr.system || !attr.dataType || attr.displayMode !== "readwrite" || attr.dataType === "xs:object" || attr.dataType === "xs:guid") {


http://pic.dhe.ibm.com/infocenter/casemgmt/v5r2m0/topic/com.ibm.casemgmt.development.doc/jsdoc/index.html


if(attr.hidden || attr.id.indexOf("_") == -1) { return; } // handle the boolean type attributes specially if(attr.dataType === "xs:boolean") { fields.push("<tr><td><h3>"); fields.push(attr.name); fields.push("</h3></td><td><input type=\"radio\" value=\"true\" name=\""); fields.push(attr.id); fields.push("\">true</input>"); fields.push("<input type=\"radio\" value=\"false\"name=\""); fields.push(attr.id); fields.push("\">false</input>"); fields.push("</td></tr>"); f.push(attr); } else if(attr.dataType === "xs:timestamp"){ // ignore timestamp attributes for the time being console.log("skip data time field - " + attr.id); } else { fields.push("<tr><td><h3>"); fields.push(attr.name); fields.push("</h3></td><td><input type=\"text\" size=\"25\" name=\""); fields.push(attr.id); fields.push("\"></input>"); fields.push("</tr></td>"); f.push(attr); } }); fields.push("</table>"); this.fieldsNode.innerHTML = fields.join("");

Next, we are going to send the user-inputted values for each attribute to the CustomWidgetContentPaneEventListener to construct the searchPayload andthe Model object in the next section. We are adding the code to do this in the postCreate function in CustomWidgetContentPane.js.


on(this.submitMeButton, "click", function(evt){ var form = that.searchform; var f = that.fieldsInForm; var valueObject = {};

array.forEach(f, function(attr) { var v; if(attr.dataType === "xs:boolean") { var i = 0, length = form[attr.id].length; for(; i<length; i++) { if(form[attr.id][i].checked) { v = form[attr.id][i].value; break; }


} } else { v = form[attr.id].value; }

if(v) { valueObject[attr.id] = {"attr": attr, "value":v}; } }); that.onSearchSubmitted(valueObject); });

8. Construct the search parameters to call the setModel(model) function in icm.util.SearchPayload to set the schema and data structures to perform a case search. Below is a screenshot of the setModel(model) function in icm.util.SearchPayload in the IBM Case Manager JavaScript Reference documentation.

We will use Model API calls to define the objectStore, solution, and caseType parameters for the Model object for the search payload in CustomWidgetContentPaneEventListener.js.

Here is one way to define params.ObjectStore. We are defining this in the buildPayload(values) function.


params.ObjectStore = solution.getTargetOS().id;

Next, the API reference notes we need the case type to do the search on. Here is one way to get the first case type defined in the solution to search on. We are defining this in the function this.widget.solution.retrieveCaseTypes(function(types)) function within the buildPayload(values) function in the CustomWidgetContentPaneEventListener.js file.


params.caseType = types && types.length > 0 && types[0].name; //


default to the first case type

We will then define the solution right after.


params.solution = solution;

9. Save all files that are open in Eclipse as a checkpoint.

7. Creating the model object and broadcasting the payload

The next step is to create the Model Object and broadcast the payload. These high-level steps are required to accomplish search using the custom widget:

• Set variable params with the Target Object Store, solution, case type, and ceQuery.

• Pass the variable params to icm/util/SearchPayload.js setModel function, which sets the Model object needed.

• Call icm/util/SearchPayload.js getSearchPayload function, which conducts the search and retrieves the payload to send.

• Load a variable with the payload from getSearchPayload.• Broadcast the payload received to Case List widget.


1. Set and pass the variable params.

With CustomWidgetContentPaneEventListener.js already open, setting the necessary variable params for Target Object Store, solution, case type, and ceQuery is already completed in the previous section.

To pass the variable params, use the setModel function. By referencing the JavaScript documentation for the icm/util/SearchPayload.js file, you can see the setModel function. The setModel along with the getSearchPayload function can be found in the icm/util/SearchPayload JavaScript API referencehere: http://pic.dhe.ibm.com/infocenter/casemgmt/v5r2m0/topic/com.ibm.casemgmt.development.doc/jsdoc/symbols/icm.util.SearchPayload.html

We are defining this in the this.widget.solution.retrieveCaseTypes(function(types)) function within the buildPayload(values) function.


searchPayload.setModel(params);

2. Call the getSearchPayload() function and pass the payload received into a variable. We are also broadcasting the payload out with the event “icm.SearchCases”. The Case List widget will handle this event. The Case List widget can pick up the icm.SearchCases incoming event and the payload to display the results.


searchPayload.setModel(params); var w = that.widget; searchPayload.getSearchPayload(function(payload) {

w.onBroadcastEvent("icm.SearchCases", payload); console.log(payload); that.displayPayload(payload); });

Note that the above code works for IBM Case Manager 5.2 fix pack 1 and later.

Use the following example below to create the search payload for IBM Case Manager 5.2 eGA version:

searchPayload.setModel(params); var payload = searchPayload.getSearchPayload(); that.widget.onBroadcastEvent("icm.SearchCases", payload); console.log(payload);


http://pic.dhe.ibm.com/infocenter/casemgmt/v5r2m0/topic/com.ibm.casemgmt.development.doc/jsdoc/symbols/icm.util.SearchPayload.html

http://pic.dhe.ibm.com/infocenter/casemgmt/v5r2m0/topic/com.ibm.casemgmt.development.doc/jsdoc/symbols/icm.util.SearchPayload.html

that.displayPayload(payload);

4. Save CustomWidgetContentPaneEventListner.js.

8. Setting Up Your Build.xml files for packaging

The next step is to set up your build.xml file. The project requires three build.xml files, one for ICMCustomWidgets, one for ICMCustomPlugin, and one master build.xml file that creates the zip file needed for deployment.

1. Edit the build.xml file in the folder ICMCustomWidgets. Locate this file and double click on it to open it.

Set the directory of your createWAR file. Add all of the files and folders under ICMCustomWidgets > WebContent and into a war file. Set value for <fileset dir=””> under the <target name=”createWAR”>.


2. Set the fileset directory for the <target name”=createEAR”>. In this case, include everything in the ICMCustomWidgets folder and include the war file.


<target name="createEAR"><ear destfile="./ICMCustomSearchWidget.ear"

appxml="./WebContent/META-INF/application.xml"> <fileset dir="." includes="*.war"/>


</ear></target>

Make sure to save your changes to ICMCustomWidget > build.xml.

3. Next, edit the build.xml file for the ICMCustomPlugin. Double click to open thefile.

4. In order to build the plugin for IBM Content Navigator, you must include the navigatorapi.jar file. Find it in your <ECMClientInstallDirectory>/configure/lib or in our case it is C:\Program Files(x86)\ibm\ECMClient\configure\lib. Copy the navigatorAPI.jar file and paste it into your lib folder under ICMCustomPlugin in your Eclipse project. Include the path for the classpath of <target name=”buildPlugin”> in the build.xml file for ICMCustomPlugin.


Make sure to save your changes.

5. Double click the build.xml file in the Build folder to open. This is the master build.xml file that generates the zip file for the custom widget deployment.

This file does not require edits. Note that the file is calling the ICMCustomPlugin and ICMCustomWidgets directories to package them together in a zip file.


9. Creating your custom widget deployment compressedfile

1. Within the Eclipse environment, right click on build.xml and select “Run as...”, then select “2. Ant Build....”


2. Make sure to select “all [default]”, “clean”, and “package”, then select run to create your jar file with your source code. Make sure the execution order matches the screenshot below.

3. Validate that your build.xml ran successfully in the console window in Eclipse.

10. Deploying and registering the IBM Case Manager 5.2 custom search widget using the IBM Case Manager configuration tool

After you update the widget, you deploy and register the IBM Case Manager 5.2 custom search widget using the IBM Case Manager configuration tool. You can use the zip file that you created by using the master build.xml file. You can also create this zip file using other methods, like renaming the extension to .ear from a .zip extension.

An IBM Case Manager 5.2 custom widget zip must include the following:

• Custom widget plug-in jar (also containing the page widget code)


• Custom widget definition json file (in a folder)

• Custom widget catalog file (in a folder)

• Optional ear file (only if the custom widget code is packaged as a ear)

Deploying using IBM Case Manager configuration tool task can be done with or without an EAR file.

If you have a small widget customization, using only the JAR is sufficient. It is recommended to use the IBM Case Manager administration client web client to register your custom widget if you are using only a JAR file. If you have a large application, it is recommended to deploy the EAR file separately and use the IBM Case Manager configuration tool.

If you have a large application deploy it as an EAR. For example, the Case Manager Client plugin is a collection of widgets. So, IBM Content Manager allows the optional EAR for deployment. In IBM Case Manager 5.1.1, deploying a custom widget involved either installing the custom widget in WebSphere Application Server or running the $AdminTask and Business Space commands iat a command line. In IBM Case Manager 5.2, you can deploying a custom widget simply by running a task in the IBM Case Manager configuration tool.

For the custom search widget, use the EAR file.

1. On the target system, start the IBM Case Manager configuration tool.

2. Open the configuration profile that you want to use.


3. Right click on the profile in the navigation tree or on any task and select Add New Task > Deploy and Register Widgets Package.

This makes a copy of the Deploy and Register Widgets Package.

4. Rename the newly created task to Register and Deploy Custom Widgets.

5. Change the Widgets package file path of the task to the location of your custom widget zip file and save the change.

6. Run the task.


7. Validate that the task ran successfully in the console below the task.

11. Adding the custom search widget to IBM Case Manager 5.2

After you register and deploy the custom widget, you can start to use it in your solutions.

1. Open Case Builder from the target system.

2. Create a new page on the solution or select an existing one.

3. Find the custom widget in the Page Designer. Note that there is a new category labeled “Custom Widgets” in Page Designer as defined in the Catalog.json file.

4. Drag the widget from the left palette to the middle to add it to the page. Make sure that you set the widget height settings to be Automatic instead of 100% in Page Designer.

5. Save and close the solution.

6. Click Commit on Case Builder page for your solution.

7. Click Deploy on Case Builder page for your solution.

8. Test the custom widget in Case Client during run time by clicking Test on Case Builder page for your solution.

12. Updating a custom widget in IBM Case Manager 5.2

If you have updated the code for your custom search widget, the steps below willhelp you to redeploy your custom search widget. Note that some of the steps below are optional while others are mandatory. Please see note below the steps depending on your level of changes. This also applies to other custom widgets in


IBM Case Manager 5.2.

1. Remove the custom widget from any page in Page Designer in Case Builder that the custom widget is added to. (optional)

2. After you update and package the widget, re-run the “Deploy and Register Widgets” task in your configuration tool with your new updated zip file for your custom widget. (mandatory)*

3. Clear your browser cache and cookies. (mandatory)*

4. Re-add the new custom widget to the pages in IBM Case Manager 5.2 within Page Designer in Case Builder. (optional)

5. Commit your changes and deploy the solution with your new widget.(optional)

However, any changes that involve changing your JSON files, events, or wiring of the widget will require steps 1-5 above to be executed. Steps 2-3 are sufficientfor simple changes to the widget JS files like updating message outputs.

In order to view where your custom widget's EAR files was deployed, go to <WAS install directory> / <WAS profile> / installedApps / <node/cell> / <custom widget directory>.

In order to view where your custom widget's plugin was deployed, go to <CaseManagement install directory> / configure / properties / plugins.

In order to view where your catalog.json and widget definition.json files were deployed, go to <Case Management install directory> / configure / properties/ widgetsPackage / <Design Object Store> / <Custom widget package>


13. Uninstalling a custom widget in IBM Case Manager V5.2

1. Navigate to your solution in Case Builder, click Edit, and then navigate to Pages. Select the page that includes your custom widget.

2. On the widget, click the down arrow and click Delete Widget. Repeat this step for each instance of the custom widget on the page.

Repeat steps 1 and 2 for each page that includes the custom widget.

3. Open your IBM Case Manager administration client. The default URL is http://hostname:9080/navigator/?desktop=icmadmin

4. In the navigation tree, under Object Stores, click on your design object store name.


http://hostname:9080/navigator/?desktop=icmadmin

5. Expand the Widgets packages folder, right-click on your custom widget, and select Unregister custom widgets. This will unregister your custom widget fromIBM Case Manager.

6. Click Finish on the next dialog.

7. Navigate to the admin desktop of IBM Content Navigator. The URL might be ina format like the following: http://hostname:9080/navigator/?desktop=admin


http://hostname:9080/navigator/?desktop=admin

8. Expand the Plug-ins folder, right-click on your custom widget plug-in, and click Delete.

9. (optional) If your custom widget zip file contained an EAR file, you must uninstall the zip file in your application server. The following example is in the WebSphere Enterprise Applications dialog in WebSphere Application Server.

Make sure to restart your application server and to clear your browser cache after.


14. Known LimitationsThe custom search widget is not designed to perform searches on multi-value case properties.

The custom search widget is not meant to be deployed alongside the custom widget package here: https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=e8206aad-10e2-4c49-b00c-fee572815374#fullpageWidgetId=Wf2c4e43b120c_4ac7_80ae_2695b8e6d46d&file=046c4fb2-b3d1-4783-acfe-6a34b28d5538

The custom search widget is now bundled together in the custom widget package that contains other custom widgets that are extended from the IBM Case Manager out of the box page widgets.

15. References

1. IBM Case Manager JavaScript API Reference◦ http://pic.dhe.ibm.com/infocenter/casemgmt/v5r2m0/topic/com.ibm.

casemgmt.development.doc/jsdoc/index.html2. Selected sessions from IBM Case Manager V5.2 Product Implementation

and Maintenance Training (PIT / PMT) (220246):◦ 09-ICM 5.2 API Overview PIT PMT (47 minutes)◦ 10-ICM 5.2 Javascript Tool Kit - Model Classes PIT PMT (31

minutes)◦ 13-ICM 5.2 Javascript Tool Kit-UI Classes PIT PMT (58 minutes)◦ 14-ICM 5.2 Event Wiring Examples-Debugging Tips PIT PMT (36

minutes)◦ 15-ICM 5.2 Building Custom Page Widgets PIT PMT (43 minutes)◦ 29-ICM 5.2 Upgrading Widgets From 5.1.1 to 5.2 PIT PMT (44

minutes)3. IBM Case Manager V5.2.0 Custom Page Widgets and Actions

Development◦ https://www.ibm.com/developerworks/community/blogs/e8206aad-

10e2-4c49-b00cfee572815374/entry/ibm_case_manager_v5_2_0_custom_page_widgets_and_actions_development?lang=en

4. Mapping Case REST API calls to Model API calls when converting customwidgets to ICM 5.2

◦ https://www.ibm.com/developerworks/community/blogs/e8206aad-10e2-4c49-b00cfee572815374/entry/mapping_case_rest_api_calls_to_model_api_calls_when_converting_custom_widgets_to_icm_5_2?lang=en


https://www.ibm.com/developerworks/community/blogs/e8206aad-10e2-4c49-b00cfee572815374/entry/mapping_case_rest_api_calls_to_model_api_calls_when_converting_custom_widgets_to_icm_5_2?lang=en



https://www.ibm.com/developerworks/community/blogs/e8206aad-10e2-4c49-b00cfee572815374/entry/ibm_case_manager_v5_2_0_custom_page_widgets_and_actions_development?lang=en








5. Using the Model API and REST API call in custom widgets for IBM Case Manager V5.2

◦ https://www.ibm.com/developerworks/community/blogs/e8206aad-10e2-4c49-b00cfee572815374/entry/using_the_model_api_and_rest_api_call_in_custom_widgets_for_ibm_case_manager_v5_2?lang=en


https://www.ibm.com/developerworks/community/blogs/e8206aad-10e2-4c49-b00cfee572815374/entry/using_the_model_api_and_rest_api_call_in_custom_widgets_for_ibm_case_manager_v5_2?lang=en



Documents

Building a Custom Search Widget from IBM Case Manager …€¦ · • Set up a Model object to perform case search in ... to the standard UI features, IBM Case Manager Page widgets