Maximo - Integration Framework File Based Error Management and How It Works

Body

Today I am going to talk about Maximo's File Based Error Management functionality.  I'll talk about how it works and the requirements to set it up.

Prior to release of Maximo 7.5, the integration framework stored failed messages from the JMS queues on the file system in a directory defined by a Maximo system property, requiring users to have direct access to the files and directories in order to correct and move files to be reprocessed by Maximo.  With the rease of Maxiom 7.5, that is no longer the case.  Now, messages that fail delivery to maximo from the JMS queues are stored in tables in the Maximo database.  For this reason, a shared global directory is no longer required for the Message Reprocessing application.

The table names are:

MAXINTERROR

MAXINTERRORMSG

However, there is a feature called File Based Error Management, which can be used to download a failed file import, which does use the global directory defined in the Maximo system properties, and requires that certain users have access to the location.  Both flat file and XML file formats are supported. 

The benefit of using the File Based Error Management is that it allows a user to download all errors produced from an import to a single file and correct multiple records at the same time.  The user can simply reimport the corrected file.

File Based Error Management is supported in a few different places in Maximo.

1.  External Systems application, Enterprise Services tab

You can perform manual imports of files in the External Systems application and select "File Based Error Management" during your import.

2.  FLATFILECONSUMER cron task instances

When you create a new FLATFILECONSUMER cron task instance, one of the parameters you can change is ISFILEEXTRACT.  By setting this value to 1, you will enable File Based Error Management for that cron task instance.

3.  XMLFILECONSUMER cron task instances.

When you create a new XMLFILECONSUMER cron task instance, one of the parameters you can change is ISFILEEXTRACT.  By setting this value to 1, you will enable File Based Error Management for that cron task instance.

Let's talk about how to set this up and use it.

1.  The first step is to set up the global directory that all server in your WebSphere cell will be able to read/write to.  This can be a mount point, or UNC path to a SAN/NAS or another host.

The user that must have full read/write to this location is the user that runs your WebSphere processes.  If you are mounting a file system that is remote to the local computer, ensure you specify a user within your domain for running these processes.  Do Not use a local system account to start your WebSphere services on Windows.

2.  In the Maximo System Properties application, specify the location for your global  directory in the property mxe.int.globaldir.  Save and perform a live refresh.

3.  At this point, you will need to restart the application servers.

4.  Next, navigate to your external system.  Ensure your enterprise service is using the continuous queue.  Note the File Based Error Management does not support the sequential queue, so the continuous queue must be enabled for any enterprise service wishing to use it.

5.  Perform an import of a record that will generate an error.  Ensure you select "File Based Error Management" on the import file dialog box.

6.  Once the message is imported, an error is generated.  Navigate to the Message Reprocessing application and click the download button beside the corresponding error message.  Notice it shows it is available for extract.

7.  Save the record to your PC without changing the file name.

8.  Now, using a text editor of your choice, you can correct the error and save the file.

9.  Next, from the External System, Enterprise Service, import the corrected file, select "File Based Error Management" again on the import file dialog box.

Once the message is processed successfully into Maximo, the corresponding message in the message reprocessing application's continuous queue will be removed and the original error is no longer available for extract.

How does it work?

When a file is enabled for extract, in the Message Reprocessing application you can click on the download button to the right of your message.  The details presented in the message reprocessing application for file extract are stored in the MAXINTEXTRACT table and are still held in the continuous queue.  Maximo uses this information to find the corresponding information in the integration error tables.

Note that you cannot directly modify the message in the queue, and will notice that the status of the message is 'EXTRACT'.

At this moment, Maximo will download the associated record stored in the MAXINTERROR and MAXINTERRORMSG tables, and write an XML or FLAT file to the global directory.  For example:

\\machinename\appdata\globaldir\errorextract\YOURINTERFACENAME\flatfiles

or

\\machinename\appdata\globaldir\errorextract\YOURINTERFACENAME\xmlfiles

The user that creates these files and needs access to this directory is the user running your WebSphere processes.

Once this file is created in this directory successfully, Maximo then delivers the file to the client browser for saving and the user can save it to a location on their pc.

The file is then removed from the file system automatically.

Now the user can correct the file contents, and navigate back to the external system application/enterprise service, and import the corrected file. No changes to the file format are necessary, and must include all the original data and file name.

If the import of the file succeeeds and Maximo is able to process the message, the corresponding error message is removed from the continuous queue and the message is no longer available for extract.

Important points to note:  If the MAXINTERROR and MAXINTERRORMSG tables have been truncated while there were messages available for extract, attempting to download those messages will result in a error HTTP 404 - file not found.  This is also true if the user running WebSphere processes cannot read/write/modify files found in the directory defined by the Maximo system property mxe.int.globaldir.

I hope I have helped you in understanding how File Based Error Management works and is used for Maximo.  Feel free to post a message if you would like additional information on this topic.