Implementing the Maximo inbound work order creation
scenario
The inbound work order (equipment failure notification) scenario involves two steps:
1.
Setting up Maximo for the work order Web service.
2.
Setting up Process Server to invoke the work order Web
service.
Setting up Maximo for the work order Web service
To enable the Web service in Maximo, complete the following steps:
1.
There are two important properties that need to be set before deploying a Web service in
Maximo. You can access the System propert
ies from the Maximo application:
GoTo
-
>
System Configuration
-
> Platform Configuration
-
> System Properties
.
o
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
).
o
mxe.int.webappurl
: This specifies the integrat
ion 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
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 Web services.
o
The
object structures
are synchronous services, easy to use, and sup
port five
different operations (create, update, query, delete, and sync).
o
The
enterprise
Web service supports additional exit processing, business rules,
and transformations not available to the object structure Web services. The
enterprise services can b
e either synchronous or asynchronous (JMS queues).
o
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 struct
ure (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, opera
tion 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 schem
a 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
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
, as
shown in Figure 7.
Figure 6. Generate schema for MXWO Web service
Figure 7. Schema director
y under Maximo application server
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
Integ
ration
-
> 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
Note:
The "Is Deployed?" check box is enabled automatically on successful depl
oyment.
Setting up Process Server to invoke the work order Web service
This article focuses on WebSphere Integration Developer V6.0.2 to develop the Process Server
artifacts. The following steps invoke the Maximo's
Work Order Web service from Process
Server:
1.
First, create a Business Integration (BI) module. From the Integration Developer
environment select
File
-
> New
-
> Project
-
> Business Integration
-
> Module
, which
creates a new module and opens the Assembly dia
gram.
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 artifa
cts are found under one single directory after the import.
3.
Open all the artifacts and edit the schema location wherever possible.
From:
4.
SchemaLocation="http://localhost:9080/meaweb/schema/service/MXWOService
.xsd"
5.
http://localhost:9080/meaweb/schema/ser
vice/MXWOService.xsd"
6.
schemaLocation="http://localhost:9080/meaweb/schema/common/meta/MXMeta.
xsd"
7.
schemaLocation="http://localhost:9080/meaweb/schema/common/mos/MXWO.xsd
"
schemaLocation="http://localhost:9080/meaweb/schema/common/mbo/workorde
r.xsd"
To:
s
chemaLocation="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.
8.
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
Figure 10. MXWO artifacts after the import
9.
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 We
b 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 servi
ce 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
Note:
Make sure the address property in the import Web service binding is pointing to
the Maximo server.
10.
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
11.
Deploy the BI module onto the Process Server runtime.
Back to top
Implementing the Maximo outbound work order notification
scenario
To notify work order changes in Maximo, complete the following steps:
Set up Maximo to notify the work order changes.
Set up the work order Web service in Process Server.
Set up Maximo to in
voke the Process Server Web service.
Setting up Maximo to notify work order changes to Process Server
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 busines
s 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
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 fashi
on. 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
, and the “Enable Listener” check box is enabled (Figure 15).
Figure 15. Enable publish channel's event listener
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 wo
rk 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.
Activa
te 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
Setting up the work order Web service in Process Server
The following steps describe how to accept a work order Web service request from Maximo:
1.
Create a Business Integration (BI) module. From the Integration Develo
per environment,
select
File
-
> New
-
> Project
-
> Business Integration
-
> Module
, which creates a new
module and opens the Assembly diagram.
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 t
he Maximo’s MXWOInterface publish channel needs to edited from
schemaLocation="http://localhost:9080/meaweb/schema/common/meta/MXMeta.
xsd"
to
schemaLocation="MXMeta.xsd"
. This ensures that the references to the artifacts
are resolved correctly after the im
port.
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.
4.
Import the Maximo artifact to the BI module (Figure 17).
Figure 17.
Import Maximo outbound artifacts into Process Server
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).
Figure 18. Business object for the work order notification
6.
Cre
ate 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 int
erface 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
Note:
The response data type can be any type.
7.
Create an export SCA Web service binding. Process Server uses an export SCA
component to accept requests from an external system. To create, go to
BI Module
-
>
Assembly Diagram
(Figure 20), drag and drop the component
Export
and add the
interface created i
n Step 6. To generate a Web service binding for the newly created
export component, right
-
click it and select
Generate Binding
and select
soap/http web
service binding
.
Figure 20. Export SCA Web service binding
Note
: Right
-
click the component to add an
interface.
8.
Create a Web service JAX
-
RPC handler. The SOAP message that Maximo sends to
Process Server requires some pre
-
processing before it can be processed. You can achieve
pre
-
processing either by a Web service exit in the Maximo event handler, or a Web
service server handler in Process Server. This article will focus on the Web service server
handler in Process Server.
The work order SOAP message from Maximo does not contain the operation name and
the target namespace to reference the right object in P
rocess Server. Process Server uses
the Web service handler to handle the incoming SOAP message and to process it
correctly. The Web service handler does the following:
o
Change the SOAP envelope.
o
Change the SOAP body to insert the operation name.
o
Log the cha
nged SOAP message on to the Process Server system out log.
To create a server side Web service handler, refer to
Support for J2EE Web services in
WebSphere Studio Application Developer
.
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
public boolean handleRequest(MessageContext msgContext
) {
System.out.println("** MaximoWebServiceHandler **");
try {
SOAPMessageContext smc = (SOAPMessageContext)msgContext;
SOAPMessage msg = smc.getMessage();
SOAPPart soapPart = msg.getSOAPPart();
SOAPEnvelope envelope = soapPart.getEnvelope
();
SOAPBody body = envelope.getBody();
Iterator it = body.getChildElements();
Object node = null;
String OperationName = null;
while( it.hasNext()){
node = it.next();
if (node instanceof SOAPBodyElement){
SOAPBod
yElement element = (SOAPBodyElement)node;
System.out.println("Parent elemnt["+element.getLocalName()+
"]");
if (element.getLocalName().indexOf("Publish") !=
-
1){
OperationName = element.getLocalName();
break;
}
}
}
if (OperationName != null){
SOAPBodyElement oldelement = (SOAPBodyElement)node;
String oldelemStr = oldelement.toString();
int endpos = oldelemStr.indexOf('>'); //replace the first element
StringBuff
er soapContentBuff = new StringBuffer();
soapContentBuff.append("<SOAP
-
ENV:Envelope ");
soapContentBuff.append("xmlns:SOAP
-
ENV=
\
"http://schemas.xmlsoap.org/soap/envelope/
\
" ");
soapContentBuff.append("xmlns:q0=
\
"http://www.ibm.com/m
aximo
\
"
");
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)));
soapCo
ntentBuff.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);
e
lementStr = 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
10.
Build and deploy the BI module onto the Process Server runtime.
Setting up Maximo to invoke the Process Server Web service
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 S
OAP/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:
EndPointURL =
Web service address
For example:
http://<WPS
hostname>:9080/MxToWPSWorkOrderWeb/sca/MXToWPSWO_Export)
.
ServiceName =
Web service name
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 applicatio
n,
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
Figure 24. Enabli
ng IFW's external system
Note:
The out
-
of
-
the
-
box Maximo comes with JMS queues configured. To configure Maximo’s
JMS queues, refer to
Manually configuring JMS queues
.
Back to top
Testing the Maximo inbound work order creation
1.
Deploy the
Inbound_PI.zip
file (sample code) on to the Process Server runtime.
2.
Submit the equipment failure Notification Form (Figure 25) u
sing the following link:
http://<WPShostname>:9080/WPSToMaximoWorkOrderWeb/AlertGenerator.jsp
.
Figure 25. Equipment Failure Notification form
3.
The work order number is returned to the client upon successful work order creation.
Back to top
Testing the Maximo outbound work order notification
1.
Deploy the
Outbound_PI.zip
file (sample code) on to the Process Server runtime.
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
3.
Process Server receives the notification and logs the message to the SystemOut.log file.
Enter the password to open this PDF file:
File name:
-
File size:
-
Title:
-
Author:
-
Subject:
-
Keywords:
-
Creation Date:
-
Modification Date:
-
Creator:
-
PDF Producer:
-
PDF Version:
-
Page Count:
-
Preparing document for printing…
0%
Comments 0
Log in to post a comment