Maximo Web Services tutorial

This entry is part of the Maximo Integration Framework series.

This article explains how to setup and use Web Services capabilities of the Maximo Integration Framework (MIF/MEA).
In Maximo there are three different types of services that can be invoked from Web Services: Object Structure, Enterprise and Standard Services. This article will focus on Object Structure Services for simplicity of discussion but is generally useful to understand how to interact with Maximo through Web Services.


Test tool setup

To play with Web Services you need a client to generate test calls to Maximo. I strongly suggest to use soapUI. It may seems complex at the beginning but is a very powerful and easy tool in the real world. You can download soapUI from here.

Create the Web Service

The first step is to define the Object Structure.
In this example we will create a person record using the out-of-the-box MXPERSON object structure so we don't need to create a new one. In real world scenarios, you typically clone an existing Object Structure to simplify or enrich it. To see the list of object structures defined or to create new object structure, use the Object Structures application under the Integration module.

Now it's time to create the Web Service. To create a new Web Service from the MXPERSON object structure go to Integration - Web Services Library - Create WS from Object Structure and select the MXPERSON object structure.


Deploy the Web Service

Now that we have defined the MXPERSON Web Service it's time to generate the XSD files that describes the service. Open the MXPERSON service in the Web Services Library application and click on the 'Generate schema/View XML' button.


The schema files are generated under the directory defined in the mxe.int.globaldir system property (e.g. C:\MIF\schema\service).

The last step is to deploy the Web Service and generate the Web Service Definition Language (WSDL) file. The WSDL file provides a description of how the service can be called, what parameters it expects, and what data structures it returns.
To deploy the Web Service, select the Deploy Web Service menu option of the Web Services Library application. If you are on TPAE 7.5 choose Deploy to Product Web Service Container - Deploy Web Service. If you get a BMXAA7755E error follow this technote to fix it.
On successful deployment the "Is Deployed?" check box should be checked.

To retrieve the WSDL file you have two options:



Test the Web Service

Open soapUI and create a new project importing the WSDL files generated in the previous steps.


I started from QueryMXPERSON sample request, removing most of the optional elements. With the following request I was able to retrieve a PERSON record from Maximo.

<soapenv:Envelope
    xmlns:max="http://www.ibm.com/maximo"
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <max:QueryMXPERSON rsStart="0">
      <max:MXPERSONQuery operandMode="AND">
        <max:PERSON>
          <max:DISPLAYNAME operator="=">Tom Revis</max:DISPLAYNAME>
        </max:PERSON>
      </max:MXPERSONQuery>
    </max:QueryMXPERSON>
  </soapenv:Body>
</soapenv:Envelope>

This is the result in soapUI.


With a similar approach is possible to use the other interfaces to create, delete and update records in the Maximo database.


Authentication

If security is enabled you will get an 'Unauthorized error'. To solve this problem you must add the MAXAUTH HTTP header.
First of all you have to encode username and password to be sent. The MAXAUTH should be formatted like this [USERNAME]:[PASSWORD] and encoded in Base 64. Here is a free Base64 online encoder.
Now you can add the encoded string to the HTTP header. In the request page where you can see your XML request on the left and response on the right, click Headers tab under the window where you can see the XML request text. Then click Add a custom HTTP header icon, specify MAXAUTH as the header name, and the value should be the encoded string.


References

Labels: , , , ,