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.

    Interacting with an Object Structure Service through HTTP
    Share this post...

    20 thoughts on “Interacting with an Object Structure Service through HTTP

    1. Hello Bruno

      is it possible to configure the system in order to have an http authentication with a maximo user credentials to access object structure?

      Thanks

      Francesco

    2. I am trying to import data for jobplan and jobtask from csv file to maximo using MIF.
      I have created object structure and enterprise service which are required for import process, and everything is working fine in the following cases:
      – Changes apply on primary and child records if the primary object is existing and the child is existing

      – if the primary and child records does not exist, MIF add them successfully.

      but the following cases does not work:
      – if i need to add new task to existing JOBPLAN that is not allowd: error message:
      BMXAA0024E – The action ADD is not allowed on object JOBTASK. Verify the business rules for the object and define the appropriate action for the object.

      Please advise if there is any solutions

    3. The example for sending data to the object structure service using the firefox plugin HTTPRequester was great. Because we are having great problems to receive data from an external SAP system we need to simulate incoming data to the MEA SAP Adapter. How does the url has to look like for sending data to the "normal" MIF? http:///meaweb/os/MXVENDOR is for the the object structure service, how do we address the MIF e.g. http:///meaweb/????/MXVENDOR_FRSAP05

    4. Great article – thank you, however, regarding securing the HTTP Servlet. I believe I have followed the instructions in the Integration Guide and have edited the maximo\applications\maximo\meaweb\webmodule\WEB-INF\web.xml file as instructed but I am still able to POST to the servlet without authentication.

      Is there another step that needs to be done? Do I need to enable SSL? Do I need to rebuild and redeploy the application?

      Many thanks

    5. I am trying to use a script (either PERL or python, whichever I can get working) to automate creating incidents within Maximo (technically IBM Control Desk). However, nothing I send to the url http://:/meaweb/wsdl/EXTSYS1_MXINCIDENTInterface is being accepted. I either get Method Not Allowed, or I am getting Errno 97: Address family not supported by protocol. Is there some guide or document that covers how to construct the XML and send it to the appropriate interface. I can use the SOAP module in PERL or the SUDS module in python if the script needs to use the SOAP methods.

    6. Hi Bruno,

      first all of congratulations on the great blog.

      Do you have tip regarding WS Query when large amount of data are involved?

      I'm testing with soapUi and the problem i'm facing is the SocketTimeOutException that seems to be the result of the large amount of records that are to be devolved, in this case we're talking 16798 records.

      Please advice if you have any idea how to improve this.

      Thanks in advanced.

      Filipa Gonçalves

    7. Hi Bruno,
      If i make a HTTP Post to this MOS service, I am able to get the response as Bytes, which is the XML output. I need to convert this back to Maximo MboSet. How we can achieve this.
      I tried:-
      SAXBuilder builder = new SAXBuilder();
      Document document = builder.build(new ByteArrayInputStream(resoponse.getBytes()));
      StructureData irData= new StructureData(document);
      I am getting the irData Size as 0.

      Suggest some alternative.

    8. Very useful article!

      I have a quick question, I am looking to modify the Response of the Sync command to include some data from the object. How might I go about doing that?

    9. If you have the new field at the primary object level,
      – create an index with all the fields that you would like to have in your response (it can be only from primary object).
      – Use this index as an alternate key in your object structure.
      – generate and view the schema. You should now be able to see the new field in the response XML. Note: non-persistent fields cannot be included as you cannot index.

    10. Hi Bruno
      https://www.ibm.com/support/knowledgecenter/en/SSANHD_7.5.3/com.ibm.mif.doc/gp_intfrmwk/rest_api/c_rest_resources.html
      As mentioned in this topic, it is possible to add custom REST Resource handlers for custom processing. It says "You can extend handlers for custom processing. You can create handlers for other resource types, and for individual instances of business object resources or object structure resources".

      Our requirement is something similar. We are looking to add additional REST API by extending the resource handler. Have you come across such a development and is there any sample available. Thanks in advance!

    11. Hi Bruno,

      I have one requirement as when i query in SAOP on INCIDENT webservices i need to restrict the ticket with other customer values. How can we acheieve this.
      Please let me know if any solution is there

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    Scroll to top