November 27, 2014

Learn how to query data with SQL

Many times Maximo users and administrator lacks database skills. These are important in several situations:
  • Write 'where clause' statements to filter data in Maximo UI.
  • Develop complex SELECT statements to extract data from multiple tables when developing report.
  • Optimize existing queries to solve performance issues.

If you need to improve your SQL skills I suggest you to read few chapters of the SQL Getting Started guide of IBM DB2. This is not just for DB2, SQL syntax is quite similar across different database types.

The important chapters to read are:
  • Chapter 4. Using SQL Statements to Access Data
  • Chapter 6. Using Operators and Predicates in Queries
  • Chapter 7. Advanced SQL (Joins paragraph)

Does anybody have other good SQL tutorials to share?

November 12, 2014

Maximo Tranining presentations

Here are some nice presentations that I use during basic education sessions for new Maximo users.

I tried to use a pretty template and a common style across all of them.



Feedback is welcome!


November 6, 2014

Maximo is the leader Enterprise Asset Management Software

Gartner has recently published its Magic Quadrant for Energy and Utilities Enterprise Asset Management Software and guess what?
IBM Maximo Asset Management is positioned it the 'Magic' corner!


Read the full report here.

October 30, 2014

Preventive Maintenance (PM) automatic work order generation

You probably know that Preventive Maintenance module in Maximo allows to schedule periodical maintenance activities in order to keep your assets running efficiently.
In other words you can use the  Preventive Maintenance to schedule the automatic generation of work orders.

Work orders can be generated manually using the 'Generate Work Orders' action in the Preventive Maintenance application. A dialog will be displayed allowing to set the number of days in the future for which the work orders must be created.



The work order generation can be easily automated using the PMWoGenCronTask cron task.
Once the cron task schedule is set you can specify the PM generation rules for each site. Open the Organization application, pick your organization and select the 'PM Options' action from the menu.
The following dialog will be displayed allowing to set the generation option for each site.



Processing all the PM records each day to generate few work orders is not the best option. Almost all the processed records will generate a warning like this:
BMXAA3191E - PM XXXXX is not due yet, or it does not fall within the active season.

A good practice is to restrict as much as possible the PM records processed using the where clause. For example the following where clause selects only the active PM records that will generate a work order in the next month.

status='ACTIVE' and
nextdate - NVL(leadtime,0) - 30 <= SYSDATE

This is important to lower PM generation workload and to avoid a long list of warning messages in the logs.


References

Using Preventive Maintenance (PM) Records to Create Work Orders
Executing PM Wogen Crontask by Site

October 29, 2014

How to display a domain description in an application

Some fields in Maximo are linked to a domain that allows to set its value from a predefined set of values. In some cases however, when the value does not provide enough information, you may wish to also display the description of the domain value that you have chosen.

For example lets consider the STATUS field of the WORKORDER object.
By default Maximo will not show the description associated to the work order status.




Here is how to display the work order status description in the Work Order Tracking application.


Create a relationship to the domain table

Identify the domain name. Open Database Configuration application and look at what domain is set for the specific attribute you are looking for.
For the WORKORDER.STATUS attribute the domain is WOSTATUS.
Now open the WOSTATUS domain and take note of where the description is stored (press Alt+F1).



Now you must define a relationship from the WORKORDER table to the WOSTATUS domain. In our example it is located in SYNONYMDOMAIN table. In other situation the domain table can be ALNDOMAIN or NUMERICDOMAIN.
Open Database Configuration application and define the following relationship for the WORKORDER object:
  • Relationship: WOSTATUSDESC
  • Child Object: SYNONYMDOMAIN 
  • Where Clause: value=:STATUS and domainid='WOSTATUS'

Save and apply configuration changes if needed.


Display the description in the application

Now you must use Application Designer to add a new multipart textbox to your screen to display the domain description close to the field value.

In our example, open the WOTRACK application add a new 'Multipart Textbox' close to the 'Status' field. Set the following properties:
  • Attribute: STATUS
  • Attribute for Part 2: WOSTATUSDESC.DESCRIPTION
  • Input Mode for Part 2: Readonly
  • Copy other properties from the old field if needed



Test the modified application and delete the old field when the the new one is working fine.



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

September 4, 2014

MxLoader 4.1 has been released !

Hi all,
I have just released MxLoader version 4.1 on developerWorks.

These are the new features:
  • Rewritten XML/TABLE conversion algorithm to support unlimited levels of nested objects
  • Many MxSheet templates added with object's primary key fields underlined in header row
  • Object count limit now works also for sync action
  • For sync operation it is possible to specify the action (Add, Delete, Update, Change, Replace, AddChange)
  • New button to quickly create custom MxLoader Object Structures
  • MxLoader.xlsm file size reduced from 4 MB to 0.5 MB
  • Comments support in MxSheet templates
  • Removed text formatting for text fields because it was messing Excel formula automatic calculation
  • Performance optimization in attribute lookup algorithm (GetAttrType)

Feel free to download it and it everyday.
For questions and support please use this forum.

June 20, 2014

Invoke an Action when a button is pressed

In this article I explain how to attach/associate an action to a push button in an application.

  1. Create the Action you have to call if not already done (Go To - System Configuration - Platform Configuration - Actions).
  2. Open your application with the Application Designer and create a Signature Option with the same name of the Action you want to call (Actions - Add/Modify Signature Options - New Row).
  3. Expand the 'Advanced Signature Options' section and set 'This is an action that must be invoked by user in the UI'.
  4. Create a Push Button on the application with the following settings
    1. Event: enter the action name
    2. Signature Option: READ 
  5.  Grant the Signature Option to appropriate users in Security Groups.

June 10, 2014

Attachments (DOCLINKS) Configuration

This procedure describes how to set up attached documents in Maximo 7.1 and above with IBM WebSphere Application Server.

In this procedure I will use [IHSDIR] and [DOCLINKSDIR] tags to identify IBM HTTP Server and attachments home directory respectively. Replace those tags according to your environment. Here are the default values.

Windows
  • [IHSDIR] - C:\Program Files\IBM\HTTPServer
  • [DOCLINKSDIR] - C:\doclinks

UNIX
  • [IHSDIR] -  /home/IBMHTTPD
  • [DOCLINKSDIR] - /home/doclinks


Attachment repository

First of all you have to create the create the [DOCLINKSDIR] directory to store your attachments. For example: C:\doclinks for Windows or /home/doclinks for UNIX.

This directory must be accessible from both the application servers and from the web servers. If you have a simple environment running on a single system you are done. Otherwise you have to share this directory and mount it on all the involved servers. This article describes several techniques to configure such environment on Windows systems.



IBM HTTP Server configuration

The second step is to publish the [DOCLINKSDIR] directory through the HTTP Server. This will allow to retrieve the attachments stored in it from the users web browser.
  1. Locate the configuration directory of the IBM HTTP Server . For example C:\Program Files\IBM\HTTPServer\conf for Windows and /home/IBMHTTPD/conf for UNIX
  2. Backup httpd.conf file
  3. Open the httpd.conf file with a text editor
  4. Find 'DocumentRoot' and change like below
    DocumentRoot "[DOCLINKSDIR]"
  5. Find '# This should be changed to whatever you set DocumentRoot to.' and change like below
    <Directory "[DOCLINKSDIR]">
  6. Save and close httpd.conf file
  7. Restart the HTTP Server
  8. Verify that the HTTP Server is configured correctly
    1. Create a test file text.txt into [DOCLINKSDIR] directory
    2. Open a web browser and type in address: http://[MXHOSTNAME]/test.txt where [MXHOSTNAME] is the hostname of your server
    3. You should be able see your test.txt document in this window. If you cannot open the test file, you must go back and check the configuration steps.


Maximo configuration


The last step is to configure where Maximo will store the attachments and how it will retrieve them.
  1. Login to Maximo with administrative rights
  2. Go To - System Configuration - Platform Configuration - System Properties
  3. Set the following properties according to your configuration
    mxe.doclink.doctypes.defpath = [DOCLINKSDIR]
    mxe.doclink.path01 = [DOCLINKSDIR] = http://[MXHOSTNAME]

    Note: These paths in Windows and Unix are case sensistive.
  4. Reload the properties with a ‘Live Refresh’ or restart application server
The mxe.doclink.doctypes.defpath defines where Maximo is storing the attachments locally. The mxe.doclink.path01 allows to translate local paths to the correct HTTP links.

Go To any application which has attachments and select Action > Attachment Library/Folders > Manage folders. Set or check the following:
  • Attachments: [DOCLINKSDIR]\attachments
  • CAD: [DOCLINKSDIR]\cad
  • Diagrams: [DOCLINKSDIR]\diagrams
  • Images: [DOCLINKSDIR]\images
Note these Default file paths are case-sensitive and must match the case of directory structure and that of the doclink.properties file.

Finally test that everything is working fine.


References


June 9, 2014

Maximo applets and Java security

Java 6 and 7 have introduced new security features that may create some problems in Maximo/SCCD/TPAE applications that make use of Java applets. Some examples of such applications are Configuration Items, Workflow Designer and Scheduler.

First of all Start Menu > Java> Configure Java > Security > Add the server host to the trusted sites


This should be enough to fix Java related issues.

Maximo Scheduler may require an additional configuration to solve the ilogViewerApplet.initProjectDataModel error.


Edit java.policy configuration file (typically located in C:\Program Files (x86)\Java\jre7\lib\security\java.policy) and add the following lines.

grant { 
    permission java.util.PropertyPermission "user.timezone", "write"; 
};

Restart the browser and Java processes and verify everything is working fine.

May 31, 2014

Automatically rotate and clean HTTP Server log files

By default IBM HTTP Server log files always grow. This may be a problem especially on production servers where there is a large amount of HTTP requests that can quickly generate a very big access.log file. This file cannot be deleted without stopping the HTTP Server and can be practically impossible to open with a text editor.

A quick solution for this is to use the rotatelogs utility located in [HTTPHOME]/bin directory.

Open the [HTTPHOME]/bin/httpd.conf file and search for 'CustomLog' directive for access.log file. Comment this line and insert a new directive like this:
    CustomLog "|bin/rotatelogs.exe -l logs/access.%Y%m%d-%H%M%S.log 5M" common

Here is how the httpd.conf file should look like.

#CustomLog logs/access.log common
CustomLog "|bin/rotatelogs.exe -l logs/access.%Y%m%d-%H%M%S.log 5M" common

With this method a new access.log file will be generated when its size reached 5 megabytes.
More information on the rotatelog command is available here.


If you want to periodically clean the HTTP Server log files you can use the technique described hereafter.

Go to IBM HTTP Server log directory. In this example it is D:\Program Files\IBM\HTTPServer\logs.
Create an empty text file cleanlogs.cmd and paste the following code into it.

@echo off

net stop "IBM HTTP Server 6.1"
net stop "IBM HTTP Administration 6.1"

echo Waiting few seconds
ping -n 4 localhost > nul

echo Deleting log files
del /Q "%~dp0"\*log

echo.

net start "IBM HTTP Server 6.1"
net start "IBM HTTP Administration 6.1"

Test the script by manually launching it. When everything works fine you can schedule this script using Windows Task Scheduler to purge the log files each night or each Sunday.

May 23, 2014

Mount shared DOCLINKS folder on Windows

A typical configuration step when building a Maximo cluster on Windows systems is to mount a shared filesystem on all the physical systems that belongs to the cluster. This allows to store attachments in a single place in order to be able to access them from all the servers that builds up the cluster.
It is also important to adopt an approach that automatically remounts the network share in case of system restarts.

This article describes the steps required to mount a shared filesystem on Windows 2008 Server.
  1. Launch Windows Task Scheduler
  2. Create a folder named 'IBM'
  3. Create a Basic Task
    • Name: Mount DOCLINKS folder
    • Trigger: When the computer starts
    • Program: net
    • Arguments: use X: \\[SHAREDFOLDER] /persistent:YES
  4. Double click on the task to open its properties
  5. Click on 'Change User or Group' button
  6. Type 'SYSTEM' and press OK
Running this task with SYSTEM privileges will make the mounted drive accessible from all users including the WebSphere processes.


Providing network credentials

If the net use command fails asking for credentials you can use the following syntax to provide them.

net use X: \\[SHAREDFOLDER] /persistent:YES [PASSWORD] /USER:[USERNAME]


Symbolic link technique

Drew Hohnstein has proposed to use the mklink command to create a symbolic link to the network folder.
A command like this should do the trick.

mklink /D C:\doclinks \\[SHAREDFOLDER]


UNC technique

If you can avoid to secure the shared folder you may also try this simple technique: Configure the doclink attachment folder in UNC path


May 22, 2014

Securing Maximo with SSL/HTTPS

Maximo installation configures by default HTTP unencrypted communication. This basic configuration may represent a security exposure especially when the server is reachable from the public internet.

This article describes all the steps needed to enable HTTPS (SSL) communications for Maximo.
It comprises the following main steps.
  1. Creation of a self-signed certificate
  2. IBM HTTP Server configuration
  3. WebSphere configuration
  4. Adjust DocLinks settings

Create a self-signed certificate

Run IBM Key Management utility - Start > Programs > IBM HTTP Server > Start Key Management Utility.
Click Create a new key database file button.


Leave default values and click OK. Take note of the key.kdb file path.



Enter a password and select Stash password to a file option. Click OK.



Click New Self-Signed... button.


Enter MX_SSL_KEY for Key Label and leave default for other fields. Click OK to create a self-signed certificate.


Select Key Database File > Stash Password and close IBM Key Management utility.





Web server configuration


Backup C:\Program Files\IBM\HTTPServer\conf\httpd.conf file and open it with text editor.

If you want to disable HTTP you have to remove or comment out the following line.

Listen 0.0.0.0:80


To enable HTTPS on the default port 443 paste the following rows.

LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
Listen 0.0.0.0:443
<VirtualHost *:443>
 SSLEnable
</VirtualHost>
KeyFile "C:\IBM\HTTPServer\key.kdb"

Verify the path of the key.kdb file matches with the one you have generated before.

Restart IBM HTTP Server by following sequence.
  1. Stop Admin Server
  2. Stop HTTP Server
  3. Start Admin Server
  4. Start HTTP Server


WebSphere configuration

Login to WebSphere ISC console and navigate down to Environment > Virtual Hosts > maximo_host > Host Aliases.
Verify that port 443 is present. Add it if missing. You may also wish to remove port 80 and other unused ports.

Navigate to Servers > Server Types > Web servers. Select webserver1 and click Generate Plug-in. Select webserver1 again and click Propagate Plug-in.
Continue from ISC console, restart MXServer in Servers > Server Types > WebSphere application servers.

Verify the connection by logging in at https://[MXHOST]/maximo, where [MXHOST] is the host name of the HTTP server. Now your server is running in SSL.


Adjust DocLinks settings

The last step is to change the URL generated by Maximo to display attachments.
Login as maxadmin and modify the mxe.doclink.path01 System Property to replace http:// with https://
Do a Live Refresh of this property and test by downloading an attachment.


References

Enabling SSL in IBM SmartCloud Control Desk
Guide to properly setting up SSL within the IBM HTTP Server
Enable HTTPS in WebSphere for Maximo, SCCD, TSRM, and Tririga

May 16, 2014

MxLoader has been released !

I am proud to announce the release of MxLoader on developerWorks. This is a great tool I have developed to help me in my day-to-day job as a Maximo specialist.

MxLoader is a Microsoft Excel spreadsheet that allows to quickly and easily query and load data into IBM Maximo, IBM SmartCloud Control Desk (SCCD) and other TPAE based applications. It brings together the power of the Maximo Integration Framework and the flexibility of Excel allowing to quickly manipulate and import data into any Maximo database.

Look at this short video for a quick overview of the tool.




Refer to MxLoader community on developerWorks to download the latest version of the tool. Subscribing to the community you will be able to write on the support forum and be notified when a new version is available.

May 15, 2014

Educational videos

Yes these are very busy days for me and probably for you all. But don't worry I will start publishing new articles soon.
In the meanwhile you can enjoy watching those two videos from my fellow colleague Andreas.

Jobplan demo (3:03 min)
Offerings/pricebook demo (2:32 min)

April 8, 2014

ClassCast exception when launching BIRT reports

Recently I went through a problem running BIRT reports from Maximo. Every time I launch a BIRT report I got a java.lang.ClassCastException exception like this.

java.lang.ClassCastException: org.apache.xerces.parsers.XIncludeAwareParserConfiguration incompatible with org.apache.xerces.xni.parser.XMLParserConfiguration

My colleague Daniel Hlawatsch found the solution based on two similar IBM TechNotes:

New Xerces library was introduced in CCMDB 7.1.1.5
Error connecting to WebServices

To solve the problem you just have to delete org.apache.xerces_2.9.0.v200805270400.jar file (backup this first) from the application server deployed application tree: maximouiweb.war\WEB-INF\birt\platform\plugins

Restart the application server and test BIRT reports.
If the problem is solved you also should eradicate the problem deleting the same file from the SMP directory: [SMPDIR]\maximo\maximouiweb\webmodule\WEB-INF\birt\platform\plugins

April 5, 2014

Change Maximo base web address

In some cases you need to be able to web address of Maximo to identify between different environments or systems. For example for the test system you want to change the base URL from the default address:
  • http://mxhost/maximo/
to:
  • http://mxhost/maximotest/

In WebSphere application server this part of the web address is called 'context root'. It can be changed using WebSphere admin console under Applications > Enterprise Applications > MAXIMO > Context Root For Web Modules.


You can change this setting from WAS console but every time you will redeploy maximo.ear file it will be reset to the default value. To automate this procedure you can set the correct value in the following files.

  • [SMPDIR]\maximo\applications\maximo\META-INF\application.xml
  • [SMPDIR]\maximo\applications\maximo\META-INF\deployment-application.xml

Rebuild and deploy the maximo EAR file and check that everything is working fine.

March 12, 2014

Read system property in a Java class

This entry is part of the Maximo Java Development series.

Here is a small piece of Java code that can be used to retrieve a system property in Java.

Properties configData = MXServer.getMXServer().getConfig();
String prop = configData.getProperty("mxe.adminEmail");

Replace mxe.adminEmail with your property.

February 26, 2014

Multiple Maximo 7.1 installations on the same administrative workstation

As you may already know IBM Maximo 7.1 does not fully support the installation of multiple environments on a single Administrative Workstation. This is partially true since IBM has developed a procedure based on the use of non-administrative system users (see TechNote 21421640). However, I find this as an overly complex technique so I have developed my own personal approach to this problem.

Note: This is an unsupported procedure. Use at your own risk. It is a quite complex procedure but is very effective in the real world.


Background Information

The installation of Maximo on a Windows system will basically create two components:
  • Deployment Engine: The IBM Autonomic Deployment Engine (DE) manages the installation of Maximo. It is typically located in C:\Program Files\IBM\Common\acsi. For more details refer to this video or this PDF.
  • TPAE: Maximo, SCCD and other TPAE-based products are installed in a specific directory that is typically named SMP (I usually install Maximo under D:\IBM\SMP) This contains all the scripts, Java classes and other stuff needed to manage the application and create the maximo.ear file that is deployed on the application server.

The technique described in this article consists in having a backup of those two directories to have the possibility of switching from one environment to another.

The backup is best performed with the robocopy command that is available on recent Windows systems. For Windows XP or Windows 2003 you can download it from here. It has great advantages over xcopy in terms of performances and reliability.


Installation Scenario

To demonstrate the technique I will walk through all the steps needed to install development, test and production environment from a single Admin Workstation. The example assumes you are working in D:\IBM directory.
  1. Install development environment - Launch the Maximo installer and install the development environment in D:\IBM\SMP
  2. Create environment identifiers files
    1. Create an empty file named DEV.txt in the SMP directory: D:\IBM\SMP
    2. Create an empty file named DEV.txt in the DE directory: C:\Program Files\IBM\Common\acsi
  3. Backup installation folders
    1. Copy the whole C:\Program Files\IBM\Common\acsi directory into a new directory C:\Program Files\IBM\Common\acsi_DEV
    2. Copy the whole D:\IBM\SMP directory into a new directory D:\IBM\SMP_DEV
  4. Tweak installation parameters - Update the following files to match the test environment configuration:
    1. D:\IBM\SMP\etc\install.properties
    2. D:\IBM\SMP\maximo\applications\maximo\properties\maximo.properties
  5. Install test environment - Do not launch the installer but clone the development environment
    1. Clone the development database into an empty test database
    2. Build maximo.EAR file and deploy it on the test application server
  6. Create environment identifiers files - Create two empty files named TEST.txt as described in step 2.
  7. Backup installation folder - Backup folder in XXX_TEST folders as described in step 3.
  8. Tweak installation parameters - See step 4.
  9. Install production environment - See step 5.
  10. Create environment identifiers files - Create two empty files named PROD.txt as described in step 2.
  11. Backup installation folder - Backup folder in XXX_PROD folders as described in step 3.

At the end of the process you will have the three environments up and running with a directory structure like this.
  • D:\IBM
    • SMP
    • SMP_DEV
    • SMP_PROD
    • SMP_TEST
Check that you have the correct DEV.txt, TEST.txt and PROD.txt files in each SMP_XXX directory Ensure you have PROD.txt file in the SMP main dir. This allows to identify which environment is currently active.

How to switch environments

Download the SmpSetEnv.cmd script and copy it in D:\IBM dir.
If you double click on the script the following prompt will appear.



The script allows you to switch from one environment to a new one. It will basically perform the following actions:
  1. Display the current active environment in D:\IBM\SMP
  2. Let you choose which environment to activate
  3. Backup D:\IBM\SMP into the appropriate D:\IBM\SMP_XXX directory
  4. Restore the appropriate D:\IBM\SMP_XXX into D:\IBM\SMP
  5. Stop the DE daemon
  6. Backup C:\Program Files\IBM\Common\acsi into the appropriate C:\Program Files\IBM\Common\acsi_XXX directory
  7. Restore the appropriate C:\Program Files\IBM\Common\acsi_XXX into C:\Program Files\IBM\Common\acsi


Remember! Always work in the main SMP directory. The SMP_XXX directories are only used as backups.

February 13, 2014

Windows Server firewall rules for Maximo/SCCD installation

Windows 2008 Server default firewall rules are very restrictive.
When installing Maximo or SmartCloud Control Desk on a remote WebSphere installed on a Windows 2008/20012 Server system you may hit some connectivity errors between the Maximo Administrative Workstation and the application server.

I have found out you have to open the following ports/protocols:
  1. Ping: this is used by the Deplyment Engine to check hostnames and availability or remote systems
  2. WebSphere SOAP (8879): Used to administer WAS remotely.
  3. HTTP/HTTPS (80/443): The HTTP Server
  4. WebSphere Administrative Console (9043): Needed to deploy MAXIMO.ear file

These are the commands that I have used to set the firewall rules.

netsh firewall set icmpsetting 8
netsh advfirewall firewall add rule name="WebSphere SOAP" dir=in action=allow protocol=TCP localport=8879
netsh advfirewall firewall add rule name="HTTP " dir=in action=allow protocol=TCP localport=80
netsh advfirewall firewall add rule name="HTTPS" dir=in action=allow protocol=TCP localport=443
netsh advfirewall firewall add rule name="WAS Administrative Console (secure)" dir=in action=allow protocol=TCP localport=9043


These commands must be ran from a command line with administration privileges. To do this right click on the Command Prompt shortcut and select Run as Administrator.

Depending on your environment you may need to open additional ports. Here is the complete list of WebSphere ports.

On the database server you need to open the ping and JDBC ports.
  • DB2: 50000
  • Oracle: 1521
  • SQL Server: 1433

January 17, 2014

Screen recorder

Today my fellow colleague Andreas Dietrich has discovered a nice little utility that is shipped with Windows 7 which I think can help you guys in several ways.
The Windows 7 "Problem Step Recorder" can be used for example to document installations or to provide as best practise for ticket documentation.
This little utility (psr.exe) should be available on every Windows 7 installation and can be launched by typing "psr" on the Windows search


When started it appears as a nice little toolbar like this.


After you have finished recording, it saves a zip file containing a MHT file that can be opened with a web browser.
The output contains:
  1. A step by step recording of what you have done and clicked including screenshots.
  2. Additonal comments that you entered while recording
It is not a video but more a step-by-step series of pictures and comments.

January 13, 2014

Migrating a Maximo server

Checkout this great series of articles by Richard Lesses describing a step by step guide of the migration of his Maximo development environment.

Part 1
Part 2
Part 3
Part 4

January 10, 2014

How to launch Workflow

Today I want to show you all the possible ways (as far as I know) of starting a workflow in Maximo.


Interactive initiate

This is the most basic way of automatically start a workflow when an object is created through the user interface. This technique will not work for objects created by MIF, workflows or escalations.
To enable workflow auto-initiate open your workflow in Workflow Designer and select the Interactive Initiate checkbox.


Escalation

Another way of activating a workflow is through an escalation.


Go to the Actions application and create a new action like this:
  • Action: STARTWF
  • Description: Start TESTWF workflow
  • Object: WORKORDER
  • Type: APPACTION
  • Value: WFINITIATE
  • Parameter/Attribute:  TESTWF
  • Accessible from: ESCALATION

Now setup an escalation to trigger the STARTWF action:
  • Escalation: STARTWF
  • Applies to: WORKORDER
  • Condition:
  • Schedule: 5m,*,*,*,*,*,*,*,*,* (every 5 minutes)
  • Escalation Points
    • Escalation Point: 1
    • Repeat: false
    • Leave other fields empty
  • Actions
    • Action: STARTWF
Don't forget to activate the escalation.


Application Toolbar Button, Action Menu or pushbutton

If you wand to let the user manually trigger a workflow from an application you have several options.
Typically this is done creating a new button on the toolbar but you can also create a new action in the menu or add a pushbutton to the application itself.

Open your application in the Application Designer.
Add the control to which you want to attach the workfow start
Set the control properties as follows:
  • mxevent: ROUTEWF
  • value: [MYWF]

Obviously you have to replace [MYWF] with the name of your workflow.


Java

There are two useful methods that can be used to start and stop a workflow on an MBO. Both are located into psdi.workflow.WFInstance class.

initiateWorkflow(String memo, WFProcess wfProcess)
stopWorkflow(String memo)

This article has a nice example of it.

Another option is to use psdi.workflow.WorkFlowService class. The initiateWorkflow(String processName, MboRemote target) allows to easily start a workflow on a specific MBO.
The Java code should be something like this

MXServer mx = MXServer.getMXServer();
WorkFlowServiceRemote wfsr = (WorkFlowServiceRemote)mx.lookup("WORKFLOW");

MBORemote mbo = (MBORemote)getMbo();
wfsr.initiateWorkFlow("[MYWF]", mbo);


Script

Similarly to Java it is possible to use the above methods to start a workflow using TPAE scripting.

from psdi.server import MXServer
MXServer.getMXServer().lookup("WORKFLOW").initiateWorkflow("[MYWF]",mbo);


Integration Framework

In this IBM TechNote is described a new feature introduced in TPAE 7.1.1.6 to start a workflow with an HTTP call to MIF.
There is also another TechNote about this.

A more general approach would be to add a custom YORN field named STARTWF and set it to 1 through MIF. An escalation can then start the workflow for all the objects that has STARTWF=1 and then reset the STARTWF flag to 0.


REST

A REST call can also be used. An example URI is the following:

POST /maxrest/rest/mbo/po/6789?wfname=MYWF HTTP/1.1 x-http-method-override: "initiateWorkflow"

Replace PO with your MBO name, 6789 with the ID of the new record and MYWF with your workflow name.