Maximo Secrets

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

Roles

Last Updated on November 17, 2022 by maximosecrets

A role is a pointer that resolves to a person or team, a person group. For example, the person who reports a service request, the buyer of a purchase order, the team responsible for safety, etc. Once it has found a person or team Maximo can derive an email address and use this in email communications. A role can also resolve to an email rather than a person, for example the email captured on a Service Request for the external person calling in to the Service Desk.

The Roles application will be found in the System Configuration module and its Platform Configuration module. It is a simple but powerful application that is used in Workflow, Escalations and Notifications, for example the Create Communication actions that can send an email to a recipient.

From the List tab you can see that Maximo provides a number of standard Roles of varying role types. The Maximo Administrator or others with similar rights can create new roles which other people use across Maximo.

When you navigate to a role in the Role tab you won’t find it has many fields, and there are no child tables.

If you are creating a new role the Type field is mandatory and you’ll soon find there are 6 types. This article will look at each of these in turn.

There are no dialogs or actions except those you would expect like the Advanced Search dialog or Duplicate, Delete actions. There is no status field and no need to make a role active, or inactive. This is a configuration application; it is expected that your Maximo administrators or IBM Business Partner has already developed the role in a development system and has migrated it through to test and production by the time you come to use it. 

There is a Migration Manager Object Structure called DMROLE with source objects of MAXROLE and LONGDESCRIPTION. The MAXROLE object exists at the SYSTEM level.

Email address (EMAILADDRESS)

The first type to review is “Email address” is the easiest to understand and perhaps the least likely to be used. There are no examples in the MAXDEMO database. It resolves to a specific email address which you enter in the Value field. 

The example shows a Role MAXSECRETS – Maximo Secrets with a Value of maximosecrets@gmail.com. I use it for test purposes. Please do not use it. The Value field is the only field that is enterable, Object, Parameter, E-mail and Broadcast are all read-only.

On the Value field the Detail menu provides the relationship tree dialog, it isn’t used with this type, you will receive the error message “BMXAA3609E – The relationship tree is only available when role type is data set, user data, or person group.” 

Person (PERSON)

The Person type is also easy to understand, the Value field represents a person referenced in Maximo. The Select Value in the Value field is used to lookup a person or go to the People application and return a value. When used in Workflow it will assign to a specific person. When used in an email communication the role resolves to the primary email address of the person.

If you select a Type, then the Object field becomes read-only. However, you can enter an object first before you choose a type. In the example, I have made the AJE role only available in the applications where WORKORDER is the main object. It would not appear in the Create Communication action on the Service Request.

For example, the Purchase Requisitions application has a Create Communication action. You could create a role for each Commodity Group that is only used on the PR object and where the Value field was the Person record of the associated Buyer. 

If the object field is left blank, then the role would appear in all applications. Incidentally, you can also enter an Object when the type is “Email Address”.

Person Group (PERSONGROUP)

Like the “Person” type the “Person Group” type can point to a specific Person Group, in this example the Value field is set to the SAFETY Person Group. The Broadcast field can be checked in which case, when used with the Create Communication action or an Escalation it will send an email to multiple members of the Person Group, if unchecked it will send to one person based on calendar/shift availability. The Ticket Communications (2) article uses this role both when broadcast is enabled and disabled, you can find it here – http://maximosecrets.com/2021/12/02/ticket-communications-2/

Incidentally, the Broadcast field can also be used with DATASET, USERDATA and CUSTOM role types.

The ”Person Group” type can also be used to point to a field that contains the value of a Person Group. When used in this case you need to enter an Object, then in the Value field the Relationship Tree dialog can be opened and the field selected. In the example shown the SR object was used and the OWNERGROUP attribute selected, the Value is then set in the bind field form “:ownergroup”. When a communication is created on a Service Request using this role it will send an email message to all the people in the Person Group that is referenced in the Owner Group field on the Service Request, in the example Broadcast is enabled.

You get to the Relationship Tree by choosing Select Fields from the detail menu in the Value field.

The role type of “A set of data related to the record” is often known as the DATASET role. It is the most common type of role as it can be used to resolve to any field that contains a person or email address in Maximo.

When I filtered by Type is dataset in the List tab you may notice that every record references an Object. You might notice that some fields like the second record for the WOLEAD role points to the LEAD field in the WORKORDER object, other records might precede this with a colon (:) in the bind field form, for example :PURCHASEAGENT. It shouldn’t matter whether you precede with the colon or not, but if you used the relationship tree from the Value field it would always be in bind field form so I would add the colon as if you had selected the field from the relationship tree.

The relationship tree can navigate deeply into Maximo. For example on the ASSET object, the ASSTSUPR role – Designated supervisor of the user associated with an asset – points to the :ASSETUSERCUST.PERSON.SUPERVISOR.PERSONID. The first three elements are all relationships and PERSONID is an attribute. If there are multiple user/custodian records for the asset then this could resolve to multiple persons, if they had different supervisors.

Note. :ASSETUSERCUST.PERSON.SUPERVISOR would give the same result, the SUPERVISOR in this case is an attribute.

The Role SRREPPERS – SR Reported Person, that I created for the first Ticket Communication article is based on the SR object and points to the :reportedemail attribute. As this is an email and not a person you need to let Maximo know this by selecting the E-mail checkbox.

In this example it is best to use the :reportedemail instead of :reportedbyid as you can raise a Service Request using a name and email address, there does not need to be an associated Person record. The article can be found here – http://maximosecrets.com/2021/12/02/ticket-communications-1/

The Broadcast field is always checked by Maximo for the DATASET role type.

The Role type of “A set of data related to the login user” is known as the USERDATA role or User role. There are no roles of this type in the MAXDEMO database, so I have created one called USERSURP – Users Supervisor. (I noticed too late that I had dyslexic fingers, I should have called it USERSUP.)

This role type is very similar to the previous one DATASET, but it always starts from the PERSON object in the relationship tree. The Value of :supervisor is the supervisor of the current logged in user, which for me is DBO – Danny Bols. The Broadcast field is not checked when a record is created.

Let’s see this one in action.

You might just be able to make out that I am in the Service Requests application, and I am logged in as AJE – Andrew Jeffery. I have used the Create Communication action and picked the role USERSURP.

When the OK button is pressed the role resolves to the email address of my supervisor Danny Bols. This Role Type is most likely to be used in Workflow. 

Custom class (CUSTOM)

The Role type of Custom Class requires a Java class file to be created. There are seven standard ones, three of which resolve to the audience in a bulletin board.

The BBAUDPG Role is a custom Role using the Custom class role type against the BULLETINBOARD object. The Value field is used to reference the Java class file. The Broadcast field is checked to send to the whole audience from all of the referenced person groups.

The Role SUPERVISOR is an example of a Custom class Role Type where it uses the Parameter field. The Parameter field can only be used with the Custom class Role type.

The IBM Documentation for the Types of Roles says that the class must implement the interface psdi.common.role.CustomRoleInterface. If you don’t do this you may get the error message “BMXAA0562E – Custom class TEST must be rewritten to implement interface psdi.common.role.CustomRoleInterface”

See – https://www.ibm.com/docs/en/mam/7.6.1?topic=overview-types-roles

In Maximo Manage (v8.x), it looks as if there is a way to use an Automation Script with a Custom Role. https://www.ibm.com/docs/en/maximo-manage/8.0.0?topic=tasks-example-automating-communication-by-using-custom-role

Deleting Roles

When deleting a role, you may receive one of the following messages:

Roles are used in:

Roles used with Other Applications

The Role does not need an Object unless it is of type DATASET. But a role is used in other applications for example Escalations, Communication Templates, Workflow, Service Level Agreements and Email Interactions which do reference an object. You should make sure that you align the objects where these get used together. 

For example, an Escalation on the SR object uses a Communication Template that should reference the SR object otherwise you will receive the error message “BMXAA1137E – Not a valid template.” Similarly on the Communication Template you should reference roles that either belong to the SR object or have a null object. You probably wouldn’t get a result if you tried to use a Role based on the WORKORDER object on a Communication Template that applies to the SR object.

For Email Interactions you would get an error message “BMXAA8557E – The email interactions need to have the configuration, communication templates, escalation, and role in sync regarding the object being interacted with”. 

If when you piece this all together and you get no email or workflow assignment don’t forget to check that the objects do align, as if not, this might be the cause of the issue. 

One response to “Roles”

  1. Communication Templates – Maximo Secrets

    […] 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/. […]

    Reply

Leave a Reply

%d bloggers like this: