September 4, 2012

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:

  • On the local filesystem in the mxe.int.globadir directory
  • With the web browser at address http://[MXHOST]/meaweb/wsdl/[OSNAME].wsdl


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

44 comments:

  1. Thanks for the post Bruno.

    One question though, you wrote that in this example you create a WO using the MXPERSON OS, how do we do that?

    ReplyDelete
  2. Hi Bruno

    Do you have any example of how to create Web Service using an Enterprise Service?

    ReplyDelete
    Replies
    1. hi mr bruno

      Do you have any example of how to create Web Service using an Enterprise Service and standard service

      Delete
    2. Hi BRUNO, is the link still alive. I need to get information on standard and Enterprise service development and deployment.

      Delete
  3. Bruno, can you describe authentication process of soap services, I am using soap ui and every time I attempt to invoke the web service I get an Unauthorized error. I am not sure if the issue is related to soap ui or if there is an SCCD exception preventing authentication into the service.

    ReplyDelete
    Replies
    1. Using soapUI for a MAM75 WS and using the security as Bruno mentioned in his article
      http://maximotimes.com/maximo/secure-mif-web-service-methods-with-native-authentication/
      when I leave the soapUI XML as
      ".....
      < soapenv:Header / >
      ....."
      I receive the error msg
      "javax.ejb.EJBException: nested exception is: psdi.util.MXApplicationException: BMXAA1268E - No user credentials."
      while when I insert
      "
      < soapenv:Header >
      < maxauth >bWF4YWRtaW46TWF4aW1vMjAxMg==
      < /soapenv:Header >
      "
      where that value is username:pwd encoded base64, I receive the error msg
      "java.lang.NullPointerException".
      What I am doing wrong?
      thxx

      Delete
    2. Giacomo,
      we have this error too...
      Do you resolved this error?

      Delete
    3. Just in case someone will have this problem in future - the MAXAUTH header is not the XML header, it's the HTTP header of the message that wraps the XML content, so you can't insert it in the XML body. the SOAP UI provides you a way to add HTTP headers to the Web Service calls - 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 : encoded with base64. You can get a sample code from here, for example: http://www.motobit.com/util/base64-decoder-encoder.asp specify maxadmin:maxadmin (if your maxadmin's password is maxadmin)

      Delete
    4. Ups, content in brackets was removed in the prev message - ..."and the value should be user:password encoded with base64

      Delete
    5. Thank you Алексей.
      I have added your instructions to the article.

      Delete
    6. Hi Bruno, there is typo in the new section - it should be user:password, not the user.password (colon instead of dot)

      Delete
  4. Nice and concise. Thanks. For those who receive exceptions when trying to deploy the web service, refer to the following:
    http://www-01.ibm.com/support/docview.wss?uid=swg21566812

    ReplyDelete
  5. Hi Bruno, we are trying to Re deploy the WEB Service. when clicked on undeploy , we getting the following error.



    BMXAA4214E - An unknown error has occurred.
    Please contact your system administrator for assistance.

    ReplyDelete
    Replies
    1. Sorry I'm not IBM support.
      You should open a PMR.
      This is a good starting point: http://www14.software.ibm.com/webapp/set2/sas/f/handbook/contacts.html

      Delete
    2. Hi Rudra,
      This is related to port issue, check the systm properties for mea web and use the proper port to re-deploy the WebService.

      Delete
  6. Hi Bruno,

    When i'm trying to create a new project and browse the WSDL file and press OK,
    i'm getting an error:
    Unexpected element: CDATA

    How I can solve it?

    Plase assist.

    Thanks & Regards,
    Tamir

    ReplyDelete
    Replies
    1. Solved it.
      Instead of giving a WSDL file,
      I gave a url -
      http://maximo_server/meaweb/wsdl/mxperson.wsdl

      Note: Don't forget to change the "mxe.int.webappurl" value at
      System Configuration >> Platform >> System Properties
      At my system the value is -
      http:///neaweb

      Delete
    2. http://maximo_server/meaweb

      Delete
  7. Hi Bruno, Neet to integrate filenet with Maxmo for accessing url and attachements.

    Is there any workaround for integrating withought webservice as both are IBM Producs.

    Any help will be appreciated.

    ReplyDelete
    Replies
    1. https://www-304.ibm.com/software/brandcatalog/ismlibrary/details?catalog.label=1TW10MA2E

      Delete
    2. Hi Brunu the link is not working

      Delete
  8. Hi Bruno, is there any way to modify the 'Response' xml to include more fields when it is returned to the external system? e.g. include the assetid in the CreateMXASSETResponse xml

    ReplyDelete
    Replies
    1. Setting mxe.int.keyresponse=1 all the operations will include the key attributes of the updated objects
      See this for more details: http://www-01.ibm.com/support/docview.wss?uid=swg21648092

      Delete
    2. Hi Bruno,
      I need to add more attributes in in addition to KEY attributes, is it possible? if so please let me know the steps.

      Delete
  9. Hi Bruno, Thank you for the post. I have a quick question, once the MIF is secure, is there way to define which users can actually call the web service, similar to restricting which users can access a given app. I would like to fully lock down the web service.

    ReplyDelete
    Replies
    1. This is an interesting topic and I'm planning to write a WhitePaper on TPAE's security to describe this and other topics.
      Just as a starting point refer to this article: https://maximotimes.com/maximo/secure-mif-web-service-methods-with-native-authentication/

      Delete
    2. This comment has been removed by the author.

      Delete
  10. Hi Bruno, Using soapUI for a MAM75 WS and using the security as you mentioned in your article.
    http://maximotimes.com/maximo/secure-mif-web-service-methods-with-native-authentication/
    when I leave the soapUI XML as

    "





    John Keller






    I am receive the error message



    axis2ns1:Server
    java.util.NoSuchElementException

    org.apache.axis2.AxisFault
    at org.apache.axis2.AxisFault.makeFault(AxisFault.java:430)
    at psdi.iface.webservices.SoapFault.makeSoapFault(SoapFault.java:48)
    at psdi.iface.webservices.MOSWebService.processDocument(MOSWebService.java:170)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:60)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:37)
    at java.lang.reflect.Method.invoke(Method.java:611)
    at org.apache.axis2.receivers.RawXMLINOutMessageReceiver.invokeBusinessLogic(RawXMLINOutMessageReceiver.java:97)
    at org.apache.axis2.receivers.AbstractInOutSyncMessageReceiver.invokeBusinessLogic(AbstractInOutSyncMessageReceiver.java:42)
    at org.apache.axis2.receivers.AbstractMessageReceiver.receive(AbstractMessageReceiver.java:110)
    at org.apache.axis2.engine.AxisEngine.receive(AxisEngine.java:208)
    at org.apache.axis2.transport.http.HTTPTransportUtils.processHTTPPostRequest(HTTPTransportUtils.java:172)
    at org.apache.axis2.transport.http.AxisServlet.doPost(AxisServlet.java:145)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:595)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:668)
    at com.ibm.ws.webcontainer.servlet.ServletWrapper.service(ServletWrapper.java:1230)
    at com.ibm.ws.webcontainer.servlet.ServletWrapper.handleRequest(ServletWrapper.java:779)
    at com.ibm.ws.webcontainer.servlet.ServletWrapper.handleRequest(ServletWrapper.java:478)
    at com.ibm.ws.webcontainer.servlet.ServletWrapperImpl.handleRequest(ServletWrapperImpl.java:178)
    at com.ibm.ws.webcontainer.filter.WebAppFilterChain.invokeTarget(WebAppFilterChain.java:136)

    Do am I missing something here.

    Thank you,
    Ravi.

    ReplyDelete
  11. How to get success and error code and message in json using post method in maximo 7.5 rest api ?

    ReplyDelete
  12. The one that was mentioned by Алексей ЧеремисеновNovember 25, 2013 at 12:00 AM, is a setting in SOAPUI. How to do that in Maximo?

    ReplyDelete
  13. Hi Bruno,

    I've got a question regarding Webservices connecting to Maximo. Currently I have it set up so that SOAPui can connect properly and Add/AddChange/Delete records.

    I was wondering if there is a way to force Maximo to not commit the inputted data from the webservice, but to still check if the data is valid. Like the preview from the data import UI.


    I would just like to check that small samples of data are valid but without adding new records, then it can all be processed in one big data load.

    Regards,
    Mark

    ReplyDelete
  14. Hi Bruno,
    Will it be possible to contact you or get your recommendation for some remote services for our IBM systems ?

    ReplyDelete
  15. Hi Bruno,
    Will it be possible to contact you or get your recommendation for some remote services for our IBM systems ?

    ReplyDelete
  16. Hi Bruno,
    We use Maximo 7.6.How to get the exchange rate(currencycode,price) ​​from a web page with web service?We want to import the values ​​from a web page and automatically add them to the exchange table.
    Can you help me?

    ReplyDelete
  17. Hi Bruno,
    Has any function to list all OS availabe to use?

    ReplyDelete
  18. Also watch out for mxe.int.allowdefaultlogin system property. Even though ejb-jar.xml might have ALLOWDFLTLOGIN set to 1, the request might error out with BMXAA1268E -
    Cannot initiate the requested service because the application
    that is
    calling the service did not provide the required login
    credentials. if mxe.int.allowdefaultlogin is set to 0.

    ReplyDelete
  19. Hi, Please let me know how to pass the MAXAUTH authentication code using C# code by calling Maximo WebService which requires base64 encoding of username:password.

    ReplyDelete
  20. Very nice...thanks
    Very nice tutorial and nice blog about web services...thanks

    ReplyDelete
  21. Web India Market
    Web India Market offer a full-circle approach in responsive website designing and web development services. Our website designing services covers Strategic Planning, Business Intelligence, Creative Application Development, Digital Marketing, SEO services and e-commerce solutions

    ReplyDelete
  22. Wow, now this is what we call an information rich blog. You have definitely covered a lot of things on Best seo services lucknow. Keep it up!

    ReplyDelete