Integrating your enterprise applications with IBM Maximo Asset Management V7.1

Integrating your applications using Web services

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.

Pandian Mariadoss (mariados@us.ibm.com), Senior IT Certified Specialist, IBM

Photo of Pandian MariadossPandian Mariadoss is an Integration IT Specialist who works on integration architecture, design, implementation for multiple projects at the IBM Global Solution Center, U.S.A. His area of focus is integrating WebSphere products using Web technology.



13 January 2010

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.

What is the Integration Framework?

The Integration Framework:

  • Is an essential component of Maximo service-oriented architecture (SOA).
  • Provides an XML interface for all Maximo business objects.
  • Provides support for bi-directional integration with external applications and middleware products.
  • Supports standard protocols such as HTTP/HTTPS, Web services, JMS, flat files, and database tables.
  • Supports message exchange in a synchronous and asynchronous model.

This article will help you integrate the Maximo application with an external system like WebSphere Process Server (hereafter called Process Server) using Web services technology. It focuses on implementing Web services for the following scenarios in Maximo:

  • Inbound transaction: Process Server detects an equipment failure notification and sends a work order creation for the failed equipment to Maximo.
  • Outbound transaction: On an event (create, update, delete, and so on) in the Maximo’s work order application, a message with the work order information is sent to Process Server.

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.

Maximo message flow of inbound and outbound transactions

This section discusses how Maximo exchanges information with an external system using Web services. Figure 1 shows Maximo components involved in processing a Web service request from Process Server.

Figure 1. Maximo inbound Web service message flow
Maximo inbound Web service message flow
  1. Process Server receives an equipment failure notification from an external system. For this article, the external system is a form-based JSP client application, which sends the equipment information when the user presses the Submit button. (The equipment information, such as the asset number, asset location, and asset owner, matches the Maximo asset information.)
  2. Process Server maps this information to the Maximo’s Worker Order business object and invokes the work order Web service using the Export SCA Web service binding.
  3. A direct connection is established between Process Server and Maximo’s Integration Framework (IFW). The IFW containing the deployed work order Web service returns a response to Process Server that confirms success or failure of the processed message. (The IFW expects all XML messages to be encoded in a Unicode format.)

Figure 2 shows Maximo components involved in publishing a Web service request to Process server.

Figure 2. Maximo outbound Web service message flow
Maximo outbound Web service message flow
  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.

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 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
      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
    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.
    • 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
    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 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
    Generate schema for MXWO Web service
    Figure 7. Schema directory under Maximo application server
    Schema directory 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 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
    Deployed MXWO Web service

Note: The "Is Deployed?" check box is enabled automatically on successful deployment.

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 diagram.
  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:
    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
    Import Maximo's inbound artifacts into Process Server
    Figure 10. MXWO artifacts after the import
    MXWO artifacts after the import
  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
    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.

  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
    Test component for import SCA component
  7. Deploy the BI module onto the Process Server runtime.

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 invoke 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 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
    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 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
    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
    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 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
    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 Developer 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 the 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 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.

  4. Import the Maximo artifact to the BI module (Figure 17).
    Figure 17. Import Maximo outbound artifacts into Process Server
    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
    Business object for the work order notification
  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
    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 in 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
    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 Process 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:

    • Change the SOAP envelope.
    • Change the SOAP body to insert the operation name.
    • Log the changed 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){
            SOAPBodyElement 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
         StringBuffer 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/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
    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 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:
    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
    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
    Associate event handler to a publish channel
    Figure 24. Enabling IFW's external system
    Enabling 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.


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) using the following link: http://<WPShostname>:9080/WPSToMaximoWorkOrderWeb/AlertGenerator.jsp.
    Figure 25. Equipment Failure Notification form
    Equipment Failure Notification form
  3. The work order number is returned to the client upon successful work order creation.

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
    Maximo Work Order tracking application
  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.


Downloads

DescriptionNameSize
Maximo filesMaximoArtifactszip9KB
PI filesInbound_PI.zip29KB
PI filesOutbound_PI.zip16KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=461085
ArticleTitle=Integrating your enterprise applications with IBM Maximo Asset Management V7.1
publish-date=01132010