Last Updated on October 29, 2023 by maximosecrets

An escalation is a background task that can monitor an object in Maximo and for the records where the condition evaluates to true it can notify you through a Communication Template or it can perform an Action. There is an Escalations application which is the focus of this article. Escalations are also embedded in a Service Level Agreement which I will discuss in a different article.

The Escalations application will be found in the System Configuration – Platform Configuration module. 

I have written a second article Escalations – Advanced Topics, which looks at validation, activation/deactivation, the associated Cron Task, the hidden table ESCSTATUS, the Communication Log, the effect of the Repeat checkbox, Duplicate and Delete Escalation, and finally the effect of the two sets of Calendar/Shift fields.

List Tab

The List Tab of the Escalations application shows us that there are several standard escalations that are based on a variety of objects, Invoice, Incident, Asset, SLA, Bulletin Board, etc. You can base an escalation on any persistent object, this is an object that is based on a table, part of the escalation is performing a query of the table to see if an event has occurred.

We’ll look at a few of the standard escalations to learn about the application.

Escalations with Single Escalation Point

A query on the object PURCHVIEW – Purchase Contracts, shows there are four provided escalations. There are two types of escalation we will look at:

• Escalation that monitors when a contract has reached its Start Date or End Date, and which has an action that changes status
• Escalation that monitors the contract renewal date and will notify you when it is approaching

For Purchase Contracts, the PURCTREFF escalation monitors the Start Date, and the PURCTREXPD escalation monitors the End Date. We are looking at the PURCTREFF escalation – Purchase contract start date has been reached and the status should be changed to approved.

• Applies To – This is the persistent object which will be queried to see if the event has occurred.
• Condition – This is the SQL Where clause that will be applied to the object/table to see if records evaluate to true. The symbol to the right of this field will launch the SQL Expression Builder (see later section). The expression shown is – STATUS=(select value from synonymdomain where domainid = ‘CONTRACTSTATUS’ and maxvalue = ‘WSTART’) – it is testing that the purchase contract current status is a synonym of WSTART – waiting to start, this is the status that occurs when you approve a purchase contract. This field is recommended, but it is not mandatory especially if the object contains a small number of records. The Escalation ESCBLTNEXP is based on the BULLETINBOARD object and it doesn’t have a condition.
• SiteA structural element of a Maximo database that is used for data separation. More/Organization – The Site and OrganizationA structural element of a Maximo database which is used for data sharing and is often aligned to a legal entity of an organisation. More fields are used for filtering; they are combined with the Condition field when the query is made. Access to the two fields depends on the level at which the object is defined. If it is a System level object neither field will be accessible. If an Organization level object as PURCHVIEW is, then only the Organization field will be accessible, the Site field will be read-only. For a Site level object, the Organization field will be read-only.
• Create Successful Execution Entry – A checkbox which when set will write entries to the ESCSTATUS table of type SUCCESS. The status of each record is SUCCESS or ERROR, errors are always written to the ESCSTATUS table.
• Last Run Time – The last date/time that the escalation ran.
• Active – A read-only field that is set by the action Activate/Deactivate Escalation. Only active escalations will execute.
• Schedule – The schedule on which the escalation will query the database (see later section).
• Calendar/Shift and Organization – Uses the calendar and shift to determine whether the escalation is in a period when it should execute.

Further down the Escalation tab is a section called Validation Results. The Validation field will show you any errors that occur when you use the Validate action. Errors can occur either at the Escalation header level or against an Escalation Point. This is discussed in the second article Escalations – Advanced Topics.

Escalation Points

Each escalation can have one or more escalation points, it needs at least one, otherwise when you go to activate the escalation you will receive the error “BMXAA1139E – Escalation 1055 cannot be activated because there are no escalation points defined.”.

• Escalation Point – A read-only field that increments when you use the New Row button. If you had created Escalation Point 2 and you used Delete Row button on Escalation Point 1 then the New Row button would be for Escalation Point 3. You cannot modify this field.
• Elapsed Time Attribute – A field that allows you to select a date or date/time attribute from the Applies To object. It is used in conjunction with the Elapsed Time Interval and Interval Unit of Measure. In the example it is set to STARTDATE – this means when the Purchase Contract Start Date is now in the past then process the specified Actions and Notifications.
• Escalation Point Condition – A SQL Where clause which further filters the condition under which this escalation is applicable. You should not repeat the SQL Where clause from the Escalation’s header in this field, just the additional conditions, both need to be true for any Actions and Notifications to be processed. Like the Condition field the detail button launches the SQL Expression Builder and shows the attributes from the Applies To object.
• Elapsed Time Interval and Interval Unit of Measure – The Interval is a decimal field with negative numbers being a time period before the Elapsed Time Attribute, and positive numbers being a time period after the Elapsed Time Attribute. The Interval Unit of Measure has a Select Value with values for SECONDS, MINUTES, HOURS, DAYS, WEEKS, or MONTHS. For example, -30 DAYS, would mean do something if time now is 30 days before the purchase contracts start date. Note, 1 MONTH is treated the same as 30 DAYS.
• Repeat – A checkbox that determines whether to repeat checking for the condition and/or time interval after the first time the condition is met. When set to not repeat (the default) if the condition is successful the escalation point will not run again.
• Calendar/Shift and Organization – Used in conjunction with an Elapsed Time Attribute to determine when Elapsed Time Interval has occurred. The elapsed time interval is calculated using the calendar and shift, it is not acting as a filter (see Escalations – Advanced Topics). 

Below the Escalation Points table window are two tabs for Actions and Notifications. You must have at least one action or notification as otherwise when you come to activate the escalation you will receive the error message “BMXAA1140E – Escalation 1041 cannot be activated because escalation point 2 has no actions or notifications defined.”

The Actions tab allows for one or more actions to be selected. When you do so Maximo always enters these against an Action Group. Often administrators will navigate to the Actions application from the Action Group field and create the action group and its member actions first, and then return with the value for the Action Group. 

You can use the New Row and Delete Row buttons, and modify the description of the action, but you cannot create an action only add an existing action to the action group. This is why you would navigate to the Actions application or do the creation of the Action Group and its actions in the Actions application before starting to set up the Escalation.

Notice the Action description should be specific. The Type is CHANGESTATUS, the Action’s Value field says what status, APPR in this case, but this field is not displayed.

It’s a similar story for the Notifications tab, one or multiple Communication Templates can be selected as the set of notifications. These are defined in the Communication Templates application and then selected in the Notifications tab.

You can create a Communication Template without navigating to the Communication Templates application by selecting a role from the Role/Recipient field then adding a Subject and a Message. Maximo will create the Communication Template in the background with the Recipient being sent to the To, rather than the cc and bcc fields. This is an unusual method, invariably you would navigate from the Template field to the Communication Template application, set up your record there, and then return with the value. This would be far more flexible, for example it would allow you to create a Communication Template that had multiple types of recipients or recipients that were not Roles, i.e. Persons, Person Groups or Emails.

In the example, the Communication Template is PURCTREFF and the role PURCHAGNTP resolves to the purchase contract’s Buyer field, attribute PURCHASEAGENT. The email Subject is “Contract :CONTRACTNUM is now effective” and when the email is sent the substitution variable will be replaced by the Contract Number. The email Message is “The effective date of contract :CONTRACTNUM has been reached and the status has been changed from WSTART to APPR.”

The PURCTREXPD escalation is similar except:

• the condition works against a contract at a synonym of APPR “STATUS=(select value from synonymdomain where domainid = ‘CONTRACTSTATUS’ and maxvalue = ‘APPR’)”, 
• the escalation point operates against the ENDDATE attribute,
• there is a different action group PURCTREXPDGRP with an action that changes status to EXPIRD,
• there is a different communication template PURCTREXPD.

The communication template has a different role CTRBUYERP which also resolves to the PURCHASEAGENT attribute on the contract. Two roles doing the same thing. I’ll highlight this as a problem, it is very easy to get multiple Roles and Actions that perform the same function. This is configuration metadata which will need to be transferred between environments, and it is worth having the controls in place to ensure that you are not effectively creating duplicates.

There are Escalations that similarly monitor the Start Date and End Date of the other types of Contract:

• Labor Rate Contract, LABCTREFF (Start), LABCTREXPD (End)
• Lease/Rental Contract, LEACTREFF (Start), LEACTREXPD (End)
• Warranty Contract, WARCTREFF (Start), WARCTREXPD (End)
• Master Contract, MSTRCTREFF (Start), MTRCTREXPD (End)

Escalation with Multiple Escalation Points

The PURCTRREN escalation monitors the purchase contract renewal date and has three escalation points that occur 90, 60 and 30 days before the value of the RENEWALDATE attribute. Notice the Elapsed Time Interval is written as negative numbers -90.00, -60.00 and -30.00.

The Escalation Condition in this case is “STATUS=(select value from synonymdomain where domainid = ‘CONTRACTSTATUS’ and maxvalue = ‘APPR’) and renewaldate is not null” – which means status is a synonym of APPR and there is a renewal date on the purchase contract.

There are no Actions, only Notifications for this escalation. For each of the Escalation Points the notification uses the same Communication Template PURCTRREN with the Role CTRBUYERP which resolves to the Buyer field (PURCHASEAGENT attribute) on the purchase contract.

It is worth repeating, each Escalation Point requires either an action or a notification.

The PURCTREXP escalation is very similar with three escalation points, but this time working 90, 60 and 30 days before the contract ENDDATE attribute with each escalation point using the PURCTEXP Communication Template – a notification that the contract will due to expire in 90, 60 or 30 days.

There are two similar escalations based on the Applies to object of ASSET:

• WARASSET – Provides a notification 90,60 and 30 days before a warranty contract is due to expire
• LEASSTDUE – Provides a notification 90,60 and 30 days before a lease/rental contract is due to expire

In both cases the Condition is for assets that have not reached DECOMMISSIONED status “STATUS!=(select value from synonymdomain where domainid = ‘LOCASSETSTATUS’ and maxvalue = ‘DECOMMISSIONED’)”.

There are three Escalation Points with an Escalation Point Condition that is doing something similar to the Elapsed Time Interval but in this case the Elapsed Time Attribute is not on the ASSET object and so the method we have seen earlier cannot be used. However, the SQL Where clause of the Escalation Point Condition can achieve this. 

“assetid in (select assetid from contlineasset where contractnum in (select contractnum from contract where status in (select value from synonymdomain where domainid = ‘CONTRACTSTATUS’ and maxvalue = ‘APPR’ and defaults = 1) and contracttype in (select value from synonymdomain where domainid = ‘CONTRACTTYPE’ and maxvalue = ‘WARRANTY’ and defaults = 1)) and warrantyenddate <= sysdate + 90)” – can be interpreted as – if the asset exists against a contract line (CONTLINEASSET) where the contract is at a synonym status of approved (APPR) and the contract type is a synonym of WARRANTY (which would not include Service Contracts) and the warranty end date is within 90 days of time now, then send the notification defined by Communication Template WARASTNOTF.

The other two escalation points are almost identical except they work when the warranty end date is within 60 days and 30 days.

Incidentally – I do not believe the defaults=1 clause is required in either case:

• On CONTRACTSTATUS this would be saying that if there were multiple APPR synonyms it should only work on the one marked as the default – why?
• On CONTRACTTYPE this would be saying that if there were multiple WARRANTY synonyms it should only work on the one marked as the default – why again?

And on another point – always consider the performance of Escalations. The applies to object is ASSET and there could be many thousands of assets that are not decommissioned and for each of these it needs to evaluate whether three escalation points conditions are valid or not, this could create a performance issue. Why not make the Applies To object CONTLINEASSET which is bound to have fewer records than ASSET? In that way the Elapsed Time Interval of WARRANTYENDDATE could have been used.

The reason for making this escalation based on ASSET is I believe historical. When Escalations were first stripped out of Workflow in Maximo v6 it was based only on main level objects and so CONTLINEASSET could not have been selected.

Expression Builder

The SQL Expression Builder will be found next to the Condition field and the Escalation Point Condition field. It is used to create a SQL clause and to then test the expression created with the Test Expression button. It works from the Applies To object – SR in this example, and the right panel shows the attributes of the SR object, but not the relationship as you will find in other similar looking dialogs. The buttons and attribute lookup are used for simple SQL expressions; however, you can type your own expression or copy and paste the where clause from a SQL tool but you need to write this assuming that the SQL From clause is a single table (no joins), the table name associated with the Applies To Object.

The And, Or, Not, Like (, ), Is Null, Is Not Null and each of the Operators adds to the expression the word or symbol shown. 

• The In button adds the text in(”,” ) and you add values between the single quotes.
• The Between button adds the text – between   and

The Calendar button provides a date/time lookup. The Classification button is a lookup to the classifications and returns a classification path of the form 1 \ 103 \ 10301 \ 1030101. Unfortunately, the lookup is not filtering by the escalation’s Applies To object. A case has been raised with IBM Support.

When you have built or typed in an Expression then you should use the Test Expression button which will test the SQL against the database. You will either receive a database specific error message or “BMXAA1151I – Validation successful.” This is what you want to see before you use the OK button to transfer the expression back to the Condition field.

If the Custom Class checkbox is used the Expression must contain a class name, it will be checked to see if it exists. I think it unlikely that this will be used in the context of an Escalation.

Schedule

The Set Schedule dialog which opens from the Schedule field is used to set the frequency for the running of the escalation. Options are set from a series of radio buttons and look ups, and include running:

• Every x second(s)
• Every x minute(s)
• Every x hour(s) on minute y (00-59)
• Every x day(s) on y day of week and at time z
• Every x month(s) on y day (01-31) and at time z
• Every x month(s) on the first/last y day of week and at time z
• Every x year(s) on y day (01-31) of a particular month and at time z
• Every x year(s) on the first/last y day of week, of the year and at time z

The Preview button shows the schedule from the radio buttons and options selected. Examples:

• Every 1 hour on minute 00
• Every 4 weeks on day Sunday at time 02:00
• Every 3 months on day 01 at time 00:00
• Every 3 months on the first Saturday of the month at time 15:00
• Every 1 year on January on day 01 at time 02:00
• Every 5 years on the last Sunday of the year and at time 23:00

The time elements are in increments of 15 minutes, 00, 15, 30 and 45 past each hour, but you can type in a time value in format 24HR:MM, for example 23:59.

When you press OK a formatted Schedule will look something like 1h,*,0,*,*,*,*,*,*,* or for the last example 5y,0,0,0,*,*,*,2,1,* i.e. it would be difficult to read the schedule field and understand what it means. 

If the Schedule starts 10m,*,*,*,*,*,*,*,*,* or 30s,*,*,*,*,*,*,*,*,* i.e. a schedule that runs every so many minutes (10m) or seconds (30s) then it is time to consider whether this will create a performance issue. This is unfortunately quite common, as during development or testing short frequencies are set, then the developer forgets to reset this to the actual frequency required. I have found over the years some Escalations or Cron Tasks that actually fail to finish because the frequency is set too short. If an escalation’s schedule is going to be less than 1 hour you need to ask yourself is there another way of achieving the same thing without using an escalation.