Upgrading Maximo Plug-in Version 4.1 to 4.2
From DataSplice
Version 4.2 of the Maximo plug-in introduces significant API changes compared to previous versions. These changes make calling functions in Maximo easier in the long run, but they do require changes to be made in order for older views to work after an upgrade.
Contents |
API Changes
Two basic changes were made to all of the method calls:
Record Identifiers
The plug-in now consistently uses record id fields to identify which values in Maximo to work with. So instead of keying off Work Order and SiteID in the work order view, everything is uniquely identified by WorkOrderID. This resolves issues where multi-site lookups did not always work properly, and should result in some minor performance improvements.
This adds an MBO Key Attributes section to the plug-in configuration:
For most of Maximo applications, the key attribute is the name of the MBO appended with ID (for instance, WORKORDER -> WORKORDERID, LOCATIONS -> LOCATIONSID, etc.). Any MBOs that do not follow this pattern and are going to be accessed by DataSplice need entries in this collection to identify the name of the key field.
Field Name Mappings
Previous versions of the plug-in applied changed values from the current record context to many of the transactions being performed. For instance, the UpdateWorkorder function only passed the work order number and some information about changing the status to the method. Any changes to additional fields were automatically determined from the context.
This had the advantage of the plug-in automatically trying to figure out the right thing to do, but it was often difficult to figure out exactly what was being changed, and it was almost impossible to chain together multiple Maximo updates in the same DataSplice event. The new method is much more explicit and consistent.
With version 4.2 of the plug-in, the Field Name Mappings section in the plug-in options has been removed and replaced with a collection of additional attributes that are to be explicitly applied to during the transaction. This allows field order dependencies to be handled easier, and allows multiple modifications in Maximo to be called from the same event without complicated workarounds.
Updating Views
Each view that invokes functionality in the Maximo plug-in (commits changes back to Maximo) will need to be inspected and updated to work with the new plug-in API. Read-only views are not affected by the changes and can be left as-is.
Identify Plug-in Function Calls
Each Call Plug-in Function action that references the Maximo plug-in will need to be inspected. These will typically by in the InsertRecord and UpdateRecord events. The following steps need to be performed for each function call:
Update Key Field Parameters
The parameter bindings for the key fields will probably be blank because the parameter names have changed since the previous version. These need to be set to the appropriate key field for the MBO in question. In most cases this field will already be part of the view query, but in some cases it might need to be added to the SQL statement (InventoryID was not part of several inventory views and might need to be added for instance).
The other parameter bindings should not have changed from the previous version and their settings can be carried forward.
Add Mappings for Editable Fields
Finally, identify the additional fields in the view that are editable by the user and need to be passed to Maximo. This list might be dependent on the event in question (for instance, more fields are typically editable during insert than with an existing record).
These values are then passed to the plug-in method as a variable collection of values to be applied to the MBO associated with the function. The specific details depends on the method in question. For instance, with UpdateWorkorder the values are applied to the work order record. With the transaction methods like CreateInventoryTransaction the values are applied to the newly created transaction record (MATUSETRANS, MATRECTRANS, etc.).
Each Maximo attribute that can be modified by the user needs to be added to the list along with the value from DataSplice to use. This allows fine-grained control over the values that are passed to Maximo. For instance, when creating a new work order the following values might be passed:
The settings for a new inventory transaction are considerably simpler - these values are applied to the new MATUSETRANS record:
- The attribute names refer to the Maximo columns or calculated fields to set. They are not case sensitive.
- Built-in Maximo attributes as well as custom attributes can be specified in the list.
- Attributes are applied in the order listed in the collection. This allows control over order-dependent operations with the MBO.
- This does not bypass Maximo permissions, so setting read only fields will result in an error.
- The values passed to the attributes can be DataSplice expressions or hardcoded values instead of references to the current record if needed.
Additional Changes
In addition, several methods were renamed or reworked slightly to present a more consistent API.
Issuing Rotating Inventory
The CreateInventoryTransaction no longer supports issuing rotating items. CreateRotatingInventoryTransaction was added to support the additional data needed for those transactions.
If both types of inventory are needed in a view, two plug-in function references will be needed in the event chain using the rotating field as the condition of which method to call.
Setting Work Order Status
The SetWorkOrderStatus method was removed. This functionality is available through the UpdateWorkOrder method, which has parameters for changing the work order status. If the status parameters are left blank the status is not changed and only the attribute settings are applied.
Asset Modification Functions
The CreateAsset method was removed and the functionality merged into the UpdateAsset method. If the AllowCreation flag is set to true and the referenced asset does not exist, a new record will be created. This mirrors the functionality with the UpdateWorkOrder method.
