Scripting With Maximo - Bruno Portaluri

are based on the explicitly defined variables whose binding type is a Mboattribute. There are no implicit variables for explicitly defined variables of otherbinding types like – Literals, Maxvars and System properties. Below is the list ofthe implicit variables. Assume “var” is the explicitly defined variable that binds toa mbo attribute.NameTypeDescriptionApplicabilityvar requiredBooleanRequired flag ofthe mbo attributethat var binds to.All launch points.The script canmodify it providedthat var is of typeOUT or INOUT.var readonlyBooleanReadonly flag ofthe mbo attributethat var binds to.All launch points.The script canmodify it providedthat var is of typeOUT or INOUT.var hiddenBooleanHidden flag of thembo attribute thatvar binds to.All launch points.The script canmodify it providedthat var is of typeOUT or INOUT.var internalSame type as the For synonymmbo attribute todomain kind ofwhich var binds to. mbo attributes [likestatus] thisrepresents theinternal [maxvalue]value for the mboattribute.All launch points.Applicable only ifvar is bound to ambo attribute thatbinds to asynonym domain.The script cannotmodify it.var previousSame type as the The previous valuembo attribute toof the mbowhich var binds to. attribute ie thevalue just beforethe attribute valuegot changed.Attribute launchpoints – applicableonly for theattribute thatgenerated theevent. The scriptcannot modify it.var initialSame type as the The initial value of All launch points.mbo attribute tothe mbo attribute The script cannotwhich var binds to. ie the valuemodify it.assigned to thatattribute when thembo wasinitialized.

Namevar modifiedTypeBooleanDescriptionIndicates whetherthe mbo attributeto which thevariable var bindsto has beenmodified or not.ApplicabilityAll launch points.The script cannotmodify it.We will cover more about them using examples as part of launch points section.Array VariablesLets talk a little bit about the array variables as that would introduce you to theconcept of Mbo Relationship Path [MRP].The MRP format is an extension of the current attribute path notation. Thecurrent mbo attribute path notation supports the dot “.” to allow traversing relatedMbos and fetching attribute value from them. An example of the current format isshown below [the examples are based of the PO mbo]:poline.pocost.costlinenum – which gives us the first POLINE’s [the relation nameis POLINE] 1st POCOST’s [the relation name is POCOST] colstlinenum attribute.ORpoline[i].pocost[j].costlinenum - which gives us the i th POLINE’s [the relationname is POLINE] j th POCOST’s [the relation name is POCOST] colstlinenumattribute.The MRP notation builds up on this attribute path notation. The one fundamentaldifference being that MRP leads to a List/Array of Mbo attributes. For example ifwe take the examples above an MRP may look like:poline.pocost.costlinenum* – which give us a combined list or array of POCOSTmbos for all POLINEs.poline[linecost 100].pocost[percentage 100].costlinenum* – which gives us allcostlinenum's where the POCOST mbos has percentage 100 for all POLINEswith linecost 100. This is effectively filtering the relation clause [poline andpocost] to sift only those mbos that satisfy the specific condition. This cangenerically be represented by *

where condition1 and condirion2 can be a Maximo condition or a raw SQLwhere. As you must have already noticed – the * at the end of this notationindicates arrays as opposed to just a scalar value.Consider another variation of this as shown h implies costlinenum from all i th POCOST of every POLINE that satisfiescondtion1.We see that the content with the brace ‘[‘ and ‘]’ can be overloaded in 3 differentways.1. It can be a number signifying an array index.2. It can be a Maximo condition which can be prefixed with the cond:3. Can be a raw SQL whereNow let’s take into consideration the different scenarios/context of this MRPevaluation. Note these cases described below can be mixed in a MRP as part ofthe different relation tokens.MRP with no filterThis is a MRP where none of the relation tokens has any associated filter. This isthe simplest case where the MRP looks like R1.R2 where R1 and R2 arerelation names and there is no associated filter clause with these relations. Inthis case the evaluation would involve just iterating over the content of R1 andR2 MboSets and preparing a list of R2 mbos.MRP with index filter:This is a MRP where one or more of the relation tokens has an associated indexfilter. This is the case where the MRP looks like R1[index1].R[ ] . where arelation token [one or more] has index filter for that Mboset identified by therelation R1 use the Mbo at index “index1” for the MRP evaluation. This is an inmemory filtering and does not impact the state of the MboSet on which the indexfilter is getting applied.MRP with condition filter:This is a MRP where one or more of the relation tokens has an associated filterwith a Maximo condition. This is another example of in-memory filtering wherethe MRP looks like R1[cond:c1].R2[ ] where c1 is a name of a Maximocondition and cond is the prefix indicating it’s a Maximo condition. Theevaluation is based on in memory filtering of the Mbos in MboSet R1 based onthe condition c1 and does not impact the state of the MboSet on which the filteris getting applied.MRP with a where filter:This is a MRP where one or more of the relation tokens has an associated filter

with a where clause. This amounts to appending an additional where clause tothe existing relation clause. This definitely would cause the related MboSet resetto be called and while it might work for certain cases it definitely would result isunpredictable output for interactive user sessions [user browsing an app]. Theimplementation should use temporary relations created dynamically to replaceeach of the relations associated with such a filter to evaluate this MRP. So forexample if the MRP was R1[where].R2.R3[where] the implementation shouldreplace [transparently] R1 and R3 with temporary relation names with the samerelation clause as their original counterparts. This will work only if all the Mbosreferred by the MRP relation tokens were not toBeSaved() their in memorystate represents their state at the persistent store.One thing to note here is – its always recommended to just use the predefinedrelationships as opposed to dynamically adding filters to the relationship justkeeping performance in mind. The reason is – in case we need to access thisvariable more than one times – the evaluator will always create a temporaryrelationship between the src and the target objects. This however will prevent theusage of a cached relationship set from the origin mbos.The where clause approach will append the where clause condition. The thecondition approach will filter the MboSet in memory without firing a sql whereclause for the added filter. This however will take more time to sift than using theSQL clause. The conditions application can be used to define the filter confitions.LaunchpointLaunchpoints are what we call the application customization points.Launchpoints define which application artifact the user wants to customize byattaching the script to that point. In effect the script is executed [launched] in thecontext of a launchpoint. For example if the user wants to customize the Assetmbos initialization routine the key words Asset mbo & initialization routinedefines that launchpoint. Another example might be that the user wants tocustomize the Asset mbo's purchaseprice attribute's field validation routine. Herethe key words that define the launchpoint are - Asset mbo, purchasepriceattribute and field validation routine. So in effect a launchpoint is aconfiguration to identify what application point we are trying to customize. Ascript can be associated with 1 or more launchpoint at the same time. Forexample a generic site level validation script can be associated with all site levelobjects in Maximo – where each association is defined as an individuallaunchpoint. A script can be associated with launchpoints of the one and onlyone type. For example a script associated with the Object launch point cannot beassociated again with another attribute launch point. Once the first association isdone between a script and a launch point – all subsequent launch points have tobe of the same type as the first one.Now lets take a look at the launchpoints [aka customization points] touched up

by the scripting framework. Below is the list of the points supported currently.1. Mbo initialization and save point logic [aka Object launchpoint].2. Mbo attribute value modification – validation and action logic [aka Objectattribute launchpoint].3. Actions – which are used by a multitude of other components likeWorkflow, Escalation, UI Menu, UI Buttons [aka Action launchpoint].4. Custom conditions – used by Workflow conditions, Conditional UI etc[aka custom condition launchpoint].Launchpoints are what you think of first when you want to customize anapplication. No wonder all the wizards in the Script app starts with defining thelaunchpoint. Next lets explore the individual point types to understand what theybring into the table for customizers and deployers.Object Launch PointFirst in our list is the object launch point. This launchpoint lets you invokescripts for the Mbo events – init and save point ones [add, update and delete]. Alaunch point can be configured to listen to one or more of these events at thesame time. The script will have access to the event Mbo [via implicit variable“mbo”]as well as all the related Mbos. The initialization event based scripts canbe used to set calculated fields, set fields as readonly/required/hidden or setconditional defaults to mbo attributes. The save point event based scripts can beused to implement save point object validations as well as save point actions.Below is an example that will demonstrate a initialization point script and the nextone would demonstrate a save point script.So lets take the use case in mind before we jump into the code andconfiguration. Suppose we want to customize the Asset application to display thetotal spare part quantity in a new non-persistent Asset object attribute calledsparepartqty. This boils down to the requirement - whenever an Asset mbo getsinitialized the sparepartqty will display the sum of all the spare part quantitiesassociated with that asset. So based on our knowledge of launch points we getthat it will be a Object Launch Point for the object Asset and we need to attachthe script to the initialization event of the Asset object. To do this we need tolaunch the “Create Scripts with Object Launch Point” wizard as shown below.

Once the wizard is launched the first thing we do is to create a launch point asshown below. Note that the “initialize” event is what we want to use for launchingthis script.So now lets look at the variables we might need to do this customization. First ofcourse is a variable called sptqt which binds to the new Asset mbo attributesparepartqty. Now we only intend to set the value of this attribute and hence thisvariable would be of type OUT. Next we need to get all the quantities from therelated Sparepart Mbos of the Asset. To do that we use the array variablenotation * to get an array of quantity values from the related sparepart MboSet.Lets say the array variable is qtys and its bind value would be asset tosparepart relation name . attribute name * which is sparepart.quantity*. The *at the end of-course indicates the array nature of this variable and also instructsthe framework to form the array using the specified relationship.

And as mentioned earlier array variables are always of type IN and that is perfectfor this as we are not modifying the quantities – we are merely summing that up.So with these basic variables defined we next would attempt to write the script asbelowif qtys is not None:sptqt sum(qtys)Basically a 2 liner which validates if there are infact sparepart Mbo's and if thereis then sum them up and set it to the sptqt variable. The scripting frameworkpicks that up and sets the value back to the binding of the sptqt ie sparepartqty.So the amount of Java coding done here is a BIG ZERO – its a pure jyhtonscript. Now going by the nature of the calculated fields – the sparepartqty shouldbe always read only. And what best place to set that to read only other than thisscript – which embodies the Asset initialization event. Below is the final scriptwhich adds the code to set the sparepartqty attribute to read only.sptqt readonly Trueif qtys is not None:sptqt sum(qtys)

Once you press the create button in the last wizard step to create the script – asuccessful creation of the script and the launch point will generate this responseas shown below.In case of a compilation error you would be forced to stay back on the last pagetill you cancell or fix this script.Here you see the magic of this implicit variable concept. When you bound sptqtto sparepartqty attribute the scripting framework injected at runtime not only thevariable sptqt but also some implicit variables like sptqt readonly, sptqt requiredand sptqt hidden each of which are of type boolean and caters to the read only,required and hidden flags of the Mbo attribute. Setting a mbo field to readonlyotherwise would have required java coding. A java code to do this samefunctionality would look like belowmbo.setFieldFlag(“sparepartqty”, MboConstants.READONLY, true);MboSetRemote sparepartSet mbo.getMboSet(“sparepart”);int i 0;MboRemote sparepartMbo sparepartSet.getMbo(i);double totalQty 0;while( sparepartMbo ! null){totalQty o sparepartSet.getMbo( i);}mbo.setValue(“sparepartqty”, totalQty, MboConstants.NOACCESSCHECK);So by this time you must have figured out what amount of pain the scriptingframework has saved you!. Dont just think in terms of the lines of code [which isalmost a 1:2] think also about the api knowledge that you would need for thissimple task. And this code does not even address the pain that you will gothrough to attach this code to the Asset Mbo's initialization routine. There yourchoices are even more hairy – either you would have to extend the Asset mboand override the init() method of that mbo to put your code [in which case in thethe above code just replace the mbo variable with “this” pointer] or you wouldend up attaching your code as a listener to the Mbo's event – which is a separateapi stack on its own!. In the scripting framwork all these are taken care for youthe moment you have pressed the “Create” button to end your wizard [thussubmitting your script]. As a script developer you just code the logic – theframework takes care of the behind the scenes plumbing work to manage and

execute your script. So yes you will save time and money with this for sure.By the way the above java code would work [provided you do the jython syntaxstyling on it – like removing the ; and the curly braces and .] even inside theJython script – that is just in case you are an avid java programmer!. Just don'tforget to import the following before you submit the script from psdi.mbo import MboRemotefrom psdi.mbo import MboConstantsfrom psdi.mbo import MboSetRemotewhich is jython way of importing external java libraries. This shows that whilescripting framework gives tremendous power to script developers to get theirMaximo customization done without knowing Maximo apis – it does not takeaway the Java coding power from the developers who are used to that. Soeffectively you can invoke all the Maximo apis [for example make a Web servicecall to fetch some external data using the Integration framework] from inside ascript as long as you have imported them properly.Next lets move onto some save point validations which hopefully will helpdemonstrate more features of this framework. As before lets deal with the usecase first. The use case here is a need to customize the Asset mbo to enforce anaming convention for assets [assetnum] based on their types [assettype]. Thiseffectively boils down to the requirement that whenever we are creating Assetswe have to follow a naming convention for the assetnum. The key words hereare in blocks which help us identify the launchpoint type and the event point inthat type. Its an object launchpoint for the Asset mbos add event. So we use theObject Launch point wizard to create and deploy this custom logic. To start withwe need to figure out the variables and their bindings. From the requirement itsclear we need the 2 input values from the assetnum and assettype. So there are2 IN variables called anum and atype which are bound to those attributesrespectively. Those are the only 2 variables that we need to do this task. Belowis the script code [in Jython]def setError(prefix):global errorkey,errorgroup,paramserrorkey 'invalidassetprefix'errorgroup 'asset'params [prefix,assettype]if atype internal 'FACILITIES' and not anum.startswith('FT'):setError('FT')elif atype internal 'FLEET' and not anum.startswith('FL'):setError('FL')elif atype internal 'IT' and not anum.startswith('IT'):setError('IT')elif atype internal 'PRODUCTION' and not anum.startswith('PR'):

setError('PR')Here we define a jython function called setError which is responsible for settingthe error flags. We see the use of the variable name internal implicit variablewhich is applicable only for attributes which uses a synonymdomain. The variable name internal provides the internal value for that attribute based onits current external value. So this script uses the internal value of the assettypeattribute to establish the naming convention. For example Assets with assettype[internal] value FACILITIES should have assetnum starting with “FT” etc.This same code in java would have required to know the Maximo api to find theinternal value of the assettype using the Translator api as below.String domainId MXServe

Scripting is a new feature that was introduced in Maximo version 7.5 based on . figure out the appropriate script engine to invoke for processing the script. The value list for available script languages come from the providing script engines in the classpath. Its common for script engines to provide multiple alias or short