October 24, 2014

Use Long Description in a Communication Template

To add the long description to the message of an email sent through a communication template you have to perform a few configuration steps.

The example below is related to WORKORDER object but can be applied to any main object.

First of all you have to create a relationship in Database Configuration between the WORKORDER object and the LONGDESCRIPTION object.
Launch Database Configuration and select the WORKORDER object. Open the Relationship tab and create a relationship with the following properties.
  • Relationship: LONGDESCINFO
  • Child object: LONGDESCRIPTION
  • Where clause: ldkey=:WORKORDERID and ldownertable='WORKORDER' and ldownercol='DESCRIPTION'

Save the relationship. You shouldn't need to activate Admin Mode.

To include the long description in a communication template use the tag :LONGDESCINFO.LDTEXT

Note
If you want to apply this technique to other objects you have to verify which is the LDKEY field to be matched against the source table.
For the TICKET object the LDKEY matches the TICKETUID field so the correct where clause is different.

ldkey=:TICKETUID and ldownertable='TICKET' and ldownercol='DESCRIPTION'

October 6, 2014

Inbound Web Service processing using XSL transformation

The title of this article is quite scaring right?
Let's describe the scenario...

You have an external application that needs to query or update data in Maximo using a Web Service call. In the real world the outbound XML schema of the caller is different from the Maximo inbound interface.
How can you transform the incoming request to the standard Maximo Web Service interface?
This article describes how to use XSLT (EXtensible Stylesheet Language Transformation) to transform the inbound XML structure to a MIF-compliant one.

 This diagram describes what we need to achieve.


NOTE: Before starting complete the Maximo inbound Web Services tutorial to have a basic understanding of inbound Web Services in Maximo and setup the prerequisite configurations for this tutorial.


Setup test tool (SoapUI)

Testing the XSL Transformation in Maximo can be really tedious. You absolutely need a tool to test the XSLT code before putting it into Maximo.
There are many tools around. I suggest to use WmHelp XmlPad for Windows or XTrans.


Sample data

In this tutorial I will focus on a sample inbound request to create or update an asset into Maximo. This is the sample XML.

<Import>
  <Equipment>
    <Equipment>001</Equipment>
    <Description>My desc</Description>
  </Equipment>
</Import>

We want this incoming XML to be transformed to the following MIF WebService call.

<max:SyncMXD-ASSET>
  <max:MXASSETSet>
    <max:ASSET>
      <max:SITEID>BEDFORD</max:SITEID>
      <max:ASSETNUM>001</max:ASSETNUM>
      <max:DESCRIPTION>My desc</max:DESCRIPTION>
    </max:ASSET>
  </max:MXASSETSet>
</max:SyncMXD-ASSET>


Develop XSL Transformation

Now the interesting part...
XSLT is a powerful tool to transform XML structures. I think it is the best technical option to integrate two different systems using Web Services.

I use XMLPad to develop XSLT and test itbut you can use any other tool of your choice.
Now test the following XSL on the sample inbound XML and you will see the magic.

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

<xsl:output method="xml" encoding="UTF-8" indent="yes"/>

  <xsl:template match="Import">
  <xsl:apply-templates select="Equipment"/>
  </xsl:template>

  <xsl:template match="Equipment">
    <max:SyncMXD-ASSET>
    <max:MXASSETSet>
    <max:ASSET>
      <max:SITEID>BEDFORD</max:SITEID>
      <max:ASSETNUM><xsl:value-of select="Equipment"/></max:ASSETNUM>
      <max:DESCRIPTION><xsl:value-of select="Description"/></max:DESCRIPTION>
    </max:ASSET>
    </max:MXASSETSet>
    </max:SyncMXD-ASSET>
  </xsl:template>

</xsl:stylesheet>


Deploy XSL file

When everything is working fine in your local test tool you are ready to set the XSL transformation in the Web Service configuration.
There are two methods to provide the XSL file to Maximo: on the filesystem or in the maximo.ear file.

The first one is simpler. First of all you have to copy the XSL file on the Maximo server. For example D:\MIF\MXD-ASSETES.xsl.
Open the Web Services application (Go To > Integration > Web Services) and select the MXD-ASSETES service created in the first tutorial. Set the full path of the XSL file in the 'XSL Map' field.

If you have a cluster of application servers it may be convenient to store the XSD file in the EAR file. Copy the XSL file in a subdirectory of the businessobjects folder in the SMP dir. For example D:\IBM\SMP\maximo\applications\maximo\businessobjects\classes\maximodev\xsl.
After having rebuilt and redeployed the maximo.ear file you can reference the XSL file setting maximodev.xsl.MXD-ASSETES in the 'XSL Map' field (without the .xsl file extension).


Test the Web Service

Now launch SoapUI application and create a new project specifying the WSDL link in the 'Initial WSDL' field. Replace the entire content of the sample request with this (setting the correct SITEID).

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:max="http://www.ibm.com/maximo"> 

  <soapenv:Header/>
  <soapenv:Body>
    <Import>
      <Equipment>
        <Equipment>001</Equipment>
        <Description>My desc</Description>
      </Equipment>
    </Import>
  </soapenv:Body>
</soapenv:Envelope>

You can see that this is just the sample XML wrapped in a SOAP envelope.

References

Using XSLT to transform inbound transactions

October 3, 2014

Maximo inbound Web Services tutorial

Web Services are the most flexible and powerful technology to integrate Maximo with other systems.

In this article I will describe the steps required to configure an inbound Web Service to create or update assets.


Setup test tool (SoapUI)

To test the Web Service you need an application to simulate inbound HTTP calls.
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 client from here.


Maximo configuration

There are two important properties that need to be set before deploying a Web service in Maximo. Open the System Properties application (GoTo > System Configuration > Platform Configuration > System Properties) and check the following two properties.
  • mxe.int.globaldir: This property specifies the root folder where all the integration configuration files are located. If this value is null, the folders are created under the current working directory of the application server (for example: C:\IBM\WebSphere\AppServer\profiles\AppSrv01).
  • mxe.int.webappurl: This specifies the integration Web application URL. It is important to ste the hostname and port you use to connect to the Maximo UI.
  • mxe.int.containerdeploy: This setting determines where you will deploy the WebService (more details later)


Object Structure (MXD-ASSET)

The first element of the MIF chain is the Object Structure.
Open the Object Structures application (Go To > Integration > Object Structures) and create the following Object Structure:
  • Object Structure: MXD-ASSET
  • Description: Assets Object Structure (MaximoDev)
  • Consumed By: INTEGRATION
  • Source Object: ASSET




Enterprise Service (MXD-ASSETES)

The second element of the MIF chain is the Enterprise Service. Open the Enterprise Services application (Go To > Integration > Enterprise Services) and create the following entry:

  • Enterprise Service: MXD-ASSETES
  • Description: Assets Enterprise Service (MaximoDev)
  • Operation: Sync
  • Object Structure: MXD-ASSET
  • Adapter: MAXIMO 



External System (MXD-EXTSYS)

The third step is to define the External System.
Open the External Systems application (Go To > Integration > External Systems) and create the a  new entry:
  • System: MXD-EXTSYS
  • End Point: not set
  • Description: Sample External System (MaximoDev)
  • Enabled: Yes

Add the MXD-ASSETES Enterprise Service in the Enterprise Services tab, and enable it.



Deploy the Web Service

Now the Web Service can be deployed.
  1. Open the Web Services Library application (Integration > Enterprise Services) and select Create WebService > Create Web Service from Enterprise Service.
  2. Select the MXD-EXTSYS_MXD-ASSETES entry and click on the Create button.
  3. Open MXD-EXTSYS_MXD-ASSETES record and select Deploy to Product Web Service Container > Deploy Web Service.
  4. The following message will be displayed: BMXAA1277I - A web service is deployed for the MXD-EXTSYS_MXD-ASSETES service.

Test the Web Service

If the Web Service has been correctly deployed, the WSDL is downloadable from the server at the following address: http://[MAXIMOHOST]/meaweb/wsdl/MXD-EXTSYS_MXD-ASSETES.wsdl
Paste this link in a web browser to verify that it has been published correctly.

Now launch SoapUI application and create a new project specifying the WSDL link in the 'Initial WSDL' field.

Replace the entire content of the sample request with this (setting the correct SITEID).

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:max="http://www.ibm.com/maximo"> 

  <soapenv:Header/>
  <soapenv:Body>
  <max:SyncMXD-ASSET>
    <max:MXASSETSet>
      <max:ASSET>
        <max:SITEID>BEDFORD</max:SITEID>
        <max:ASSETNUM>001</max:ASSETNUM>
        <max:DESCRIPTION>My desc</max:DESCRIPTION>
      </max:ASSET>
    </max:MXASSETSet>
  </max:SyncMXD-ASSET>
  </soapenv:Body>
</soapenv:Envelope>

Now if you click on the small arrow on the upper left side of the request window you should receive a message back from the server. Fix any error until you get a success message and the asset is created on Maximo. This screenshot shows what you should see.



September 7, 2014

Remove legacy (Actuate) reports from Maximo


If you are upgrading from Maximo 5 or 6, to Maximo 7.1 or 7.5, you may want to remove legacy (Actuate) Maximo 5 or 6 reports.
The following SQL script deletes those obsolete report entries from the database.

delete from reportlookup
where reportlookup.reportnum in
(select reportnum from report
where runtype in ('ESPREADSHEET', 'QUERY', 'REPORT'))
or reportlookup.reportnum is null
or reportlookup.reportname is null;

delete from reportlabel
where reportname like '%.rox'
or reportname like '%.dox'
or reportname like '%.vts'
or reportname like '%.vtf';

delete from report
where reportname like '%.rox'
or reportname like '%.dox'
or reportname like '%.vts'
or reportname like '%.vtf';

Reference: Maximo Wiki - Deleting reports