Configuring Map Symbology on Maximo Scheduler

Customizing Maximo Scheduler Map look and feel

Author: Marcelo Blechner, Staff Software Engineer, marcblec@br.ibm.com

Author: Rafael Thomas Goz Coutinho, Advisory Software Engineer

On Maximo Scheduler, the geographic location of records (such as assets and work orders) can be viewed as markers on a map. In order to make such information meaningful and easily interpreted by the user, different shapes and color codes are used to represent different types of Maximo objects and in different states.

Maximo Scheduler has already defined a standard set of symbologies for Workorders, Assets etc. However in some cases it is important to change the symbology for a Workorder priority 1, or to create a new symbol for a new Workorder worktype.

This article describes how to configure the symbologies for Maximo Scheduler in order to have custom representations of Maximo entities on the Map.
 

Adding layers tool to a Map Control

The first thing to do is to add the Layers tool to your Map control. The Layers tool allows you to change the default symbology for an object on the map. In order to add it you must go to Application Designer application and update the Map control property Tool items. Tool items is a property that contains a list of tool identifications that will be displayed on the map. For example the value ['RefresherTool','FullScreen'] defines 2 tools on the map identified by RefresherTool (which is a tool to force the map refresh) and FullScreen tool that allows you to force the map to be displayed in fullscreen.

The layers tool is identified by LayersTool. You need to add it to the list of Tool items, for example:
 

 ['LayersTool','RefresherTool','sep','FullScreen']

The property value above is going to add the layers tool, the refresh tool, a separator for a better user interface and the fullscreen tool. After saving the presentation in Application Designer the map toolbar will contain the buttons as shown below:

 

Symbology types

In Maximo Scheduler there are two types of map symbology: route symbology and symbology based on record attributes.
 

Route symbology

Route symbology is mainly used to differentiate each resource route. For instance in the Graphical Assignment application work orders are displayed on the map with routes linking them to each other. Each route corresponds to a crew or labor responsible for that set of work orders. Users can quickly identify the work orders assigned to each route because their markers have the same color (the route color).

Here is an example of map markers when the Route Symbology is active. Note that the markers and the route polyline have the same color.


 

Symbology based attributes

Symbology can be set based on the records attributes. The user may want the map to display assets differently based on their statuses. Unlike route symbology, this one is customizable and the user can select which attribute the symbology will be based on and the images for each specific attribute value. It is also possible to define images for ranges of numeric values, like priority.

For instance here are Workorders with symbologies based on Worktype, Status and Priority:





As seen on the image above, symbologies greatly improves the understanding of the entities on the Map.
 

Symbology configuration file

The configuration of the symbologies is done on the map-symbology-config.json file located in MAXIMOROOT/applications/maximo/properties folder.

This file is in json format and contains information on the three basic symbology elements: layer, symbology and legend.

Layer: A layer is a group of records of the same type for which different symbologies can be applied. It is usually a Maximo Object. For instance, a work order record will be displayed on the map in the work order layer. A layer can be switched on and off. When a layer is switched off, all markers corresponding to records that belong to that layer will not be visible.

Symbology: A symbology is a classification rule in which layer records are assigned to subsets of records. This classification rule can be either the possible values of a certain attribute or a range of values, in case of numeric attributes. For instance, work orders can be divided according to status, priority, work type.

Legend: A legend is the definition of an attribute value (or range) within a certain symbology. The legend contains information on the value (or range) that it represents as well as the symbol to be used as map marker for all records that match the legend. For instance, if the current selected symbology for work order is "status", all work order records with status=APPROVED will be drawn on the map according to what is defined for the "approved" legend.



Example Layer, Symbology and Legend Dialogs (Work Order - Status).



Example of map markers when the Priority Symbology is selected for Work Order Records.
The Map Symbology configuration file (map-symbology-config.json) is located in the same directory as the maximo.properties file (<MaximoRoot>/applications/maximo/properties).

Below is the description of each configuration properties.
 

Layers

Each item in the "layers" array contains the following attributes:
 

• "id": A Maximo object name. (Required)
• "label": Layer label. If set, it will show up for all users, overriding localization. (Optional)
• "labelGroup" and "labelKey": Properties used to retrieve the localized label. Ignored if "label" property is set. If neither "label" nor the "labelGroup"/"labelKey" pair are set, the "id" attribute will be used. (Optional)
• "symbologies": Array of symbologies. Explained below. (Required)
• "symbologyTitle": Label for dialog with this layer's symbologies. If set, it will show up for all users, overriding localization. (Optional)
• "symbologyTitleGroup" and "symbologyTitleKey": Properties used to retrieve the localized label. They are ignored if "symbologyTitle" is set. If neither "symbologyTitle" nor the "symbologyTitleGroup"/"symbologyTitleKey" pair are set, the layer's label is used. (Optional)

An example of how to create a layer configuration is available in the "Creating the symbology configuration for a new layer from scratch" section.
 

Symbologies

For each Layer there are several symbology definitions. Each symbology defines on which attribute a Layer is represented. The properties available are:
 

• "id": Usually a Maximo attribute name that exists in the object defined by the parent layer. (Required)
• "label": The label to be displayed for this symbology. If set, it will show up for all users, overriding localization. (Optional)
• "labelGroup" and "labelKey": Properties used to retrieve the localized label. Ignored if "label" is set. If neither "label" nor the "labelGroup"/"labelKey" pair are set, the title associated with this attribute (if it is a Maximo attribute) will be used. If the label cannot be retrieved by any of the previous methods, the "id" will be used as label for this symbology. (Optional)
• "legends": Array of legends. Explained below. (Required)
• "type": The possible values for this property are: "domainvalue", "tablevalue", "numeric", "dynamic".
  • Use "domainvalue" if this symbology's legends are Maximo synonym domains (for instance, work order status).
  • Use "tablevalue" if the legends are records from a Maximo table (for instance, work types).
    • "domainObject": Required if type is "tablevalue". Defines the Maximo object that contains the records to be associated with this symbology's legends.
    • "domainIdField": Required if type is "tablevalue". Defines a key field from "domainObject". Entries in this field will be matched with this symbology's legends.
    • "domainValueField": Required if type is "tablevalue". Defines a value field from "domainObject. Entries in this field will be used as labels for this symbology's legend whenever a "domainIdField" entry matches a legend defined in this configuration file.
  • Use "numeric" if the legends are numeric and need to support ranges (for example, priorities).
  • The "dynamic" type is used only for some specific symbologies that are built dynamically and do not depend on this configuration file (for instance, Resources). (Optional)
• "legendTitle": Label displayed on symbology's legends dialog. If set, it will be the label that shows up for every user, overriding localization. (Optional)
• "legendTitleGroup" and "legendTitleKey": Properties used to retrieve the localized label. Ignored if "legendTitle" is set. If neither "legendTitle" nor the "legendTitleGroup"/"legendTitleKey" pair are set, the dialog title for this symbology's legends will be the same as this symbology's label. (Optional)

An example of how to create a symbology configuration is available in the "Creating the symbology configuration for a new layer from scratch" section.
 

Legend

For each symbology there are several legend definitions. Each legend defines what symbol to use if the attribute of an entity of that layer matches this legend. The properties available are:
 

• "id" - If symbology type is "domainvalue", the "id" must match a MAXVALUE entry of a synonym domain.
  • If symbology type is "tablevalue", the "id" must match a "domainIdField" entry of "domainObject".
  • If symbology type is "numeric", values must be unique within a symbology.
• "label": The label to be displayed for this symbology. If this property is set, it will be the label that shows up for every user, overriding localization. (Optional)
• "labelGroup" and "labelKey": Properties used to retrieve the localized label. Ignored if "label" is set. If neither "label" nor the "labelGroup"/"labelKey" pair are set, the label for this legend will be retrieved from a Maximo database if a synonym domain or table value match was found. If the label cannot be retrieved by any of the previous methods, the "id" will be used as label for this legend. (Optional)
• "minValue" and "maxValue": Required if type is "numeric". Defines the range of numeric values that this legend represents. The range is inclusive, i.e. a if minValue is 1 and maxValue is 10, both 1 and 10 are included in this range.
• "isDefault": The only value that can be defined for this property is "true". Omit this property when the legend is not the default legend. Records that do not match any of the existing legends from this configuration file will be drawn using the marker defined for the legend that has the "isDefault" property set. At least one legend in each symbology must have "isDefault" property set.
• "symbol": The "symbol" contains a set of properties that define the marker to be used for this legend. (Required)

An example of how to create a legend configuration is available in the "Creating the symbology configuration for a new layer from scratch" section.
 

Symbol

The Symbol actually defines the image file to use, the image dimensions etc. The properties for a symbol are:"url": Marker URL image. (Required)

• "urlRTL": Marker URL image for "right-to-left" languages. (Optional)
• "color": Used as fill colors for markers with polygons. (Not implemented yet)
• "offsetx" and "offsety": Defines how much (in pixels) the marker must be moved from the record's reference position. (optional)
• "width" and "height": Defines the width and height of the marker image (in pixels). If not defined, the marker will be displayed with its default size.

"fwm_default": Used as "id" for symbologies that have only one legend. Both the symbology and the legend have "fwm_default" as id.

"fwm_others": Used as "id" for legends that have the "isDefault" property set, but it is not mandatory.
 

Changing an existing symbology configuration

The default version of map-symbology-config.json contains symbology definitions for the following Maximo objects: Work Order, Labor, Crew, Service Address, Service Request, Asset, Location, Change, Activity and Task, Release. Note that the id must be the corresponding Maximo Object Name, for instance, "amcrew" for Crew, "sr" for Service Request. For other objects that may have a service address associated (i.e. objects that can be displayed on a map) but do not have a specific entry in the map-symbology-config.json file, the "others" layer definition will be used. This layer definition cannot be removed; otherwise records of Maximo objects that do not match any layer in the configuration file will not be displayed on the map. Note that only default symbology and legend are defined for the "others" layer. This is by design because the only purpose of this layer is to specify a default marker for any "mappable" record with no layer defined.

Adding a new entry to the Map Symbology Configuration file

Suppose you have created a new work type entry and want it to be available in the "work type" symbology for work orders. Here are the steps:Open map-symbology-config.json

1. Look for the "worktype" symbology:

{
    "id": "worktype",
    "type": "tablevalue",
    "domainObject": "worktype",
    "domainIdField": "worktype",
    "domainValueField": "wtypedesc",
    "legendTitleGroup": "map",
    "legendTitleKey": "workorderworktypelegendtitle",
    "legends": [
        {
            "id": "null",
            "labelGroup": "map",
            "labelKey": "emptylegendlabel",
            "symbol": {
                "url": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/symbology/workorder/map_WO_workType_blank.png",
                "urlRTL": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/rtl/symbology/workorder/map_WO_workType_blank.png",
                "color": "",
                "offsetx": 24,
                "offsety": 36,
                "width": 47,
                "height": 36
            }
        }
[..]

Note the three properties that are responsible for binding the work type table entry with the entries in this configuration file:

1. "domainObject": "worktype" - the domain object name
2. "domainIdField": "worktype" - the table column from object "worktype" containing the key that must match the work type being added
3. "domainValueField": "wtypedesc" - the table column from which work type description will be retrieved

Using any existing legend (cm, em, pm) as example, copy an entire legend entry and paste it between 2 existing entries.

Make sure that there is only one legend with the property "isDefault":"true".

Example of a legend entry that can be used in the before mentioned copy/paste process:

{
    "id": "cm",
    "symbol": {
        "url": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/symbology/workorder/map_WO_workType_correctiveMaint.png",
        "urlRTL": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/rtl/symbology/workorder/map_WO_workType_correctiveMaint.png",
        "color": "",
        "offsetx": 24,
        "offsety": 36,
        "width": 47,
        "height": 36
    }
},

Considering that the work type to be added is "Calibration" (CMCAL), make the following changes in the copied legend entry:
 

1. Replace the value of the "id" property with "cmcal", so it becomes"id":"cmcal".
2. Replace the value of the "url" property with the image path to be used. Note: all the existing work order images are 47x36 (width x height) and they have the marker point horizontally centered and at the bottom of the image, so the existing values for width, height, offsetx and offsety can remain unchanged. For instance, if you choose to use map_WO_1c29a8.png, the "url" entry will become "url":"../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/symbology/workorder/map_WO_1c29a8.png".Change the "urlRTL" property accordingly so the new image is displayed when Maximo Scheduler is configured for right-to-left languages.

# Figure 5: Marker image example with dimensions.

Should you use an image with dimensions different from the ones from Figure 5, then width, height, offsetx and offsety must be changed accordingly. It is important, however, that the dimensions and marker point position be the same in both LTR and RTL images because they share the same settings.

The new legend entry should now look like this:

{
    "id": "cmcal",
    "symbol": {
        "url": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/symbology/workorder/map_WO_1c29a8.png",
        "urlRTL": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/rtl/symbology/workorder/map_WO_1c29a8.png",
        "color": "",
        "offsetx": 24,
        "offsety": 36,
        "width": 47,
        "height": 36
    }
},

After making the changes, do the following:

1. Save the map-symbology-config.json file.
2. Shut down the Maximo application server.
3. Rebuild maximo.ear by executing <MAXIMO>/deployment/buildmaximoear.cmd.
4. Re-deploy the new maximo.ear on your application server and restart the application server.

The new work type should now be visible in the legends dialog. Work orders with work type set to "CMCAL" should now show up on the map with the new marker image if the current symbology selected is "work type".

Below is an example of work order records showing up on the map with work type as selected symbology.



Example of map markers when the Work Type Symbology is selected for Work Order records. Note that the bottom right record is the custom marker added for work type CMCAL.
 

Creating the symbology configuration for a new layer from scratch

In articles Adding a Map to any Maximo application and Making your Maximo objects available on the Map we explained how to add a Map Tab to a Maximo application and how to make a Maximo Object GISable, i.e. able to store and use geographic location information.
Now we are going to create symbology configuration for the Item object so that a custom marker can be used to represent records on the map.
The first thing is to create a new layer for the Maximo Object: Item. The following snippet shows the properties to be added in order to add the new layer:

[..]
{
    "id":"item",
    "label":"Item",
    "symbologyTitle": "Item Symbology",
    "symbologies": []
}
[..]

The "id" property must match the Maximo object name "item". The label that will show up on the "layers" dialog is the value of the "label" property. Note that, by using the "label" property instead of the pair labelGroup/labelKey, the label will always be the same, regardless of the user selected language. The same goes to the "symbologyTitle" property, which is the label for the layer's symbology dialog.

By default, the layer tool is not available on custom maps, but it can be added following the steps in this guide Configuring Tools in Maximo Scheduler Maps.

The next step is to create the default symbology (because all layers in the configuration file must have at least one symbology and one default legend for that symbology).

[..]
{
    "id":"item",
    "label":"Item",
    "symbologyTitle": "Item Symbology",
    "symbologies":
    [
        {
	    "id": "fwm_default",
	    "labelGroup": "map",
	    "labelKey": "defaultlayerlabel",
	    "legendTitle": "Item Legend",
	    "type": "domainvalue",
	    "legends": []
        }
    ]
}
[..]

Since this symbology is the only one (and consequently the default one), its "id" is "fwm_default". Note that there is no need to create a new label for the default symbology, so you can use the same labelGroup/labelKey pair used for all other default symbologies. Alternatively, a "label" property could have been used instead. The "legendTitle" property, which is the title of this symbology's legend dialog, can be explicitly set as "Item Legend".

The last step is to add the entries for the default legend and define the symbol to be used as marker for Item records on the map.

[..]
{
    "id":"item",
    "label":"Item",
    "symbologyTitle": "Item Symbology",
    "symbologies":
    [
        {
	    "id": "fwm_default",
	    "labelGroup": "map",
	    "labelKey": "defaultlayerlabel",
	    "legendTitle": "Item Legend",
	    "type": "domainvalue",
	    "legends":
            [
                {
	            "id": "fwm_default",
                    "labelGroup": "map",
                    "labelKey": "defaultlayerlabel",
	            "symbol":
	            {
                        "url": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/symbology/workorder/map_WO_1c29a8.png",
                        "urlRTL": "../webclient/javascript/ibm/tivoli/fwm/mxmap/resources/rtl/symbology/workorder/map_WO_1c29a8.png",
                        "color": "",
                        "offsetx": 24,
                        "offsety": 36,
                        "width": 47,
                        "height": 36
                    },
                    "isDefault": true
                }
            ]
        }
    ]
}
[..]

Since this legend is the only one (and consequently the default one), its "id" is "fwm_default" and the "isDefault" property is set to true. In this case, the "id" could have any other value as long as the "isDefault" property is set. Here again we can use an existing label for the default legend by copying the values for the labelGroup/labelKey pair of other legends. Again, alternatively, a "label" property could have been used instead.
The dimension properties were copied from other symbols because the marker images defined in the url properties are existing work order images with dimensions as specified in figure 5. However, other images can be used.

In order for the new layer configuration to take effect, do the following:

1. Copy the new layer configuration properties from the example above.
2. Open map-symbology-config.json and paste the layer properties after the last layer definition.
3. Save the map-symbology-config.json file.
4. Shut down Maximo application server.
5. Rebuild maximo.ear by executing <MAXIMO>/deployment/buildmaximoear.cmd.
6. Re-deploy the new maximo.ear on your application server and restart the application server.

This is how an Item record will show up on the map:



And if the layer tool has been added to the map control, here is what the layer dialogs should look like: