Last Updated on November 19, 2022 by maximosecrets

Communication Templates

Maximo provides the ability to send emails to recipients from many applications, but the most widely used will be from a service request or a work order. Other applications with a Create Communication action are Purchase Requisition, Purchase Order, Bulletin Board and the KPI Viewer. Emails can also be sent automatically as part of a workflow process or an escalation which monitors the Maximo system for an event and performs actions and notifications when the event occurs. An escalation can be used to monitor a Service Level Agreement which can be applied to many types of record in Maximo.

The Create Communication action can be used like any regular email with fields for To, CC or BCC, Subject and the message body which may contain rich text formatting or images. A communication can also contain one or more attachments or links to web pages. The Create Communication dialog can have an applied Communication Template and the communication template may fill out the elements of the email, To, CC, BCC, Subject, Message, even the linked documents.

The subject and message may pull data from the application’s record against which the Create Communication action is being used. The Communication Template may contain embedded bind variables. For example, “New Service Request 1002” in the subject header would be referenced as “New Service Request :TICKETID” in the communication template. The bind variable in this case is :TICKETID, bind variables are preceded with a colon (:) and then the attribute name. The attribute name can also be preceded with a relationship name. For example, “Warranty on asset :ASSETNUM is expiring on :CONTRACTLINEASSET.WARRANTYENDDATE .” The relationship CONTRACTLINEASSET has been defined on the ASSET object to the CONTRACTLINEASSET object, it is the SQL where clause that will successfully join the two underlying tables. The result would be something like “Warranty on asset 11430 is expiring on 10/23/19 .”.

The Communication Templates application will be found in the Administration module and also the System Configuration and Platform Configuration submodule. A communication template applies to a particular Maximo object and is accessible from workflow, escalations, Maximo applications, or all three. When an email is sent the record can be saved as a Comm Log Entry, COMMLOG is the table where the records are saved, and this will then be visible in the Communication Log tab of an application.

The Recipients tab is where you define on the communication template who will receive the email notification. There are four table windows and in each of these you define whether the recipient will appear in the To, CC or BCC part of the email. The recipient could be one or more people defined in the People application, in which case the email is derived from their primary email address. The recipients could be the members of one or more person groups or a single individual in a person group who is on shift at the time the email is sent. The recipient list could be a specific set of email addresses. The first table window allows you to define one or more roles and a role will be resolved to one or more people or email addresses, more on roles in the next section.

The email can also contain attachments. These can be attachments applied specifically to the communication, for example a screenshot, or attachments on the communication template itself, for example a form to be filled in. The Attachment Folders tab allows you to send as an attachment any documents related to the current record that exist in the selected folders of the application or one of its referenced applications. For example, a communication on a work order might have both the photo taken from the last inspection and a photo of the asset when it was first installed, or the work instructions on the job plan related to the work order.

Roles

A role is used in workflow, escalations and in a communication template. The Roles application will be found in the Platform Configuration submodule under the System Configuration module. It is a simple application with eight fields, but it is more powerful than first impressions. Bear in mind that a role will resolve to a person or email address because we wish to assign that person an action in a workflow or notify them as part of a communication.

A role resolves to a person, an available person in a person group or all the people in a person group, a dataset that resolves to one or more people, a relationship that resolves to the logged-in user’s person record, a custom class that resolves to one or more people when executed, or one or more email addresses.

When the role type is PERSON the value entered is the PERSONID of someone that can be seen in the People application.

When the role type is PERSONGROUP the value entered is the identifier of a specific Person Group. The broadcast checkbox is used to broadcast an assignment to everyone in the person group or if left unchecked to the first person who is available on the shift at the time the assignment is made, or the communication is sent.

When the role type is DATASET an object is required, and the value entered has a field selector which allows you to select an attribute of this object or an attribute of a related object. For example, if the WORKORDER object is selected then you could create a role to the :LEAD or :OWNER attributes, which will be people. You can also resolve to a set of people, for example :OWNERGROUP resolves to a person group that can contain multiple people. You can use a relationship or a string of relationships, so that the supervisor of the user associated with an asset might be defined as :ASSETUSERCUST.PERSON.SUPERVISOR.PERSONID . The role can resolve to a set of email addresses rather than people in which case the E-mail attribute should be checked.

When the role type is USERDATA there cannot be an object and the field selector will start at the PERSON object. For example, this would be used to assign workflow to the user’s supervisor.

When the role type is CUSTOM there is no object and the value must reference a JAVA class file, there is no lookup. There are a few standard roles, for example the three bulletin board audiences for organizations, sites and person groups, the Maximo Administrator, the logged in user, and a couple of workflow roles. However, new custom classes can be created if the other role types will not resolve to what is needed.

The last role type is EMAILADDRESS, the value is an email address or a set of email addresses. This type can only be used on notifications and not on a workflow assignment.

Bulletin Board

The Bulletin Board application will be found in the Administration module. When a new bulletin message is created and made active it will appear in the Bulletin Board portlet on a user’s Start Center. When it has been read by a user it will disappear from their bulletin messages.

A new bulletin message is created, and the post date will default to time now, an expiration date must also be given, this is the date/time when the message will be removed from the bulletin board portlet. The subject of the bulletin message is mandatory but not so the long description which can contain rich text formatting, for example, highlighting a safety awareness bulletin.

The audience of the bulletin can be defined as all users of an 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, all users of a SiteA structural element of a Maximo database that is used for data separation. More or all people belonging to a Person Group. Multiple of each of these types of audience records can be created but a user will only receive the bulletin once if they belong to multiple audiences, for example they are a member of two or more of the referenced person groups. If no audience record is created then all Maximo users will receive the bulletin message, this is used, for example, when alerting people to the Maximo system going down for a maintenance period.

The statuses of a bulletin message are Draft (the default), Approved, Rejected and Deferred. One user can create the message, and another approve, reject or defer it.

Not all users log into Maximo frequently enough to see the bulletin messages. There is a Create Communication action which can send an email notification to the audience. This can use a Communication Template which is predefined to pick up the same Subject and Message body. The audience is defined using a set of Roles which will resolve to find one or more email addresses. For example, a Role for a Person Group can resolve to the email addresses of the members of the person group. When the email has been sent the content of the email can be saved and associated with the bulletin message and viewable under the Communication Log tab.

Escalations

An escalation is a background task that runs automatically at a fixed schedule. It runs on the Cron Task which is where all automated background processes run, for example, Inventory reorder, work order generation from a PM. An escalation is just one job on the cron task, it is called ESCALATION, and each individual escalation is one instance on that cron task. The Escalation application will be found in the Platform Configuration submodule under the System Configuration module. The Cron Task Setup application will be found in the same submodule.

Escalations are used to monitor events that occur in the Maximo database and then to perform one or more actions and/or send one or more email notifications when that event occurs. Many events may be time dependent. For example, an escalation to automatically close a work order 90 days after it has been completed, an escalation to alert the contract manager, 90, 60, and 30 days before a contract is due to expire.

An escalation can have multiple escalation points and the last example would have three because the criteria is slightly different for each period. The actions and notifications are linked to the escalation point rather than the escalation itself.

An escalation applies to a persistent Maximo object, persistent means an object that has a corresponding database table or view, as opposed to a non-persistent object which is one which is only held in memory. An escalation can be made specific to an organization or site. Both the Escalation and the Escalation Points have a condition, a SQL where clause, which if both conditions evaluate to true will result in the actions and notifications being processed. An escalation’s condition can also be set for certain times of day defined by a calendar or shift. For example, an escalation which runs out of hours on emergency work received.

On the escalation point an Elapsed Time Attribute can be entered, this is a date or date/time field, and the Elapsed Time Interval and Interval Unit of Measure attributes are used to define when the escalation occurs in relation to this date/time. For example, 1 day before (-1) a 14-day SLA, an email may be sent. The escalation point also has a calendar and shift, but this is used for calculating the elapsed time period. For example, if a calendar is Monday to Friday, 09:00-17:00 and the target date is a Monday then one day before will be the previous Friday.

An escalation point may also be set to repeat while the condition persists. For example, to send an email each week until someone does something to determine that the condition of the escalation evaluates to false at which time the repeating stops.

An escalation runs at the schedule you set and the conditions you apply. The escalation must be validated and made active before the escalation will run. Setting too frequent a schedule or creating a poor condition that has to evaluate too many rows will lead to poor performance of the Maximo system, so beware, the escalation system is in the module that would normally only be used by the Maximo Administrator.

At the bottom of the Escalation application are two tabs for the actions and notifications, each with a table window. When you go to enter an action Maximo will automatically create an action group for you to enter actions against. An action might be change status, or set a value, for example, when you are using the repeat on an escalation point you might increment a field by one to show how often this has happened.

The Service Level Agreement (SLA) application uses escalations. At the end of the SLA Commitments table window is a button, Define Escalation, which will create an escalation and escalation point to monitor the commitment. For example, if the SLA commitment is to respond to a service request in 8 hours then and the escalation is used to monitor whether an actual start has been entered and to start sending email notifications a few hours before the target start has been reached, there might be a different email sent to the supervisor when the SLA has been breached. If the SLA has multiple commitments which are being monitored, then they share the same escalation, but each commitment has a different escalation point. The SLA Escalations tab gives you access to similar functionality as the Escalations application, so a user who sets up SLAs need not have access to the Escalations application itself.

Actions

Actions are used on Escalations and Workflow. There are six types of actions, the most common would be to set the status or set a value on an attribute. Actions act against a Maximo object, both persistent and non-persistent. The Actions application will be found in the Platform Configuration submodule under the System Configuration module.

When the action type is GROUP (Action Group) the Select Members button can be used to pick other actions which share the same object, or which are custom actions where the object field is left blank. A child action cannot have an action type of GROUP, but the same action can belong to multiple action groups. When an action has been added to an action group it appears in the Members table window.

When the action type is APPACTION (Application Action) an object should be entered, and this would be the main object for the application. The value field will become mandatory. There are only a few application actions which are provided, and they would be the actions which do not open a dialog box. Some application actions will allow a parameter to be entered, for example from the SR (Service Request) object you may choose an application action of CREATEWO that creates a work order linked to the SR, the parameter field is used to pick an active Job Plan to be applied as part of that action. Similarly, if the application action creates a type of ticket the parameter can be used to apply a ticket template.

When the action type is CHANGESTATUS (Change Status) the object field becomes mandatory and this would normally be the main object of an application. The value field is used to enter the status, the parameter field cannot be used. This type of action is widely used in workflow, but it is also used on escalations to approve or expire contracts or to close tickets and work orders and other records some weeks after those records were set to resolved or completed. The memo field is used to populate the memo field on the status change record.

When the action type is SETVALUE (Set Value) the object field and the parameter/attribute field both become mandatory, the object field will need to be entered first. A common use of this action type is to set the owner or owner group of a ticket or work order to a value. The lookup on the value field will open the Expression Builder which would allow a math function to be performed on a numeric field, for example, :wopriority=:wopriority+1 . The Expression Builder has some built in functions that use the special bind variables, for example, :&DATE&, or :&PERSONID&.

When the action type is CUSTOM (Custom Class) both the value field and the parameter field can be entered. The custom action would either be a Java Class or an Automation Script that has an Action Launch Point, but it would require programming effort to use this type of action unless one of the prebuilt action classes can be used.

When the action type is EXECUTABLE (Command Line Executable) only the value field can be entered. This type of action will rarely be used. It could run a program file on the server, in which case the value field is used for the file to be run.

E-mail Listener

The E-Mail Listener is used to receive inbound email messages and process them into Maximo. A background Cron Task polls email accounts for new messages and adds these to a staging table and queue which are then processed sequentially. The extraction of the email into the queue uses a Java Messaging Services (JMS). A Java Message Driven Bean (MDB) is activated when the message is added to the queue. The processing of the emails can run in parallel and asynchronously enabling high volume receipt of emails.

An application is provided to enable the configuration of the E-mail Listener, this will be found in the Platform Configuration submodule under the System Configuration module. The Email Listener uses a workflow process to process the inbound messages. As an email is read embedded attachments, for example images, and other attachments, for example, document files or PDFs, are extracted and stored in the Maximo server as part of the attached documents functionality.

An inbound email will normally create a new Service Request and add the email data and attachments so that they are visible in the Communication Log tab on the Service Request application. If the email subject contains an existing SR number, then it will create the communication log records against the SR. If an email message cannot be processed then the Administrator E-mail will be sent an email depending on the type of error, these emails utilise several prebuilt Communication Templates. The invalid email can be reprocessed from within the Email Listener application.

The Email Listener can also create/update Incident and Problem records in addition to Service Requests. The Email Listener can change status on any main object of a Maximo application, for example to change the status of a work order when the technician has arrived at site and then again when they have left site. An email can contain the object and where clause of a query and the Email Listener will return the results of the query. The Email Listener can also process emails which contain formatted messages as text or XML, for example a set of value pairs, WORKTYPE=EM.

The Email Listener has functions to delete processed emails from the mail box and to automatically send a confirmation message when an email has been received. The Email Listener performs a security check on the sender of the email to ensure that they have the privilege to add, update or change status. There is an application called Email Interaction Setup that is used for changing the status of a Maximo record using a smartphone, it utilises the Email Listener.