Menu Reference Group

The main data entry method for the Pitram Mobile application is a wizard style main menu.  This allows the user to navigate through a series of screens culminating in the submission of an event to the event server.  Frequently used screens within the wizard can be allocated to shortcut buttons on the main mobile display to reduce the number of steps that a user must go through to enter common events.

The structure and appearance of the menus for the Pitram Mobile device are controlled by the Menu Reference Group.  Eventually this group will be maintained by Pitram. In version 3.9, a series of configured menu items can also be specified to enhance the layout and functionality of the Mobile user interface–refer to Configuring the menu displays the Menu Reference Group topic in the Extra Reference Group section.

The following record must exist in the RA_EXTRAREFERENCEGROUPS table for main menus to be distributed:

ReferenceGroupName ReferenceGroupType ReferenceGroupVersion ReferenceGroupActive
MainMenuGroup MainMenuGroup 1 1

Menu Database Tables

The Main Menu reference group is actually made up of 12 different tables.  This may seem daunting, but it should become clear if you follow through this section step by step.

You should understand the following concepts:

To understand how menus work, you must understand how events within PITRAM are structured.  Anything that occurs within the system (truck dump, alarm raised, person logging in, etc.) is recorded as an Event Packet.  Each category of events has a unique numeric code and a predefined set of parameters or data elements.

For example, all summed MEASURE events against equipment units within the system have a unique ID of 514.  They all expect to contain two data elements, MEASURECODE and MEASUREVALUE.

In effect, all a PITRAM menu does is construct an event packet and submit it to the system.  Each path through the menu has to gather the correct values for its data elements either from “FixedDataElements” (e.g. we know whenever a person hits the FUEL button that the MEASURECODE is Litre) or through user data entry.  Users can enter data either through a numeric keypad, or by selecting from a list of text values.

Lists of text values can either be based on a PITRAM Active List maintained through Pitram, or be based on a hard-coded list.

Main Menus vs Screens vs Lists

A potentially confusing area in the terminology is the difference between menus, screens and lists.

Menu

A menu is a screen presented to the user that does not relate directly to a Data Element.  It is never the last thing the user selects.  It always leads into one or more screens that allow the user to select or enter data.

Screen

A screen is the method through which a users enters or selects data.  A screen can either allow input of numeric data, or it can show a list of value from which the user can select.  Every screen results in the entry of 1 data element into the event packet.

Lists

Lists are a subset of screens.  For example, a screen that allows the user to select a dump location will display a list of locations.  Lists can be based on a set of fixed values or on an active list configured in Pitram.

Refer to the "Concepts and Terms" topic at the start of this document for more information.

The following tables should exist in the Pitram Server database:

  • RD_MAINMENU_Metadata
  • RD_MAINMENU_MenuDisplayConfiguration
  • RD_MAINMENU_MainMenu
  • RD_MAINMENU_LocalisedMainMenu
  • RD_MAINMENU_MainMenuItem
  • RD_MAINMENU_LocalisedMainMenuItem
  • RD_MAINMENU_FixedDataElement
  • RD_MAINMENU_Screen
  • RD_MAINMENU_LocalisedScreenDisplayName
  • RD_MAINMENU_StaticList
  • RD_MAINMENU_LocalisedStaticListItem
  • RD_MAINMENU_EventTokenSelection

All tables are prefixed with RD_MAINMENU_.  For the remainder of this section, this prefix will be removed to make the document more readable.

Metadata

The Metadata table contains a single row for each version of menus released.  A single version encapsulates all menus within the system  This means that version 1.0 will contain TruckMenus, SurfaceMinerMenus, LoaderMenus all related back to a single metadata record.  This record simply contains information update who last updated the data.  As this group is currently not managed by Pitram, these fields should be populated manually. 

RD_MAINMENU_MetaData

ReferenceGroupVersion

LastUpdateDateTime

LastUpdateUser

LastUpdateMachine

CreateDateTime

1

9/22/2006

mlayng

MM00318

9/19/2006

MenuDisplayConfiguration

The MenuDisplayConfiguration table is a place to store information related to how the menu looks on screen.  It controls items such as button width, font names and size, button locations.  Through this table, a standard look and feel for the menu can be designed and applied throughout the system.

Pitram does not require any values to be set within this table and I would recommend leaving it unless a need arises to use it.

RD_MAINMENU_MenuDisplayConfiguration

ConfigurationName SettingName ReferenceGroupVersion SettingNameDataType SettingNameText SettingNameNumeric
ConfirmationScreen FontFamily 2 0 Arial 0
ConfirmationScreen FontSize 2 1   12
DefaultConfig ButtonWidth 2 1   180

Data type 0 = text, 1 = numeric.

MainMenu

The MainMenu table contains a record for each menu that is defined within the system.  Each Pitram Mobile instance has a single menu, so a typical MainMenu table will contain rows such as TruckMenu, SurfaceMinerMenu, DrillMenu and LoaderMenu.

The MenuName field contains the unique name that defines this menu throughout the configuration.  It is also the name selected during the Pitram Mobile install screen that defines which menu is shown by that application. 

The ReferenceGroupVersion is the version defined in the metadata table.

The DefaultDisplayName is the name of the menu as displayed on the screen (used in message boxes and warnings).

The ConfigurationName and ConfirmConfigurationName fields relate to the MenuDisplayConfiguration table and help define the appearance and behaviour of the menu in general (ConfigurationName) and the confirmation process that occurs when a user tries to submit an event (ConfirmConfigurationName).

RD_MAINMENU_MainMenu

MenuName ReferenceGroupVersion DefaultDisplayName ConfigurationName ConfirmConfigurationName
LoaderMenu 1 Loader Menu DefaultConfig ConfirmationScreen
TruckMenu 1 Truck Menu DefaultConfig ConfirmationScreen

In some configurations it is possible for a menu to call another menu (see MainMenuItem table below).  In this case, the menu being called would also have an entry in the MainMenu table.

LocalisedMainMenu

The LocalisedMainMenu table simply allows the “DefaultDisplayName” of the menu to be displayed in different languages.  For example, if the default language for the system is English, there could be a record in this table that defines the display name for machines that are running a Chinese locale.  In general this table will not be used.

RD_MAINMENU_LocalisedMainMenu

Locale MenuName ReferenceGroupVersion DisplayName
zh TruckMenu 1 <Chinese representation of “Truck Menu”>

MainMenuItem

Each row in the MainMenuItem table relates to a button on a menu. For example, if your main menu looks like the following screenshot, you would have 9 rows in your MainMenuItem table for the TruckMenu.

Below is a sample of what a MainMenuItem table may look like. The ReferenceGroupVersion and MenuName provide the foreign key link back to the MainMenu table. Ie they identify which menu items relate to a truck menu as opposed to menus for other units.

The DisplaySequence field defines the order in which the menu items are displayed on screen. Number occurs across the screen first and then down.

The DisplayText and DisplayImage field defines the text and image displayed on each button. It is difficult to import images straight into SQL Server so I would ignore this feature until the Pitram configuration interface is in place.

The EventId column contains the numeric id of the event that is going to be raised. Common event ids are listed in Appendix B.

If there is a value in the NextMenuId column, then it will be the name of another MainMenuItem that will be displayed when the button is pressed. This is generally only used if you want to have a sub menu for something like cycle states.

The DisplayImageHeight, DisplayImageWidth and DisplayImagePixelFormat fields are used to control the way the bitmap is displayed within the button – best to ignore for now.

The ShortcutSequence and ShortcutColour fields are related to the ability to assign menu items to shortcut buttons. Shortcut buttons are displayed on the left hand side of the Pitram Mobile screen and allow easy access to the most commonly used menu items.  The sequence defines the order within the shortcut toolbar (lowest number displayed at the top of the screen. The colour defines the background color of the button.  Common colour values can be found in Appendix B.

The MenuHide column allows a menu to be defined, but not shown on the main menu screen. This would be used if there was a requirement to define a menu that was attached to a shortcut button that was not to be shown on the main screen. A value of “1” will cause the menu to be hidden.

The remaining four fields control which primary token creates the event. A primary token is generally the equipment code for which data is being entered. In normal operation these fields can be left blank. Events will be raised against the equipment unit that this particular instance of Pitram Mobile represents.   In some cases you may want to submit an event against a primary token other than the one your Pitram Mobile represents. This is generally needed for supervisory menu functions.

If the PrimaryTokenMode is set to a value of “1”, then the menu will submit an event against whatevever primary token is defined in the PrimaryToken and PrimaryTokenType fields.  PrimaryToken is the code of the token in question (e.g. EX007, DT004) while the PrimaryToken type is one of “EQUIPMENT”, “PERSON”, “LOCATION”.

If the PrimaryTokenMode is set to a value of “2”, then the event will be raised against the equipment unit that the Pitram Mobile is allocated to.  For example, if our Pitram Mobile unit represents DT004 and it is currently working under EX001, any events raised from this menu item will be raised against EX001.  If DT004 is not currently allocated to an equipment unit then no event will be submitted and a message box displayed to the operator.

If the PrimaryTokenMode is set to a value of “3”, then the event will be raised against the location that the Pitram Mobile is allocated to. 

If the PrimaryTokenMode is set to a value of “4”, then the event will be raised against the person currently identified as the primary operator of this equipment unit. If there is no primary operator, no event will be submitted and a message box displayed to the operator.

If the PrimaryTokenMode is set to a value of “5”, then the user can select the primary token from a list. The PrimaryTokenType field needs to identify whether we are dealing with a list of EQUIPMENT, LOCATION, PERSON. The PrimaryTokenSelectionScreenId needs to provide the name of a screen that lists the appropriate primary tokens (see section regarding the Screen table below). 

RD_MAINMENU_MainMenuItem

ReferenceGroupVersion MenuName DisplaySequence DisplayText DisplayImage EventId NextmenuId DisplayImageheight DisplayImageWidth DisplayImagePixelFormat ShortcutSequence ShortcutColour MenuHide PrimaryTokenMode PrimaryToken PrimaryTokenType PrimaryTokenSelectionScreenId
1 TruckMenu 0 Set Loader   258   30 70 9              
1 TruckMenu 1 Operating Delay   1025   30 70 9              
1 TruckMenu 2 Maintenance   1025   30 70 9              
1 TruckMenu 3 Queue   1025   30 70 9              
1 TruckMenu 4 Load   1025   30 70 9              
1 TruckMenu 5 Haul   1025   30 70 9              
1 TruckMenu 6 Dump   513   30 70 9              
1 TruckMenu 7 Fuel   514   30 70 9              
1 TruckMenu 8 Engine Hours   517   30 70 9              

LocalisedMainMenuItem

The LocalisedMainMenuItem table allows you to specify the display name for each menu item is a separate language.  Not populated for most sites.

FixedDataElement

The FixedDataElement table allows you to specify the data elements for an event packet that you do not want a user to select.  For example, if we have a menu option for the user to enter their fuel usage, we do not want the user to have to enter that the measure code is “LITRES”.  This would be entered through this table.

The ReferenceGroupVersion and MenuName and DisplaySequence fields provide the foreign key link back to the MainMenuItem table.

The DataElement contains the name of the data element that is being set. 

The DataElementDataType has a value of 0 if you are defining a text value and a value of 1 if you are defining a number. 

The actual value you are setting will be in either the DataElementValueText or DataElementValueNumeric field depending on the data type you are working with.

RD_MAINMENU_FixedDataElement

ReferenceGroupVersion MenuName DisplaySequence DataElement DataElementDataType DataElementValueText DataElementValueNumeric
1 TruckMenu 7 MEASURECODE 0 Litre  

Screen

The Screen table defines any data entry screen through which the user can set the value of a data element.  This can involve selection from a list or entry of a number.  Screens are not related to a single menu item.  The same screen can be used through multiple menu items and even multiple times within the same menu item if the need arises.

The ReferenceGroupVersion field contains the version of reference data we are dealing with (as with all other tables throughout the menu system). 

The ScreenId provides a unique name for the screen throughout the system.  The ScreenType field determines whether this is a numeric entry screen (“0”), a list based on reference data active lists (“1”) or a list based on fixed values (“2”).

The DataElementName provides the name of the data element that the entered value will be recorded against.

The ReturnValueDataType determines whether a string (“0”) or numeric (“1”) is returned from the selection.

For screen types of type “0” (numeric entry), the NumericMin, NumericMax, and DecimalPlaces fields define the valid entry range and formatting for the screen.

For screen types of type “1” (ref data list), the DataTokenGroupName and ActiveListName fields define the reference data used to populate the list (e.g. EQUIPMENT and Trucks).

dbo_RD_MAINMENU_Screen

ReferenceGroupVersion ScreenId ScreenType ScreenDisplayName DataElementName ReturnValueDataType DataTokenGroupName ActiveListName NumericMin NumericMax DecimalPlaces ConfigurationName
1 DumpLocation 1 Dumps DESTINATION 0 Location DumpLocation        
1 EngHrPrompt 0 Enter Engine Hours MEASUREVALUE 1     0 999999 1  
1 EquipmentLoaders 1 Loaders EQUIPMENT 0 Equipment Loaders        
1 FuelPrompt 0 Enter Litres MEASUREVALUE 1     0 500 0  
1 IdleStates 1 Idle States STATUS 0 Status TruckIdleStatus       IdleScreen
1 BreakDownLocations 2 Break Locations LOCATION 0            
1 MaintStates 1 Maintenance STATUS 0 Status TruckMaintStatus       MaintScreen

If we are dealing with a screen type of “2” (static list) then we expect 1 or more matching records in the StaticList table.

StaticList

The ReferenceGroupVersion and ScreenId fields provide the foreign key relationship back to the Screentable. The StaticListSequence field defines the list order.

The DisplayValue defines the text actually displayed on the screen, while the actual value returned as a data element is stored in either the ReturnValueText or ReturnValueNumeric field.

dbo_RD_MAINMENU_StaticList

ReferenceGroupVersion ScreenId StaticListSequence DisplayValue ReturnValueText

ReturnValueNumeric

 

1 BreakDownLocations 1 Go Line GoLine  
1 BreakDownLocations 2 Workshop Wshop  

LocalisedStaticListItem

This reference group simply provides a method to localise the display text from a StaticListItem.  This will not generally be populated.

ScreenSequence

It is the ScreenSequence table that links screens with menu items.  It is this table that defines which screens, in which order, should be displayed when a menu item is clicked.

The ReferenceGroupVersion, DisplaySequence and MenuName provide the foreign key relationship back to the MainMenuItem table.  The screen id specifies the screen that is to be displayed.  If more than one screen is to be displayed for a given menu item, then the screen sequence provides the ordering.

RD_MAINMENU_ScreenSequence

MenuName DisplaySequence ScreenId ReferenceGroupVersion ScreenSequence
TruckMenu 0 EquipmentLoaders 1 0
TruckMenu 1 IdleStates 1 0
TruckMenu 2 MaintStates 1 0
TruckMenu 6 DumpLocation 1 0
TruckMenu 7 FuelPrompt 1 0
TruckMenu 8 EngHrPrompt 1 0

EventTokenSelection 

The EventTokenSelection table controls behaviour related to prompting the user for information when an event is automatically generated.  For example, we may need to a ask the user for a dump location when the VIMS system generates a dump event.

There are four fields in the table.   The ReferenceGroupVersion and MenuName fields define the foreign key relation to the MainMenu table.

The EventInformationSelectionType determines what type of event selection this row relates to.  Valid values are:

  • 0 = Selection used when prompting for a dump location
  • 1 = Selection used when a truck needs to select its loader
  • 2 = Selection used when prompting for engine hours
  • 3 = Selection used when prompting for a delay status.
  • 4 = Selection used when prompting for secondary Engine Hours (introduced to cater for units that have two engines).

The DisplaySequence field relates back to the MainMenuItem table and defines which menu will be invoked when this event type is selected.

Note that the functionality which determines whether or not a particular event selection occurs is configured through the Pitram Mobile wizard – the reference data just defines which menu item will be selected when asked.

How to map the menus and screens

There is no question that this structure is complex.  It was never designed to allow manual entry.  It has currently been omitted from Pitram on the basis that it is not something that users would have to adjust on a daily basis.

I would suggest the following steps when faced with configuring this group:

  • Map out the menus in excel – construct a tree starting with what you want to see at the top level, and all of the screens that are shown for each menu item.
  • Try and work out which of the screens you have drawn actually contain the same information – the less screens you need to configure, the easier your life will be
  • Work out which active lists you need to define for you screens.  Go back into Pitram and create these lists.
  • Enter data into the tables.  Start by entering main menu items and screens.
  • Test each menu.  If you have configured a menu with the wrong data elements, Pitram mobile will display you a message to that effect when you try and submit an event packet.