Overview This use case in this document show how the tooling provided with the products based on Tivoli s process automation engine can help you add value through product extensions and/or integration to other products. All features described below are available for Maximo Asset Management products and the Smart Cloud Control Desk solution. Use Case 2: Extending object/application to support a new object attribute and a validation for that attribute using either Scripting or Java. 9/11/2013 Page 1
Use Case 2: Extending object/application to support a new object attribute and a validation for that attribute using either Scripting or Java. Requirement There is a need to display the total of all available spare parts of an asset on the Assets application s main tab. Currently, the out of the box functionality does not include such a field and a user must access the Spare Parts tab of Assets application to count and total the available spare parts. Computing the total of all available spare parts must happen not only when the particular asset is first brought up on the main tab, but also on all subsequent changes to any of the individual spare part quantities. Solution A customization needs to be implemented that will meet the requirement. This customization includes: 1. Adding a persistent attribute to the ASSET MBO 2. Adding a field to the Assets presentation XML that is bound to the new attribute 3. Adding logic to compute the total of all available spare parts on an asset under different conditions Approach Adding a new attribute and updating the presentation XML are standard configuration tasks that can be implemented rapidly using the respective applications, namely, Database Configuration and Application Designer. However, the implementation of logic requires code to be written. Add SPAREQTY attribute to ASSET MBO A persistent attribute SPAREQTY of type DECIMAL with length and precision of 15 and 2 respectively are added to the product environment using the Database Configuration application. 9/11/2013 Page 2
Database is configured to apply the structural changes. NOTE: This attribute could be non-persistent as well so that the computations always happen in memory and the resulting total is never stored in the database. A disadvantage of the non-persistent approach is that for reporting purposes, the report will need to place similar computation logic against this custom attribute if it is to be presented in enterprise reports. I have chosen instead to persist the computed value. Add Spare Quantity field to the ASSET presentation A Spare Quantity field is added to the ASSET presentation on the Asset tab, as part of the asset header fields. Note that the field is marked read-only to prevent any edits by end users. 9/11/2013 Page 3
Programming the custom logic Each of the four options below demonstrates a certain facet of the customization approach: 1. Scripted object initialization with variables and binding: Programming the logic necessary to compute total of spare parts when the business object is being initialized. This ensures that when the asset record is brought up on the List tab or on the main tab of the Assets application, the current total is already computed. This particular programming approach uses automation scripting and script variables alone. No MBO APIs are utilized in this facet. 2. Scripted object initialization with MBO API: Programming the logic necessary to compute total of spare parts using APIs when the business object is being initialized. The execution context of this facet is the same as #1 with the exception that the automation script uses Maximo s public MBO APIs to retrieve and iterate the necessary data. 3. Scripted field validation with MBO API: Programming the logic necessary to recompute the total whenever the spare part quantity of an individual spare part changes. This ensures the total is re-calculated whenever a user changes an individual spare part s Quantity in the Spare Parts tab. With this particular approach, the automation script code uses Maximo s public MBO APIs to retrieve and set data. 4. Java field validation: Programming the logic necessary to re-compute the total whenever the spare part quantity of an individual spare part changes. This facet is the same as #3 except that it is implemented using pure Java and a field validation class. This approach therefore requires a build, deploy, application server shutdown and re-start to take effect. 9/11/2013 Page 4
#1: Scripted object initialization with variables and binding An Object Launch point ASSETSPARES is defined using the Automation Scripts application. In Step 1 of the Object Launch point wizard, the Active flag is turned on, the Object ASSET is selected, no Object Event Conditions are associated, and the Event Initialize is chosen. In Step 2 of the wizard set the Script name ASSETSPARES; set the Language to python and Log Level default to ERROR. Two variables are added into the Variables section of Step 2: 1. v_sparearray representing the array of Spare part quantities that we need for computation. v_sparearray is therefore an IN variable. 2. v_spareqty representing the computed total to be set back into the new SPAREQTY attribute of ASSET MBO. v_spareqty is an OUT variable returned from the script. 9/11/2013 Page 5
IN Variable OUT variable 9/11/2013 Page 6
The bindings for the two variables are shown on this table: Variable Binding (Launch Point Remarks Attribute field in UI) v_sparearray SPAREPART.QUANTITY* Array of quantity ( the * identifies that it is an array) values retrieved from the SPAREPART MBO by traversing the ASSET to SPAREPART using relationship SPAREPART v_spareqty SPAREQTY Computed total spare parts value set back into the ASSET MBO s SPAREQTY field. By checking the Suppress Access Control flag for this variable we ensure that the script can set the value even if it has been marked read-only In Step 3 of the wizard, the actual programming logic expressed using Jython syntax is placed into the multi-line text box. For readability, Jython code should be authored in Eclipse (with PyDev plugins) or with Notepad++ (with built-in support for Python language). One can use other favorite code editors. Code is then copy-pasted into Step 3 or into the Automation Scripts Code field. Generally, I place print statements at beginning and end of script to serve as a debug device. These statements are output to the log file based on the level of logging configured for Automation Scripting. The logic is very simple: 1. Ensure v_sparearray is not empty (line 2). 2. Iterate through the array (line 4). 3. Compute the running total (line 5). 4. Store the total in the v_spareqty variable (line 7). After the wizard completes, this customization is live and can be tested immediately. 9/11/2013 Page 7
#2: Scripted object initialization with MBO API With this approach, no script variables and bindings are utilized. An Object Launch point ASSETSPARESAPI is defined exactly the same as with option #1. No variables are defined in Step 2. In Step 3, the following code is copied / typed in: The code shown above implements the same computation logic as the script in option #1. The difference is that MBO APIs are employed here to iterate, retrieve and set data values. The logic is again straightforward: 1. A handle to the SPAREPART MBO set is obtained (line 1) Note: SPAREPART specified on line 1 is the relationship name used from the ASSET MBO to the SPAREPART MBO. 2. A check is performed to determine we have a valid handle (line 2). 3. The records (objects) in the set are counted (line 3). 4. The record set is iterated (line 5). 5. For each record (object) in the record set, the Quantity value is retrieved (line 6). 6. The retrieved Quantity value is added to a local variable totalqty (line 7). 7. The computed total is set back into the ASSET MBO s SPAREQTY attribute (line 8). Comment [CG1]: At first I tried to say The number of records is counted but it seemed better to say The records in the set are counted. Had an issue with subject-verb agreement in the original wording. The difference between options #1 and #2 is the knowledge required of Maximo s MBO APIs to retrieve record sets, iterate record sets and get and/or set values from / to a particular instance of an object (record). In most cases, the choice to use option 2 over option 1 is made based on whether or not the implementer has a reasonable knowledge of the Maximo MBO APIs. 9/11/2013 Page 8
#3: Scripted field validation with MBO API With this approach, a custom field validation is implemented which is triggered as soon as a user types a value into the Quantity field of the Spare Parts section of the Spare Part tab. Thus this field validation does not operate directly against the ASSET MBO; rather it operates against the QUANTITY attribute of SPAREPART MBO that was just modified. An active Attribute Launch point ASSETSPARESFLD is defined against the SPAREPART MBO and the QUANTITY attribute of SPAREPART using Step 1 of the wizard. In Step 2 only the Script name is provided, ASSETSPARESFLD. Other fields are defaulted. No variables are added. In Step 3, the following code is added: Explanation for the code: 1. The computation is performed only if the entered quantity is greater than zero (line 4). 2. From the current MBO (SPAREPART), the code jumps to the owner MBO (ASSET) using the getowner() public API (line 5). 3. Code checks whether the owner handle is null (line 6). 4. Code retrieves the current value of the ASSET MBOs SPAREQTY attribute. It uses the getfloat() method since the DECIMAL value must be retrieved (line 7). 5. Once retrieved, the code adds the newly entered Quantity value from the Spare Parts tab into the ASSET MBO s total SPAREQTY (line 8). 9/11/2013 Page 9
6. When setting the computed value back into SPAREQTY, the code applies a security flag ( NOACCESSCHECK ) to ensure the computed value can be set back into the attribute. Hence, the first line of the code imported the MboConstants class, which contains declarations for a number of such flags. 9/11/2013 Page 10
#4: Java field validation With this approach, Java is utilized and a Java class is authored to implement the same field validation logic that we implemented in option #3. Several steps are required to complete this customization: 1. Author the Java class that implements the field validation logic to re-calculate the total spare quantity when individual quantity is updated. 2. Compile the Java class and run the standard Maximo build to prepare the EAR file. 3. Use the appropriate deployment procedure to deploy the EAR into the application server. 4. Re-start the application server and log back into Maximo as an administrator. 5. Open the Database Configuration application and find the attribute (QUANTITY, in our example) to which the field validation class should be attached. 6. Type in the fully qualified name of the field validation class and save the configuration. 7. Configure the database to apply the change. The implementation of the Java class includes this code: 9/11/2013 Page 11
Explanation: 1. The FldSparePartQuantity class lives in a Java package called com.ibm.custom which reflects the fact this is a customization (line 1). When this Java source file is added to the development project, it is placed under a folder structure businessobjects\classes\com\ibm\custom to match the Java package. 2. The FldSparePartQuantity class extends a MBO framework base class MboValueAdapter (line 10). The MboValueAdapter base class provides a field- 9/11/2013 Page 12
level listening capability and is typically overridden to incorporate validation logic. 3. The action() method of the base class is overridden (line 19). The action() method is used to perform specific actions after the data in the field has been validated with the validate() method. In our example, we are not performing true data validation on the entered quantity field. Instead, once the quantity field is updated, we want to simply re-calculate the ASSET MBOs SPAREPART field. The action() method is the appropriate implementation approach. 4. The remainder of the re-calculation logic appears lines 21 through 33. The code here is almost identical to the approach used for #3 option. Additional handling is needed to deal with the float data type. NOTE: This field validation class implementation is a simplified example. Depending upon the business requirement, other field validation classes may implement (override) additional methods, throw exceptions, and so forth. 9/11/2013 Page 13