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.
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
Download the Integration guide from here and search for 'Securing the HTTP Servlet'.
Here is the link: http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.mam.doc_7.1/pdf/mam71_integration_guide.pdf
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
hi i am just join in trainee for maximo asset management .how to learn maximo in easy way .can u help me……..
What are the services using in MIF?
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
Enterprise Service (synchronous)
http://[hostname]:[port]/meaweb/es/%5Bextsysname%5D/%5Bentservname%5D
Object Service (synchronous)
http://[hostname]:[port]/meaweb/os/%5Bobjservname%5D
Standard Service (synchronous)
http://[hostname]:[port]/meaweb/ss/%5Bstdservname%5D
Web Service
http://[hostname]:[port]/meaweb/services/%5Bwebservname%5D
Hi. Thanks for this. Due to restrictions, the only client I can use to test this is Fiddler2. When I post the query, I get a response of
4b
Error 500: nested exception is: java.lang.StringIndexOutOfBoundsException
0
The Technote at http://www-01.ibm.com/support/docview.wss?uid=swg21460182 suggests case-sensitivity but I cannot see where the problem lies for me. Any ideas anyone?
My total mistake. I had pasted the simpleperson query against the mxperson object!
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
When i used POST method i receive error as Method not allowed. Please help
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.
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
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.
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?
As far as I know you can only include object IDs in the respons enabling the mxe.int.keyresponse setting.
See here: http://www.ibm.com/support/docview.wss?uid=swg21414088
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.
Hou to get WORKLOGs of an INCIDENT using meaweb/os/mxincident ?
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!
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
The source of a web service can be an object structure service, a standard service, or an enterprise service.