This chapter covers the creation and configuration of Java customizations required for processing Events triggered by the IBMFileNetContent Engine. It describes the development of custom Java code and the deployment of a Code Module which is invoked. The use of Workflow Subscriptions which enable a workflow to be launched on the storage of a document in the Content Engine Object Store is described with a step-by-step example.
The full Content Engine Java APIdocumentation can be found with the following link:
IBM recommends that Content Engine Web Services can be used where a system is not compatible with the use of the IBM FileNet Java or .NET API. For further Content Engine Web Service code examples, see
Part 1 – Supporting Documents. This Part provides references to freely downloadable documents which provide additional reading material supporting the chapter.
Part 2 – Configuring Java Components for Content Engine Events. In this Part, a Java project is built, step by step, to create and deploy the example fn_eventhandlers.jar file, which we then show how to deploy, for use with the Audit Master solution covered in Chapter 1.
Part 3 – Testing the Add Document to Folder Event. In this Part, we test the Add Document to Folder Event. The TestHarness code in the Eclipse project requires a valid Document Object to be used to link to an existing AUDIT_TEST folder which is created and used as a test setup for the EventHandler code.
Part 4 – The DbExecute Workflow Step for Calling Database Stored Procedures. In this Part, we describe the use of the DbExecute workflow step. This allows a Database Stored procedure to be invoked from an IBM Case Manager Workflow step. This is supported using the IBM FileNet P8 Process Designer tool.
Part 5 – Standalone Process Designer Installation. This Part describes the installation and configuration required to install the Windows Client Standalone Process Designer, which is then used to add a DbExecute workflow step to the Audit Master Solution we created in Chapter 1.
Part 1 – Supporting Documents
There are two very useful downloads which provide additional examples and links to downloadable Java code supplied freely by IBM.
IBM FileNet Java API Call Examples
This MS Word document can be downloaded as shown in Figure 2-1. It describes the download of an IBM DemoJava.zip file and the configuration of the Java Eclipse IDE which can be configured to run working examples to show the use of the IBM FileNet Content Manager Java API calls to create, store, and retrieve Document and Folder objects in a Content Object Store.
This gives the downloaded document, entitled
“IBM FileNet P8 Java Development on ECM Cloud Private Container P8 Examples”
This free download document, IBMFileNetP8JavaDevelopmentonECMCloudPrivateContainerP8Examples.docx, can be downloaded using the URL link:
The Java code developed for custom events should be compiled into an appropriately named Java archive, or “jar” file. To install this code, the jar file should be made accessible to a machine that has access to the acce (IBM Administrative Console for Content Platform Engine) application.
“IBM FileNet P8 Java Development on ECM Cloud Private Container P8 Examples”
This describes the download and installation of an Eclipse IDE for Java development and the basic configuration of the supporting Java jar files for the IBM FileNet API on a Red Hat RHEL 8.0 Linux system.
For the Audit system, the following Java code in this chapter provides the custom event, AddDocToFolder. This Java code will work on Red Hat Linux or MS Windows operating systems which have IBM FileNet Content Engine installed.
In enterprise applications, normally code needs to be included in a “war” file and deployed so that its classes are accessible. The Content Engine Event code, however, uses a Java jar file with the classes required for events which can be contained within the Content Engine Object Store. This makes for easy deployment and maintenance. The jar file is added to the Object Store through the acce tool, which has the ability to choose hidden classes.
Part 2 – Configuring Java Components for Content Engine Events
In this Part, we will build a Java project, step by step, to create and deploy the example fn_eventhandlers.jar file, which we then show how to deploy, for use with the Audit Master solution covered in Chapter 1.
The final Java project structure we build in the Eclipse Java IDE will have the main Java components as shown in Figure 2-2.
The Java code project is created using the following steps:
1.
In the Eclipse Java IDE, select the menu items File ➤ New Project.
2.
Eclipse supports a number of different project types; we will select a standard Java project type.
3.
The Next command is clicked to add the Project attributes.
4.
The Project name is entered as AuditEventHandler.
5.
The module-info.java was created as follows.
6.
The Eclipse IDE prompts you to check if you wish to open the Java perspective. This predefines the window frames that are opened and the panels that are displayed, which are considered most useful for Java program development.
7.
At this point, we have just one empty Java class and the Java JRE System Library defined for the project.
8.
To create a new Java package, com.asb.ce, we need to right-click the src folder, highlighted in Figure 2-9, and select the New ➤ Packageoption from the menu drop-downs. We can then enter the package name as shown in Figure 2-10.
9.
We can now add Java code as a Java Class to the “empty” com.asb.ce package by right-clicking the com.asb.cepackage we created in step 8 and then selecting the menu items, New ➤ Class (highlighted in Figure 2-11).
10.
The attributes required for the Java Class are displayed; we just add the name of the class we want to give as CEConnection. This class will be called to create a Java connection object to enable access to the IBM FileNet Content Engine Object Store.
11.
For the CEConnection.java Java code, we just cut and paste a Standard IBM code example as shown in Figure 2-13 and listed fully in Listing 2-1 later in this chapter.
12.
Notice in Figure 2-13 that the imports for all the com.filenet.api… packages are flagged with errors (a white cross on a red background). This is because we need to add the IBM FileNet API jar files to the Java project properties, which we will now provide in the next steps.
First, we have to copy the IBM FileNet client jar files from their installed location on the Linux server to the reference classpath directory we create using
mkdir /opt/FileNetJars
13.
Next, we can add the copied .jar files created in step 12 to the Project Classpath.
14.
The files are added as shown in Figure 2-18 from the /opt/FileNetJars directory.
It can be seen that the result of adding the jar files has corrected the errors as highlighted in Figure 2-19. However, there are still some import failures showing on the java.util… package imports and the javax.security package.
15.
To correct the Java package import errors, we need to add a JRE library, using the Add Librarycommand, to the Project Classpath as indicated in Figure 2-20.
16.
We need to add a JRESystem Library type which we select and then click the Next> command button to show a command which will give a list of the available JRE versions.
17.
The Installed JREs command is clicked to allow a choice of installed JRE Java System .jar files.
18.
As shown in Figure 2-23, the Add command is used to add the JRE to the Classpath for the project, and then the Apply and Close command is clicked.
The Properties for the AuditEventHandlerproject now show the JRE System Library in the Java Build Classpath.
19.
In order to ensure the correct import packages are used to build the project, it is sometimes necessary to use a specific order of .jar files, so that the earlier versions of a package are consistent with the functions required, since it is possible that a Class module with the same name appears in more than one .jar file. The Classpath order of the referenced .jar files can be adjusted using the panel shown in Figure 2-25.
20.
The CEConnection.java source code is now free of errors.
This code is deployed as follows:
Create the Project and add the CEConnection.java (Standard IBM code).
package com.asb.ce;
import java.util.Iterator;
import java.util.ResourceBundle;
import java.util.Vector;
import javax.security.auth.Subject;
import com.filenet.api.collection.ObjectStoreSet;
import com.filenet.api.core.Connection;
import com.filenet.api.core.Domain;
import com.filenet.api.core.Factory;
import com.filenet.api.core.ObjectStore;
import com.filenet.api.util.UserContext;
/**
* This object represents the connection with the Content Engine. Once
* connection is established it initialises the Domain and ObjectStoreSet object with
* the available Target Store Domain and ObjectStoreSet.
*
*/
public class CEConnection {
private Connection con;
private Domain dom;
private String domainName;
private ObjectStoreSet ost;
private Vector osnames;
private boolean isConnected;
private UserContext uc;
// ASB001
private String _username = "";
// ASB002
private static final String encryption_delimiter = "
"; // Newline
/*
* constructor
*/
public CEConnection() {
con = null;
uc = UserContext.get();
dom = null;
domainName = null;
ost = null;
osnames = new Vector();
isConnected = false;
}
// Object Finalize (called before Garbage collection)
// ASB003.
protected void finalize() {
this.disconnect();
}
// ASB004.
public void disconnect() {
if (isConnected) {
uc.popSubject();
con = null;
dom = null;
isConnected = false;
}
}
// ASB005
public String getCurrentUser() {
return _username;
}
// ASB006 Returns the IBM Object Store java Object
public ObjectStore getObjectStore(String ObjectStore)
{
// This hard coded example would have String variables read from an encrypted Config.xml or config.properties file
// in a Production Environment!
// Values passed are User , password , the stanza jaas.conf.WSI value, MTOM SOAP URL link
// The jaas.conf.WSI is a file in the path /opt/IBM/ECMClient/configure/CE_API/
// The stanza is as follows in the jaas.conf.WSI file :
dom = Factory.Domain.fetchInstance(con, null, null);
return dom;
}
/*
* Returns ObjectStoreSet from Domain
*/
public ObjectStoreSet getOSSet() {
ost = dom.get_ObjectStores();
return ost;
}
/*
* Returns vector containing ObjectStore names from object stores available
* in ObjectStoreSet.
*/
public Vector getOSNames() {
if (osnames.isEmpty()) {
Iterator it = ost.iterator();
while (it.hasNext()) {
ObjectStore os = (ObjectStore) it.next();
osnames.add(os.get_DisplayName());
}
}
return osnames;
}
/*
* Boolean method which checks whether the connection has been established with the Content Engine or not.
*/
public boolean isConnected() {
return isConnected;
}
/*
* Returns the IBM FileNet ObjectStore object for the passed object store name string.
*/
public ObjectStore fetchOS(String name) {
ObjectStore os = Factory.ObjectStore.fetchInstance(dom, name, null);
return os;
}
/*
* Getter method which Returns the domain name.
*/
public String getDomainName() {
return domainName;
}
/*
* Getter method which Returns the current connection object.
*/
public Connection getCurrentConnection() {
return con;
}
/*
* Getter method which Returns the domain object.
*/
public Domain getCurrentDomain() {
return dom;
}
}
Listing 2-1
The CEConnection Java class object
Now we can create another Java Class for the project. This is the Event Handler itself, so we add a new class package, com.ibm.filenet.p8.ce.eventhandlers.codemodules, as shown in Figure 2-27.
Next, the AuditModule Java class is created under this package using the screen in Figure 2-28.
The following code is the main CodeModule class with the Event Handler AuditModule class for the addDocToFolder Java method.
ct.set_RetrievalName("AuditDocTest"); // ASB Test Document name
int docLen = ct.get_ContentSize().intValue();
byte[] buf = new byte[docLen];
stream = ct.accessContentStream();
try {
stream.read(buf, 0, docLen);
String readStr = new String(buf);
System.out.println("Content:
" + readStr);
} catch (IOException ioe) {
ioe.printStackTrace();
}
System.out.println("
Element Sequence number: " + ct.get_ElementSequenceNumber().intValue() + "
"
+ "Content type: " + ct.get_ContentType() + "
");
}
return stream;
}
}
Listing 2-3
The TestHarness Java class object
The integration with the IBM FileNet Event system is interfaced using the AddDocToFolder Event Java Class. This implements the abstract IBM FileNet Content Engine class, EventActionHandler, using the code listed as follows.
EngineRuntimeException ere = new EngineRuntimeException();
ere.setStackTrace(e.getStackTrace());
throw ere;
}
finally {
logger.debug(M_NAME + " Finished");
}
}
}
Listing 2-4
The AddDocToFolder Event Java Class object code
Add the FileNet 5.5.x jar libraries to the project AuditEventHandler, TestHarness class module run configurations:
Modulepath
Jace.jar
eeapi.jar
log4j-1.2.17.jar
pe.jar
peResources.jar
log4j.jar
Classpath
AuditEventHandler
JRE System Library[jre]
peResources.jar
pe.jar
log4j-1.2.17.jar
log4j.jar
Jace.jar
eapi.jar
This AuditModule Code Module contains one Event Handler class, addDocToFolder. This is passed the Case Audit Report document object to be filed in an AUDIT_TEST common Folder for ease of access to audits using the IBM Case Manager Audit Master solution.
The code loads the Audit Report class Document Objects with the String property, AUD_folder_Id_to_file_in, which contains the GUID of the Case Target Object Store’s AUDIT_TEST folder. The addDocToFolder Event Handler is triggered and causes a new DRCR (Dynamic Referential Containment Relationship Object) Folder link object to be created, which is the standard linking method to allow an IBM FileNet Folder to link in a many-to-many relationship with the FileNet Audit Report Document objects.
Custom Code Module Java JAR API Call Development
1.
Confirm that the “CodeModules” folder exists. This is a root-level folder of class “Folder.” It only has one special attribute. It is a “hidden” folder and so is not visible in IBM Content Navigator. If this folder does not exist, create it as you would create any other folder, and then change its “isHiddenContainer” attribute as shown in Figure 2-31.
Adding a Code Module
2.
Create a new Document in this folder. Right-click the “CodeModules” folder in the tree view, and select “New Document.”
3.
You will be presented with the AddDocument wizard. Enter a name (DocumentTitle) for the Document. We will see this later when we come to configure the Events. This will show as the name of the code module.
4.
Select “Next>”, ensuring that the tick box is selected to indicate that the content is to be provided for the Code Module.
5.
On the next wizard page, use the “Add” button to select your jar file (fn_eventhandlers.jar).
6.
Change the MIME type before adding the File.
You will need to enter this as application/x-zip-compressed.
The Browsebutton is used to find the compiled fn_eventhandlers.jar file. On our Linux system, this is in the path /root/eclipse/java-2021-12/eclipse, but this is system dependent.
The Open command button is then used to select the fn_eventhandlers.jar file for the Add Content button in Figure 2-36 to add into the Object store.
On clicking the Next>command button, we see Figure 2-39.
The Property values for the fn_eventhandlers Code Module are displayed; we just click the Next> command again (highlighted in Figure 2-40).
The next screen shows the Version property options for the document; in this case, we use the default options as shown in Figure 2-41.
The Next> command shows the Retention time options for the document, which can be set to allow automatic removal after a selected time interval.
For this functionality, we use the default, which never deletes the document.
The next screen shows the Code Modules Storage area. We set this to the default using the drop-down highlighted in Figure 2-43 and then click the Next> command button.
Finally, we can create the AuditEventHandler Code Module by clicking the Finishcommand highlighted in Figure 2-44.
The Code Module can now be seen in the CodeModules folder.
Creating a Custom Event Object
Before the AuditEventHandler Code Module can be integrated as a new Custom Event in the OS2 Object Store for IBM Case Manager, it has to be linked to other Object Store objects. The first of these is the Event Object.
We will now create a new Event Object called AddDocToFolder.
You will need to perform the following steps for the Event:
1.
In the acce tree view, expand “Events, Actions, Processes” and select “Event Actions.” Right-click “Event Actions” and select “New Event Action.” You will be presented with the “Name and Describe the Event Action” wizard.
The AddDocToFolder Display name and Description boxes for the event are entered as shown in Figure 2-48.
2.
Select “Next.” In the “Name and Describe the Event Action” wizard page, enter “AddDocToFolder” in the name. The description is optional and defaults to the same as the name value. In this case, we select a slightly more detailed description.
3.
Select “Next.” On the next wizard page, enter the “Event Action Handler Java Class Name.” This value is as follows for the event:
and select the “Configure Code Module” checkbox shown in Figure 2-49.
4.
Click “Next.” On the next wizard page, click the “Load Existing” button; you should see a list with the code module name we created in the “Create Code Module Step 2” earlier. Select this item.
5.
Click OK.
6.
Click “Next.” The parameters to be run to create an Event Handler are displayed.
7.
Click “Finish” to complete the wizard.
Configuring Workflow Subscriptions
Content Engine Objects, such as Folders and Documents, can subscribe to certain events and have the preceding “event action” code fire on these events. We will now describe how to subscribe the creation event of a Document of class “Audit Report” to the AddDocToFolder event action.
Note
The AddDocToFolder event code creates a link of the created Audit Report Document to the AUDIT_TEST folder that is defined.
1.
In acce, select Classes ➤ Document ➤ Audit Report from the tree view.
2.
Right-click the Audit Report class and select “New Subscription” from the context menu.
3.
Enter the Subscription Name as AUD_AddDocumentToFolder and click “Next” on the “Create Subscription” screen.
4.
Select a name for the subscription that describes it for this type of object. This is because Event Actions can be used for multiple object types and for multiple events (Create, Update, etc.), and so well-named subscriptions are easier to understand and maintain.
At this point, you can see that there is an option to Create a workflow subscription.
5.
Click “Next.” The one or more system events (or custom events) can now be selected using tick boxes. We are just going to select the Document Object Creation Event.
6.
On the “Select the Triggers” screen, select “Creation Event” from the list and click “Next.”
7.
Click “Next.” On the “Specify an Event Action” page, select “AddDocToFolder” from the drop-down.
8.
Select “Next.”
Click Finish. The preceding screen is displayed showing the status of the AUD_AddDocumentToFolder New subscription creation.
This subscription can now be tested by creating a document of class “Audit Report.” Once created, you should see the Document linked to the AUDIT_TEST folder.
Creating the fn_eventshandler.jar
The following steps were used to create the fn_eventshandler.jar, Events Handler jar file, which we used in the previous section, from the Eclipse Project.
In the Eclipse Java IDE tool, we can export the Project classes and supporting files to the fn_eventshandler.jar file we need for integration with IBM Case Manager.
The Eclipse Java JAR file export wizard is selected and the Next> command is clicked as shown in Figure 2-66.
The defaults shown in Figure 2-67 are selected for the AuditEventHandler project. Then the Browsebutton is used to choose the exported JAR file destination path.
The default Eclipse path shown in Figure 2-68 was used with the file name entered as fn_eventhandlers.jar.
Part 3 – Testing the Add Document to Folder Event
The TestHarness code in the Eclipse project requires a valid Document Object to be used to link to an existing AUDIT_TEST folder which we need to create, and also we need to note the Object Id property values which identify them. These Id property values uniquely identify Folder and Document objects in the IBM FileNet Target Object Store which is used by the IBM Case Manager system.
In acce, the IBM Administrative Console for Content Platform Engine, we can create Folder objects, import and view Document and property template classes, and identify the Document Id values for a specific Object Store class object.
The IBM Case Builder web application of the IBM Case Manager system can also be used to create new Document Classes and their related properties. We will create the new property with the symbolic name, AUD_folder_Id_to_file_in.
We are going to add the property as a Global Solution property template as follows.
We select to add a New property and enter the property details shown in the screen in Figure 2-74.
Next, we need to add this new property to the Audit Report Document class so we can programmatically read the Folder Id string property from it and so identify the Folder to link the Audit Report class documents to. (This is the function of the Java Event program we have developed, which is now available in the Target Object Store.)
The new Audit Report Document class, folder_id_to_file_in class property, is now defined in the updated Audit Master solution. Now we need to redeploy the Audit Master Solution (stored in the IBM Case Manager Design Object Store, OS1) to the working Target Object Store (OS2). This process will update the existing Audit Report document class with the new property we have created.
After we save and close the changes to the Audit Master solution, we use the Redeploy All menu option shown in Figure 2-79.
If there are changes edited into the Audit Master solution, and these are not deployed, a yellow warning triangle appears below the green tick mark icon.
This yellow warning triangle disappears after a successful redeployment.
Now we create the AUDIT_TEST folder in the OS2 Target Object store using the IBM FileNet acce web application tool. We right-click the Root Folder node and select the New Folder menu option to show a New Folder tab as shown in Figure 2-82.
The Finish command is used, as shown in Figure 2-84, to create the Folder AUDIT_TEST, which we will use to hold links to all the Audit Report case Documents of the Audit Master solution.
The status window shows the Date and Time of the folder creation and the time taken.
We now need to find and display the unique Id of the AUDIT_TEST folder object we created and use this in our TestHarness Java program to test the functionality of our AddDocToFolder Event Java Class.
The AUDIT_TEST folder ID string value is found to be {896F3369-7AF8-405E-85A7-3E18F90ACE43} for the Object Store I am using and can be copied and pasted to the TestHarness Java program to run a test in the Eclipse Java IDE. First, we need to create an Audit DepartmentCase to use for the Tests.
The case is searched for using the % wildcard for the Case Identifier as shown in Figure 2-89.
Since we have redeployed the Solution, this case is now the first Case entered in the system.
To test that an Audit Report Document is created, we use the Add ➤ Add Document from Local System option shown in Figure 2-91.
The Audit Report Document class is selected as shown for our test.
We can now enter the Audit Report Document Class properties, which now include our AUDIT_TEST folder Id string in the folder_id_to_file_in property.
We can now run the TestHarness Java program in the Eclipse IDE and use the unique SymbolicName property AUD_folder_Id_to_file_in String value, {896F3369-7AF8-405E-85A7-3E18F90ACE43}, to link the test document to the AUDIT_TEST folder.
We also need to manually add the AC.pdf example file’s Audit Report Document class Id to the TestHarness code to allow it to locate and link the document. In the live usage of the Event Handler, the Custom Event subscription automatically passes the Document’s Id to the Event Java module.
The Test Document ID for the AC.pdf file shown earlier is {00D14A81-0000-C31E-A7D2-F2B7CF2D4803}; this is then entered into the TestHarness code.
//The Test Document ID for AC.pdf file is {00D14A81-0000-C31E-A7D2-F2B7CF2D4803}
Document d = (Document) os.getObject("Document", "{00D14A81-0000-C31E-A7D2-F2B7CF2D4803}");
am.addDocToFolder(d);
}
Listing 2-5
The test_AddDocToFolder Java Class code
In the preceding code, the Document, AC.pdf, is retrieved into the Java Object d, which is an Audit Report FileNet Content Engine Document class. The document now has the Id of the AUDIT_TEST folder it is to be linked to.
The TestHarness.java code is shown in Figure 2-100.
For the code block, see Listing 2-3 listed in the section “Configuring Java Components for Content Engine Events.”
In order to successfully run the TestHarness.java, we have to ensure the Classpath for the Run configurations option of the TestHarness.java program contain the references to all the .jar files it references.
In order to run the TestHarness program without “Class Not Found” Java errors, we need to check that all the program dependencies, including the required supporting Java library files, are on the Classpath.
After running the TestHarness program, we can see that the AC.pdf file has been successfully linked to the AUDIT_TEST folder in the OS2 target object store Content Store.
During the initial TestHarness program runs, we noticed that we get Java log4j warnings about a missing appender. This requires us to initialize the log4j system which we are using to send debug output (and which the IBM FileNet API jar file, jace.jar, also uses to log messages for debug).
The src folder needs to be updated with a log4j.xml and log4j.dtd file for configuring the logger commands.
The file is expected to be called log4j.xml with an XML format with standard tags to define the appenders.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd" >
We have entered the content for the log4j.xml and also a standard log4j.dtd from the apache download site.
But, after saving the log4j.xml and rerunning the TestHarness program, we still get the following warnings.
As highlighted in Figure 2-111, we need to add the appender for the filenet_error.api.com.filenet.apiimpl.util.ConfigValueLookup class to the log4j.xml file.
Next, we re-export the fn_eventhandlers.jar file which now includes the updated log4j.xml and log4j.dtd files.
The updated fn_eventhandlers.jar file created earlier is shown in the Linux folder path in Figure 2-116.
We can now retest the Audit Solution cases.
Retest results of the Audit Master solution updates are shown in Figure 2-117.
We can add multiple documents of type Audit Report to the same Audit Department case, and they should also appear in the AUDIT_TEST folder.
In the AUDIT_TEST folder, we now also see the same highlighted document appear linked. We should emphasize here that this is a single document version copy with links in multiple folders.
In the preceding examples we tested, we have manually added the Folder Id, for AUDIT_TEST folder, which is the string GUID, {896F3369-7AF8-405E-85A7-3E18F90ACE43}, to the Audit Report Document class String property, folder_Id_to_file_in (with the full unique Id, AUD_folder_Id_to_file_in).
However, we have the option to set this Folder Id as a default value for the folder_Id_to_file_in property of the Audit Report document class by editing it into the Audit Master solution. What is more interesting is that the default value stored in this way could be set differently for different Document classes, which would open up the possibility of automatically filing different types of documents in different folders, using the same Java code module we have created. We will now show this just for the Audit Report document class at the moment.
The IBM Case Builder web application can now be used to modify our initial Audit Master solution again.
We can now update the folder_id_to_file_in property of the Audit Report Document class by selecting the Propertiestab, and using the mouse-over, we can see the Edit icon (highlighted in Figure 2-124).
Now, we can set the Default value for the folder_Id_to_file_in property to the AUDIT_TEST folder Id property value (which is the string GUID {896F3369-7AF8-405E-85A7-3E18F90ACE43}).
In addition, notice that there is a Hidden boolean option available (highlighted) for properties, which we could utilize if required, so that a normal user would not even be aware that this property existed. The Audit Reports would appear “as if by magic” to this user in the AUDIT_TEST folder!
Having updated the Audit Master solution again, we can now deploy the changed solution as shown in Figure 2-127.
A Confirmation pop-up dialog window is then displayed as shown in Figure 2-128.
On adding an Audit Report document class to a new Case now, we automatically have the folder_Id_to_file_in property filled with the AUDIT_TEST folder Id value.
In the preceding screen, it should be noted that the Auditor can be still actively using the Case, in the IBM Case Manager application, because as soon as the system detects the Create Event for the Audit Report document class, it will appear (on selecting the Refresh command) in the acce web application shown in Figure 2-133.
In summary, the Audit Report Document class Creation Event triggers the AddDocToFolder Java EventHandler, a Class in the fn_eventhandlers.jar (which is registered as a Code Module in the OS2 Object Store). This links the new Audit Report document of class type AUD_AuditReport to the AUDIT_TEST folder using the property AUD_folder_Id_to_file_in which contains the unique ID (GUID) of the AUDIT_TEST folder.
This functionality can then be used to automatically provide a second link to all the Audit Report case documents, which can then be viewed centrally in one Folder location.
Part 4 – The DbExecute Workflow Step for Calling Database Stored Procedures
One other integration we cover in this chapter is the DbExecute workflow step. This allows a Database Stored procedure to be invoked from an IBM Case Manager Workflow step. This is supported using the IBM FileNet P8 Process Designer tool. This tool is available as a .jar applet and also a standalone Java program version running on Windows as a client application linked to the IBM Case Manager server.
The IBM Auto-Claims Case Manager Solution Example
The following free download covers the example DB2 Stored Procedure for an Insurance Company, IBM Case Manager Auto ClaimsSolution:
“Importing Case Manager Solution Auto Claims example into Case Manager 5.3.3 on RHEL 8.0”
There are several points of integration with the IBM FileNet P8 Process Designer for building an IBM Case Manager workflow, shown in this section.
Methods of Displaying a Case Type Task Workflow
Figure 2-136 highlights the web-based Process Designer applet menu, which can be launched for the development of the Solution Case Type Workflow tasks used to process and display active Cases to Auditors and Case Administrators.
There is also a graphical view available of the same workflow as used in FileNet P8 Process Designer, which can be displayed in the IBM Case Builder web application tool as follows.
First, we load the Audit Master solution by clicking the blue Audit Master link shown in Figure 2-135.
1.
We then click the Audit Department Case type shown earlier to display the attributes of the Case Type as shown in Figure 2-137.
2.
From here, we select the Tasks option from Audit Department Case Type menu options.
The Figure 2-137 screen has a drop-down which allows a document loaded into the IBM OS2 Target Object Store to automatically invoke the Audit Master solution Audit Department task workflow, if we select a Starting document class from the drop-down shown earlier. For the moment, we will leave the default option, which is to start the Audit Department Task manually from each Case, when this is required.
The Tasks option Audit Process page is shown in Figure 2-138.
Now, we have two options to view the Workflow here. The first option, shown in Figure 2-138, launches the IBM FileNet P8 Process Designer as an embedded Java Applet. (But see later why this is rarely able to be used!)
The Case Builder Workflow Step Designer Application
The second option is to use the Step Designer, shown using the highlighted icon in Figure 2-139.
Clicking the icon highlighted in Figure 2-139 gives the Task Workflow, Step Designer, a high-level Workflow design page for the IBM Case Builder, shown in Figure 2-140.
The Palette on the left-hand side of the screen, shown in Figure 2-140, of the Workflow Step Designer contains different types of Workflow step and Role Lanes which can be dragged and dropped using the mouse to the right-hand pane in the dragged lanes which are then defined for each Security Role.
Unfortunately, in our requirement, for which we wish to use the DbExecute step (which is a Stub Step dragged into the System Lane), the details of the DbExecute step have to be entered using the IBM FileNet P8 Process Designer Java program.
The Process Designer Plugin Applet in IBM Content Navigator
The next option for accessing the IBM FileNet P8 Process Designer is to configure the access from the IBM FileNet Content Navigator web application, using the IBM FileNet P8 Process Designer plugin applet.
This is accessed using the link from our IBM Content Navigator web application server, ecmukdemo6, using the URL:
http://ecmukdemo6:9081/navigator/?desktop=admin
After logging in to the IBM Content Navigator web application tool shown in Figure 2-142, we can select the Plug-ins menu item as follows.
The Content Platform Engine CPEAppletsPlugin.jar file is available by downloading it from the installed Content Platform Engine server (ecmukdemo6) using the URL:
The Content Platform Engine CPEAppletsPlugin.jar file is then available from the /root/Downloads Linux directory path for use.
The downloaded CPEAppletsPlugin.jar file name and path have to be manually typed into the selected admin JAR File path as /root/Downloads/CPEAppletsPlugin.jar to Load it from the Linux directory as shown in the highlighted screenshot in Figure 2-147.
The loaded CPEAppletsPlugin.jar file displays the Version details and the contained Actions available.
The CPEAppletsPlugin.jar security must be changed before loading as follows.
We can use the Linux command:
chmod 775 CPEAppletsPlugin.jar
Without this, there will be Load errors in the Content Navigator web application.
On refreshing the desktop, the Plug-ins tab page should now have the highlighted IBM FileNet P8 Process Designer and Process Tracker Actions plugin:
The next step is to select the IBM Content Navigator Repositories menu highlighted as follows, in order to create new connections to the IBM Case Manager Design (OS1) and Target (OS2) Object stores.
A New Repository connection can be added using the FileNet Content Manager drop-down option.
The connection parameters are then filled out as highlighted in Figure 2-153.
The EJB connection string is used, iop://ecmukdemo6:2809/FileNet/Engine.
The user login credentials for access to the IBM FileNet P8 OS2 Content Object store are prompted for.
On acceptance of the credentials by the IBM FileNet Content Manager system, the list of tabs is enabled for configuration. We need to select the Configuration Parameters tab shown in Figure 2-155.
We now have to enable the Display workflow definition classoption shown on the next screen.
The preceding procedure is repeated to add the OS2 repository.
The Copy option can be selected for the Default repository folder contextmenu.
This is a template menu which is found by scrolling down to the highlighted position shown in Figure 2-159.
The copied menu now shows the Open Process Designer and Open Process Tracker menu actions.
The highlighted arrow key in Figure 2-160 is used to copy the selected Open Process Designer and Open Process Tracker options, and then their positions can be edited using the up/down arrow keys on the right of the panel to change the menu item order.
Configuring the DbExecute Connection
In order to call the DbExecute step from a Task Workflow, calling a database stored procedure, we have to log in to the IBM FileNet Content Manager acceadministration tool and create a DbExecute connection using the highlighted tab in Figure 2-162.
The Design Object Store OS1 does not have any DbExecute Connections.
The Target Object Store OS2 already has a DbExecute connection which we set up for the standard IBM Auto Insurance Claims example solution.
The Edit command shows the example connection parameters as shown in Figure 2-164.
The Additional Desktop Components for IBM Content Navigator are also changed to enable the display of the Global toolbar.
In the Advanced settings of the IBM Case Manager administration client desktop, we must also select the tick box to “Enable the desktop for FileNet P8 workflow email notifications,” as shown in Figure 2-166.
Figure 2-167 is a zoom in to show the mouse-over information against this option.
In Figure 2-168, the copy of the Repository folder context menu we made can be seen in the drop-down. We can now select our copy of this menu type for our IBM Content Navigator Desktop, which we named CPE Process Designer.
See the following web pages for details of running the Workflow Process Designer Applet in IBM Content Navigator:
In the current release of browsers, the embedded applet jar file used by the IBM FileNet Workflow Process Designer is often disabled by the browser (including on my systems!). So, this Part describes the installation and configuration required to install the Windows Client Standalone Process Designer, which is then used to add a DbExecute workflow step to the Audit Master Solution we created in Chapter 1.
We will install the IBM FileNet Process Engine Client tools using the Windows client installer for IBM Content Foundation, Content Platform Engine for Windows system, which can be downloaded from the IBM Software Catalog as a zip file, ICF_5.5.0_WINDOWS_ML.zip.
We first unzip the ICF_5.5.0_WINDOWS_ML.zip software package to subfolders as in the example shown in Figure 2-169.
Next, we run the 5.5.0-ICFCPE-WIN.EXE program by right-clicking the program and selecting Run as administrator as shown in Figure 2-170.
The installation program checks for existing deployments and ensures the required prerequisites are installed.
After accepting the windows pop-up for the installer to use the Windows Administrator, we see the progress status bar shown in Figure 2-171.
After several minutes, the following initial installation window is displayed.
We click the Next command button to show the IBM License Acceptance splash screen, with a scrollable license text window.
The installation options are chosen on the next screen.
We just need to install the Client tools for the IBM Content Platform Engine, so we just select for the .NET Clients and the Tools.
Note
The preceding default path does not exist on our MS Windows client system, so we had to post-edit the Process Designer environment batch file later. Also, if a valid path is entered, you must ensure that it does not contain any spaces (so, use the DOS short form for a directory, e.g., “C:PROGRA~1…” rather than the “C:Program Files…” directory name).
We will be asked in the next installation screen to enter the IBM FileNet P8 Content Engine Service Definition SOAP WSDL URL link. This can be tested in a browser which can connect to the Linux ecmukdemo6 server (the Windows hosts file should have an entry for the IP address).
This SOAP URL is http://ecmukdemo6:9080/wsi/FNCEWS40MTOM.
The tested URL is entered in the screen in Figure 2-178.
This URL link is also used by the Java API in a properties file called WcmApiConfig.properties, so this is also entered in the next screen shown as follows.
The following screen, shown on clicking the Next command button in Figure 2-179, shows a summary of the selected installation options which can be initiated by clicking the Install command button.
The installation status is shown in the next Install screen in Figure 2-181.
After the installation is completed, there is an option to launch the configuration manager with a tick box, which in this instance we don’t require, since we are using the Windows Client for the Standalone Process Designer Java application. (The Configuration Manager is used to prepare and install a new IBM Content Platform Engine server system.)
Fixing the Process Designer Shell Script Environment Variables
The Windows DOS cmd.exe command window (run as the Windows Administrator) can now be used to run the pedesigner.bat Windows shell script file. However, as will be seen later, we have to do some editing on the environment variable initiation shell scripting to obtain a working JAVA_HOME and CLASSPATH environment configuration!
We have to include the Process Engine Connection point for the Designer Object Store which has the name CP1.
Unfortunately, we have the JAVA_HOME Windows environment variable pointing at a JRE Classpath which does not exist.
However, we also have a Folder path with spaces, which does not work for the shell script!
In Figure 2-187, we make changes to ensure there are no spaces in the classpath which we can achieve by using the DOS short form of the directory path for the top level c:Program Files (x86) directory, which has a DOS short form of c:PROGRA~2.
Then, we also have to edit the cpetoolenv.bat shell script file, which is called by the main pedesigner.bat shell script file, as shown in Figure 2-188.
This results in the updated shell script file in Figure 2-189.
We can now launch the Standalone Process Designer Java program using the Windows cmd.exe DOS window, with the commands as follows:
cd c:PROGRA~2IBMFileNetContentEnginePE
pedesigner.bat CP1
This loads a pop-up window prompting us for a Process Engine administrator login.
We now see the first screen of the IBM Standalone Java program, Process Designer, which we can use for the editing of IBM Case Manager solution Task workflows.
We can now load the Audit Department Task Workflow of our Audit Master Case Manager Solution.
The first step is to use the File ➤ Solution ➤ Edit… menu option as shown in Figure 192.
We now see the option to select from the available IBM FileNet Object Stores, used by Case Manager for the Design (OS1) and Target (OS2) object stores, where our solution is stored. We select the OS1Design Object store where the Audit Master solution is developed.
From the OS1 Object Store, we navigate down to the Audit Master solution following the Object Store folder path OS1 ➤ IBM Case Manager ➤ Solutions ➤ Audit Master, as shown in Figure 2-194.
We are now presented with a list of IBM Case Manager Solution components. For the Workflows, we select the Solution Definition file shown in Figure 2-195.
We are now shown a pop-up window with a drop-down which shows the Case Types available. (For the Audit Master solution, we only have one Case Type at the moment, Audit Department… there can be many!)
The selected Case Type then shows the AUD_AuditProcess Task Workflow to be used. (There can be many Case Type workflows!)
We can now add the DbExecute Workflow step.
The DbExecute Workflow Step Addition
The following URL covers the system setup for DbExecute:
The following procedure is used in the IBM FileNet acce web application to configure the database JDBC link required by the Workflow DbExecute step. It defines the JDBC URL which allows the FileNet system to connect to a server database, by an administrator specifying a server name and port number and entering the required database name and logon details to access the Stored Procedure to be used.
Procedure to Configure a DbExecute Connection in the Content Engine Store
To set a DbExecute connection:
1.
Access the DbExecute Connections tab in the administration console:
a.
In the domain navigation pane, select the object store.
b.
In the object store navigation pane, click Administrative ➤ Workflow System.
c.
In the details pane, click the DbExecute Connections tab.
2.
Click New.
3.
Enter the connection information and database parameters.
Click Validate to test the database connection.
We can now see the AuditDb object we have successfully created in the DbExecute Connections tab.
The preceding steps were repeated for the OS2 Target Object Store.
We can now insert test rows into the AUDIT_DEPT table which is in the DB2 auditdbdatabase.
The DbExecute Stored Procedure SQL
The Stored Procedure, ADD_AUDIT_DEPT, listed in Figure 2-204, which we have developed, can be called by the DbExecute step to add a row to the DB2INST1.AUDIT_DEPT table in the auditdb database, using parameters passed for each column of the table.
See the following web page for the full DbExecute procedure steps:
We can now define the DbExecute system step for the workflow system using the installed Standalone Process Designer.
Note
To create a new DbExecute connection, an XA and non-XA JDBC Datasource will need to be set up for the IBM FileNet WebSphere application server to enable access for the database.
See the link for a full description of an alternative JDBC DbExecute connection creation (on Page 51 of the document):
Procedure to Add the DbExecute System Step to the Task Workflow
To specify a new DbExecute system step:
1.
From the General System Palette, use the mouse to drag a DbExecute step onto the workflow map.
After the General System Palette select box is ticked, the icons open up as shown in Figure 2-208. Then the highlighted DbExecute step can be dragged and dropped into the Process Designer work area.
2.
Enter the database name in the parameter window shown in Figure 2-209.
Note
The name that is used to create a stored procedure is used to call it in the Workflow. Process Designer does not allow a Stored Procedure name to be entered with quotes for the DbExecute system step. See the link as follows for the full details:
Enter the name of the stored procedure to execute (ADD_AUDIT_DEPT).
In Figure 2-209, we have entered the required DbExecute step parameters which require the Database Connection Alias we set up.
4.
The different supported databases for the DbExecute calls must have all of its parameters declared as follows:
out – SQL Server
in out – Oracle
inout – DB2
The preceding parameter types are set to allow the values to be maintained bidirectionally. This allows the updated values to reflect the stored values passed in as parameters to the stored procedure.
The parameter data types passed in must match the types that are specified in the stored procedure SQL and can be of the following types:
Designer Param Type
Oracle Param Type
SQL Server Param Type
DB2 Param Type
String
varchar
Varchar
varchar
Integer
number
Int
int
Boolean
number
Bit
number
Float
number
Float
float
Time
date
Datetime
timestamp
Stored Procedure Parameter Limitations
Arrays are not supported for Stored Procedure parameters.
Note
If a Date/time, Integer, Boolean, or Float parameter is set to null by a stored procedure, an exception will be thrown.
Oracle
SQL Server
DB2
Maximum number of parameters in procedure
1024
1024
1024
String parameter maximum characters
4000
4000
4000
Example SQL Table Creation for the DB2 Database
The table in the auditdb database we are interested in has the following DDL.
CREATE TABLE "DB2INST1"."AUDIT_DEPT" (
"AUDITOR_NAME" CHAR(40 OCTETS) NOT NULL,
"DEPTNO" INTEGER NOT NULL,
"AUDIT_DATE" DATE,
"COMMENTS" CHAR(200 OCTETS) NOT NULL,
"AUDIT_STATUS" CHAR(10 OCTETS) NOT NULL
)
ORGANIZE BY ROW
DATA CAPTURE NONE
IN "USERSPACE1"
COMPRESS NO;
Listing 2-7
The Create Audit_Dept table SQL script
DbExecute Stored Procedure Installation
The following db2 commands are used to install the Stored Procedure SQL code. The code was edited into a SetAddAudit_Stored_ProcedureV1.sql file containing the SQL.
db2 connect to auditdb
db2 -td@ -vf SetAddAudit_Stored_ProcedureV1.sql
The SQL code we enter for the Stored Procedure is as follows.
CREATE OR REPLACE PROCEDURE ADD_AUDIT_DEPT (INOUT VARRESULT INT,
The ADD_AUDIT_DEPT Stored Procedure DB2 SQL script
To support the transfer of the IBM Case Manager Audit Master solution Audit Department case data to the separate auditdb database server table AUDIT_DEPT, we need to define some Workflow Data Fields to hold the Case Data. These are set up with initial default values in the Workflow Properties, Data Fields tab shown in Figure 2-211.
The LaunchStep Field Assignment parameters are first set up with String values to test the Stored Procedure and Workflow during “debugging” as shown in Figure 2-212.
The Case Task Fields can be added next, after testing the Stored Procedure with fixed values for a “live” test of triggering the DbExecute step to populate the AUDIT_DEPT table.
In Figure 2-214, we now have the Field Assignments set with Case Task values for the Audit Case.
After the LaunchStep Workflow Data Field Assignments are configured to the Case Fields, we can now select the DbExecute step and choose the Workflow Data Fields, in the order they are required to be used as Parameters for the Stored Procedure, as shown in Figure 2-215.
Now the DbExecute step is completed, we can use the Validate Workflow menu action to ensure the Workflow “compiles” with no syntax errors (the workflow can either be stored as the industry standard XPDL, or there is an IBM FileNet P8 proprietary workflow .pep file structure which can be used).
A few minor changes were made to the Comments field to use one of the built-in Functions available in the Workflow design system, as shown in Figure 2-217.
After the Workflow DbExecute step has been entered and validated, we can Save and Close the Audit Master Solution Task workflow we have created and redeploy the Audit Mastersolution using the IBM Case Builder web application as shown in Figure 2-220.
In the IBM Case Builder, we should see a Warningtriangle (if a refresh of the Case Builder application has been conducted). This also shows the User and Date and Time that the solution was last modified.
We can now deploy the updated Audit Master solution, which now has a Task workflow with our DbExecute workflow step.
We now get a pop-up window which lists the detected changes which require deployment. Notice that the system locks the items as a warning, because the IBM Case Builder supports multiple Solution editors for the same Solution, as long as they are working on different areas of a Solution. In this case, we have a lock from the Standalone Process Designer.
We can check the result of adding records into the AUDIT_DEPT table using the IBM Data Studio application. Initially, we have the record from the Test Insert SQL we ran earlier in the development.
We can now create a new Audit Department Case from the deployed Audit Master solution which is now deployed to the Target Object Store (OS2). This can then be accessed to launch our Task workflow.
We can now start the Audit Process task as shown in Figure 2-225.
The first test showed that we need to grant security access on the ADD_AUDIT_DEPT stored procedure to give it execute permissions.
After the Security update, we used the db2 command line to launch the ADD_AUDIT_DEPT stored procedure to check that it was functioning correctly. This is shown using the db2 command in Figure 2-227. Notice that on the Linux system, we have to wrap the call command in double quotes, as follows:
db2 "call ADD_AUDIT_DEPT (1, 'A S Bluck',00003,'2022-06-18','Test of the Procedure','Working')"
We can now check that the Table row has been inserted into the AUDIT_DEPT table, which can be seen in Figure 2-228.
The Data Fields are all initialized now as String values, except for the VARRESULT status parameter, which is left as an Integer.
We can run a first test using the local String variables to eliminate any Null field issues.
If issues are found with Null values (such as in a date field, e.g., as found with the AutoClaims Solution, where the Field is set to NOT NULL in the table), then the test parameters in the Workflow can be temporarily hard-coded to eliminate issues.
Note
In the preceding db2 call on the Linux server, the Stored Procedure call has to be surrounded by double quotes to be executed with the db2 command-line processor.
Testing on Different Database Platforms
If you want to compare SQL statements in different databases, a website called SQL Fiddle allows a developer to switch between different database providers.
It supports a drop-down for MySQL, PostgreSQL, MS SQL Server, and SQLite, which you can run test some SQL queries and the syntax against.
This is very useful if a database platform would take time to install and configure and you have time constraints. Using SQL Fiddle, you just create your database and can run the queries in the web-based application!
The following questions cover the functions using Code Module Events, IBM Process Designer, and DbExecute, which we covered in this chapter.
MULTIPLE CHOICE QUESTIONS
1.
What IBM application would you use to confirm that the “CodeModules” folder exists?
a)
The IBM Content Navigator
b)
The IBM acce Administrative Console for Content Platform Engine
c)
The IBM Case Builder
d)
The IBM Process Designer
2.
An IBM Stored Procedure String parameter for the Oracle Database system is limited to
a)
64 characters
b)
1333 characters
c)
4000 characters
d)
1024 characters
3.
The IBM Standalone Process Designer Tool is initially installed using the program
a)
cmd.exe
b)
pedesigner.bat
c)
5.5.0-ICFCPE-WIN.EXE
d)
cpetoolenv.bat
4.
The main purpose of a Workflow Subscription is
a)
To enable the creation of a Folder Object
b)
To enable the creation of a Document Object
c)
To enable a workflow to be launched on the storage of a document
d)
To enable a Case to be created in IBM Case Manager
MULTIPLE CHOICE ANSWERS
1.
b) The IBM acce Administrative Console for Content Platform Engine
2.
c) 4000 characters
3.
c) 5.5.0-ICFCPE-WIN.EXE
4.
c) To enable a workflow to be launched on the storage of a document
QUESTIONS
1.
Describe what steps you would use to install a new Custom Event, given that you have been given a working fn_eventshandler.jar file and have been asked to configure an AddFolder Java Class Event Handler triggered on the creation of a new Folder.
2.
What databases does IBM Case Manager Workflow support and what types of Datasource are recommended to be configured to support a connection for use with DbExecute?
3.
What methods are used for resolving issues in the deployment of an IBM Case Manager Solution?
In Chapter 3, we will cover the use of the Java language to customize Workflow Components with the example development of a Java jar file for the IBM Java Messaging Service calls and its deployment for use in an IBM Case Manager Workflow.