This document is intended to take the reader through a use case of how you can leverage the tooling provided with the Maximo products in order to add value through product extensions and/or integration to other products. All Maximo features described below are also available as part of the SCCD solution.
Use Case : Extend the Asset object with 3 new attributes, make those attributes available in the UI and enable those attributes to be updated from another application using integration.
This use case will hi-light the following capabilities:
Enabling new attributes to be part of a SOAP-based web service for update by an external system.
Adding new attributes to the Maximo Asset Object At the start of this type of integration, the first step is to identify what object is the appropriate one to extend. Often this is decided based on the application you want the additional attributes to be available from. There are a multiple ways to determine which object(s) is connected to an application, below are two:
a. Identify the Main object of the application using Application Designer app. Note: columns from other objects are likely to be used with the application.
b. Using field help by placing cursor into a field and hitting Alt/I
Once you have identified the object that you wish to extend, you then can use the Database Configuration application to add your attributes to the business object and its underlying table in the database.
When you define a new field you can set properties such as data type, length, title (label that is displayed in UI) and default value. Depending upon your requirements (if field is not read-only), you may want to define an associated domain to control the values allowed or provide a Java class and/or script that contains validation logic for the field.
After you have defined the new fields, these changes must be applied to the database by setting the system into Admin Mode and then running DB Configure. When completed, you need to exit Admin Mode and your fields should be available in the ASSET Maximo Business Object (MBO) and defined in the underlying ASSET table in the database. At this point you can now configure the Asset application to display the new fields that you added to the ASSET object.
If you plan to develop new business objects, there is additional information at this link: https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20Maximo%20Asset%20Management/page/Maximo%20business%20object%20development.
Enabling the Asset application to display new attributes The Application Designer application allows you to configure the UI for existing (or new) applications. You can add new fields to the UI, move the location of existing fields or remove UI fields from the application.
For more detailed information on customizing the Maximo UI, see the following: https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20Maximo%20Asset%20Management/page/Configuring%20the%20user%20interface
For our use case, we will add the 3 new attributes created earlier to the Asset tab of the Asset application.
To add a field, select the section you want to add field to. One way to add a field is to select an existing field in that section and right click and select Copy. Then if you right click and select Paste a new field will be placed directly below the selected field:
Once the new field is on the canvas (above), you right click on the field and select Properties. Perform a look up on the Attribute field and select your new field by entering the field name and object name in the Select Values dialog (below).
After the attribute is selected you can then provide additional information such as a customer field Label and Input Mode.
You can then repeat this process for all the fields you plan to add.
Enabling new attributes for integration
Now that the 3 new attributes are part of the Asset object and visible in the Asset application, you are now in position to provide data for those attributes using integration.
To support updating a fields using integration, the fields must be configured as included within an existing object structure. Since our new fields are persistent (saved to the DB), these fields would automatically become part of any object structure that has the ASSET object wthin it. For our use case will we assume that we plan to use the MXASSET object structure.
Now that we know the object structure supports the new fields we added, the next step is to decide how to integrate data into those fields. There are multiple options that an integration can leverage, often times this is decided based on the capabilities of the external system that is integrating with Maximo.
From a protocol perspective, let’s assume that the external application, by practice, prefers to integrate with other applications using SOAP-based messages (web service). Given that, this eliminates other possible options that the integration framework supports such as XML/HTTP, REST, DB tables, delimited files and XML files.
With the protocol set to SOAP, there are still 2 possible options, enable the object structure as a web service or configure an enterprise service on top of the object structure and enable that as a web service. Using the enterprise service provides the capabilities to push the message through a JMS queue (asynchronous processing) if desired and also provides the ability to implement customizations using the processing rules feature, Java or XSLT. In our case let’s say that the integration should be synchronous and there is no need for customization as the client will invoke the object structure web service with the correct XML format based on the Maximo schema. Using the Web Services Library application, an object structure web service will be created using the MXASSET object structure.
The screen below shows the web service created for MXASSET with the available operations.
The final step is to deploy the web service which will generate schema and WSDL files. Depending upon the customer implementation of the system, the web service may be deployed using the Axis SOAP engine (Product container) or using the application server (Application Server container). See this link for more information: http://pic.dhe.ibm.com/infocenter/tivihelp/v49r1/topic/com.ibm.mbs.doc/wsregistry/c_ctr_overview.html
Below is a screen shot of the step to deploy the web service:
When deployed, the WSDL and Schema files will be located in subfolders under the integration Global Directory (defined in system property mxe.int.globaldir). Depending upon property configurations, the schema file may resolve ‘included’ files to a single file (recommended) based on the setting of the mxe.int.resolveschema to 1 (true). The WSDL file can include the schema file if the mxe.int.wsdlincludesschema system property is set to 1 (true).
The object structure service schema is located at:
The web service is available to invoke at: http://hostname:port/meaweb/services/MXASSET
For all of the above, MXASSET represents the object structure name.
Now that the web service is deployed the next step is to create a SOAP client on the external system that can build the XML message according the Maximo schema and invoke the Maximo web service. You can retrieve the schema as mentioned above and also view a sample XML from the object structure application.
For the MXASSET object structure the XML could be something similar to below. This XML uses the ‘Sync’ operation of the service which will attempt to find the asset record and update it. When the Asset does not exist, the service will create the asset. The ‘key’ of the Maximo Asset that will be used to find the asset is the ASSETNUM and SITEID. These values must be passed in order to find an existing record. In the example XML below, the processing will attempt to find asset SAMPLE1 in site BEDFORD.
SAMPLE ASSET 1
Field 1 Value
Field 2 Value
Field 3 Value
If the record is found, processing will update these fields: DESCRIPTION, NEW1, NEW2 and NEW3. Any attributes (or other objects/attributes of the object structure) that are not provided in the XML are not updated. For records being created, many fields not provided in the XML are likely to be populated with a default value as configured in the business object.