Setting up a Cluster/Integration Framework for Maximo 7.1 on WebSphere 6.1

Answer

When using the Maximo Integration Framework (IF) in a clustered environment the following should be considered. Note that this document does not cover all possible scenarios and many other configurations can be used that satisfy your particular requirements.

· For best performance with minimal impact to users, the IF can be configured to run on a single instance of Maximo while users log in and work with User Interface (UI) Instances of Maximo. In this case, you will need separate application servers (IF and UI instances).

· To share these resources, all resources will need to be defined at the cell level within the WebSphere console. The reason for this is although the IF instance will do all of the processing of inbound transactions, outbound transaction events will still occur from the UI instances upon saving Maximo records. This means that the UI instances need to have access to the JMS resources such as connection factories in order to be able to send outbound messages.

· The IF instance which will be responsible for processing inbound IF transactions from the continuous queue will need to have the Message Driven Bean (MDB) deployed along with the Maximo application to it's own application server and therefore will need a maximo.ear build that is slightly different than the UI instances which will not need the Message Driven Bean running within them.

· In this example configuration, there are two distinct buses. Specific resources exist only on their respective buses. To prevent problems with stranded messages on remote queue points, crontasks are configured to run on a server instance that is local to the bus it is a member of. In the case of outbound JMS transactions, the seqqout crontask instance runs on the UI server instance since the sqout queue is defined on the UI bus, however there is no performance impact observed with this crontask in a typical environment as it has very little processing to do on messages.



Below you will find instructions for setting up a cluster environment for UI instances of Maximo and a stand-alone application server for Maximo IF transaction processing.

In the example configuration below, we will use the following names:
MXSERVER is the application server for the Maximo UI from initial installation.
MXMIF is the application server for the Maximo Enterprise Adapter instance
MXCLUSTER is the cluster
MXUI1 is a clustered server for the UI
MXUI2 is a clustered server for the UI

Create a second application server: Name this second server MXMIF

1. Open the WebSphere Administrative Console.
2. Click Servers > Application servers, in the Application servers pane, click New.
3. In the Create New Application Server screen, enter MXMIF in the Server name field and click Next.
4. In the Select a server template screen, leave the selected “default” and click Next.
5. In the Specify server specific properties screen, check “Generate Unique Ports” checkbox, click Next.
6. Click Finish, and then click Save.
7. Heap size: Click on the new MXMIF server > Java and Process Management > Process Definition > Java Virtual Machine and fill in both the Initial and Maximum Heap sizes. Click Apply and then click Save
NOTE: When setting the maximum heap size for the MXMIF application server JVM, the admin guide says to set this to 1024MB, however, since this application server will not be used by users directly, the memory size can be increased to 2048MB so that it can handle large volumes of messages

Creating a cluster and cluster members

1. Click Servers > Clusters, in the Server clusters screen, click New.
2. In Step 1: Enter basic cluster information, enter MXCLUSTER in the Server name field, check Prefer local checkbox, click Next.
3. In Step 2: Create first Clustered Servers member, enter the following:
a. Enter MXUI1 in the Member name field.
b. Accept the defaults in the Select Node and Weight fields.
c. Check the Generate Unique Http Ports checkbox.
d. Select the “Create the member using existing application server as a template” radio button and choose MXSERVER (this is the application server name created initially for Maximo) from the drop down list and click Next.
4. In Step 3: Create additional cluster members, enter MXUI2 in the Member name field, click Add Member and then click Next.
5. Click Finish to create the cluster and clustered servers, then click Save

Update Virtual Hosts

This procedure describes how to verify port numbers used by the clustered servers. It also explains how to update the virtual host with the port number information. A virtual host enables a single host machine to resemble multiple host machines. Each virtual host has a logical name and a list of one or more DNS aliases by which it is known.
1. To verify port numbers of the clustered application servers, perform the following actions:
a. Servers > Application Servers, click MXUI1.
b. Under the Communications, click Ports.
c. Make a note of the WC_defaulthost port number for use below (9082, 9083).
2. Repeat Step 1 for MXUI2.
3. Environment > Virtual Hosts, click New.
4. Enter MXCLUSTER_host is the Name field, click Apply.
5. Click Host Aliases under Additional Properties.
6. Click New in the Host Alias panel to add 3 Host name and port number values to the host aliases list:
a. Host Name: *, Port: 80 (IBM HTTP Server port), click OK.
b. Host Name: *, Port: 9082 (same as port number for MXUI1), click OK.
c. Host Name: *, Port: 9083 (same as port number for MXUI2), click OK.
7. Click Save.

Creating data source providers for JMS stores

Set two data sources in the WebSphere console for use by the JMS resources

Note that each data source will require a unique schema, one will be used by the IF instance, and the other by the cluster. This is a WebSphere requirement that two message engines require unique schema names. As you add bus members, each member added will cause a unique message engine to be created. In this configuration there are two members, the IF instance and the cluster.

Since two schemas will be required for this configuration, and the first schema name will be the maximo schema, work with your DBA to create a second schema in the same database specifically for use by the second data source before proceeding with the steps below.

Important: The user that owns the second schema must be able to create tables.

Creating the data source provider

This example is Oracle, for either SQL Server or DB2, you have to make appropriate changes.

1. Resources > JDBC > JDBC Providers
2. Select a valid scope from the dropdown that represents the top level (cell), such as Cell=ctgCell01.
3. Click the "New" button.
4. In Step 1: Create new JDBC provider, select the following:
a. Select your database type.
b. Select the provider type (i.e. oracle and oracle driver).
c. In the implementation type dropdown select "XA data source".
d. In the name field, enter oraclexa, click “Next”.
5. In Step 2: Enter database class path information, enter the local path to your oraclethin.jar in the Directory location box, example: C:\ibm\SMP\maximo\applications\maximo\lib\ and click Next.
6. Click “finish” and then click the oraclexa again
7. Edit the Class path box with the correct path to the oracethin.jar as follows:
C:\ibm\SMP\maximo\applications\maximo\lib\oraclethin.jar
8. Click Apply and then click Save.

Creating the first data source

A JMS server requires a data repository (also called a data source) to be configured to maintain messages. To configure the data sources - one for inbound and one for outbound, you can either use the current Maximo database or a separate database. This example is Oracle, for either SQL Server or DB2, you have to make appropriate changes.

1. Navigate back to your JDBC providers and click oraclexa.

2. Click “Data sources" and then click New.
3. In Step 1: Enter basic data source information, in the Data source name field enter: oraclexads
4. In the JNDI name field, enter: jdbc/oraclexads, click “next”.
5. In Step 2: Enter database specific properties for the data source, enter the JDBC URL for your database (this can be found in your maximo.properties if you are not sure)

jdbc:oracle:thin:@server:1521:maximo

9. Select the Data store helper class name dropdown and select your database version, click Next.
10. Click “Finish” and then click Save
11. Repeat the above steps 1-8 to create a second Data source called oraclexads2.

Creating your first JAAS-J2C authentication data

1. Navigate back to your JDBC provider called oraclexa, click Data sources, click your data source called oraclexads
2. Under Related Items, click the link for "JAAS-J2C authentication data", click New
a. In the alias field, enter a value you would like to use: i.e. maximo
b. Enter the username and password used to connect to the database.
c. Enter a description that identifies this entry
3. Click apply.
4. Navigate back to your data source called oraclexads.
5. In the dropdown field for "Component managed authentication alias", select your data alias (i.e. maximo)
6. Click Apply and then Save.
7. Navigate to your data source again and click the test button at the top of the screen to test your data source.
8. Repeat steps 1-7 above to create a second JAAS-J2C authentication data named maximo2 for the oraclexads2 datasource.

Creating JMS resources for use in a clustered environment

Creating the JMS buses:

1. Service Integration/Buses, click New.
2. In Step 1: Create a new bus, enter in the name field "mifjmsbus"
3. Deselect the "Bus Security" checkbox and click “Next”, then click “Finish”.
4. Navigate to the bus you just created and select it
5. Change the "High message threshold" to 500,000 messages
6. Click "Apply" and then Save.
7. Repeat the above steps 1-7 to create a second bus called “uijmsbus”.

Adding members to the buses:

1. Service Integration/Buses
2. Select mifjmsbus, select "bus members", click Add.
3. In Step1: Select server, cluster…, select the “server” radio button, select MXMIF server from the drop down, click “next”
4. In Step 2: Select the “Data store” radio button, click Next.
5. In Step 3: Provide the message store properties,
a. select the “Use existing data source” radio button.
b. In the data source JNDI name field, enter: jdbc/oraclexads
c. Enter the schema name for the authentication alias used by this data source (i.e. maximo).
d. Select the alias you created for this data source from the dropdown.
e. Make sure the “create tables” checkbox is checked, click Next.
6. Click “finish” and then click Save.
7. Repeat steps 1-6 above for the uijmsbus, except using maximo2 and jdbc/oraclexads2

Setting the message store authentication alias

1. Service Integration/Buses and select mifjmsbus, select “Messaging engines”
2. Select the message engine from the list, there should be only one for the IF server
3. Under “Additional Properties” select “Message store”
4. In the authentication alias dropdown, select the maximo alias, click Apply and then click Save.
5. Repeat the above 4 steps to for the uijmsbus and maximo2 alias.

Creating bus destinations

cqin

1. Service Integration/Buses, select mifjmsbus
2. Click "Destinations", click New
3. Under Select destination type, select "Queue" and click “Next”
4. In Step 1: Set queue attributes, the Identifier field, enter "cqinbd" and click “Next”
5. In Step 2: Assign the queue to a bus member, under Bus member select Node=ctgNode01:server=MXMIF and click “Next”, then click “Finish”.
6. Navigate back to this destination, and set the exception destination radio button to “Specify” and set the value in the textbox to cqinbderr
7. Click “Apply” and click Save.
8. Repeat steps 1-7 for the cqinbderr queue.

sqin

1. Service Integration/Buses, select mifjmsbus
2. Click "Destinations", click New
3. Under Select destination type, select "Queue" and click “Next”
4. In Step 1: Set queue attributes, the Identifier field, enter "sqinbd" and click “Next”
5. In Step 2: Assign the queue to a bus member, under Bus member select Node=ctgNode01:server=MXMIF and click “Next”, then click “Finish”.
6. Navigate back to this destination, and set the exception destination radio button to “None”.
7. Click “Apply” and click Save.

sqout

1. Service Integration/Buses, select uijmsbus
2. Click "Destinations", click New
3. Under Select destination type, select "Queue" and click “Next”
4. In Step 1: Set queue attributes, the identifier field, enter "sqoutbd".
5. In Step 2: Assign the queue to a bus member, under Bus member select Node=ctgNode01:server=MXCLUSTER and click “Next”, then click “Finish”.
8. Navigate back to this destination, and set the exception destination radio button to “None”.
9. Click “Apply” and click Save.

Creating the IF connection factories

1. Resources/JMS providers
2. Select “Default Messaging Provider”, Cell=ctgCell01 scope
3. Select "Queue connection factories", click New and fill in the following:
a. In the name field, enter "mifconfact"
b. In the JNDI name field, enter: jms/maximo/int/cf/intcfmif
c. Select the bus mifjmsbus from the dropdown, click "apply".
4. Go back to "Queue connection factories", click New and fill in the following:
a. In the name field, enter "uiconfact".
b. In the JNDI name field, enter: jms/maximo/int/cf/intcfui
c. Select the bus uijmsbus from the dropdown.
d. Click "apply" and then click Save.

Create Continuous inbound error queue:

1. Resources/JMS providers
2. Select “Default Messaging Provider”, Cell=ctgCell01 scope
3. Click “Queues”, then click "New".
4. Enter the name as "CQINERR"
5. In the JNDI name field, enter "jms/maximo/int/queues/cqinerr”
6. Select the mifjmsbus as the bus for this queue from the bus name drop down
7. Select the cqinbderr queue from the queue name drop down
8. Click "Apply".

Modify JMS queues

Continuous inbound queue:

1. Select "CQIN"
2. Select the mifjmsbus as the bus for this queue from the bus name drop down
3. Select the cqinbd queue from the queue name drop down
4. Click "Apply".

Sequential inbound queue:

1. Select "SQIN"
2. Select the mifjmsbus as the bus for this queue from the bus name drop down
3. Select the sqinbd queue from the queue name drop down
4. Click "Apply".

Sequential outbound queue:

1. Select "SQOUT"
2. Select the uijmsbus as the bus for this queue from the bus name drop down
3. In Select the sqoutbd queue from the queue name drop down
4. Click "Apply" and then click Save.

Creating the JMS Activation Specifications

1. Resources/JMS/Activation specifications.
2. If it already exists, select and delete the current Activation specification “intjmsact”
3. Resources/JMS/JMS providers
4. Select “Default Messaging Provider”, Cell=ctgCell01 scope
5. Click “Activation specifications”, then click "New".
a. In both the Name field and the JNDI name field, enter "intjmsact"
b. In the "Destination JNDI name" field, enter "jms/maximo/int/queues/cqin"
c. Select the bus "mifjmsbus" from the bus name drop down
d. Set Maximum batch size to 10, set Maximum concurrent end points to 5
6. Click Apply
7. Repeat the steps above for a second activation specification called “intjmsacterr”
a. both the Name field and the JNDI name field, enter "intjmsacterr"
b. In the “Destination JNDI name” field, enter “jms/maximo/int/queues/cqinerr”
c. Select the bus "mifjmsbus" from the bus name drop down
d. Set Maximum batch size to 1, set Maximum end points to 10
8. Click “apply” and then click Save.

Changes required in Maximo

1. Launch the Maximo application and log in:
http://host:port/maximo
2. Navigate to the Integration/External Systems application
3. Select any external system and then from the Select action menu, select add/modify queues
4. Modify the connection factory names for your queues to match the names created above and the Maximum try count value as below:

Continuous inbound queue:
Queue JNDI name: jms/maximo/int/queues/cqin
Queue Connection Factory: jms/maximo/int/cf/intcfmif
Maximum Try count: 3

Queue JNDI name: jms/maximo/int/queues/cqinerr
Queue Connection Factory: jms/maximo/int/cf/intcfmif
Maximum Try count: 0

Sequential inbound queue:
Queue JNDI name: jms/maximo/int/queues/sqin
Queue Connection Factory: jms/maximo/int/cf/intcfmif
Maximum Try count: 0

Sequential outbound queue:
Queue JNDI name: jms/maximo/int/queues/sqout
Queue Connection Factory: jms/maximo/int/cf/intcfui
Maximum Try count: 0

5. Save your changes.

6. Configure you JMS crontasks (see the Systems Administrator guide for details).

Build and deploy multiple EAR files from the same Maximo directory.
You will need to build multiple ear file builds of Maximo where some of the files to be included in each ear file will be different from the next, you do not need multiple instances of the Maximo installation folder.

For example, the User Interface application server requires one ear file that disables the IF Inbound crontasks and the Integration Framework application server requires an ear file that disables the Outbound crontasks.

For each file that will be modified making it different for one ear from the next, make a copy of that file and name it appropriately. An example of the files that would be unique to each ear file for the above scenario might look like this:

maximo.properties
maximo.propertiesUI
maximo.propertiesIF

ejb-jar.xml
ejb-jarUI.xml
ejb-jarIF.xml

ibm-ejb-jar-bnd.xmi
ibm-ejb-jar-bndUI.xmi
ibm-ejb-jar-bndIF.xmi

Where there are 3 copies of each file, one with the default name, the next named for the User Interface ear, and one named for the Integration Framework ear.

In this scenario, for two ears you would make two copies of the file buildmaximoear.cmd and give them names such as the following:

buildmaximoear-UI.cmd
buildmaximoear-IF.cmd

These would be the files you use to build your individual ear files.

These are the steps to change the new cmd files to build your unique ear files:

1. Edit the buildmaximoear-UI.cmd file, and at the top, enter the following shell commands:

copy /Y \ibm\SMP\maximo\applications\maximo\properties\maximo.propertiesUI \ibm\SMP\maximo\applications\maximo\properties\maximo.properties

copy /Y \ibm\SMP\maximo\applications\maximo\mboejb\ejbmodule\meta-inf\ejb-jarUI.xml \ibm\SMP\maximo\applications\maximo\mboejb\ejbmodule\meta-inf\ejb-jar.xml

copy /Y \ibm\SMP\maximo\applications\maximo\mboejb\ejbmodule\meta-inf\ibm-ejb-jar-bndUI.xmi \ibm\SMP\maximo\applications\maximo\mboejb\ejbmodule\meta-inf\ibm-ejb-jar-bnd.xmi

2. Change the EAR_FILENAME variable to reflect the unique ear file name for the UI and IF, for example:

set EAR_FILENAME=maximoUI.ear

3. You can then run this build scripts to build the ear files. In this case, the resulting ear file will be named maximoUI.ear.

4. Repeat the above steps to create the maximoIF.ear as well, changing references from UI to IF.

Prepare the UI application

1. Edit the maximo.propertiesUI file and add the donotrun option as below:
a. mxe.crontask.donotrun=JMSQSEQCONSUMER.SEQQIN, BBCron.BBCRON1, ESCALATION. ESCESCBLTNEXP, REPORTLOCKRELEASE, REPORTLOCKRELEASE1, REPORTUSAGECLEANUP, REPORTUSAGECLEANUP1

Since we want almost all of the crontasks to run in the IF instance, all crontasks will be listed here except for the JMSQSEQCONSUMER.SEQQOUT - this crontask will need to run in the UI instance.

Note: Use of the above donotrun option is recommended over the target-enabled option because the donotrun option is Cluster-aware. Therefore, if the crontask is running in one application server, and that application server is shut down, another application server can take over running the crontasks.

Be sure to go through your list of crontasks and note each instance in the correct case and add it to the mxe.crontask.donotrun parameter in the maximo.propertiesUI, each separated by a comma

2. Build the maximoUI.ear file.

Prepare the IF application

For the MXMIF application instance, edit the following files and uncomment the message driven beans for the continuous queues:

1. Locate the file under \ibm\SMP\maximo\applications\maximo\mboejb\ejbmodule\meta-inf\ejb-jarIF.xml and edit the file and make sure the following four sections are uncommented to look like below:

<!-- MEA MDB -->
<message-driven id="MessageDriven_JMSContQueueProcessor_1">
<ejb-name>JMSContQueueProcessor-1</ejb-name>
<ejb-class>psdi.iface.jms.JMSContQueueProcessor</ejb-class>
<transaction-type>Container</transaction-type>
<message-destination-type>javax.jms.Queue</message-destination-type>
<env-entry>
<env-entry-name>MESSAGEPROCESSOR</env-entry-name>
<env-entry-type>java.lang.String </env-entry-type>
<env-entry-value>psdi.iface.jms.QueueToMaximoProcessor</env-entry-value>
</env-entry>
</message-driven>


<!-- MEA MDB for error queue -->
<message-driven id="MessageDriven_JMSContQueueProcessor_2">
<ejb-name>JMSContQueueProcessor-2</ejb-name>
<ejb-class>psdi.iface.jms.JMSContQueueProcessor</ejb-class>
<transaction-type>Container</transaction-type>
<message-destination-type>javax.jms.Queue</message-destination-type>
<env-entry>
<env-entry-name>MESSAGEPROCESSOR</env-entry-name>
<env-entry-type>java.lang.String </env-entry-type>
<env-entry-value>psdi.iface.jms.QueueToMaximoProcessor</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>MDBDELAY</env-entry-name>
<env-entry-type>java.lang.Long </env-entry-type>
<env-entry-value>30000</env-entry-value>
</env-entry>
</message-driven>


<!-- MEA MDB -->
<container-transaction>
<method>
<ejb-name>JMSContQueueProcessor-1</ejb-name>
<method-name>*</method-name>
</method>
<trans-attribute>Required</trans-attribute>
</container-transaction>

<!-- MEA MDB for error queue -->
<container-transaction>
<method>
<ejb-name>JMSContQueueProcessor-2</ejb-name>
<method-name>*</method-name>
</method>
<trans-attribute>Required</trans-attribute>
</container-transaction>


2. Locate the file under \ibm\SMP\maximo\applications\maximo\mboejb\ejbmodule\meta-inf\ibm-ejb-jar-bndIF.xmi and edit the file using a text editor and make sure the following 2 sections are uncommented to look like below:

<!-- MEA MDB -->
<ejbBindings xmi:type="ejbbnd:MessageDrivenBeanBinding" xmi:id="MessageDrivenBeanBinding_1" activationSpecJndiName="intjmsact">
<enterpriseBean xmi:type="ejb:MessageDriven" href="META-INF/ejb-jar.xml#MessageDriven_JMSContQueueProcessor_1"/>
</ejbBindings>

<!-- MEA MDB for error queue -->
<ejbBindings xmi:type="ejbbnd:MessageDrivenBeanBinding" xmi:id="MessageDrivenBeanBinding_1" activationSpecJndiName="intjmsacterr">
<enterpriseBean xmi:type="ejb:MessageDriven" href="META-INF/ejb-jar.xml#MessageDriven_JMSContQueueProcessor_2"/>
</ejbBindings>


3. Edit the maximo.properties file and add the donotrun option as below:
a. mxe.name=MXMIF
b. mxe.crontask.donotrun=JMSQSEQCONSUMER.SEQQOUT

Note: SEQQOUT will be the only crontask entry because this is the only crontask that we do not want to run.

4. Rename the current maximo.ear (for keeping) and then build the maximo.ear. When the new ear has been built, rename the new ear to ”mxmif.ear”.

Deploy both the UI and IF applications

1. Deploy both ear files:
a. The maximoUI.ear will be deployed to the MXCLUSTER, when mapping modules to servers make sure you select both the MXCLUSTER as well as the webserver1 and when mapping virtual hosts to web modules use the virtual host you created above: MXCLUSTER_host
b. The maximoIF.ear will be deployed to the MXMIF application, for the application name change from "MAXIMO" to MXMIF. When mapping modules to servers make sure you select both the MXMIF as well as the webserver1 and when mapping virtual hosts to web modules use the virtual host you created above: maximo_host

2. Start the MXCLUSTER Cluster and the MXMIF application server.


The Integration Global Directory:

When you deploy a web service, a folder called Axis2 is updated with the service you have just deployed. This file will be written under to root folder of the Integration Global Directory. If WebSphere application servers will be distributed in a multi-node environment, the integration global directory must exist in a shared location that all application servers can access.

This directory is used for error file extract and wsdl files for web services.
This shared location can be either a mapped drive or UNC share (Windows), or a mount point (Unix). The user specified to run the WebSphere services must have access to read and write to this share or mount point. This includes the node agent. In Windows, do not use a local system account to start Windows services but rather a domain account as local system accounts to not have access to mapped drives or UNC shares.

You set the integration global directory path in the System Properties application, the property is called mxe.int.globaldir.

Deploying web services

When deploying web services, you will need to set up the web service administration URL and port to point to the MXMIF application server IP address and port. When sending transactions to these interfaces, you will need to point your web service client to the IP address and port of the MXMIF application server IP address and port, not the cluster address for the UI instances

It is also important to make sure that the Integration Global Directory is in a location that all application servers in a multi-node environment can access. See the next section for information on the Integration Global Directory.


Important note:

Importing data can only be performed while logged into the IF instance where the Message Driven Bean is deployed. Exporting data can only be performed while logged into one of the UI applications


For further information or other scenarios, please contact IBM TPAE Support.