Bruno Portaluri (MaximoDev)

IBM Maximo consultant, geek, agile evangelist

Maximo Web Services tutorial

Posted on Posted in MaximoTagged , , , ,

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

Maximo Web Services tutorial

47 thoughts on “Maximo Web Services tutorial”

  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?

    Reply

  5. 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.

    Reply

  6. 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

    Reply

  9. 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.

    Reply

  11. 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

    Reply

  14. 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.

    Reply

  18. 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)

    Reply

  20. 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.

    Reply

  24. 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

    Reply

  27. 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.

    Reply

  29. 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.

    Reply

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

    Reply

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

    Reply

  34. 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

    Reply

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

    Reply

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

    Reply

  37. 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?

    Reply

  39. 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.

    Reply

  40. 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.

    Reply

  43. Hi, I want to make a Service Request from SOAPUI and I am using the MXAPISR endpoint.
    I have seen that since the MXAPISR the Address data is not filled in and for the address I am using mxsrvad.
    Finally, to try to relate the Service Request to the Service Address, I have seen that there is / maximo / oslc / os / mxtksrvad, but I cannot join the data. Does anyone know how to do it?
    Thanks

    Reply

  44. Bruno,
    After upgrading from Maximo 7.6.0.8 to 7.6.1.1, I had an issue with my client code that performs a HTTP POST on an Object Structure.
    I had to change my code on the request header to use the following for 7.6.1.1:
    conn.setRequestProperty(“MAXAUTH”, encoding);
    instead of what I used in 7.6.0.8:
    conn.setRequestProperty(“Authorization”, “Basic ” + encoding);

    Have you run into this issue?

    Here is the error I received:

    [2/26/20 12:07:34:759 EST] 00002458 webapp E com.ibm.ws.webcontainer.webapp.WebApp logServletError SRVE0293E: [Servlet Error]-[MOSServiceServlet]: com.ibm.ws.webcontainer.webapp.WebAppErrorReport: BMXAA1268E – No user credentials.
    at com.ibm.ws.webcontainer.webapp.WebAppDispatcherContext.sendError(WebAppDispatcherContext.java:637)
    at com.ibm.ws.webcontainer.webapp.WebAppDispatcherContext.sendError(WebAppDispatcherContext.java:667)
    at com.ibm.ws.webcontainer.srt.SRTServletResponse.sendError(SRTServletResponse.java:1346)
    at psdi.iface.servlet.MOSServiceServlet.doPost(MOSServiceServlet.java:182)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:707)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:790)
    at com.ibm.ws.webcontainer.servlet.ServletWrapper.service(ServletWrapper.java:1235)
    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:143)
    at com.ibm.ws.webcontainer.filter.WebAppFilterChain.doFilter(WebAppFilterChain.java:96)
    at com.ibm.tivoli.maximo.filter.MTIntegrationFilter.doFilter(MTIntegrationFilter.java:66)
    at com.ibm.ws.webcontainer.filter.FilterInstanceWrapper.doFilter(FilterInstanceWrapper.java:197)
    at com.ibm.ws.webcontainer.filter.WebAppFilterChain.doFilter(WebAppFilterChain.java:90)
    at com.ibm.ws.webcontainer.filter.WebAppFilterManager.doFilter(WebAppFilterManager.java:969)
    at com.ibm.ws.webcontainer.filter.WebAppFilterManager.invokeFilters(WebAppFilterManager.java:1109)
    at com.ibm.ws.webcontainer.webapp.WebApp.handleRequest(WebApp.java:4217)
    at com.ibm.ws.webcontainer.webapp.WebAppImpl.handleRequest(WebAppImpl.java:2208)
    at com.ibm.ws.webcontainer.webapp.WebGroup.handleRequest(WebGroup.java:304)
    at com.ibm.ws.webcontainer.WebContainer.handleRequest(WebContainer.java:1030)
    at com.ibm.ws.webcontainer.WSWebContainer.handleRequest(WSWebContainer.java:1817)
    at com.ibm.ws.webcontainer.channel.WCChannelLink.ready(WCChannelLink.java:382)
    at com.ibm.ws.http.channel.inbound.impl.HttpInboundLink.handleDiscrimination(HttpInboundLink.java:465)
    at com.ibm.ws.http.channel.inbound.impl.HttpInboundLink.handleNewRequest(HttpInboundLink.java:532)
    at com.ibm.ws.http.channel.inbound.impl.HttpInboundLink.processRequest(HttpInboundLink.java:318)
    at com.ibm.ws.http.channel.inbound.impl.HttpInboundLink.ready(HttpInboundLink.java:289)
    at com.ibm.ws.tcp.channel.impl.NewConnectionInitialReadCallback.sendToDiscriminators(NewConnectionInitialReadCallback.java:214)
    at com.ibm.ws.tcp.channel.impl.NewConnectionInitialReadCallback.complete(NewConnectionInitialReadCallback.java:113)
    at com.ibm.ws.tcp.channel.impl.AioReadCompletionListener.futureCompleted(AioReadCompletionListener.java:175)
    at com.ibm.io.async.AbstractAsyncFuture.invokeCallback(AbstractAsyncFuture.java:217)
    at com.ibm.io.async.AsyncChannelFuture.fireCompletionActions(AsyncChannelFuture.java:161)
    at com.ibm.io.async.AsyncFuture.completed(AsyncFuture.java:138)
    at com.ibm.io.async.ResultHandler.complete(ResultHandler.java:204)
    at com.ibm.io.async.ResultHandler.runEventProcessingLoop(ResultHandler.java:775)
    at com.ibm.io.async.ResultHandler$2.run(ResultHandler.java:905)
    at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1909)

    Thanks,
    Doug

    Reply

  45. Has anyone answered whether it’s possible to edit the response of a call to a soap service, particularly to include additional attributes?
    I see the entry about setting mxe.int.keyresponse to 1, but what about attribute values other than key values?
    It is possible to have a query service available for a second call, following a Create or Sync, but having the initial response message suffice would be cleaner.

    Reply

Leave a Reply

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

Scroll to top