Last Updated on October 29, 2023 by maximosecrets

A communication template is a template for an outbound email and is used in Workflow, Escalations and in applications through the Create Communication action. The Communication Templates application will be found in the Administration module and in the System Configuration – Platform Configuration module.

List Tab

There are a variety of existing Communication Templates which you will find in a MAXDEMO database and in a new installation of Maximo, these perform specific functions across Maximo. They are worth reviewing but I would not change the existing templates better to duplicate them.

Many of the existing Communication Templates are designed for specific functions within Maximo.

• There are 37 communication templates used with the Email Listener (LSNR)
• There are 11 communication templates used with Email Interactions (MFMAIL)
• There are 13 communication templates used with Contracts (query in template field “pur,war,lab,lea,mst”)
• There are 6 communication templates used with Global Issues (TG)
• There are 4 communication templates used with User Self Registration (REG)
• There are 5 communication templates used with Reports (Applies to REPORT)

Consequently, if you change them and now something doesn’t work, you may not have a record of how it was delivered out of the box, which is why it is best to use the Duplicate Template action and then to use the duplicated record.

Communication Template Tab

As part of the article on Ticket Communications I created a simple Service Request acknowledgment template. I’ll use this as an example to go a bit deeper on each Communication Template field. The original article can be found here – http://maximosecrets.com/2021/12/02/ticket-communications-1/

The main object of the Communication Templates application is COMMTEMPLATE, a System level object.

• Template – The TEMPLATEID is the unique key and is defined as UPPER 16. For new records I would accept the autokey. 
• Description – The short description for the communication template that is shown in lookups, so take care to describe the purpose carefully. This field has a long description which can be used to provide clarity of the purpose and intended use.
• Created By and Date – Defaults to the person and date/time when the Communication Template was created. There are no Modified By/Date fields.
• Status – Defaults to INACTIVE. You must use the Change Status action to make the Communication Template ACTIVE for it to be used in an Escalation, Workflow or in the Create Communication action in applications. There is no status history, but there is a hidden Status Date field.
• Applies To – The object name that has the records on which the Communication Template can be applied. This can be any Maximo object, but it would be typical to only use this on the main objects that support an application. It is a mandatory field. If you were on the Service Requests application the lookup in the Create Communication action would be restricted to those records from the SR object. 
• Accessible From – A mandatory field that provides the context for the Communication Template; ESCALATION, WORKFLOW, APPS – Maximo Applications, or ALL. If you are in the Service Requests application using the Create Communication action you will only be able to select communication templates with an Accessible From setting of APPS or ALL. For an Escalation against the SR object, it would be ESCALATION or ALL.
• Track Failed Messages – A checkbox which when set will write a Communication Log message if the email fails to be sent. Default = 0.
• Comm Log Entry – A checkbox which when set will write a record to the Communication Log table when you send the email. From the Create Communication action this is when you use the Send button. Default = 0. The default for this field might be changed in many implementations to 1.

As there are many records that you should avoid changing, or which might remain unused by your implementation, I would consider changing the status of all Communication Templates to INACTIVE initially, or a synonym of INACTIVE, perhaps MAXIMO – Core Maximo (Do not delete). The Change Status action works from the List tab against a selected set of Communication Templates.

The To, cc and bcc fields are read-only and are derived from the entries you make in the Recipients tab (see later).

The Send From is the email address which the recipient will see as having originated the email.

The Reply To is the email address used by the recipient to reply to the received email. If it remains empty then a reply will be to the email address from which the email is sent (see later).

The Send From and Reply To email addresses may contain substitution variables (bind fields) that will resolve to an email address held somewhere in Maximo. In the screenshot the Send From is :user.primaryemail.emailaddress. The colon (:) indicates the start of the substitution variable. The first two elements are relationships, and the last element is an attribute. This is known as “dot notation” and the order of the relationships is known as the relationship tree. For this example, based on the Applies to Object of SR it means, from the SR object use the relationship called USER to navigate to the child object and then use the relationship PRIMARYEMAIL from that child object to navigate to it’s child object (the grandchild of SR).

These relationships can be reviewed in the Database Configuration application:

• USER links to the PERSON object and the logged in user’s person record (personid=:&PERSONID&)
• PRIMARYEMAIL links from the PERSON object to the EMAIL object and the record marked as primary for the logged in user (personid=:personid and  isprimary=:yes).
• EMAILADDRESS is the value of the attribute EMAILADDRESS on the EMAIL object.

Subject – is the subject of the email and is defined as ALN 254, it may also contain substitution variables.

Message – is the message body of the email and is defined as a CLOB field (Character Large Object), up to 999,999 characters, it may also contain substitution variables.

In the example shown there are a few substitution variables:

• :person.firstname – is the first name of the reported by person
• :user.displayname – is the display name of the logged in user who is sending the email
• :user.primaryphone.phonenum – is the primary phone number of the logged in user
• :user.primaryemail.emailaddress – is the primary email address of the logged in user

Both Subject and Message are language enabled fields, allowing the same Communication Template to be used to send emails in different languages (see later).

Recipients Tab

There are four table windows in the Recipients tab, and they are all set to be collapsed when you open the tab. You can enter one or more Roles, Persons, Person Groups or Email Addresses. These are not dynamic; they do not open if there are records in the table window. You can tell which have records because each table window shows a record count, there are 2 Roles defined.

The majority of Communication Templates you create will use Roles, the top table window, and I would uncheck the Collapsed checkbox in the Table property, which you could do in Application Designer application for the application called COMMTMPLT.

The Roles table window allows you to enter multiple roles through the Select Roles button. Most of the time you would use New Row as you only have one existing Role to find, although it is one additional click to do so. You must select either To, cc or bcc (blind copy). You could select all three check boxes, although that does not make sense, it would not mean that the recipient would receive the email message multiple times.

The two Roles in this example are two new ones created to send the email to the Reported Email and the Affect Person’s Email on the Service Request. This is two different ways of using Roles the first requires the E-mail attribute to be checked, but not in the second example. This was explained in the Ticket Communication (1) article I gave at the top of this article. There is an article on the Roles application, which you can find here – http://maximosecrets.com/2021/12/03/roles/.

When picking a role, the role itself may reference an Object, i.e. it is only supposed to be used in a communication based on that object. The Select Value on the Role field in the Roles table window does not restrict which role can be applied. It should be where there is alignment between the Communication Template Applies to Object and the Role’s object or where the Role’s object is null. 

I’ve opened the other three table windows so that you can see the fields.

• With Persons you have the button Select People. These are persons that are referenced in Maximo and again you need to choose To, cc or bcc.
• With Person Groups you have the button Select Group, and these are defined in the Person Groups application. You need to choose To, cc or bcc. The broadcast check box allows you to send an email to all members of the Person Group, or a single person based on the availability of the people in the Person Group, this would take into account the calendar/shift, holidays, vacation, sick and other periods of non-availability (see later).
• With E-mails you only have the New Row button, and you enter an email address with its To, cc or bcc setting.

You can use a combination of these four table windows and the additions you make are added to the To, cc and bcc fields on the main Communication Template tab, these are non-persistent fields (not saved to the database). All recipients are stored in the object/table COMMTMPLTSENDTO. The Type field holds the values ROLE, PERSON, GROUP, or EMAIL.

Communication Template Attachments

The Communication Templates application has the normal paperclip button and actions – View Attachments, Add New Attachments and Add from Library. From the Add New Attachments, there are options for Add New File or Add New Web Page.

As an example, we will add the home page for Maximo Secrets as a Web Page to the Attachments document folder. I’ve specified the URL as https://maximosecrets.com, given a document name MAXIMOSECRETS and a document description – Maximo Secrets Home Page. In the Advanced Options I have selected – Add document to the document library for others to use – so that the same URL can be linked to other records in Maximo, not just Service Requests.

When the OK button is pressed the document MAXIMOSECRETS is added to the Attachments table window for this Communication Template. When you use the hyperlink the web page or document will open in a separate window.

You might refer to these as hard-wired documents. When the Communication Template is used, the hard-wired documents are attached to the email being sent. When using the Create Communication action from an application you can delete the document before pressing the Send button, you wouldn’t be able to do this for an Escalation.

Attachment Folders Tab

The Attachment Folders tab shows the folders that have been associated with the applications which have a main object the same as the Applies To object, in this case SR. In the system I am using there are four applications associated with the SR object, SR – Service Requests, PLUSGSR – Service Requests (O&G), CREATESR and VIEWSR – The Self-Service SR applications, Create Service Request and View Service Requests.

There is no New Row or Delete Row buttons in the Folders table window. The only thing you can do is set the Send with Communications check box. When selected the attachments in that folder for the record from which the communication will be sent will be included in the email communication.

In Maximo, documents and other files, and URLs to web pages are stored in a Document Folder which is a Maximo folder name that may point to a physical folder. They are set up in the action Attachment Library/Folders – Manage Folders. 

Once a folder is created it is then associated with an application through the action Attachment Library/Folders – Associate Folders. 

Testing the Communication Template

For the Communication Template SRACK, and on the Attachment Folders I’ve indicated that I wish to include in the outbound email any documents in the Attachments folder in the SR application.

On Service Request 1337 the View Attachments dialog shows two documents, 1025 and 1026 which are attached directly to the SR record, these were two screenshots from the Ticket Communications articles. There are two attachments which were previously manually attached in the Create Communication dialog, and which were entered against the Attachments folder in the COMMLOG application but are also visible from the Service Request record.

I am logged in as Andrew Jeffery and when I use the Create Communication action and select the Communication Template SRACK, then the two Roles are resolved to email addresses, the Reported email address on the Service Request (To) and the primary email address of the Affected By Person (cc). 

The fields of the Communication are filled out with values taken from the Service Request record where there were substitution variables. For example:

• The Subject includes the reference to the Service Request number (:ticketid) – 1337.
• The first line of the Message includes the First Name of the Reported by Person (:person.firstname) – Mike
• The third line of the Message includes the Display Name of the logged in user (:user.displayname) – Andrew Jeffery
• The fourth line of the Message is the Primary Phone Number of the logged in user (:user.primaryphone.phonenum) – 0777-18216742
• The last line of the Message is the Primary Email Address of the logged in user (:user.primaryemail.emailaddress) – andrew.jeffery@znapz.com. This substitution variable was also used in the Send From field.

Scrolling further down in the Create Communication dialog we have the MAXIMOSECRETS document that came from the SRACK Communication Template, and the documents from the Attachments folder on the Service Request, documents 1025 and 1026. In this dialog you could delete the attachments that you do not wish to send, but you wouldn’t have that opportunity in an Escalation or a Workflow process.

Multi-language Communication Templates

Earlier we said that both the Subject and Message supported multiple languages. The main object, COMMTEMPLATE, is language enabled and the language table is called L_COMMTEMPLATE.

If you change the language for your login, in this case to NL – Dutch, you can then navigate to the Communication Templates application, find the record SRACK and modify the Subject (Onderwerp) and Message (Bericht). The changes you are making are being made to the language table for these two fields and signed with a LANGCODE of NL. It is only the static text that needs to be changed and not the substitution variables.

I have changed the login of Andrew Jeffery with a language of NL, logged out and logged back-in. Now going to the Service Requests application (Serviceaanvragen), I can find the Create Communication action (Bericht maken) and find the same Template (Sjabloon) SRACK. As my language is currently NL, it will use that language for the Subject (Onderwerp) and Message (Bericht). It is using the language of the logged in user and not the language of the Reported By Person or other recipient.

The same Communication Template is supporting multiple languages, which is good to know. However: 

• This would work well if a Service Desk user only had to support one language, but if the Service Desk user is supporting multiple languages, they will need to keep changing their profile and logging out and logging back in again so that they can use the Communication Template in the expected language of the recipient. 
• If the Communication Template had an attachment, then it is likely that the attachment needed to be in the language of the user.

Both of these points are easily handled if the Communication Template was specific to a single language, rather than using the multi-language aspect of the Communication Template. For example, SRACK-NL would be the Dutch version, and SRACK-EN the English version and each would only have attached documents in the required language.

Logged in as Mike Wilson who has a Language of EN – English in his profile, the email that was sent via the Create Communication action is visible from within Maximo in the Log – Communication Log tab of Service Request 1337. This includes the three documents, the one from the Communication Template SRACK and the two from the Service Request – Attachments folder.

If you now used the View Attachments action (paperclip button) you would see three additional records (the top three) representing the documents sent to the email recipient and associated with the COMMLOG application. Don’t be alarmed that document 1025 and 1026 appear multiple times, it does not mean the document is stored multiple times, only that the same document, or web page, is linked to multiple records in Maximo.

Communication Templates using Person Groups

In this scenario I wanted to show an example of Rich Text Formatting in the message as well as the difference between a Broadcast to the members of a Person Group and when the Broadcast field is left unchecked.

I’ve created a new Communication Template PRI1ALERT – Priority 1 Alert, which Applies To the SR object and is Accessible From ALL.

• Send From is set to :user.primaryemail.emailaddress – the primary email address of the logged in user
• Subject is set to “Priority 1 Alert – :ticketid”
• Message is “This is to notify the receipt of Priority 1 request or incident. Target Response is :targetstart”

On the Recipients tab I have added the Person Group of TIER2 and the Broadcast field defaults to being checked.

I have also changed status on the Communication Template to ACTIVE so that I can use it.

On a new Service Request 1345, raised by Fran Garcia (FRAN) on behalf of Ed Adams (ED) I’ve used the Create Communication action and selected the PRI1ALERT Communication Template.

I am logged in as Andrew Jeffery and the Send From field has resolved to my primary email address from my Person record. In the Subject the substitution variable :ticketid has been replaced with 1345, the SR Number, and in the message the Target Start Date of 08/12/21 11:10 has been substituted at the end of the message. The Rich Text Formatting in the message has been carried through to the Create Communication dialog.

After the Send button is used the record appears in the Log – Communication Log tab, including the red text – Priority 1.

It was also received in my Inbox as I am a member of the TIER2 Person Group. The rich text formatting carries through to the received email.

Notice the other recipient is Bob Caldone.

There are three members of the TIER2 Person Group. The Service Request has no organization or site, and this is the reason why I received the email (AJE – Andrew Jeffery) and not ADAMS – Hank Adams who has a Use for 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 of EAGLENA. Bob Caldone (CALDONE) receives the email because he is marked as the Group Default.

If I added a vendor to the Service Request 1345, this would set an organization, and if that Organization was EAGLENA then Hank Adams (ADAMS) would receive the email. Similarly, if the Service Request had a SiteA structural element of a Maximo database that is used for data separation. More of BEDFORD, then anyone who had a Use For Site of BEDFORD would receive the email. 

Multiple people could receive the email because the setting for the Person Group in the Communication Template PRI1ALERT is set to Broadcast.

In the Recipients tab of the Communication Template for PRI1ALERT I have now deselected the Broadcast check box.

On the Service Request 1345 when the Create Communication action is used only one person from the Person Group will receive an email. In this case it is me, AJE – Andrew Jeffery. The selection is based on availability, and this will take into account a person’s calendar. All people in this person group have DAY/DAY calendar/shift. The test of availability is performed at the time the communication will be sent. If I waited until late afternoon when nobody is available, then there would be no recipient for the email.

The test of availability uses the Sequence order in the Person Group where the lowest sequence number would be considered first. But Bob Caldone has a Sequence of 10 and Andrew Jeffery has a Sequence of 20, why didn’t Bob Caldone receive the email instead? The answer found from tests performed on the second Ticket Communication article is that it ignores the settings for Use for Organization and Use for Site when not broadcasting, or rather it excludes these persons from receiving an email. A case has been raised with IBM Support for this. The Ticket Communications (2) article can be found here – http://maximosecrets.com/2021/12/02/ticket-communications-2/.

In the People application I’ve given myself (AJE) a half-day holiday today 07:00 to 11:00 with Reason Code VAC. 

As time now is 10:40 and I’m still on holiday, then nobody will receive an email, the To field is empty.

I’ve just added in Thomas Barry (BARRY) who also has a DAY/DAY calendar/shift and if I run the Create Communication action again, he will be the recipient of the email.

Notice that I had previously added in Bob Crocker (CROCKER) with Use for Site BEDFORD, and I made ADAMS the Organization Default and CROCKER the Site Default. This makes no difference; they still do not appear as a recipient when Broadcast is left unchecked.

In 10 minutes, when the time is after 11:00, I’ll be able to see whether Andrew Jeffery takes over from Thomas Barry as the recipient of the email. AJE’s vacation finishes at 11:00. … After 11:00 now, AJE – Andrew Jeffery did become the recipient of the email instead of Thomas Barry.

When broadcast is disabled only one person (or no person) will be the recipient of the email. The recipient is based on the availability of the person and the sequence number.

Incidentally, if a person has no calendar/shift they are deemed to be available 24×365 and so would receive the email if they were considered first according to the sequence.

Reply To

When we sent the email earlier the Send From attribute is the Name element and the email address in angle brackets is the value in the System Property mxe.smtp.user. The example shown is andrew.jeffery@znapz.com <maximosecrets@gmail.com>.

If I replied to this email, it would be sent to the email address maximosecrets@gmail.com, the email address of the host Maximo system. This is the same email address from which it was sent, and unless you have the Email Listener setup, or someone to monitor this address a reply may never be reviewed.

You may wish to add a Reply To address the same as for the Send From attribute on the Communication Template. This means that if someone does reply to the sent email it will be returned to the email address of the sender and not the host email address. In the Reply To field for the Communication Template PRI1ALERT I have entered :user.primaryemail.emailaddress.

When the Communication Template PRI1ALERT is used in the Create Communication dialog the Reply To address is resolved.

Now if you replied to the receipt of the email, it would be sent to andrew.jeffery@znapz.com instead of the host email address maximosecrets@gmail.com.

Maximo has an Email Listener which can retrieve emails (new requests or replies) from an inbox and process them into Maximo, including attaching the email to the Communication Log of the original Service Request, a subject for future other articles.

Track Failed Messages

In the Communication Template there is a check box called Track Failed Messages. The idea behind this is that when something goes wrong in the sending of an email, perhaps the email address doesn’t exist, then you’ll be able to see this in the Communication Log. At the time of publishing this article I haven’t been able to get this to work and I have raised a case with IBM Support.

This feature was added with Maximo 7.5.0.3 along with changes to the Email Listener and the addition of the Email Interaction Setup application. There were two additional fields in COMMLOG object ISSENDFAIL and KEEPFAILED and an action called SEND_FAILED. The idea was that a COMMLOG that failed to be sent would have ISSENDFAIL set to 1 and then an Escalation could use the action SEND_FAILED to find these records and resend the communication. Perhaps it only works if the Email Listener is also setup. I’ll have to find out and then when I have it working, I’ll write a separate article on this.

The two articles I found on this in the IBM Documentation were:

https://www.ibm.com/support/pages/resending-failed-email

https://www.ibm.com/docs/en/mam/7.6.0?topic=solutions-resending-failed-email

Neither gives more information than I’ve provided above.