Interacting with an Object Structure Service through HTTP

This entry is part of the Maximo Integration Framework series.

In this tutorial I will show how easy it is to query and update data in Maximo using the Integration Framework (MIF) Object Structure Services using a simple HTTP client.

HTTP test client setup
A great tool for creating sample test HTTP requests is a great Google Chrome add-on called Postman REST Client. I strongly suggest to add it to your Chrome browser. If you are a Firefox user then you may try HTTPRequester.

Querying People data
Login to Maximo, open Object Structures application under the Integration module and search for MXPERSON object.
In the Action menu select Generate Schema/View XML and select the Query operation in this dialog.

On the left side you can see a sample XML for querying people. On the right side there is a sample response.
Removing all the unnecessary elements and attributes from the request we get the following XML.

<max:QueryMXPERSON xmlns:max="http://www.ibm.com/maximo">
 <max:MXPERSONQuery>
 </max:MXPERSONQuery>
</max:QueryMXPERSON>

Now open Postman (or any other HTTP test client) and type into the address the following URL:

URL: http://[MAXIMOHOST]/meaweb/os/MXPERSON
Method: POST
Request type: Raw
Request: Paste the previous XML sample request

Where [MAXIMOHOST] is the hostname of your Maximo server.
This is how Postman client should look like.

Now click on 'Send' button and you will see all your people listed.
If you get an error try to look in the logs.

Simplify the Object Structure
In real integration scenarios you typically do not need all the attributes of an object. It also a good practice to remove unneeded attributes and child objects to improve performances.
First of all let's remove unnecessary child objects. Go to Integration - Object Structures application and search for MXPERSON object. Duplicate the Object Structure and call it MXSIMPLEPERSON. Remove the child objects PHONE, EMAIL, SMS and save it. Now you should have only one row in the 'Source Objects' table.
The next step is to remove unnecessary fields. Let's say we are only interested in the name of each person. Open the MXSIMPLEPERSON object and select 'Exclude/Include Fields' from the Action menu. Tick the Exclude checkbox on all the rows except the following:

FIRSTNAME
LASTNAME
PERSONID (primary key)

Save the MXSIMPLEPERSON Object Structure and open Postman the HTTP client. Change the Object name in the URL to MXSIMPLEPERSON and update the request as follows.

<max:QueryMXSIMPLEPERSON xmlns:max="http://www.ibm.com/maximo">
 <max:MXSIMPLEPERSONQuery>
 </max:MXSIMPLEPERSONQuery>
</max:QueryMXSIMPLEPERSON>

Now you have a much simpler response from the MXSIMPLEPERSON Object Structure Service.

Take you time and review carefully the information contained in the response XML.

Filtering output using a WHERE clause
If you want to retrieve a subset of the records you can specify an 'SQL where clause' in the WHERE element of the XML. The following example will list all the people with first name starting with the letter 'A'.

<max:QueryMXSIMPLEPERSON xmlns:max="http://www.ibm.com/maximo">
 <max:MXSIMPLEPERSONQuery>
  <max:WHERE>upper(FIRSTNAME) like 'A%'</max:WHERE>
 </max:MXSIMPLEPERSONQuery>
</max:QueryMXSIMPLEPERSON>

Filtering output using XML elements
The alternative approach is to specify the PERSON (or any other filter) in the XML like this. The following example will list all the people whose first name is 'Andrews'.

<max:QueryMXSIMPLEPERSON xmlns:max="http://www.ibm.com/maximo">
 <max:MXSIMPLEPERSONQuery>
  <max:PERSON>
   <max:FIRSTNAME operator="=">Andrew</max:FIRSTNAME>
  </max:PERSON>
 </max:MXSIMPLEPERSONQuery>
</max:QueryMXSIMPLEPERSON>

Create and update an object
The Sync operation allows to create or update an existing object. To see the structure of the XML, open the MXSIMPLEPERSON Object Structure open the Action menu and select Generate Schema/View XML and select the Sync operation.
Now let's see how to create a new person record. Paste the following HTTP request in your HTTP client.

<max:SyncMXSIMPLEPERSON xmlns:max="http://www.ibm.com/maximo">
  <max:MXSIMPLEPERSONSet>
    <PERSON>
      <PERSONID>TEST1</PERSONID>
      <FIRSTNAME>FFF</FIRSTNAME>
      <LASTNAME>LLL</LASTNAME>
    </PERSON>
  </max:MXSIMPLEPERSONSet>
</max:SyncMXSIMPLEPERSON>

The same Sync operation can also update records. If you change the first name in the previous XML and leave everything unchanged, the TEST1 person record will be updated.

<max:SyncMXSIMPLEPERSON xmlns:max="http://www.ibm.com/maximo">
  <max:MXSIMPLEPERSONSet>
    <PERSON>
      <PERSONID>TEST1</PERSONID>
      <FIRSTNAME>FFFnew</FIRSTNAME>
      <LASTNAME>LLL</LASTNAME>
    </PERSON>
  </max:MXSIMPLEPERSONSet>
</max:SyncMXSIMPLEPERSON>

Where do we go from here
We have covered few of the user scenarios that can be fulfilled with the Object Structure Services. For more information please refer to the Integration Guide.

Labels: beginner, http, integration, mif