Академический Документы
Профессиональный Документы
Культура Документы
13 Jan 2010
This article explains the Web services capabilities of the IBM® Maximo® Asset
Management's Integration Framework and shows you how to integrate it with
WebSphere® Process Server.
Introduction
The IBM Maximo V7.1 Asset Management System manages an organization’s
assets throughout its life cycle - from requisition to retirement. Maximo V7.1 uses the
Integration Framework to integrate with an external system to exchange information.
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 1 of 30
developerWorks® ibm.com/developerWorks
Requirements
This article assumes that the IBM Maximo Asset Management System V7.1 is
already installed, configured, and running in your environment. Also, WebSphere
Process Server V6.0.2 is installed and running in the same environment. The
artifacts to be deployed in Process Server are built using WebSphere Integration
Developer V6.0.2 (hereafter called Integration Developer) and require an Integration
Developer environment.
Downloads
This article provides the following zip files that you can download:
• The MaximoArtifacts.zip file contains the necessary Maximo files that you
can import onto the Process Server to invoke or process the Maximo’s
Work order Web service.
• The Outbound_PI.zip file is the Process Server Interchange file to
implement the Maximo Work Order outbound's scenario.
• The Inbound_PI.zip file is the Process Server Interchange file to
implement the Maximo Work Order inbound's scenario.
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 2 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 3 of 30
developerWorks® ibm.com/developerWorks
1. On a work order event (create, update, and delete), the IFW identifies the
component business object associated with the event and constructs the
work order (MXWO) object structure.
2. The publish channel associated with the object structure is invoked if any
rules or pre-processing is applied and a XML message is constructed.
3. The IFW sends the message to a JMS queue (jms/sqout). A cron task
(out-of-the box process) defined in the Maximo application server extracts
and sends the message to a message router, which identifies the Web
service handler associated with the publish channel.
4. The Web service handler uses the properties endpoint URL and service
name to invoke the Web service deployed in Process Server.
5. The Export Web service SCA binding receives the SOAP message and
constructs the business object for further processing.
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 4 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
1. There are two important properties that need to be set before deploying a
Web service in Maximo. You can access the System properties from the
Maximo application: GoTo -> System Configuration -> Platform
Configuration -> System Properties.
• mxw.int.globaldir: This property specifies the root folder where all
the integration configuration files are located. If this value is null, the
folders are created under the directory from which the application
server is started, or from the current working directory of the
application server for example:
C:\IBM\WebSphere\AppServer\profiles\AppSrv01).
• mxe.int.webappurl: This specifies the integration Web application
URL. The syntax is http://<Maximo
hostname>:port#/meaweb. "port#" points to default_host under
the Ports option in the WebSphere Application Server admin console
for Maximo (Figure 3).
Figure 3. mxe.int.webappurl system property
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 5 of 30
developerWorks® ibm.com/developerWorks
2. Next, you need to define the object structure. The inbound work order
creation scenario uses the work order object structure (MXWO) to
process its business events. The work order object structure comes as a
Maximo out-of-the-box feature and it defines the business object for the
inbound scenario. To see the list of object structures defined or to create
new object structure, use the Maximo application. Click GoTo and select
the menu option Integration -> Object Structures (Figure 4).
Figure 4. Work order object structure
3. Now create the work order Web service. In Maximo, there are three
different types of Web services: object structure, enterprise, and standard
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 6 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
Web services.
• The object structures are synchronous services, easy to use, and
support five different operations (create, update, query, delete, and
sync).
• The enterprise Web service supports additional exit processing,
business rules, and transformations not available to the object
structure Web services. The enterprise services can be either
synchronous or asynchronous (JMS queues).
• The standard services are created from methods that are annotated
in the application services.
This article focuses on the object structure Web services. To create a new
Web service from the object structure (MXWO), use the Maximo
application. Click GoTo and select the menu option Integration -> Web
Services Library. From the Web Service Library page, click the select
Action drop-down list box to select the Create WS from Object
Structure menu option. From the Create Web Service from an Object
Structure Definition dialog box (Figure 5), select the object structure for
which you want to create the Web service.
Figure 5. Create Web service from MXWO object structure
4. To generate XSD files (data types, operation type) for the newly created
MXWO Web service, use the Maximo application. Click GoTo and select
the menu option Integration -> Web Services Library. In the Web
Service Library page, search for the Web service created in Step 3 and
select it. The schema for the selected Web service can be generated by
clicking the Generate schema / view XML button (Figure 6) and clicking
OK.
The schema files are generated under the directory defined in the
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 7 of 30
developerWorks® ibm.com/developerWorks
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 8 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
5. The newly created MXWO Web service needs to be deployed and the
Web service definition language (WSDL) has to be defined. To deploy the
Web service, use the Maximo application. Click GoTo and select the
menu option Integration -> Web Services Library. From the Web
Service Library page, click the select Action drop-down list box to select
Deploy Web Services (Figure 8). On successful deployment, the WSDL
files are generated under the directory defined in mxe.int.globadir. If
no value is defined for this property, the WSDL gets generated under
<WebSphere installed
directory>\AppServer\profiles\AppSrv01\wsdl>.
Figure 8. Deployed MXWO Web service
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 9 of 30
developerWorks® ibm.com/developerWorks
2. Prepare the Maximo artifacts before importing them into the BI module.
Move all the Maximo MXWO Web service artifacts (MXMeta.xsd,
MXWO.xsd, workorder.xsd, MXWOService.xsd, and MXWO.wsdl) to a
common directory. This action ensures that all the artifacts are found
under one single directory after the import.
3. Open all the artifacts and edit the schema location wherever possible.
From:
SchemaLocation="http://localhost:9080/meaweb/schema/service/MXWOService.xsd"
http://localhost:9080/meaweb/schema/service/MXWOService.xsd"
schemaLocation="http://localhost:9080/meaweb/schema/common/meta/MXMeta.xsd"
schemaLocation="http://localhost:9080/meaweb/schema/common/mos/MXWO.xsd"
schemaLocation="http://localhost:9080/meaweb/schema/common/mbo/workorder.xsd"
To:
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 10 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
schemaLocation="MXWOService.xsd"
schemaLocation= "MXMeta.xsd.xsd"
schemaLocation="MXWO.xsd"
schemaLocation="workorder.xsd"
This ensures that the references to the artifacts are resolved correctly
after the import.
4. Import the edited artifacts into the BI module. Select all the artifacts and
import them to the newly created BI module. On successful import,
Integration Developer creates the Maximo business objects and Web
service port to invoke the MXWO Web service. To import the artifacts into
Integration Developer, right-click the BI module, then Import -> File
System -> Browse to the artifacts directory (Figure 9 and Figure 10).
Note: The MaximoArtifacts.zip file contains all the necessary Maximo files
that you can import to the Process Server to invoke the Maximo’s Work
order Web service.
Figure 9. Import Maximo's inbound artifacts into Process Server
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 11 of 30
developerWorks® ibm.com/developerWorks
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 12 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
5. Create an import SCA Web service binding. Process Server uses the
import SCA component to invoke the external service. This article focuses
on creating an import SCA component with SOAP/HTTP Web service
binding. Expand the Web service ports from the BI module and drag and
drop the service port MXWOSOAP11Port onto the Assembly diagram.
Integration Developer invokes the user with the option of “export with web
service binding” or “import web service binding”. Select the import option
with soap/http web service binding and Integration Developer creates
an import WSDL that invokes the Maximo’s MXWO Web service (Figure
11).
Figure 11. Import type SCA component with Web service binding
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 13 of 30
developerWorks® ibm.com/developerWorks
Note: Make sure the address property in the import Web service binding
is pointing to the Maximo server.
6. Now test the import SCA Web service component. Integration Developer
provides a test component to test the SCA artifacts. To test the Work
Order Import SCA component, right-click MXWOPortTypeImport1 and
you can input values to the work order Web service, and then click
Continue (Figure 12). Integration Developer invokes the Maximo MXWO
Web service and returns a response on successful completion of the test.
Figure 12. Test component for import SCA component
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 14 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
1. First, define the object structure. The outbound work order notification
scenario uses the work order object structure (MXWO) to notify its
business events. The work order object structure comes as a Maximo
out-of-the-box feature and it defines the business object for the outbound
scenario. To see the list of object structures defined or to create a new
structure, use the Maximo application and GoTo -> Integration-> Object
Structures. Figure 13 shows the Object Structures page.
Figure 13. Work order object structure
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 15 of 30
developerWorks® ibm.com/developerWorks
2. Define a publish channel. Maximo can send events to the external system
using either a asynchronous publish channel or synchronous invocation
channel. This article will focus on sending the work order event
notification in a asynchronous fashion. The publish channel defines what
kind of event it will process based on the object structure and applies
processing rules, if any, after the event has happened and sends the final
message to a message queue. Maximo comes with the MXWOInterface
publish channels as an out-of-the-box feature, which captures the work
order events. To access a publish channel, use the Maximo application
and select GoTo -> Integration-> Publish Channels and filter on
MXWOInterface to get the work order publish channel (Figure 14).
Figure 14. Work order publish channel
3. Enable the Publish channel event listener. The event listener is used to
capture events from the object structure associated with the publish
channel. To enable the listener in the MXWOInterface publish channel, go
to the drop-down list and click Select Action -> Enable Event Listeners,
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 16 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
4. Generate the schema for the publish channel. The schema generated
from the publish channel will be used by Process Server to define the
data type for the notification request. To generate the schema from the
MXWOInterface publish channel, Select Action -> Generate Schema /
View XML and the schema for work order data type is generated under
the Global directory defined in the mxe.int.golabdir system property.
If no value is defined for this property, the schema gets generated under
<WebSphere installed
directory>\AppServer\profiles\AppSrv01\schema.
5. Activate the JMS cron task. Maximo uses the JMS cron task to extract the
work order event message from the message queue and sends it to the
message router. The message router then invokes the specific event
handler to send the message to an external system. To activate the JMS
cron task, use the Maximo application and GoTo -> System
Configuration -> Platform Configuration -> Cron Task Setup, filter on
JMSQSEQCONSUMER, select the the SEQQOUT cron task instance
name, click Active, and save the record (Figure 16).
Figure 16. Activate the JMS cron task
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 17 of 30
developerWorks® ibm.com/developerWorks
The following steps describe how to accept a work order Web service request from
Maximo:
2. Prepare the Maximo artifacts before importing them into the module.
Move the Maximo’s MXWOInterface publish channel data type artifacts
(MXMeta.xsd, and MXWO.xsd) onto a common directory. This action
ensures that all the artifacts are found under a single directory after the
import.
3. Edit the schema location. The schema location for the artifact MXWO.xsd
generated from the Maximo’s MXWOInterface publish channel needs to
edited from
schemaLocation="http://localhost:9080/meaweb/schema/common/meta/M
to schemaLocation="MXMeta.xsd". This ensures that the references
to the artifacts are resolved correctly after the import.
Note: The MaximoArtifacts.zip file contains all the necessary Maximo files
that you can import to Process Server to process the Maximo’s Work
order Web service request.
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 18 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
5. Create a business object specific for the work order request. The input
data type for the Maximo notification request is defined using the Maximo
artifact MXWO.xsd. Create a new business object with a name
(Publish<Maximo Object structure name>), such as
PublishMXWO, and define the namespace as
http://www.ibm.com/maximo. The object contains just one attribute,
<Maximo Object Structure Name>Set of type <Maximo
Object Structure Name>SetType (for example, MXWOSet of type
MXWOSetType). To create it, go to BI module -> Data Types -> New ->
Business Object, set the name as PublishMXWO, and the namespace
as http://www.ibm.com/maximo (Figure 18).
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 19 of 30
developerWorks® ibm.com/developerWorks
6. Create a Web service interface for the work order request. The Web
service interface contains an operation specific for accepting the Maximo
notification request. The syntax for the operation name is
Publish<Maximo Object structure name>, such as
PublishMXWO, to accept the work order request. To create it, go to the BI
module -> Interfaces -> New -> Interface. In the interface wizard,
uncheck the Default namespace and provide a new namespace
(http://www.ibm.com/maximo), (Figure 19) and click Finish. In the
interface window, click Add Request Response Operation and provide
the operation name PublishMXWO and the data type created in Step 5.
Figure 19. Web service interface for the work order notification
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 20 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 21 of 30
developerWorks® ibm.com/developerWorks
Listing 1 shows the code for the Web service handler (server-side), which
modifies the incoming SOAP request from Maximo.
Listing 1. Code for ServiceHandler.java
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 22 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
soapContentBuff.append("xmlns:q0=\"http://www.ibm.com/maximo\" ");
soapContentBuff.append("xmlns:xsd=\"http://www.w3.org/2001
/XMLSchema\" ");
soapContentBuff.append("xmlns:xsi=\"http://www.w3.org/2001
/XMLSchema-instance\">");
soapContentBuff.append("<SOAP-ENV:Body>");
soapContentBuff.append("<q0:" + OperationName +
"xmlns:q0=\"http://www.ibm.com/maximo\">");
soapContentBuff.append('<' + OperationName + '>');
soapContentBuff.append(processContentString(oldelemStr.substring
(endpos+1)));
soapContentBuff.append("</q0:" + OperationName + '>');
soapContentBuff.append("</SOAP-ENV:Body>" +
"</SOAP-ENV:Envelope>");
StreamSource source = new StreamSource(new
StringReader(soapContentBuff.toString()));
msg.getSOAPPart().setContent(source);
msg.saveChanges();
}
msg.writeTo(System.out);
System.out.println();
}catch (Exception e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
return true;
}
public String processContentString(String elementStr){
//This function is to add the namespaces for the first Child Object
//after the Set Object type
String result ="";
//Shift from MXWOSet Object
result = elementStr.substring(0, elementStr.indexOf('>')+1);
elementStr = elementStr.substring((elementStr.indexOf('>')+1));
result = result + elementStr.substring(0,
(elementStr.indexOf('>')));
result = result + " xmlns=\"http://www.ibm.com/maximo\">";
result = result + elementStr.substring(elementStr.indexOf('>') + 1);
return result;
}
9. Add the service handler to the Export SCA Web service port. The Export
SCA uses the service handler to pre-process the incoming SOAP
message. To associate a handler to an export SCA Web service
component, open the project in J2EE perspective and select EJB
Projects -> BI modeuleName -> ejbModule -> META-INF ->
webservices.xml. In the Handlers tab (Figure 21), associate the newly
created service handler to the export SCA Web service component’s port.
Save the setting.
Figure 21. Associate a service handler to a Web service
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 23 of 30
developerWorks® ibm.com/developerWorks
10. Build and deploy the BI module onto the Process Server runtime.
For Maximo to invoke the Web service running Process Server, complete the
following steps:
1. Set up the Web service event handler. The message router in Maximo
routes the event message to the appropriate event handler. For the Work
Order notification scenario, the message needs to be sent to an external
system using SOAP/HTTP. To achieve this, use the Maximo application
and GoTo -> Integration -> Endpoint (Figure 22), select the new
Endpoint, and provide the name MXWOENDPOINT. In the Handler type,
provide WEBSERVICE and populate the EndPointURL and ServiceName
with the following and save the record:
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 24 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
For example:
MXToWPSWO_Export_PublishWOInterfaceHttpService.
Figure 22. Maximo EndPoint with Web service handler
2. Associate the handler to the work order publish channel. The final step is
to associate the event handler to the MXWOInterface publish channel,
which is listening for work order events. From the Maximo application,
GoTo -> Integration -> External Systems, filter on EXTSYS1
(out-of-the-box), and go to Publish channels filter and search for
MXWOInterface. If not found, select new Row, enter the Publish
Channel Name (MXWOInterface) and the EndPoint (MXWOENDPOINT).
Enable the MXWOInterface for the external system EXTSYS1 by
selecting Enabled?, and then activate the external system (EXTSYS1) by
selecting Enabled? (Figure 23 and Figure 24).
Figure 23. Associate event handler to a publish channel
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 25 of 30
developerWorks® ibm.com/developerWorks
Note: The out-of-the-box Maximo comes with JMS queues configured. To configure
Maximo’s JMS queues, refer to Manually configuring JMS queues.
2. Submit the equipment failure Notification Form (Figure 25) using the
following link:
http://<WPShostname>:9080/WPSToMaximoWorkOrderWeb/AlertGenerator.
Figure 25. Equipment Failure Notification form
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 26 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
3. The work order number is returned to the client upon successful work
order creation.
2. Change the status of the existing Maximo Work Order. This sends a work
order change notification message (Figure 26).
Figure 26. Maximo Work Order tracking application
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 27 of 30
developerWorks® ibm.com/developerWorks
3. Process Server receives the notification and logs the message to the
SystemOut.log file.
Conclusion
This article described the integration capability of the IBM Maximo Asset
Management System with WebSphere Process Server by using Web services
technology. It also showed you how to set up Maximo to send and receive work
order information to an external system.
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 28 of 30 © Copyright IBM Corporation 2010. All rights reserved.
ibm.com/developerWorks developerWorks®
Downloads
Description Name Size Download
method
Maximo files MaximoArtifactszip 9KB HTTP
PI files Inbound_PI.zip 29KB HTTP
PI files Outbound_PI.zip 16KB HTTP
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
© Copyright IBM Corporation 2010. All rights reserved. Page 29 of 30
developerWorks® ibm.com/developerWorks
Resources
Learn
• JAX-RPC Web service handlers
• Maximo V7.1 Installation Guide
• Maximo V7.1 Integration Guide
• IBM Maximo Asset Management product page
• deloperWorks WebSphere Process Server and WebSphere Integration
Developer zone
• WebSphere Process Server product page
Discuss
• WebSphere Process Server discussion forum
• WebSphere Integration Developer discussion forum
Integrating your enterprise applications with IBM Maximo Asset Management V7.1
Page 30 of 30 © Copyright IBM Corporation 2010. All rights reserved.