Maximo Secrets

A site dedicated to Maximo containing over 300 articles, podcast episodes and YouTube videos, updated weekly.

Escalations – Advanced Topics

In this article we will look at the actions found in the Escalations application and a number of advanced topics so that you understand the use of the Repeat field, the Calendars/Shifts on the escalation and escalation point, and how communications are written to the Communication Log. We will also review how to determine the success or failure of the running of an escalation.

Validate and Activate

When you have created your escalation, you will need to validate and activate it, activation will perform a validation and often the validation step is just passed. In this example I deliberately created an error by typing directly into the condition field “priority = 1” rather than using the SQL Expression Builder. When using the Validate action the error message “BMXAA1147E – Validation failed. Please check the validation section for errors.” was displayed.

You need to expand the Validation Results table window to see that it says: 

\

 Escalation header error:ORA-00904: “PRIORITY”: ongeldige ID

The error message is coming from an Oracle database, on a Dutch server. You can look up the database error message online, ORA-00904: string: invalid identifier Cause: The column name entered is either missing or invalid. Action: Enter a valid column name. In this case, there is no PRIORITY on the SR view it is either REPORTEDPRIORITY or INTERNALPRIORITY.

The validation results occur for both the Condition field on the header and each of the escalation points and the validation results will point you to where the problem occurs. If I move the same condition to the Escalation Point then the message will point to the escalation point with the issue, it says:

\

 Escalation point:1:ORA-00904: “PRIORITY”: ongeldige ID

If there are issues on the condition for both the Escalation Points and the Escalation header then both will be shown in the Validation Results field. When there is an Escalation Point condition error the line at fault is conveniently highlighted. This uses the non-persistent field VALIDATIONERROR which is set to 1 for Escalation Points that fail the validation.

If you used the Activate/Deactivate Escalation action without using the Validate action you would receive the error message “BMXAA3056E – The expression could not be parsed because of a syntax error.” and you would then use the Validate action to see what caused the error. As we generally write perfect conditions, we initially skip the Validate action until we are forced to use it because we have made a mistake.

There are a couple of other errors which are common:

After issues have been corrected when you use the Validate action you should get the message “BMXAA1151I – Validation successful.” When you then use the Activate/Deactivate Escalation you will receive the banner message BMXAA1145E – Escalation 1041 has been activated.  

The Active check box in the top right of the application will now be checked and all fields in the Escalation tab are now set read-only. If the Escalation definition needs to be modified you need to use the Activate/Deactivate Escalation action again to deactivate the escalation, this action is a toggle between the two states.

The Validate and Activate/Deactivate Escalation actions can both be controlled through security defined in the Security Groups application, this allows a separation between team members that may create the escalation from those who activate it.

Cron Task

All escalations run on a Cron Task called ESCALATION. For each Escalation there is a Cron Task Instance which is the same name as the Escalation but with a prefix of ESC, ours is called ESC1041. You can see that the escalation’s schedule is transferred through to the Cron Task Instance’s Schedule, every 1 minute, and you can see from the Last Run Timestamp that it has already run. 

The Cron Task Instance is set Active. This is not the same field as the Active field on an Escalation. Deactivating the escalation will deactivate its corresponding Cron Task Instance, and vice versa. Activating the Cron Task Instance will also activate the corresponding escalation. They are kept synchronised.

The Cron Task Instance will Run as User MAXADMIN.

Escalation Status

There is a table called ESCSTATUS that is not normally exposed in the Escalations application, but as you can see, I have added it. It shows the status of each escalation point as it runs, the status values are either ERROR or SUCCESS and the status memo shows the error message.

As you can see Escalation 1041 has an ERROR. Currently I have changed the Escalation Point Condition to be specific to the test service request I am using, I have set it to – ticketid=1346 – and this is why the Records Processed is set to 1, rather than a larger number that fulfils the condition for the Escalation Point.

The persistent fields I used in the table window are STATUS, STATUSMEMO, STATUSDATE, ESCREFPOINT.REFPOINTNUM, RECORDSPROCESSED with ORGID and SITEID shown in the details area. You’ll need to create a relationship on ESCSTATUS back to the child object ESCREFPOINT with a Where Clause of refpointid=:refpointid .

I couldn’t find any routine which deletes old ESCSTATUS records. They should be deleted if you delete the corresponding Escalation Point, but I have found that this is not always the case and have raised a case with IBM Support. Currently it is leaving redundant ESCSTATUS records, ones that refer to an escalation point that no longer exists.

It didn’t take too long to find the answer once I could see the error “BMXAA0019I – The Send From field is either read only or part of the primary key. You cannot edit this field.” This is a general error message that can occur in any application where you are inserting a value into a field that is marked as read-only, or far less likely updating one of the primary key fields.

Recently I wrote a set of three articles on Ticket Communications and in the third one I had set the System Property of mxe.commlog.SendFromEditable to 0, its default value is 1. The System Property makes the Send From field read-only when set to 0, editable when set to 1. I have now reset it back to 1 and the next time the Escalation runs I get a status of SUCCESS. You can find the article here – http://maximosecrets.com/2021/12/02/ticket-communications-3/

It’s another day and overnight I had the Escalation deactivated. I set the escalation active again about 20 minutes ago and now I have the same error and you are probably wondering what I am doing. I have reset the System Property back to 0 to force the error to come out.

If you look in the second column of the header of the Escalation you will see that the Create Successful Escalation Entry checkbox is now deselected. This is how it should be set unless you are trying to test something or gather statistics on the number of records being processed, and KPIs is probably a better approach to this, unless this is for performance reasons.

With Create Successful Escalation Entry unchecked you will not get a SUCCESS record being written to the ESCSTATUS table, there were no records written for the last 20 minutes. However, you will still get the ERROR record being written to the ESCSTATUS table, as you just saw.

Incidentally if an escalation encounters an error on one of the records in a set it will continue with the next record.

Time to reset that System Property back to 1.

There are two saved queries I would suggest you create:

For deeper evaluation of Escalation errors, you will need to do some logging and here is a useful article – https://www.ibm.com/docs/en/mam/7.6.0?topic=ee-escalation-logs

Communication Log

Originally in Maximo v6 when Escalations were stripped out of Workflow into its own application the Workflow and Escalations didn’t write to the Communication Log table, this was added in Maximo 7.1 and a new Communication Log tab added to the Escalations application.

When the Escalation is running, and with a schedule of 1 minute, you may find your email inbox has been quickly inundated with new emails, this is due to the Repeat setting on the Escalation Point which I will explain in more detail in a while.

If you look in the Details section, you can see that the email was sent by the escalation on behalf of service request (Owner table = SR) number 1346 (Id). You can see who the email was sent To, the Subject and the Message. The Cc and bcc fields are also in the Details section but are not visible in the screenshot.

The Communication Template being run by escalation 1041 is PRI1ALERT – Priority 1 Alert. There is a checkbox called Comm Log Entry which when checked records an entry in the Communication Log. If this is left unchecked there will be no Communication Log record.

In the Service Requests application for SR 1346 when the Communication Template’s Comm Log Entry is set and the Escalation has generated the communication, then the:

The Escalations application Communication Log tab show the records from the COMMLOG table via a database view called ESCCOMMLOG which filters records where orgobject = ‘ESCALATION’, i.e., filters records where the originating record is ESCALATION.

Where in Maximo v6 a communication sent from a ticket or work order was written to the COMMLOG table, with Maximo 7.1 the originating record’s identifier was written to the same record allowing it to be seen from both the ticket or work order record and the escalation record that generated it.

Repeat

The reason why we were getting an email every minute for Escalation Point 1 was because the Repeat field is checked. If it is unchecked when the escalation runs it writes a record to the ESCREPEATTRACK table and a check will be made to see if a record exists and if it does the escalation point will not execute a second time. In effect there is a subquery to the ESCREPEATTRACK table if it is unchecked and no subquery if it is checked.

The Repeat field defaults to 0. If the escalation runs once successfully it writes a record to ESCREPEATTRACK for the owning record, a Service Request, Work Order, or other record that the escalation is executing against. It will never run against that record again.

When an escalation is deactivated entries in the ESCREPEATTRACK table are not deleted, they will remain. They are also not deleted if you set the Repeat field to active. You can also not see whether there is an ESCREPEATTRACK record for your service request, work order or other record. This can make testing of an escalation point with Repeat unchecked rather difficult. 

Sometimes you can write an Escalation Condition or Escalation Point Condition which will mean that when the escalation has run once, it will never run again, and hence the Repeat flag can be set. This is most likely where the Escalation has an action. For example, an Escalation which has an action that changes status should not attempt to run a second time, but that can be overcome by an Escalation Condition which filters the records when the escalation runs, down to specific statuses. If you can, it is better to construct conditions that run once with the Repeat set to 1, it will also avoid a subquery to the ESCREPEATTRACK table which can become very large indeed.

If you do need to have Repeat unchecked for an escalation point, then after it has run once, if you need to test it again you could delete the escalation point and recreate it. Alternatively, you can duplicate the escalation (delete the old one) and do further tests on the new duplicated escalation. I have adopted both techniques numerous times in the writing of this article.

To find Escalations with an ESCREPEATTRACK record I created a query with a where clause of – (escalation in (select escalation from escrepeattrack)). Note. Deleting the Escalation Point does not delete the ESCREPEATTRACK records linked to it.

Duplicate Escalation

When you use the Duplicate Escalation action the Escalation and Escalation Points are duplicated, and the new escalation references the same Action Group and set of Notifications. If the original escalation was activated then the duplicated escalation will not be active, and no Cron Task Instance exists for it yet. 

On the duplicated escalation an Action Group is created even if the original escalation had no Action Group, this leads to an Action record that doesn’t do anything. A case has been raised with IBM Support about this.

Delete Escalation

The Delete Escalation action will first prompt the user to confirm the action. In response to the confirmation then the deletion reverses the process of creation. It must deactivate the escalation, and this would deactivate the Cron Task Instance allowing it to be deleted. Each Escalation Status (ESCSTATUS) record and Repeat Tracking record (ESCREPEATTRACK) would be deleted. Each Escalation Communication Log record (COMMLOG) that references the Originating Application of ESCALATION is modified to blank the ID field (ORGNAME). The Escalation Notification records that reference the Escalations Reference Points are deleted, but not their Communication Templates. The Escalation Reference Points (ESCREFPOINT) are deleted, this deletes the reference to the Action Group. Finally, the escalation itself is deleted (ESCALATION).   

If this leaves redundant Action Groups and Communication Templates, then these need to be deleted from their applications.

If an Escalation created a communication on a ticket or work order and the Communication Log records exist, then these records will still be present after the escalation has been deleted.

Calendar/Shift

In this part of the article, I wanted to explore the Calendar/Shift on the Escalation and the Escalation Point. I’ve created a new escalation 1064 against the SR object and a condition that will just add a notification to SR 1364 which we have used before. The escalation references the DAY/DAY calendar/shift from EAGLENA organization. You have to enter the Calendar Organization field first; this differs from the behaviour found elsewhere in Maximo where you use the Select Value on the Calendar field first and it will populate the Calendar Organization from the record selected.

The escalation has been validated and activated and it has run a few minutes ago. There is no email, this is because time now is after the end of the DAY/DAY calendar/shift. Although I have set Create Successful Execution Entry there is no Escalation Status record. The escalation’s selection criteria have not found a record.

I’ve deactivated the escalation and changed the calendar/shift to EVENING/EVENING. Time now will find a work period in this calendar and shift. I’ll need to validate and activate again.

After a couple of minutes, if I look at the Escalation Status tab there is one record with a status of SUCCESS.

On the Communication Log there is also a record to indicate a communication has been generated. Notice the To, cc and bcc fields are empty – no email will have been sent, but a COMMLOG record has been created. The reason why there is no recipient is because the Communication Template I had previously created, PRI1ALERT, uses a Person Group TIER2 without the broadcast setting, and there is nobody who is available as everyone is on a DAY/DAY calendar/shift. This would be considered bad data rather than a software issue. 

To summarise the Calendar/Shift on the Escalation header is acting as an additional filter condition along with the Condition, Organization and Site fields. The current time must find a work period in the calendar/shift for it to execute the Escalation Points.

We’ll now look at the Calendar/Shift on the Escalation Points. These fields are mostly used with a Service Level Agreement (SLA). The SLA has an Applies To Calendar which is used for filtering, a bit like the calendar/shift on the header of the escalation. The Calculation Calendar is used to derive a target date and represents business/operating hours. For example, if an SLA had a response of 3 days and today was Thursday, should the Target Start be derived for the Sunday or Tuesday? If the business hours were M-F 09:00-17:00 then you would say Tuesday, 3 working days from Thursday. It is implied then that if you wanted a reminder email 1 business day before the Target Start is due to be reached, you would want to receive the email on Monday and not Saturday. Hence there is a need for a calculation calendar on an Escalation Point. These fields would be used when using an Elapsed Time Attribute.

I’m using a new escalation which has a condition that will only effect SR 1346, it has no Calendar/Shift on the escalation record. For the Escalation Point, there is no condition, the Elapsed Time Attribute is TARGETSTART and the interval is -1 DAYS using the DAY/DAY calendar. This means that the notification should occur one day prior to the Target Start. I have set the Target Start on SR 1346 to Monday 20th December 2021 at 09:00. One day before this on the DAY/DAY calendar should be Friday 17th December 2021 at 09:00, this is tomorrow morning. I simplified the notification against the Escalation Point to make sure that I would be the only recipient, that way when I get the email notification from my mail system, I know the escalation has just run. Notice the Repeat is not checked.

It is now Friday 17th December and the Escalation has now been activated and I have just received my email notification. The Last Run Time has been updated and the Escalation Status says SUCCESS with Records Processed 1. 

The escalation point is considering the calendar/shift to determine whether to send the email. If it were not, then I would have received the email on Sunday 19th 2021 at 09:00. The Calendar/Shift fields are acting as a calculation calendar and are not being used for filtering as is the case with the calendar/shift on the escalation’s header.

I made the mistake of deactivating the escalation as soon as it had run and then immediately thought there was something that I wanted to check, so I activated it again – hence the gap of 3 minutes in the Status Date between the two records.

What I wanted to check was what would happen with Repeat unchecked the next time the schedule on the escalation was due to run, it should not attempt to send a second email as there is now an ESCREPEATTRACK record. I didn’t receive an email, but a second record was written to the ESCSTATUS table with a status of SUCCESS but with a Status Memo of No data found and Records Processed of 0. With further testing I found that you would keep getting a similar record in the ESCSTATUS table with a memo of No data found. With the Escalation Point set to Repeat I quickly found many emails had arrived in my inbox.

Leave a Reply

%d bloggers like this: