Domains are used to create a list of values on a field. The domain defines the data to be shown, but displaying the list is something you configure in the user interface, by using the Application Designer application. A domain also applies a validation on the field, if a value is entered that does not exist in the domain set of values, then you will receive an error message.

The Domains application will be found in the System Configuration – Platform Configuration module. You will find all the domains created by IBM for the Maximo system. The system I am using has HSE and the Service Provider add-ons installed and so you may find a smaller number to the 900+ records found on my system.

There are six domain types which we will review – ALN, NUMERIC, NUMRANGE, SYNONYM, TABLE and CROSSOVER. The button Add New Domain will allow you to create each type except for SYNONYM, this is because Maximo business logic is tied to the internal values of a synonym domain, more on this later. Domains are defined at the System level, but we shall soon find that you can define values at the 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 and SiteA structural element of a Maximo database that is used for data separation. More level.

ALN Domain

The ALNDOMAIN has an alphanumeric value and a description that can be up to 140 characters unless this has been modified. The VALUE field is defined as being ALN 254, sometimes just the values are used and there are no descriptions.

The example shown are the four default values for a Downtime Code, the reason for the downtime, Adjust, Breakdown, Minor Stop, Setup. You are free to change these, and there is a delete button on the right-hand side of the table window. Don’t add the language equivalents of these codes as extra records, as Maximo supports a language table on Domains, we’ll also come to that a little later.

The Data Type can be UPPER, LOWER or ALN. Upper case only, or mixed case with the ALN option are the most frequently used. There is also a length field. The Data Type and Length should tie-up with the same Data Type and Length used for the attribute where you are adding the domain.

In the Database Configuration application and the Attributes tab you will find a field called Domain in the second column of the table details. It is this field where you apply the domain to an attribute of a Maximo object, and by doing so any new values entered will be validated against the set of values defined by the domain.

For the object ASSETSTATUS and the attribute CODE, the DOWNCODE domain has been applied. Notice the CODE attribute has the same Type and Length definition as that entered for the domain. 

If a site (or organization) wishes to have a different set of values, then this is possible by creating additional records. In the example the FLEET site wants to use SCHED (Scheduled) and UNSCHED (Unscheduled).

If we go to the Assets application for the FLEET site’s asset A6002 and use the Report Downtime action, then the two values SCHED and UNSCHED are displayed for the Downtime Code lookup, it’s Select Value. The other four values for the downtime code are not shown for assets in the FLEET site. If you add one record at the Organization or Site level, then you need to add all the values that you wish to be seen by records which reference that organization or site.

NUMERIC Domain

The NUMERIC domain type is like ALN with a code and description (117 characters) but the Data Types that can be used are those held in numeric database fields, AMOUNT, DECIMAL, DURATION, FLOAT, INTEGER, SMALLINT. Numeric type fields will have a set Length, but they may also have a Scale. Again, this should align with the attribute definition where the domain will be used.

The default length and scale are as follows:

• AMOUNT (10,2) – cannot be modified
• DECIMAL (16,2) – may be modified
• DURATION (8,0) – cannot be modified
• FLOAT (8,0) – may be modified
• INTEGER (12,0) – cannot be modified
• SMALLINT (10,0) – cannot be modified

The Length and Scale of an AMOUNT field and the Length of an INTEGER and SMALLINT field can be globally set using the Field Length and Format action and dialog found in the Database Configuration application. 

An example of a Numeric Domain is the Ticket Priority (TICKETPRIORITY) used on a Service Request for the INTERNALPRIORITY and REPORTEDPRIORITY attributes. The attribute length and scale are actually 12,0, but the domain is defined as 4,0. 

NUMRANGE Domain

There are not many examples of the Numeric Range Domain in a MAXDEMO database, one that you will find is the GRTYPE, Guard Rail Type, which is provided as part of Linear, which is now part of MAS Manage. You do need to specify the Data Type, Length and Scale as for the NUMERIC domain.

The values can exist is multiple ranges, normally defined as 1,2,3, etc. For each range you can specify a Range Minimum and a Range Maximum with an Interval. In the example, the range is 1 to 40 with an Interval of 1, this will allow the values 1,2,3,4 … 40 to be entered but you will receive an error message if the value is outside of this range. In this example, entering a value of 0 will give the error message “0 is not defined in the domain GRTYPE. (BMXAA0211)”.

The NUMRANGE domain does not provide a set of values in a lookup, you only get a validation when you enter a value.

Another example from the HSE add-on or the O&G Industry Solution is the Priority Matrix (PLUSGMATRIXPRIOR) which has five ranges. In this case the ranges are contiguous, but they do not have to be. This is an example where the domain has been used to provide some functionality rather than a validation of values. The ranges are in hours and they are used to calculate target dates on the work order. But if this domain was used to provide validation of an entered value, then valid values would be between 0 and 2,880.

The most likely use of a custom Numeric Range Domain would be in creating percentages with a range between 0 and 100. If you defined the Numeric Range Domain as an Integer, then only integers can be used, and the Interval would be 1. But the Interval field is defined with a type of FLOAT, so an interval of 0.01 could be used to allow a percentage on a Decimal field with up to 2 decimal places. 

An interval of 2 can be used to provide odd or even numbers.

Synonym Domain

A Synonym domain is used for most status fields in Maximo. The PERSONSTATUS domain which only has values of ACTIVE or INACTIVE is a synonym domain. 

With a Synonym Domain there is an Internal Value against which Maximo business logic is written and then one or multiple Values that exist at the level of the Internal Value. We call the values “Synonyms of”, and the internal values the statuses.

There is terminology or phrasing we tend to use when we describe synonym domains. For example – “The synonym domain LOCASSETSTATUS which is used for the status of Locations and Assets has the statuses of NOT READY, OPERATING and DECOMMISSIONED (also IMPORTED) and the synonyms of INACTIVE, MISSING, BROKEN and SEALED at the DECOMMISSIONED level.” Whenever we talk about synonym domains it is important to emphasise the level (Internal Value) as that helps to describe the Maximo functionality, the business logic which is tied to the internal values.

We tend not to include the internal value when describing the synonyms of an internal value, notice I didn’t use the synonym status of DECOMMISSIONED when describing the synonyms of the DECOMMISSIONED level, we would be repeating the term. But DECOMMISSIONED is a valid Value at the Internal Value of DECOMMISSIONED, and where the Internal Value and Value are the same, this is also the Default Value, the default can be changed.

For Synonym Domains you can also set up domain values at the Organization or Site level. For the old locationA physical place where assets exist and where work can be performed. More status synonym domain LOCSTAT I have added a new status NOTOPERATING at the DECOMMISSIONED level for the FLEET site and made it the default.

When you use the OK button, you will receive a warning message “BMXAQ0290W – One or more synonym domain values have been modified. If you have any records that reference old synonym values, you need to update them for the system to work properly. Introducing customer, site or organization synonym values does not automatically include all existing global ones.”

The result is that Maximo has created new status values at each level for the FLEET site, one new record for the Internal Values of PLANNED, OPERATING and DECOMMISSIONED. The valid values when working on the FLEET site would be PLANNED, OPERATING and NOTOPERATING, a value of DECOMMISSIONED would be rejected with an error message as although this is an Internal Value for the FLEET Site it does not exist as a Value.

Adding Conditions to Status Values

You might have noticed the action View/Modify Conditions as we were looking at ALN, NUMERIC and SYNONYM domains. This action allows you to control the statuses that are displayed based on the current status.

Before you use the View/Modify Conditions action you should select the domain value that you wish to change, you can also click in the row. The internal unique identifier of the domain status record is then used to filter for any existing conditions. What you see in the screenshot is the filter fields, and not the start of creating a condition, you still need to use the Insert Row button (+).

I have created a Condition in the Conditional Expression Manager application, 1015 – Always False with an expression of 1=2 and applied it to a new condition for the NOT READY status in the LOCASSETSTATUS synonym domain. I’ve applied this so that this condition is only applied to the ASSET object.

After you have used the OK you will see on the right-hand side an icon to show that a condition exists for the NOT READY status. If you click this button, it will take you into the View/Modify Conditions dialog for this row. To see all the conditions applied to the domain you need to clear the filter.

In the Assets application you can see that there is no NOT READY status available in the list of statuses. The condition that is tested results in false and so the value is not displayed. However, it does appear in the Locations application.

Note. The condition does not apply from a Select Value in the Advanced Search or from the List Tab, it is only applied in a field which is being used to update a record.

I’ve added three more conditions on the synonym statuses of BROKEN, MISSING and SEALED to exclude them all from the LOCATIONS object. You need to clear the filter field for Value ID in order to see all the conditions.

You can see that the synonym statuses of BROKEN, MISSING and SEALED which are more applicable to assets are now no longer selectable for a location, but they are still available for an asset.

You might have wondered – Is there a way of adding the same condition to multiple values in one action? You might have also spotted in an earlier screenshot the button Set Conditions, in the bottom left corner. If you select multiple statuses and use the Set Conditions button you get a slightly different dialog. The Set Conditions dialog allows you select a Condition Number and optionally an Object. I am applying the same condition to the three statuses, BROKEN, MISSING and SEALED, but this time for the ASSET object.

After using the OK button and using View/Modify Conditions and clearing the Value ID field in the filter, you will now find an additional three conditions have been added. 

Table Domain

There are several table domains in a MAXDEMO database, but most of them are used for the configuration of Maximo. There is one used with the Budget Monitoring application called ATTRIBUTES.

A table domain is a lookup on data that exists elsewhere in Maximo, in this case we are looking up against the set of fields defined in the Maximo database, looking up against an Object called MAXATTRIBUTE. There are two SQL Where clauses.

The List Where Clause defines what records will be shown in a lookup, in the example “objectname=:objectname” means show me the records from the Object where the objectname (MAXATTRIBUTE.OBJECTNAME) is equal to the value in the launching records :objectname field.

The Validation Where Clause is normally similar to the List Where Clause, but it is the validation that will be performed when a value is entered into the field and this clause should resolve to only finding one record. In the example it is “objectname=:objectname and attributename=:attributename”. Meaning, validate that the record from the MAXATTRIBUTE object has the same objectname and attributename as the :objectname and :attributename in the current record, this is the record as shown in the application screen, and not the record that is currently in the database.

In the Budget Monitoring application and the Manage Rules action and dialog, the Select Value on the Attribute field shows the attributes of the Object which in this case is LABTRANS, used in the Labor Reporting application.

The columns of the records found, Attribute and Title in this case, is defined by the Lookup for the field as found in the application definition which will be found in the field’s property in Application Designer.

If the validation fails, you can provide an error message by referencing an Error Message Group and Error Message Key. These would be defined in the Database Configuration application and action Messages.

Table Domains can be used for the validation of a value entered in the attributes of a Classification.

CROSSOVER Domain

The top half of a crossover domain looks just like a table domain, but it is the bottom half where it differs, you can just see the top of a table window called Crossover Fields.

There is no List Where Clause in this example, there will be no Select Value lookup. This example is one of several across Maximo which copy data from one object to another when a record is created. In this case, when you create a work order from a service request, the attribute ORIGTKID is populated with the TICKETID of the Service Request and the crossover domain is on the ORIGTKID attribute, so it fires and if the validation is successful it copies over a set of fields from the TICKET object to the WORKORDER object.

To find other similar crossover domains search in the Domains application with a Domain of cross,2 and a Domain Type of CROSSOVER.

The Error Message Group and Error Message Key are used to configure the type of error message. In this case a MSGBOX is displayed with an Error Message ID of BMXAA4289E and a message of ‘Not a valid ticket.’. The messages used in Maximo will be found in the Database Configuration application and action Messages.

The Crossover Fields table window has a number of fields to explain.

The Source Field is the field in the Object from which you are looking up a record, in this case TICKET.

The Destination Field is the field in the object from which the Crossover Domain fires, in this case the domain is on the WORKORDER object. The example shows that the Tickets ASSETNUM field is copied to the same field on the Work Order. The row above this indicates that the value of the Tickets attribute AFFECTEDPERSON is copied to the ONBEHALFOF field on the Work Order. 

The sequence is the order in which we want the fields to be copied across. As shown, you do not need to enter a value, but it is important when there are two or more related fields. For example, if you were copying the Calendar and Shift to another object, you would want the Calendar to be populated before the Shift is populated because there is a validation on these fields, a Shift with a null Calendar would give an error, as a shift must belong to a Calendar.

The field Accept NULL Values considers what to do if the source field is null or blank. The attribute is COPYEVENIFSRCNULL which describes this function well. If Accept NULL Values is set then if the source is null, it will be copied, which will blank out any value in the destination record. If it is not set, then any non-null value will be copied overwriting the destination field.

The field marked No Overwrite (COPYONLYIFDESTNULL) when set will only copy the source value to the destination field if the destination is currently null or blank. If it is not set, then the source value will be copied overwriting the destination field’s value.

The Condition on Source is a condition created in the Conditional Expression Manager and it must be written in the context of the source Object. If the condition evaluates to true, the value in the attribute will be copied.

The Condition on Destination is a condition created in the Conditional Expression Manager and it must be written in the context of the destination Object. If the condition evaluates to true, the value in the source attribute will be copied, if false it stops the value from being copied.

If a condition uses fields on the destination object which are manually entered, then obviously the condition will only be true if someone has entered something in the dependent fields first. For example, if a condition is going to use the work order STATUS this can be evaluated as the STATUS field has a default and always has a value. However, if a condition is going to use the WORKTYPE and this does not have a default value, then it will only evaluate to true if the user has first selected the work type.

When using the Condition on Destination field the Sequence field is important. The condition is evaluated when the field is set therefore the condition cannot use a field which has not been set yet.

Disable Caching

Disable Caching was introduced at the same time as Type-Ahead functionality in a field as part of Maximo 7.5, and this is part of a set of functionalities to support client-side validation, validation performed in the browser before validation occurs on the server. Client-side validation can improve performance. 

Type-Ahead is a display of the results of entering a few characters in a field, as additional characters are entered the filtering narrows the resulting set. It is the default for fields with simple domains, ALN, NUMERIC and SYNONYM. In Maximo 7.5 you could only disable caching for simple domains, but this would be unusual as the values are static, they change infrequently, so you should want the data to be held locally in the browser, unless company policy was to disallow caching. 

The action Disable Caching is performed for specific domains, and it stops the values from the domain from being cached on the client-side by the browser. It is used with simple domains, for NumRange and Crossover type domains you will receive the error message “BMXAA0029E – You are not authorized to perform this action for this record. Contact your system administrator to request changes to your authorization”.

In the screenshot I am using the Synonym Domain LOCASSETSTATUS and I have marked the Disable Caching toggle. The default is that caching of domain values occurs in the browser, therefore the field will be set off for all domains, caching is being enabled. Having performed this and with clearing my browser history I noticed no difference in the speed of loading data values for the domain in the Assets application. Note, I also work on a pretty slow network, so if performance has improved my network didn’t notice it.

You can now disable caching for TABLE type domains. You might want to use the Disable Caching on new table domains that you create. For example, if you created a table domain for Companies of Company Type ‘M’ – Manufacturers, and you added a new manufacturer, you wouldn’t find it being referenced on an asset until the cache expires. Therefore, you should disable the cache for table domains, unless you are certain the data is static and rarely changes, or you have configured a type-ahead with a ‘Refresh cache every’ – 1 day or 2 days. Type-Ahead is only available with Table Domains not simple domains.

Application Export and Application Import

The Domains application has the actions to perform an Application Export and Application Import, one of the applications which has this feature enabled by default although it can be added to most Maximo applications. Both actions use the Object Structure MXDOMAIN_FLAT.

The Object Structure MXDOMAIN_FLAT not only includes the MAXDOMAIN object but also the supporting objects for the different types of domains. I would be inclined to duplicate this object structure once for each type of domain and include the parent object MAXDOMAIN and only the relevant object, for example ALNDOMAIN for ALN Domains.

The Application Export and Application Import work from the List tab against a selected set of records. I think the output as a spreadsheet works best if all the domains are of the same type. 

Domains are normally associated with the configuration of the Maximo system, they provide some field validation, and the values may be tied to Workflow, Automation Scripts or Java code. These domains are copied across Maximo environments DEV, TEST and PROD using Migration Manager. Changes to the domain values can cause issues with the overall configuration of the Maximo system, and so these applications and their data values are often considered as off-limits to anyone not involved with the development or maintenance of the Maximo system.

However, there is a set of Domains which are considered as Data, the domains that support the values of Attributes associated with Classifications. ALN, NUMERIC, NUMRANGE and TABLE domains are all supported, but not for SYNONYM or CROSSOVER types. These domains may be defined by the Engineering, Procurement or Inventory departments and they may wish to load and maintain their own domain values for use with Classifications that they control. 

Updating domains by different sets of users can cause issues. This can be overcome by adding an additional attribute to the Domains application to provide the Purpose or Ownership of the domain. Then, controlling who has access to which domains through use of Security Group, Object Data Restrictions.

Now that we understand that there are different sets of users who may need to update Domains it becomes easier to understand why the Application Export and Application Import functions have been provided, so that some privileged users can create and modify domains and copy the data from one Maximo environment to another without having to know how to achieve this with Migration Manager.

Domains and Language Tables

As standard, the ALN, NUMERIC and SYNONYM domains which all have a value and a description, support a language table so that the description of the lookup value can be shown in the language of the user. The domains table MAXDOMAIN also has a language table L_MAXDOMAIN. The three language tables are L_ALNDOMAIN, L_NUMERICDOMAIN, L_SYNONYMDOMAIN.