The Maximo Integration Plug-in enables the DataSplice server to connect to a Maximo Application Server. Maximo versions 5 and later are supported. Note that the same plug-in can handle the various versions of Maximo, but different configuration files (Views, etc) are needed because of the schema differences between the versions.

The plug-in uses Java Remote Method Invocation (RMI) to communicate with a Maximo Application Server, which ensures that all transactions are processed in a way that respects user permissions, customizations, etc.

Additional Installation Steps

Several steps need to be performed prior to starting the DataSplice server. These can be performed after the server has been started - just remember to restart the service afterwards.

Copy Initial Configuration Files

The plug-in ships with initial configuration files that provide a default configuration for various versions of Maximo. These files need to be manually copied for initial installations. Navigate to the Server\Resources\Maximo <Version> Storage\DS <Version> and copy the contents into the root Server\Storage\ folder. The <Version> numbers refer to the corresponding version of Maximo (6.x or 7.x) and the version of DataSplice being used (3.1 or 3.2)

When upgrading the plug-in, the files can also be copied to use updates from the base package. Care must be taken to not overwrite local configuration changes however.

Run TSQL Script for SQL Server

If using the SQL Server version of Maximo, a function needs to be installed to allow DataSplice to recursively fetch hierarchical location records from the database. The script Server\Resources\Scripts\Func_DS_GetSubLocations.sql needs to be run against the Maximo database using Query Analyzer or another database utility.

Recompiling RMI Stub Files

RMI communication relies on stub classes to work over the network, and in some cases these are not up to date, which causes problems with the .NET to Java interface used by the plug-in. Unfortunately it is difficult to tell if the files are out of date, but this will result in errors like "Method '<method>' in type '<type>' from assembly 'transientProxies', Version=0.0.0.0, Culture=neutral, PublicKeyToken=null' does not have an implementation" or "The invoked member is not supported in a dynamic module" when trying to commit transactions to Maximo.

Refer to the Recompiling Maximo RMI Stub Files document in the addendum for instructions on recompiling these classes.

Setting Up the Java Classpath

The Java environment used by the plug-in will need to be able to access the various MBO Java classes that are passed across the RMI connection. This option uses the standard Java syntax for classpaths, which on Windows machines consists of various paths separated by semicolons (;). We recommend creating a <InstanceRoot>\Classpath\ folder to contain the jar files needed to access Maximo. It's possible to reference files anywhere on the file system, it is usually easier to keep them in one spot.

The classpath must contain the various psdi.* classes that implement the MBO layer. These can be referenced in two ways:

JAR File

Use the Java jar utility to create an archive of the MBO classes (jar vcf psdi.jar psdi\*) and copy this file to the DataSplice server. This will need to be updated every time Maximo is patched or the class files are otherwise changed.

Parent Directory Reference

Reference the folder that contains the psdi classes. This is used primarily when DataSplice is installed on the same machine as Maximo, and allows the plug-in to directly reference the class files used in the Maximo hierarchy. Note that referencing network paths is fairly unreliable and should not be used.

In addition, if the MBO objects have been customized to use classes in addition to those in the above jar packages, those might need to be added to the classpath.

Additional configuration for Maximo 7

Use Java version 1.6 for Maximo 7

For Maximo 7 the DataSplice server will need the javax.mail package mail.jar available from Sun in it's CLASSPATH. Also, log4j jar must be in the server's CLASSPATH. Log4j can be found on the Maximo deployment server, your version may vary but a typical location is c:\Maximo71\applications\maximo\lib\Log4j-1.2.13.jar

Application Server Security (LDAP Integration)

Refer to the Maximo Application Server Authentication document in the addendum for details on the additional configuration steps needed if Maximo is not configured to use its built in authentication mechanism.

Initial Configuration

Once the installation steps are complete and the DataSplice service is started, the following steps are typically used to configure the plug-in:

1. Create an ADO.NET connection profile named maximo that connects to the target database.
   
2. Specify the correct Java Runtime Environment to use by providing a value for the JVM DLL Path option. The list will display all the runtimes registered in the Windows registry, or you can specify a different runtime by copying the full path to a jvm.dll.
3. Update the Java Classpath option to reference the necessary Java classes.
   
4. Provide values for the Maximo Server Name, User Name, User Password, and Site (5.x only) options that will allow the DataSplice to connect to the target Maximo application server.
5. Select maximo for the Maximo Database Connection Profile option.
   
6. Save any changes. This may take a minute or so to process in some cases.
7. Verify that the Plug-in Status Message does not contain any initialization errors. In some cases the server must be restarted for changes to take effect, which will be indicated in the status message.
8. Update role membership by adding Maximo security groups and users the the desired roles. More information is provided in the Role Base Permissions section.
   

Basic Settings

The following settings control how the plug-in interacts with Maximo:

Plug-in Status Message

This option prints various status and diagnostic information regarding the status of the plug-in in. The contents are particularly useful for troubleshooting connectivity problems.

When a connection has been established successfully, the status of all the internal sections will be Ok:

Maximo Version MAXIMO Application Server 6.2.3 Build 209 DB Build V600-664 [majorVersion = 6]
Plug-in Status = Ok
Java Interop Status = Ok
Java RMI Communication Status = Ok
Java RMI Communication Status Details
RMI host = maxdev1 port = 1099 searching for object name = MXServer
   List RMI Registry:
      found RMI object = MXServer

ADO.NET Database connection using connection profile = maximo
Database connection Ok

Field Name Mapping

Many of the methods exposed by the plug-in attempt to automatically apply changed values to Maximo when transactions are committed. In order for this to work, the plug-in needs to know how to map the fields in the DataSplice views to the corresponding attributes in Maximo.

Explicit mappings are not needed if the names are the same ignoring spaces and text casing (for instance, "Start Date" and "STARTDATE" are automatically associated). Mappings are typically global and will apply to all views, but view-specific mappings can be added by specifying the key like <View Name>::<Field Name>.

In general, this needs to be updated if extra fields, etc. are added to the DataSplice views and are editable. Add an entry for each field that maps DataSplice field to the corresponding Maximo attribute name.

MBO Update Settings

This section is used to control which attributes are dynamically generated by Maximo when creating new records.

The default values for this section do not need to be modified in the majority of installations.

This section defines attributes for users and groups when they have corresponding permissions available in Maximo, which are later referenced by the views to enable various functionality. This section applies to Plug-In version 4.1.175 and lower. Version 4.1.176 (and up) utilize the internal DataSplice roles to define the security attributes (see Security Attributes by Role).

Security Attributes by Role

MAXIMO

The MX_HAS_PERMISSION attribute is defined with place holders for the Application and Option filtering. This allows for additional attributes to be defined by referencing the MX_HAS_PERMISSION attribute while passing in the desired application and option values to check.

For example: we can define a new work order attribute, MX_CAN_CREATE_WO as := ${MX_HAS_PERMISSION('WOTRACK','INSERT')}

Additionally, there are 3 attributes required for proper execution of DataSplice. Typically, these attributes are predefined and set when installing the Plug-in. However, how these attributes get defined (and where) has changed between version 4.1.150 and 4.1.151. Thus, when upgrading from version 4.1.150 (or lower) to version 4.1.151 (or higher), the administrator may need to create the following attributes in the MAXIMO role.

If the "People" view is available in the Support section of views, then the attribute definitions needed are;

If the "People" view is NOT available in the Support section of views, then the attribute definitions needed are;

Administrators can copy the new views added in version 4.1.151 from [Root DataSplice]\Server\Resources\Maximo [version 6 or 7] Storage\[v3.1 or v3.2]\Views\Maximo\Support

1. People
2. Site Info
3. User Preference

MAXIMO Condition Monitoring

MAXIMO Inventory

MAXIMO Work Order

Troubleshooting

The plug-in is distributed with a couple of scripts that can help diagnose connectivity problems with Maximo. These are contained in the <Instance Root>\Server\Resources\JavaTest\ folder. The scripts run simple Java applications that are completely independent from DataSplice, and are useful for distinguishing problems with the DataSplice configuration vs. issues with the associated Maximo services.

The scripts contain several path variables to reference Java and the Maximo class files. Edit these values and then run the scripts to test the functions. Typically these should be run from the machine the DataSplice Server is installed on to verify that the appropriate services are available.

RMI Services Test (run_RMITest.bat)

This script connects to the specified RMI service and prints out the exported objects. This tests that 1) the RMI services are accessible and 2) the desired Maximo server instance is available. The list of exported objects should contain the instance referenced in the Maximo Server Name option, and if this is not the case the plug-in will not be able to initialize.

MBO Connectivity Test (run_MaximoDsTest.bat)

This test attempts to establish a session with the Maximo application server and access data in one of the MBO objects. Again, if this test is not successful then the plug-in will not have any chance of working correctly.

RMI Class Errors

In some cases, error messages will be displayed when committing transactions to Maximo with the following messages:

• Method '<method>' in type '<type>' from assembly 'transientProxies', Version=0.0.0.0, Culture=neutral, PublicKeyToken=null' does not have an implementation 
• The invoked member is not supported in a dynamic module

This is an indication the one or more RMI stub classes is out of date and needs to be recompiled. Refer to the Recompiling Maximo RMI Stub Files document in the addendum for instructions on recompiling these classes.