IBM Maximo Customization and Development

Migrate Maximo configurations with MxLoader

2019-08-22T21:43:00.002+02:00

Have you ever struggled migrating configurations from Development to Test environment and then to Production?
If the answer is yes, you are not alone. I think this is the one of the most common issues when managing multiple environments in medium-large Maximo projects.

Keeping several Maximo environments in synch while ensuring a fast release cycle required in today's projects is challenging and typically involves two flows.

The first flow of configuration changes is the classical release flow. You have to release configurations from Development to Production through all the intermediate environments and entails the build of some sort of 'configuration package' that is deployed on each environment.
However, in the real world, all those environment will loose sync after some time so we need to realign back through the chain using a database cloning procedure (backup and restore). This is a well known practice to rebuild a development environment ensuring all

In my experience I have seen a lot of different approaches to build 'configuration packages'.

The simplest form of package is brain memory. This is the simplest form of package. It is applicable only when there is only one Maximo administrator/developer but is very unreliable and there is no change log of what has been released.
The second type of package is a text file with precise instructions of what configuration must be applied. This is the minimum level that I personally adopt on small projects involving up to 2-3 environments and 1-3 administrators/developers. The file can be prepared by the developer and passed to the system administrator (together with automation scripts, application XMLs and other configuration files) to be deployed. Such packages can be stored on a shared folder for tracking purposes or versioned on a CVS/SVN repo.
Instead of having unstructured text files, some teams tries to define a standard template for documenting configurations. These are typically Excel spreadsheets. I do not personally use this approach because it is quite compelling to find a set of templates to cover all possible kind of configurations and there is no great advantage over the text-file approach.
The official approach is to use the IBM Migration Manager. I have seldom used this approach and is perfect for large environments and big teams. The biggest problem of this tool is that it is not really easy to understand what configurations are stored in the package since it actually is a zip file containing large XML files.

I have recently developed my own approach based on MxLoader to overcome limitations of the approach 4 thus providing a more reliable process than approach 2.

In MxLoader 6.1 I have released a set of Object Structures and templates specifically developed for migrating configurations: Conditional Expressions, Reports, Object Data Restriction, Attribute Data Restriction, Domains, Database Objects/Attributes/Relationships/Indexes, Automation Scripts, Application Signature Options, Security Group Authorizations, Actions, Roles, Escalations, Workflows, Communication Templates,etc.

I typically use the templates with the 'Query' action to extract the configuration from the development environment. I incrementally build the appropriate where clause in cell D1 to extract the minimum set of records. When I have finished building the package, I switch to the integration environment in the Config sheet and use the 'Sync-AddChange' action to apply the configurations.

The main advantage of this approach is that it is really easy to see what configurations are in the package and what changes are actually applied to the production environment.

I encourage you to download MxLoader and give it a try. I will do my best to publish some tutorials in the next future about migrating configurations using such great tool.

The hidden features of Work Logs

2019-08-09T19:09:00.000+02:00

Work Logs are a very useful feature in Maximo and Control Desk products to allow users to keep notes of the progress of work.

A very nice feature of work logs is that Maximo displays all work logs for the current record an related ones. Lets make an example. If there is a work log on a work order originated from a Service Request, Maximo will display both SR logs and Work Order logs in the Work Order Tracking application.
In the example below we are in the Work Order Tracking application displaying work logs on work order 1019. The first work log has been added to the work order but the second one is attached to the originating service request 1214.

To go in details, Maximo will display records on the Work Logs tab with the following logic:

Work logs attached to the current record
Work logs for the originating and follow up records
If the ticket is global, all work logs in related to this global
If it is 'View SR App' (VIEWSR) or cloned by it, display only work logs which are marked as 'Client Viewable'

These rules seem pretty reasonable but in some cases we may prefer to adopt different rules. In such cases we can use a well hidden feature.

The system property psdi.worklog.workorder.useWOrelationship allows to specify a custom rule in the CUSTOMWOWORKLOG relationship of the WORKORDER object.
The system property psdi.worklog.ticket.useTKrelationship allows to specify a custom rule in the CUSTOMTKWORKLOG relationship of the TICKET object.

For example if we want to display only work logs related to the currently displayed work order we can configure Maximo as follows.
Open the System Properties application and set psdi.worklog.workorder.useWOrelationship to 1. Then apply configuration changes by selecting the record and clicking on 'Live Refresh' action.

Now open Database Configuration application, open WORKORDER object and go to the Relationships tab. Search for CUSTOMWOWORKLOG relationship and set it to:

recordkey=:wonum and class=:woclass and siteid=:siteid

This is how the configuration should look.

If we now open work order we will not see the work log on the service request.

Tracking elapsed time in work order status history

2019-08-04T18:31:00.001+02:00

A common requirement from my clients is to track how much time work orders have been in each status.
IBM Maximo already has the Work Order History dialog that displays the date and time of each status change. Unfortunately it may be not straightforward for a user to calculate the time spent in each step of the process or to develop a KPI to set processing time goals in your work management flow.

What I usually implement is a very simple time-tracking feature that just displays the elapsed time (time spent) attribute for each row. Note how the new history dialog is much more readable now.

To achieve this result we just need three configurations:

A new attribute to store the 'elapsed time' value in the WOSTATUS table.
An automation script to calculate and set the value in the custom attribute.
Modify the Work Order history dialog to display the new attribute.

Note that he same technique can be implemented for tickets (service requests) with very few modifications.

Elapsed Time attribute

Open Database Configuration application and create a new field like this:

Object: WOSTATUS
Attribute: XXXELAPSEDTIME (replace XXX with your own custom prefix)
Title: Time spent (or Elapsed Time)
Type: DURATION

Apply database configuration changes to create the new field in the database.

Automation Script

Open Automation Scripts Applications and create the following script.

# Script: WOSTATUS_TIMETRACKING
# Launch Point: Object (Save - Add - After Save)
# Object: WOSTATUS
# Calculate the time spent in previous status and update XXXELAPSEDTIME

from psdi.mbo import Mbo
from psdi.mbo import MboConstants

# Perform calculation only on interactive sessions to avoid the following error when generating PMs in the background.
# BMXAA3212E - Error while generating work order for PM. BMXAA8229W - Record WOSTATUS has been updated by another user.
if interactive:
  # get latest status history records
  shSet = mbo.getMboSet("$WOSTATUS$", "WOSTATUS", "wonum=:wonum and siteid=:siteid")
  shSet.setOrderBy("changedate desc")

  # calculate elapsed time
  if shSet is not None:
    lastSh = shSet.getMbo(1)
    thisSh = shSet.getMbo(0)
    if lastSh is not None and thisSh is not None:
      diff = (thisSh.getDate('CHANGEDATE').getTime() - lastSh.getDate('CHANGEDATE').getTime()) / float(3600000)
      lastSh.setValue("XXXELAPSEDTIME", diff, MboConstants.NOACCESSCHECK+MboConstants.NOVALIDATION)

Application dialog

The new WOSTATUS.XXXELAPSEDTIME attribute is now automatically updated by the script so we just have to display it in the application dialog.
Open Application Designer and search for WOTRACK application.
Edit the viewhist dialog and add the XXXELAPSEDTIME attribute in the first table.

Disable default attachment folder

2019-08-03T17:31:00.000+02:00

One of the fist lessons I have learned through all these years as Maximo consultant is that every time there is a default value for a field the user will not change it. A very common example of this is the Folder field of the Add Attachment dialog.

The value of this field will always default to the first folder available in alphabetical order. If we want to force the user to select the most appropriate folder for the attachment, then we have to remove that default value.
The attribute we want to change is DOCLINKS.DOCTYPE. Unfortunately, setting a default value for this field in Database Configuration will not work (believe me I have tried) so we have use a more powerful feature to control the behavior of this attribute. The solution I have found is to use a very simple automation script. Here it is.

Open the Automation Scrips application and create a new record with the following data:

Type: Script with Attribute Launch Point
Launch Point: DOCTYPEDEFAULT
Description: Reset default Attachment Folder for application WOTRACK
Object DOCLINKS
Attribute: DOCTYPE
Event: Run Action
Script: DOCTYPEDEFAULT
Script Language: python
Source: paste code below

#-------------------------------------------------------------------------------------------------------------
# Script: DOCTYPEDEFAULT
# Launch Point: DOCLINKS.DOCTYPE - Run Action
# Reset default Attachment Folder for application WOTRACK
#-------------------------------------------------------------------------------------------------------------
from psdi.mbo import MboConstants

if mbo.getOwner() is not None:
  # reset the default value only for a specific set of applications
  if mbo.getOwner().getThisMboSet().getApp() in ("WOTRACK", "ASSET"):
    if mbo.getMboValue("DOCTYPE").getPreviousValue().asString()=="":
      # set an invalid value so the user is forced to set a correct value
      mbo.setValue("DOCTYPE", "-", MboConstants.NOVALIDATION)

The script is quite simple.

It first checks if the owner application is in a specific set. This is because we may need to override the default behavior only for a specific set of applications. In the example it work only for Assets and Work Order Tracking applications.
Verifies that the previous value of the DOCTYPE field is not already set. I have used this trick to detect if the attribute was just initialized or the user already set the value.
Sets an invalid value '-' so the user is forced to set an appropriate folder.

Where was an asset located at a certain time in the past?

2019-04-26T16:52:00.001+02:00

Maximo has a well known feature to display the history of where an asset was located. It is accessible from View Asset Move History from the Asset application.
In the following example the asset DS01-A-002 was created in location DS01-S-SA-01 and then moved to other two locations.

The data displayed in this dialog is stored in the ASSETTRANS database table.
By querying this table we can answer questions like this:

Where was my asset located at a specific point in time?
What assets were in a specific location at a specific point in time?

Now lets start reading date from the ASSETTRANS table for asset DS01-A-002. We will get the same results displayed in the dialog above.

select assetnum, toloc, datemoved
from assettrans
where assetnum='DS01-A-002'
order by datemoved;

If we want to know where the asset was the 20th of April we need to know the largest DATEMOVED before that date.

select assetnum, max(datemoved)
from assettrans
where datemoved<TO_TIMESTAMP('2019-04-20', 'YYYY-MM-DD')
and assetnum='DS01-A-002'
group by assetnum;

Now we can join this result in the following way to retrieve the list of asset's locations 'as of' 20th of April at 11AM.

select a.assetnum, a.siteid, a.toloc
from assettrans a
join
(select assetnum, siteid, max(datemoved) d
 from assettrans
 where datemoved<TO_TIMESTAMP('2019-04-20 11:00:00', 'YYYY-MM-DD HH24:MI:SS')
 group by assetnum, siteid
) h on h.assetnum=a.assetnum and h.siteid=a.siteid and h.d=a.datemoved
order by a.assetnum;

We can now see that asset DS01-A-002 was located in DS01-S-SA-02 as expected. The query includes all the assets and can be filtered by asset or location.

Note that in this last query we have added the SITEID field since ASSETNUM/SITEID is the primary key of the ASSET table.

Logging in automation scripts

2019-04-03T21:58:00.001+02:00

I have to admit, I'm a big fan of automation scripts.
Recent updates released with Maximo 7.6.0.9 have almost covered all the possible customization needs including library scripts, REST APIs, MIF processing, before/after save event. All the new features are well documented in this somewhat secret document.

However whatever nice feature will be added in the next feature pack, we will never have a debugger like we have with Java and Eclipse. This could be a serious problem when you have to develop and maintain a complex set of scripts in your environment.
The best way to mitigate such problem is to correctly use Maximo logging APIs.

In my projects I usually define a custom logger in the Logging application. It's a good practice to give a short name of your customer. In this example I have defined mxdev logger for my MaximoDev customer.

I can now log messages to this custom logger using Maximo APIs. In the following example I first import the MXLoggerFactory class, then I get the reference to my mxdev logger and then I use the MxLogger APIs to write messages in the system log.

from psdi.util.logging import MXLoggerFactory

logger = MXLoggerFactory.getLogger("maximo.mxdev")

logger.info("Entering SR_INIT script for ticket " + mbo.getString("TICKETID"))
logger.debug("This is a debug message")

There are several good reasons for doing that.

I can select the logging level of my scripts dynamically in the Logger applications. I typically have that set to DEBUG in development and test environment. In production I set that to WARN or INFO to reduce verbosity.
Logging is always a good way of commenting the code.
It allows me to search for a specific string in the scripts when I see strange behaviors in the logs.

Avoiding FetchResultStopLimit errors in Java or scripts

2019-03-18T22:50:00.000+01:00

Today I had to face an issue deleting a large set of records from a Maximo table using an automation script. My script was something like this.

mboSet = MXServer.getMXServer().getMboSet("MYTABLE", mbo.getUserInfo())
mboSet.deleteAll()
mboSet.save()

Unfortunately the table I had to purge (MYTABLE in the example) was having more than 5000 rows so when I launched the script I got the following error.

BMXAA7387E - While attempting to retrieve 5001 of MYTABLE, the operation was terminated because the preset limit 5000 was exceeded for retrieving MYTABLE into a single set. Reduce the number of selected objects for the operation.

The simple solution would have been to increase the mxe.db.fetchResultStopLimit Maximo system parameter as documented in this post but I was looking for a more elegant solution.
Searching a little in the Maximo Java code i discovered the MboSet.setLogLargFetchResultDisabled() method that was exactly what I was looking for. Calling this method before the bulk operation will disable logging of large fetch result set to avoid FetchResultLogLimit errors. As a positive side effect it also increased the performances a lot.

The updated script now works like a charm.

mboSet = MXServer.getMXServer().getMboSet("MYTABLE", mbo.getUserInfo())
scSet.setWhere(where)
# disable logging of large fetch result set to avoid FetchResultLogLimit errors
mboSet.setLogLargFetchResultDisabled(True)
mboSet.deleteAll()
mboSet.save()

Automation Script to reset user's Start Centers

2018-11-28T18:48:00.000+01:00

In a previous post I have explained how to force the reload of a the start center for a specific group of users.
I have now developed a useful automation script that can be invoked from the Security Group application to automatically perform this task with just one click.
Register the script as a Script with an Action Launch Point and link it to a sigoption and to a menuaction, toolbar icon or application button as described in this post or this one.

# Reset users Start Centers
# Object: MAXGROUP
# Resets the Start Centers for all users assigned to the selected Security Group
# Should be called when all users are logged off so the start center is reloaded after the login
# See: http://maximodev.blogspot.com/2012/11/how-to-reset-users-start-centers.html

from psdi.server import MXServer
from psdi.mbo import MboConstants
from psdi.util.logging import MXLoggerFactory


def deleteSc(objectName, where):
 scSet = MXServer.getMXServer().getMboSet(objectName, mbo.getUserInfo())
 scSet.setWhere(where)
 logger.debug("Deleting rows from " + objectName)
 # disable logging of large fetch result set to avoid FetchResultLogLimit errors
 scSet.setLogLargFetchResultDisabled(True)
 scSet.deleteAll()
 scSet.save()


logger = MXLoggerFactory.getLogger("maximo.maximodev")
logger.debug("Entering ASSET_INIT script")

logger.info("Entering ASTS_RESET_STARTCENTER")
grpname = mbo.getString("GROUPNAME")

where1 = "scconfigid IN (SELECT scconfigid FROM scconfig WHERE groupname='" + grpname + "')"
where2 = "layoutid IN (SELECT layoutid FROM layout WHERE " +where1+ ")"


deleteSc("RSCONFIG", where2)
deleteSc("FACONFIG", where2)
deleteSc("INBXCONFIG", where2)
deleteSc("KPILCONFIG", where2)
deleteSc("KPIGCONFIG", where2)
deleteSc("ACTIONSCFG", where2)
deleteSc("PORTLETDISPLAY", where2)
deleteSc("LAYOUT", where2)
deleteSc("SCCONFIG", where1)

MTTx Terminology

2018-09-28T22:04:00.001+02:00

When it comes to asset reliability measurement all the different MTTx acronyms start to appear but sometimes is not clear to everybody the exact meanings of these terms.
In this post I want to give a very simple explanation of these reliability KPIs.

MTTD - Mean Time To Detect - How long it takes to discover a problem.
MTTK - Mean Time to Know - How long it takes to understand the problem.
MTTR - Mean Time To Repair - How long it takes to fix the problem.
MTTF - Mean Time To Failure - Amount of time the system is available and operating. Also known as "uptime".
MTBF - Mean Time Between Failures - Amount of time that elapses between one failure and the next.

MTBF is the sum of MTTF and MTTR, the total time required for a device to fail and that failure to be repaired.
MTBF = MTTR + MTTF

Here is a nice representation for these KPIs.

How to correctly handle synonym domains in automation script

2018-09-27T17:49:00.000+02:00

We all know that Maximo allows the definition of new internal values for synonym domains. A common example is the LOCTYPE domain that defines the allowed values for the LOCATIONS.TYPE field.
If we want to implement a special business logic for the OPERATING type of locations we can write something like this in our automation script.

loctype = mbo.getString("TYPE")
if loctype=="OPERATING":
  # do something....

However, if we define a new alias for the OPERATING type this script will not work as expected because it will not manage automatically the different internal values of the LOCTYPE domain.

The best solution is to use the psdi.mbo.Translate.toInternalString method like this:

from psdi.server import MXServer

loctype = MXServer.getMXServer().getMaximoDD().getTranslator().toInternalString("LOCTYPE", mbo.getString("TYPE"), mbo)
if loctype=="OPERATING":
  # do something....

The toInternalString method will translate the internal value of the LOCATIONS.TYPE field to the corresponding domain external value.

There are two implementations of the toInternalString method that are documented in the Javadoc.

String toInternalString(String listName, String value)
Convert a specified value in the list to an internal MAXIMO value.
String returned is a single value.
Parameters:
- listName The valuelist name (valuelist.listname). This is not case sensitive.
- value The external value (valuelist.value). This is case sensitive.
Returns The internal value (valuelist.maxvalue)

String toInternalString(String listName, String value, MboRemote mbo)
Convert a specified value in the list to an internal MAXIMO value.
String returned is a single value.
Framework will use the siteid of the passed in MBO if it is site level, or the orgid of the MBO if it is org level to find out the actual values for the specified domain, and use those values for translation. If the siteid and orgid of the MBO is null, all the value records will be considered.
Parameters:
- listName The valuelist name (valuelist.listname). This is not case sensitive.
- value The external value (valuelist.value). This is case sensitive.
mbo the MBO that the translation values are used for or the MBO which the site and org is same with the MBO that the translation is used for.
Returns The internal value (valuelist.maxvalue)

Sending SMS from Maximo calling an external Web service

2018-08-30T18:13:00.002+02:00

In my last project I had to implement a customization to send SMS messages using Skebby. The service APIs are obviously based on REST and JSON so I ended up writing an automation script to integrate Maximo with the Skebby service.
In the process of writing the code I have faced (and solved) some interesting issues so the developed script is quite complex and is an interesting demonstration of several useful techniques:

External REST service invocation (POST and GET)
JSON manipulation
Retrieve Maximo system properties
Usage of Java classes
Appropriate logging using MXLoggerFactory
Display error messages with parameters

The script is based on WORKORDER object and requires two custom system properties (sms.username, sms.password) and two messages (SmsSendError, SmsSendOk).
Here it is.

from java.lang import String
from java.io import BufferedReader, InputStreamReader
from java.net import URL, URLEncoder
from java.nio.charset import StandardCharsets
from com.ibm.json.java import JSONObject, JSONArray

from psdi.server import MXServer
from psdi.util.logging import MXLoggerFactory

logger = MXLoggerFactory.getLogger("maximo.script")
logger.debug("Entering SEND_SMS script")


BASEURL = "https://api.skebby.it/API/v1.0/REST/"
SMS_SENDER = "Maximo"
SMS_DEST = "+3933511111111"

sms_text = "Ticket " + mbo.getString("WONUM") + " - " + mbo.getString("DESCRIPTION")

properties = MXServer.getMXServer().getConfig()
username = properties.getProperty("sms.username")
password = properties.getProperty("sms.password")

urltxt = BASEURL + "login?username=" + URLEncoder.encode(username, "UTF-8") + "&password=" + URLEncoder.encode(password, "UTF-8")
logger.debug("Authenticating: " + urltxt)
url = URL(urltxt)
conn = url.openConnection()
conn.setRequestMethod("GET")

if conn.getResponseCode() != 200:
  conn.disconnect()
  msg = "HTTP Error: " + str(conn.getResponseCode()) + " - " + str(conn.getResponseMessage())
  logger.error(msg)
  service.error("asts", "SmsSendError", [str(conn.getResponseCode()), str(conn.getResponseMessage()), "Authentication failed"])

br = BufferedReader(InputStreamReader(conn.getInputStream()))
authResp = br.readLine()
conn.disconnect()

#logger.debug("Authentication output:" + authResp)
# auth tokens are returned separated by a ';' character
user_key,session_key = authResp.split(';')

logger.debug("Authentication tokens:" + user_key + "," + session_key)

logger.info("Sending SMS to " + SMS_DEST + " - " + sms_text)

url = URL(BASEURL + "sms")
conn = url.openConnection()
conn.setRequestMethod("POST")
conn.setRequestProperty("user_key", user_key)
conn.setRequestProperty("Session_key", session_key)
conn.setRequestProperty("content-type", "application/json")
conn.setDoOutput(True)

recipients = JSONArray()
recipients.add(SMS_DEST)

obj = JSONObject()
obj.put("message_type", "TI")
obj.put("returnCredits", False)
obj.put("sender", SMS_SENDER)
obj.put("recipient", recipients)
obj.put("message", sms_text)
jsonStr = obj.serialize(False)

logger.debug("SMS Json Request=" + jsonStr)

os = conn.getOutputStream()
postData = String.getBytes(jsonStr, StandardCharsets.UTF_8)
os.write(postData)
os.flush()

if conn.getResponseCode() != 201:
  br = BufferedReader(InputStreamReader(conn.getErrorStream()))
  output = br.readLine()
  logger.error("Error: " + output)
  conn.disconnect()
  msg = "HTTP Error: " + str(conn.getResponseCode()) + " - " + str(conn.getResponseMessage() + " - " + output)
  logger.error(msg)
  service.error("asts", "SmsSendError", [str(conn.getResponseCode()), str(conn.getResponseMessage()), output])

br = BufferedReader(InputStreamReader(conn.getInputStream()))
output = br.readLine()
logger.info("OK: " + output)
conn.disconnect()

service.setWarning("asts", "SmsSendOk", None)

The script has been developed to avoid external dependencies like this example.

Disable automatic asset/location population in Work Order and Ticket applications

2018-08-23T15:41:00.004+02:00

Maximo has a feature that automatically populates the asset when a user enters a location and viceversa. This is a feature may be useful for most clients but some other clients don’t like this behavior. Unfortunately Maximo does not have a built in switch to disable this.

The best solution to solve the problem is to use an automation script with an attribute launch point.
This is documented in this post but i made few improvements to it.
My script resets the asset only when the location has been changed and ASSETNUM is changing from null to a new value. This is because there is already a warning dialog when the asset is changed from another value.

This is how I have defined my automation script. I have tested it for Service Requests application but it should work fine for Work Orders as well.

Script: SR_LOCATION
Language: python
Launch Point: SR_LOCATION_ACTION
Object: SR (this could be also be WORKORDER or TICKET)
Attribute: LOCATION
Event: Run Action (Validate should also work)
Variables: none

Script:

from psdi.mbo import MboConstants

if not mbo.isNull("LOCATION"):
  if mbo.getMboValue("ASSETNUM").getPreviousValue().asString()=="" and not mbo.isNull("ASSETNUM"):
    mbo.setValueNull("ASSETNUM", MboConstants.NOVALIDATION_AND_NOACTION)

How to restrict allowed status changes for workorders

2018-08-22T16:29:00.000+02:00

Maximo has a predefined set of statuses for work orders that are defined in the WOSTATUS synonym domain. The values and their meaning are well documented in the official documentation.
Unfortunately the allowed state transitions are hardcoded in the psdi.app.workorder.WOStatusHandler class and cannot be easily changed since they are defined as private arrays.
Here is a brief summary of the allowed status changes.

	WAPPR	APPR	WSCH	WMATL	INPRG	COMP	CANCEL	CLOSE
WAPPR	-	Y	Y	Y	Y	Y	Y	Y
APPR	Y	-	Y	Y	Y	Y	-	Y
WSCH	Y	Y	-	Y	Y	Y	-	Y
WMATL	Y	Y	Y	-	Y	Y	-	Y
INPRG				Y	-	Y	-	Y
COMP						-	-	Y
CANCEL							-	Y
CLOSE								-

From status APPR you can set any target status.

This allows too much freedom in some cases so we want to restrict the allowed state transitions.
For example you might want to prevent users from changing the status of work orders that are in APPR (Approved) status to CLOSE (Closed) or CAN (Canceled).

First, navigate to Condition Expression Manager and create the following conditional expression:

Condition: WONOTAPPR
Description: Work Order is not in APPR status
Type: Expression
Expression: :status not in ('APPR')
Always Evaluate: false

Open the the Domains application and bring up the WOSTATUS domain.
Select the CAN status row and click on the View/Modify Conditions button.
Select the "new row" button and select the new condition you created above, and click OK.

Do the same to COMP and CLOSE status if you wish.
If you now open any work order in APPR status you will notice that the list of allowed target statuses is shorter.

The good part is that the same rule applies also if you click on the quick actions.

References

How to extract emails to notify users

2017-10-25T19:05:00.004+02:00

There are several situation where you need to quickly notify a set of users sending them an email. These are few examples of such situations.

There is a urgent maintenance activity to perform on Maximo that requires to enable the admin mode and logoff all the users.
You are going to rollout an additional validation into an application that will affect the way technicians must enter data when closing work orders.
An important event has appended (incident or critical problem) and you must alert people as soon as possible.

The built-in Bulletin Board application often solves these problem that allows to broadcast information throughout your organization. You can specify an audience for a message, based on organization, site or person group. Messages will appear on the start centers and a notification icon will be displayed at the top of the window.
Furthermore, the 'Create Communication' action allows to send an email to the selected audience.

There are just two limitation of this approach.

You want to use a Security Group to select who to notify.
You want to send the email from your inbox in order to interact with the recipients more easily.

I have solved this little problem with an easy trick. I have added the email address to the list view of the Security Groups application.

It is really easy... follow this steps:

Open the Application Designer application
Search for application USER
Add a column in the list view and type PERSON.PRIMARYEMAIL in the Attribute field
Save

Now if you go the Users application you will see the email addresses of your users listed. You can also filter by security group in the advanced search to refine your list.

Exporting the table and pasting the email addresses cells into your preferred email client will do the trick.

A similar configuration can also be used in the People application (PERSON). However, you can't search for security groups from there.

Now don't spam your users everyday...

Security groups and application authorizations

2017-08-04T15:38:00.001+02:00

We all know how flexible Security Groups are when dealing with user roles and granting application authorizations. However, flexibility often brings complexity.
You have carefully designed user's roles defining what applications and actions they are allowed to access in Maximo and implemented all using Security Groups application. The system goes live and after one or two years everything is messed up. Is too hard to check who has access to what and you no longer sure if the young electrician that was just hired 2 months ago has access to Database Configuration or Application Designer :-)

Maximo has a built-in report called Security Group Access that can help but I hardly find it useful. In my opinion it is too detailed to get an overall idea of the security configuration. For example, I'm now working on a medium-sized Maximo solution with 20 security groups and around 250 users. Well... the 'Security Group Access' report is 89 pages long!

That was not going to work. I needed I better solution for my purpose so I decided to open my preferred SQL client and Eclipse BIRT Designer to have some fun. Results were pretty good so I have decided to share them with the Maximo community.

I came up with two custom reports that give me a quick grasp of the setup of user's authorizations. The first one is called Security Overview and simply lists all the Security Groups and Start Centers counting how many users are assigned to them.

The second report is called Application Security Overview. It tries to represent which security groups provide access to applications. It is not an easy task to represent so many information in a single report but I'm finally proud of the results so here is what I have achieved to get.

The report lists all the applications in the rows and the security groups in the columns. The cell is yellow if read access is granted, orange if write access is granted, the number is the count of sigoptions granted.
The report can easily get too big if more than 20 security groups are defined so I decided to accept a list of security groups as filter so I can analyze smaller sets of data separately.

Download and installation instruction is available here.

Any feedback is highly appreciated.

Is your Maximo database in good health?

2017-06-02T11:58:00.000+02:00

We all know Maximo is a complex product. It has plenty of features and is very flexible but sometimes complex to manage especially when system performances are poor.
A lot of things may affect the perceived performances of Maximo and it may be hard to have an overview of the entire system configuration.

What are the largest tables in the database that may need archiving?
Are database statistics updated to optimize database queries?
How much data is stored for each site?
Has the workload of system increased over the last years?
What are the most heavy reports users execute?
What are the most resources-consuming crontasks and escalations?
How is the reports/crontasks/escalations workload spread across the day?

These and many other questions have an answer in the Maximo Health Check report.
Maximo Health Check report is a utility for IBM Maximo and IBM Control Desk that can help identify and analyze issues, errors, or incorrect configurations that can lead to unsatisfying system performances.

Adding more JVMs to your application server cluster seldom solves Maximo performance issues. In our experience, the most effective performance improvement techniques are on the database side.
For large Maximo systems data archiving may be needed. This is because, after several years of usage, large volume of data accumulated into some tables slowing down database inserts and updates. Moving unnecessary data out of those tables can greatly improve overall system performances.
When specific application queries, reports or escalations have unsatisfying execution times database indexes optimization could be the answer. Adding the right indexes and removing the wrong ones is a complex activity that requires deep skills but can produce outstanding results in many cases.
Sometimes index optimization is not enough to fix a badly written SQL query. In this case SQL queries optimization is the right technique. SQL queries are everywhere in Maximo: start center portlets, application queries, escalations and reports. By simply refactoring those SQL statements I have obtained impressive results in many cases.
Database tuning is the last chance. Assuming IBM suggested settings have been applied, this is 'brute force' approach can bring some incremental improvement to overall performances.

Download and run the Maximo Health Check report and you may find interesting information about your Maximo system.

Maximo REST APIs examples

2017-04-04T18:04:00.001+02:00

This entry is part of the Maximo Integration Framework series.

In this tutorial I will show how easy it is to query and update data in Maximo using the Integration Framework (MIF) REST interface.

HTTP test client setup

To send REST calls you first need to setup an HTTP client. In this tutorial I will use a Google Chrome add-on called Advanced REST Client.

Retrieve a record

In this first example I will show you to retrieve a PERSON record from Maximo using a REST call with an HTTP GET request:

http://[MXHOST]/maxrest/rest/mbo/person/1

Probably you will get an authentication error like this:

Error 401: BMXAA0021E - User name and password combination are not valid. Try again.

This means that you have to pass the authentication credentials to your request. If you are using native authentication you can pass the _lid and _lpwd arguments as described in this example:

http://[MXHOST]/maxrest/rest/mbo/person/1?_lid=wilson&_lpwd=wilson

Now you should see the PERSON record identified by the PERSONUID=1.

NOTE: For all the examples below I will exclude the authentication arguments for simplicity.

MBO and OS resources

The REST API provides access to business objects and integration object structures.

The two calls below will provide access to the same resource:

http://[MXHOST]/maxrest/rest/mbo/person/1
http://[MXHOST]/maxrest/rest/os/mxperson/1

The first call access data straight from the PERSON object through MBO persistence layer.
The second call access data from the MXPERSON integration object structure through the MIF.
You will notice that results are slightly different.

Data format (XML or JSON)

By default Maximo retrieves data in XML format. JSON could be used instead passing the _format argument:

http://[MXHOST]/maxrest/rest/mbo/person/?_format=json

Query

To retrieve the REVIS person record use the following REST call:

http://[MXHOST]/maxrest/rest/mbo/person/?personid=revis

Note that Maximo will perform a wildcard search by default so if you type 're' instead of 'revis' you will get a list of records that contains 're' in the PERSONID field:

http://[MXHOST]/maxrest/rest/mbo/person/?personid=re

To search with an exact match use the ~eq~ token as demonstrated in this examples:

http://[MXHOST]/maxrest/rest/mbo/person/?personid=~eq~revis

http://[MXHOST]/maxrest/rest/mbo/person/?personid=~eq~re

Results can be sorted using the _orderby, _orderbyasc or _orderbydesc argument. Multiple attributes can be passed separated by a comma character.

http://[MXHOST]/maxrest/rest/mbo/person/?personid=re&_orderby=statusdate
http://[MXHOST]/maxrest/rest/mbo/person/?personid=re&_orderby=status,statusdate

Create or Update a record (AddChange)

To create an existing record the AddChange action can be used. The following example will create a new person named RESTINT. Note that in this case a POST request must be used instead of a GET.

http://[MXHOST]/maxrest/rest/mbo/person/?_action=addchange&personid=restint&firstname=Rest&lastname=Int

To update the same record we can use the PERSONUID returned from the create. In my example it's 161.

http://[MXHOST]/maxrest/rest/mbo/person/161?_action=addchange&personid=restint&firstname=RestNew&lastname=IntNew

Updating child objects

Lets now pretend we need to update an asset specification and one of its attributes. You will see things are now a little more complex.

First of all we can create a new asset with a POST request.

http://[MXHOST]/maxrest/rest/mbo/ASSET/?assetnum=myasset01&siteid=BEDFORD&description=TestTest

Take note of your ASSETUID and query the new record with a GET request.

http://[MXHOST]/maxrest/rest/mbo/ASSET/2585

Now login to Maximo, classify the MYASSET01 as a BEARING, add an ALN attribute and save it.
If you query the asset using the GET request above you will notice that you just have a CLASSSTRUCTUREID attribute with a number in it specifying the classification. This is not usable in our scenario and will not allow to update attribute.

The right approach is to switch to the object service structure. Try to query the new record with a GET request like this:

http://[MXHOST]/maxrest/rest/os/MXASSET/2585

You will see that the HIERARCHYPATH field is now available and a subelement ASSETSPEC returns the attribute.
If we now want to update the value of the ALN attribute we can use a POST with a dotted notation like this:

http://[MXHOST]/maxrest/rest/os/MXASSET/2585?ASSETSPEC.1.ASSETATTRID=BEARTYPE&ASSETSPEC.1.ALNVALUE=ABC&ASSETSPEC.1.LINEARASSETSPECID=0

If you want to set a new classification here's an example:

http://[MXHOST]/maxrest/rest/os/MXASSET/2585?hierarchypath=BEARING%20\%20ROLLER

Note how the spaces have been encoded in the URL with the '%20' string.

Hope this can help all of us dealing with integration scenarios using REST calls...

References

IBM Documentation
Maximo REST APIs reference material

Load failure codes in Maximo with MxLoader

2017-03-16T08:45:00.000+01:00

Creating and maintaining the hierarchy of failure codes in Maximo can be quite long and boring task using the standard Failure Codes application. The easiest and fastest way of importing Failure codes and the corresponding hierarchy is using MxLoader.

The example described in this post is available in this tailored in this sample MxLoader file. Please download it before proceeding.

Since there is no out-of-the-box object structure in Maximo to import failure codes, you first have to create the MxLoader custom object structures. This can be easily accomplished by clicking on the Create Custom Object Structures in the MxLoader ribbon in Excel.

The second step is to load the failure codes IDs and descriptions.
The FailureCodes worksheet on the example will load one failure class, two problems, two causes and three remedies.

Note that in the last column we have the language code. This is helpful if you want to transalate the failure codes in multiple languages.

We have just loaded a flat list of failure codes so now we need to create the hierarchical structure. The Failure Hierarchy template allows you to load failure class hierarchy using the custom MXL_FAILURELIST Object Structure. The example in the FailureHierarchy worksheet loads a small hierarchy using the failure codes defined previously.

Note how the failure hierarchy is specified in a flat table.
The object IDs in the square brackets will be generated dynamically by MxLoader during the import process. Do not enter those IDs manually.

This is how this failure tree will look in Maximo.

Note that the Failure Hierarchy template does not allow querying existing failure hierarchy. This can be a limitation if you want to copy a failure class hierarchy from one organization to another or from one server to another.
To extract an existing failure hierarchy you have use an SQL query like this.

SELECT f.orgid, f.failurelist classid, f.failurecode class,
  p.failurelist problemid, p.failurecode problem,
  c.failurelist causeid, c.failurecode cause,
  r.failurelist remedyid, r.failurecode remedy
FROM failurelist f
LEFT OUTER JOIN failurelist p ON p.parent=f.failurelist AND p.type='PROBLEM'
LEFT OUTER JOIN failurelist c ON c.parent=p.failurelist AND c.type='CAUSE'
LEFT OUTER JOIN failurelist r ON r.parent=c.failurelist AND r.type='REMEDY'
WHERE f.parent IS NULL
ORDER BY f.failurecode, p.failurecode, c.failurecode, r.failurecode;

MxLoader is also able to upload custom levels of failure codes in the hierarchy. For example, if you have a custom level called SYSTEM, you can simply add it to the columns and MxLoader will handle it.

References

Failure Codes in IBM Maximo Asset Management (SlideShare)
Failure codes (TechMCQ)
How to load failure code hierarchy using MIF

Maximo keyboard shortcuts

2017-02-06T17:34:00.003+01:00

You know IBM Maximo has a lot of fields and sometimes can be boring entering data. Here are some keyboard shortcuts that can ease the pain. I have highlighted in bold the most common and useful ones.

Tab > The most important keyboard shortcut is the TAB key. It allows you to move across fields without using the mouse and also performs data validation and auto-completion.
Space > Select or clear a check box.
Alt + F1 > Display field help for field in focus.

There are few other useful shortcuts to move across applications.

Alt + C > Go to the Start Center.
Alt + G > Open the Go To menu. Use the arrow keys to choose the desired app.
Alt + B > Bulletins
Alt + R > Reports
Alt + P > Profile
Alt + S > Sign Out
Alt + H > Help
Alt + R > Return
Alt + W > Return with Value

Last but not least you can quickly create and save records with these Toolbar Buttons shortcuts.

Ctrl + Alt + I > Insert New Record
Ctrl + Alt + S > Save Record
Ctrl + Alt + A > Change Status
Ctrl + Alt + C > Clear changes
Ctrl + Alt + P > Previous Record
Ctrl + Alt + N > Next Record

This is a simplified list of the available keyboard shortcuts. For more information refer to the official documentation.

Maximo search operators

2017-01-29T16:11:00.003+01:00

Maximo search features are quite advanced but often neglected. By using the advanced search techniques described in this post it is possible to find relevant records easier and faster.

Equal

The equal '=' operator can be used to find only records that match that a word or number exactly. In other words '=' means "exact match".
Example: Enter =123 to find any records with the exact characters 123 in the field. (Search results would not include numbers such as 0123 or 1234AB. If you enter just 123, without the =, search results would include 0123 and 1234AB.)

Not Equal

To search for all values that are not equal to a specific value enter '!='.
For example, typing !=WAPPR in the status field will retrieve all records that are not in WAPPR status.

Greater/Less

The '<' and '>' characters can also be used to search for records that are bigger or smaller than a specific value.

Greater than '>': searches for any date after or number/word greater than the specified value.
Example: Enter >1172 finds records of occurrences that have work order number greater than 1172.
Less than '<': searches for any date before or number/word smaller than the specified value.
Example: Enter <1172 finds records of occurrences that have work order number smaller than 1172.

List of values

You can use comma ',' operator to list the records that match with either of the values specified. It basically acts as the OR operator.
For example, typing WAPPR,COMP in the status field will retrieve all records that are in WAPPR or COMP status .

Wildcards

You can use a "wildcard" characters with letters or numbers to indicate you want to find records that begin with, end with, or contain those letters/numbers.
There are four characters you can use as a wildcard:

Asterisk '*' or percent sign '%': stand for any number of characters (zero, one, or multiple) in the specified position.
Example: Enter 123* to find records that start with 123, such as 123, 12345, 123ABC.
Example: Enter *123 to find records that end in 123, such as 123, 5123, PUMP123.
Example: Enter *123* to find records that contain 123, such as 123, 1234, PUMP123xy.
Underscore '_' or question mark '?': stand for a single character in the specified position.
Example: Enter 123_ to find any four‐character records that start with 123, such as 1234, 1230, 123g.
Example: Enter or _18 to find any three‐character records that end with 18, such as 418, J18.

NULL Values

You can search for null and not null values by entering the following values into a search field on the Find tab:

To search for a null value enter: ~null~
To search for not null values enter: != ~null~

If your keyboard does not have the tilde '~' character you may type enter this character by typing 126 on your numeric keypad while pressing the 'Alt' key.

Dates

A small additional tip for searching dates in the current month.
If you want to search for WO's with scheduled start date less than today, you don't need to type or select the whole date into the search field because Maximo automatically appends the current month and year in the where clause.
For example, if you search with <15, system will return all WO's where scheduled start date before the 15th of the current month.

References

Understanding Search Methodologies
To Search For Records in a Maximo Database
Search for NULL values in Maximo applications

Find inactive users in Maximo

2017-01-18T15:15:00.000+01:00

Here is a quick SQL query you can use to find inactive users that haven't logged into Maximo in the last 2 months.

DB2

select * from maxuser
where status='ACTIVE'
and sysuser=0
and not exists (select userid from logintracking where logintracking.userid=maxuser.userid and attemptresult='LOGIN' and attemptdate>(current date-60 DAYS))
order by userid;

Oracle

select * from maxuser
where status='ACTIVE'
and sysuser=0
and not exists (select userid from logintracking where logintracking.userid=maxuser.userid and attemptresult='LOGIN' and attemptdate>sysdate-60)
order by userid;

SQL Server

select * from maxuser
where status='ACTIVE'
and sysuser=0
and not exists (select userid from logintracking where logintracking.userid=maxuser.userid and attemptresult='LOGIN' and attemptdate>getdate()-60)
order by userid;

Obviously, the above query works only if you have enabled the login tracking feature in Security Groups - Security Controls.

This is very useful if you want a quick idea about how many users are really accessing the system.
Another interesting use of this query is to optimize Maximo licenses by simply deactivating users that no longer use the system. You can even define an escalation that automatically do the job for you.

Long Descriptions in Maximo

2017-01-17T16:03:00.002+01:00

Long descriptions in Maximo are a special fields meant to store long text. Unlike all the other fields they are stored in a dedicated table called LONGDESCRIPTION. Tables link to the LONGDESCRIPTION table through their unique ID and the long description attribute is stored in a CLOB field.

Let's change the long description of the work order '1000' with few lines of text.

If we run the following SQL we can retrieve the internal ID of the work order.

select wonum, workorderid, description from workorder where wonum='1000';

Here we are interested to the WORKORDERID field which is the internal numeric identifier of the work order. This value is referenced in the LDKEY of the LONGDESCRIPTION table.
This is how we can retrieve the long description.

select * from LONGDESCRIPTION where ldkey=37 and ldownertable='WORKORDER';

Multiple attributes in the Mbo can have long descriptions. The LDOWNERCOL says which column owns the long description. The LANGCODE allows to have translated versions of the same long description field.

Long description fields can be associated with any attribute in Database Configuration setting the 'Long Description Owner' checkbox.

In the MAXATTRIBUTE record, the ISLDOWNER column is set to 1 if the column has a long description. For each long description owner there is a nonpersistent attribute named +"[ATTRNAME]_LONGDESCRIPTION" that will store the data in the LONGDESCRIPTION table.

Improving Assets and Locations drilldown dialog

2016-12-28T12:10:00.002+01:00

The Assets/Locations drilldown dialog is one of the most longstanding and criticized features of Maximo.

This dialog is almost unchanged from release 6.1 and definitely lacks some important capabilities to provide a unified view of assets and location hierarchy. However, we can make few minor improvements to the standard dialog to make it slightly better.

Increase size of the dialog

I think the most usability improvement is to increase the size of the dialog allowing to see more elements in the drilldown. The default size is definitely too small for the typical modern screen resolutions.
Unfortunately there is no system setting for this and we have to tweak the dialog definition in the library.
Open the Application Designer and select the Export System XML action from the menu. Click on the small arrow for the LIBRARY row to export the file. Open the XML file with a good text editor and search for psdi.webclient.beans.common.DrilldownTreeBean.
There are two occurrences of this string in the file inside the 'drilldown' dialog definition. One is for the Locations tab and one is for Assets tab.
Change the height attribute increasing it from the default 150 to 350 or 400.

<tree id="locations_tree" beanclass="psdi.webclient.beans.common.DrilldownTreeBean"
width="500" height="350" checkfornewnodes="true"
ignorestructurechange="false" orderby="location asc" relationship="LOCATIONS" selectfirstnode="true">

Now in the Application Designer app, click on the Import Application Definition to import the modified LIBRARY.xml file.

You can see from the screenshot below how much easier it is to get a grasp of the location hierarchy with the new larger dialog.

Increase child records limit

Another small improvement that can be made is to improve the default limit of child records that can be displayed. The default value is set in the control-registry.xml file and is typically set to 50 which is too low.
To override the default value, just add the maxchildren attribute and specify a larger value like 500. This is how the locations_tree definition should look like.

<tree id="locations_tree" beanclass="psdi.webclient.beans.common.DrilldownTreeBean"
width="500" height="350" maxchildren="500" checkfornewnodes="true"
ignorestructurechange="false" orderby="location asc" relationship="LOCATIONS" selectfirstnode="true">

For more information refer to this post.

Tracking Changes using Audit feature

2016-11-29T16:02:00.000+01:00

A common requirement in Maximo is to track changes made by users on a specific object (database table). In Maximo terms this is called 'Audit Tracking'.
In this post I will describe how to enable audit tracking for a specific set of attributes of an object and how to display the updates in a separate tab of the corresponding application.
I will use the Assets application for this tutorial and here is the final outcome I have achieved.

There are three configurations to be implemented for this:

Enable audit of the main object and select attributes to be audited
Define relationship to the audit table
Customize the application to display the audit log from the UI

Enable audit

First step is to enable the auditing of the table you want to monitor.
Open the Database Configuration application, select ASSET object and check the Audit Enabled flag.

You now have to select which fields will trigger the audit record. Switch to the Attributes tab and select the Enable Auditing flag for STATUS, SERIALNUM, LOCATION, DESCRIPTION fields.

Enable admin mode, apply configuration changes and disable admin mode.
A new database table A_ASSET will be created and, from now on, all the changes to the audited fields will be traced in the audit table.

Define relationship

In order to be able to display the audit records we have to create a relationship from the ASSET table to the A_ASSET table.
Open the Database Configuration application, select ASSET object and in the Relationships tab create the following relationship.

Relationship: A_ASSET
Child Object: A_ASSET
Where Clause: assetnum=:assetnum and siteid=:siteid

Customize application

Now you can use the relationship you have just created to display records from the child A_ASSET audit table in the Asset application.
Open Application Designer application, select the ASSET application and export the app's XML definition.
Backup the file and edit it with a text editor. Paste the text below before the last </tabgroup> before the </clientarea> tag.

<tab id="myhist" label="History">
  <section id="myhist_grid1">
    <sectionrow id="myhist_grid1_11">
      <sectioncol id="myhist_grid1_11_1">
        <section id="myhist_grid1_11_1_1">
          <multiparttextbox dataattribute="assetnum" descdataattribute="description" id="myhist_grid1_1"/>
        </section>
      </sectioncol>
    </sectionrow>
  </section>
  <table id="myhist_t1" inputmode="readonly" label="Asset history" orderby="EAUDITTIMESTAMP desc" relationship="A_ASSET">
    <tablebody displayrowsperpage="10" id="myhist_t1_tb">
      <tablecol dataattribute="SERIALNUM" id="myhist_t1_SERIALNUM"/>
      <tablecol dataattribute="STATUS" id="myhist_t1_STATUS"/>
      <tablecol dataattribute="LOCATION" id="myhist_t1_LOCATION"/>
      <tablecol dataattribute="DESCRIPTION" id="myhist_t1_DESCRIPTION"/>
      <tablecol dataattribute="EAUDITUSERNAME" id="myhist_t1_EAUDITUSERNAME" label="Changed By"/>
      <tablecol dataattribute="EAUDITTIMESTAMP" id="myhist_t1_EAUDITTIMESTAMP" label="Changed Date"/>
    </tablebody>
  </table>
</tab>
</tabgroup>
...
</clientarea>

Watson IoT MQTT APIs walkthrough

2016-06-03T12:18:00.001+02:00

After several experiments with IBM Watson IoT Platform I have decided to take a step back and play MQTT manually to really understand how it works. In this post I will walk through my experiments with of the Watson IoT Platform MQTT messaging API for devices, applications and gateways.

Prerequisites

First of all you need an account on IBM Watson IoT Platform on Bluemix. In all cases you need to create your own Internet of Things Platform service and create your own device type and device. I suggest you to follow the IoT Starter tutorial if you are on familiar with Watson IoT.

Another important preliminary step is to have an MQTT client to simulate MQTT calls. I have decided to use MQTT Spy tool. Download it from here and have it ready on your PC. There is a very good tutorial here if you want to learn more.
If you don't like it you can also try MQTT Lens.

Publish event from a device

This is the most simple example. A device sending MQTT messages to the cloud.
The device must be first registered on Watson IoT Platform. On you IBM Bluemix dashboard, click on the Internet of Things Platform service. Open the dashboard by clicking on the 'Launch Dashboard' button.
Open the Devices page and click on the Create Device button. First create a Device Type and then a new Device with the following details:

Type: TestDeviceType
Name: TestDev1
Security token: test1234

A summary page will be displayed with the device information needed for the connection.

Now we are ready to send our first message.
Devices use the following identification/authentication information (detailed documentation):

Client ID in formatted as d:[OrgId]:[DeviceType]:[DeviceId]
Username is use-token-auth
Password is the authentication token generated during device registration
Topic for publishing events is iot-2/evt/status/fmt/json

Create an new connection on MQTT Spy (replace [OrgId] with your Organization ID).

Protocol version: MQTT 3.1.1
Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
Client ID: d:[OrgId]:TestDeviceType:TestDev1
Username: use-token-auth
Password: test1234

Now you can publish the first MQTT message.

Topic: iot-2/evt/status/fmt/json
Data: {"d":{"status":"Hello Watson IoT"}}

Now open the Watson IoT device details and click on the Publish button on MQTT Spy. You should see the incoming message like this.

Publish event from an application on behalf of the device

The Watson Iot Platform allow to define external applications that can publish events on behalf of any device and subscribe to device events. In this tutorial we will publish a message for the Dev1 device and subscribe to its events.

We first need to define the application on Watson Iot Platform Dashboard. Open the Access and API Keys tab, then click on Generate API Keys button. Take note of the API Key and Authentication Token.

Applications use the following identification/authentication information (detailed documentation):

Client ID in formatted as d:[OrgId]:[AppId]
Username id the API Key generated during registration
Password is the Authentication Token generated during registration

An application can publish events as if they came from any registered device.

Topic for publishing events is iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json

Create an new connection with your MQTT client.

Protocol version: MQTT 3.1.1
Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
Client ID: a:[OrgId]:App1
Username: enter your API Key
Password: enter your Authentication Token

Now you can publish a message on behalf of device TestDev1 used before.

Topic: iot-2/type/TestDeviceType/id/TestDev1/evt/status/fmt/json
Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm App1"}}

Subscribe to device events from an application

An application can subscribe to events from one or more devices using topic iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json
The MQTT wildcard character '+' can be used to subscribe to more than one type of event.

On MQTT Spy subscribe to all events from the TestDev1 device using topic iot-2/type/TestDeviceType/id/TestDev1/evt/+/fmt/json

Play with MQTT Spy and see how App 1 is notified when publishing events from the device. Try changing the subscription topic as well.

Gateway

Gateways can publish events from itself and on behalf of any device connected to it. In this tutorial we will publish a message for the Dev1 device and see how it is received from the subscribed app.

Open the Devices page on your Watson IoT dashboard and click on the Add Device button. First create a Gateway Type and then a new Gateway.

Type: TestGwType
Name: TestGw1
Security token: test1234

Gateways use the following identification/authentication information (detailed documentation):

Client ID in formatted as g:[OrgId]:[GwType]:[GwId]
Username is use-token-auth
Password is the authentication token generated during device registration

Note that these information are very similar to the device connection properties but the Client ID has now a 'g' prefix instead of 'd'.
A gateway can publish events on behalf of a device.

Topic for publishing events is iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json

Create an new connection with your MQTT client.

Protocol version: MQTT 3.1.1
Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
Client ID: g:[OrgId]:TestGwType:TestGw1
Username: use-token-auth
Password: test1234

Publish an event for the gateway:

Topic: iot-2/type/TestGwType/id/TestGw1/evt/status/fmt/json
Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm Gw1"}}

Publish an event for the device:

Topic: iot-2/type/TestDeviceType/id/TestDev1/evt/status/fmt/json
Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm Gw1"}}

Note haw the App1 subscription is receiving the events from the device. You can also try to subscribe to the gateway's events.

References

IBM Watson IoT Platform documentation
MQTT Spy tutorial