IBM Maximo Web Services: shaping with XSLT

In this articles I’m showing you as to shape a IBM Maximo Web Services with Extensible Stylesheet Language Transformations ( XSLT) to adapt the IBM Maximo web-service interfaces with any interface exposed by web services.

As you know a IBM Maximo Web Service interaction is a combination of configuration entities in the Maximo Base Services environment that act in concert to achieve the following:

• prepare a request and pass request parameters to the web service
• invoke a web service from a chosen business application
• retrieve the results from the web service in the form of a response
• display the results in the context of the business application
• apply the result data into the application the web service was launcher

Follow these link to get a deeper introduction to Integration Framework and Web Services.

The Integration Framework includes powerful support to manage Extensible Stylesheet Language Transformations (XSLT) logic and add even more capability to your web services. You can use XSLT to shape incoming XML requests (the payload for Web services is XML) and outgoing results. The XSLT code allows you to create formatting structures that interpret and modify existing XML elements.

Usually when you have integrate two system you start from service specification by WSDL file. During this top down approach, you have to implement underlying code to match the specification. The XSLT support helps you map different data structure between two different system.

Honestly I do not like the Maximo’s interaction feature, a very frustrating issue I found was that the interactions applications do not support certain schema elements. Secondly some options are not very clear at first glance, in general I prefer to design the integration with a relatively high number of degrees of freedom.

So when Maximo acts as web services client my approach is:

• create custom integration object with the structure which will be the foundation of our integration.
• create custom end-point based on web service.
• create invocation channel based on: custom end-point, custom integration object, custom request XSL file and response XSL file.
• create action based on psdi.iface.action.InvokeCustomClass custom class and name equal to your invocation channel name.

This approach has two main advantages:

• The IBM Maximo Web Services is fired by custom action, as you know a custom action can be used in workflow, web user interface button and escalation. That means you have true flexibility for your applications.

• Using request XSLT and response XSLT you avoid to develop Java classes to adapt the different data structure. The XSLT files transform the outgoing Maximo data into external system’s format and vice versa.

For example to adapt my invocation channel XML ( InvokeMY_TICKET ) based on MY_TICKET integration object:

<?xml version="1.0" encoding="UTF-8"?>
<max:InvokeMY_TICKET xmlns:max="http://www.ibm.com/maximo" creationDateTime="2016-01-01T03:49:45" >
  <max:MY_TICKETSet>

  <max:CLASS>INCIDENT</max:CLASS>         
      <max:CHANGEDATE>...</max:CHANGEDATE>
      <max:CREATIONDATE>...</max:CREATIONDATE>                                                            
      <max:EXTERNALRECID>...</max:EXTERNALRECID>
      <max:REPORTEDPRIORITY>...</max:REPORTEDPRIORITY>
      <max:STATUS> </max:STATUS>    

......
                                                                    
      <max:TARGETFINISH>...</max:TARGETFINISH>
      <max:TARGETSTART>...</max:TARGETSTART>
      <max:TICKETID>...</max:TICKETID>
      <max:TICKETUID>...</max:TICKETUID>
  </max:INCIDENT>

  </max:MY_TICKETSet>
</max:InvokeMY_TICKET>

to external system’s XML (the payload for Web services is XML) :

      <urn:createTicket>
       
         <urn:TransactionDetails>       
            <urn:sourceSystem>...</urn:sourceSystem>
            <urn:destinationSystem>...</urn:destinationSystem>
            <urn:interactionDate>...</urn:interactionDate>
            <urn:businessId>...</urn:businessId>
         </urn:TransactionDetails>


         <urn:TroubleTicketDetails>
            <urn:sourceTicketId>...</urn:sourceTicketId>
            <urn:severity>...</urn:severity>
            <urn:workDate>...</urn:workDate>
            <urn:shortDescription>...</urn:shortDescription>
            <urn:description>...</urn:description>
         </urn:TroubleTicketDetails>

         <urn:CustomerDetails>
            <urn:cid>...</urn:cid>
            <urn:companyName>...</urn:companyName>
         </urn:CustomerDetails>

      </urn:createTicket>

I wrote the following XSL transformation:

request XSL file

?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:max="http://www.ibm.com/maximo" >

<xsl:template match="/">
<xsl:apply-templates select="max:InvokeMY_TICKET" />
</xsl:template>

<xsl:template match="max:InvokeMY_TICKET">
<urn:createTicket xmlns:urn="urn:CG_IN_TTMService" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<urn:TransactionDetails><xsl:text>
    <urn:sourceSystem>MAXIMO_MN</urn:sourceSystem>
    <urn:destinationSystem>REMEDY_EXT</urn:destinationSystem>
    <urn:interactionDate><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:CHANGEDATE"/></urn:interactionDate>
    <urn:businessId> <xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:BUSINESSID"/> </urn:businessId>
</urn:TransactionDetails>

<urn:TroubleTicketDetails>
    <urn:sourceTicketId><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:TICKETID"/> </urn:sourceTicketId>
    <urn:workDate><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:CHANGEDATE"/></urn:workDate>
    <urn:shortDescription><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:DESCRIPTION"/></urn:shortDescription>
    <urn:description><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:LONG_LONGDESCRIPTION"/></urn:description>
    <urn:severity><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:REPORTEDPRIORITY"/> </urn:severity>    
</urn:TroubleTicketDetails>

<urn:CustomerDetails>
    <urn:companyName><xsl:value-of select="max:MY_TICKETSet/max:INCIDENT/max:COMPANY"/> </urn:companyName>
</urn:CustomerDetails>

</urn:createTicket>
</xsl:template>
</xsl:stylesheet>

response XSL file

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:max="http://www.ibm.com/maximo" >

<xsl:template match="/">
<xsl:apply-templates select="urn:createTicketResponse" />
</xsl:template>

<xsl:template match="urn:createTicketResponse">

<max:InvokeMY_TICKETResponse xmlns:max="http://www.ibm.com/maximo" creationDateTime="2016-01-01T03:49:45">

<max:MY_TICKETSet action="Change" >  
 <max:INCIDENT><xsl:text>
        <max:CLASS>INCIDENT</max:CLASS>
        <max:RESULTCODE>  <xsl:value-of select="urn:ResponseData/urn:resultCode"/> </max:RESULTCODE>
        <max:RESULTMESSAGE>  <xsl:value-of select="urn:ResponseData/urn:resultMessage"/> </max:RESULTMESSAGE>
    <max:EXTERNALID>  <xsl:value-of select="urn:ResponseData/urn:TicketId"/> </max:EXTERNALRECID>
        <max:WORKDATE>  <xsl:value-of select="urn:ResponseData/urn:WorkDate"/> </max:WORKDATE>
        <max:ESTATUS>  <xsl:value-of select="urn:ResponseData/urn:status"/> </max:STATUS>
    <max:TICKETID>  <xsl:value-of select="urn:ResponseData/urn:sourceTicketId"/> </max:TICKETID>
    </max:INCIDENT>
</max:MY_TICKETSet>

</max:InvokeMY_TICKETResponse>
</xsl:template>
</xsl:stylesheet>

XSLT is very flexible, here are some advantage and disadvantage of using XSLT

Advantages:

• Avoiding to implement and to deploy Java code.
• Testing XSL transformation without to restart the Maximo server.
• Being template based, XSLT is more resilient to changes in documents.
• By separating data (XML integration object) from the presentation (XSLT), it is very easy to change the output format in any time easily.
• XML has self-documenting capability

Disadvantages:

• It is difficult to implement complicate business rules in XSLT
• Using XSLT have performance penalty in some cases

These simple steps can help in a majority of cases, what are yours ?

Your comments and suggestions are welcome.