Embedded Menu Manager

Last Updated: November 30, 2012

The Embedded Menu Manager (EMM) feature provides a programmable framework that allows Cisco IOS software to present a custom, character-based menu or wizard user interface in order to guide you through complex configuration tasks.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table at the end of this module.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Prerequisites for the Embedded Menu Manager

  • Familiarity with Tool Command Language (Tcl) and eXtensible Markup Language (XML) programming is assumed.
  • EMM depends upon the Tcl 8.3.4 Cisco IOS subsystem, as well as the Expat XML parser subsystem. EMM is only available on images that support Tcl 8.3.4 and Expat.

Restrictions for the Embedded Menu Manager

EMM commands can be executed using the Cisco IOS command-line interface (CLI). EMM configuration mode, like global configuration mode, is accessed from privileged EXEC mode. Access to privileged EXEC mode should be managed by restricting access using the enable command password.

Information About the Embedded Menu Manager

EMM Overview

EMM allows the extension of the Cisco IOS user interface by means of a Menu Definition File (MDF). This file is written in XML with optional embedded Tcl and defines menus and wizards. Wizards consist of a series of query/response pairs that can assist you in performing a complex task. This feature provides a custom menu-driven application that allows user accounts to be set up to automatically run menu systems when the users log in. The accounts can be set up to do this via the autocommand option of the username command.

Any Tcl command supported in Tcl shell mode is also available in EMM MDF.

Preconfigured MDFs can loaded at any time or can be loaded at router startup in global configuration mode, and can be located in any Cisco IOS file system that the router has read access to. If run from user EXEC mode, the MDF is automatically removed from memory once loaded (one-off mode). If run from global configuration mode, MDFs remain in memory and can be run over and over from user EXEC mode by supplying the menu name as an argument to the emm command.

EMM also provides a replay/record feature, where all user actions taken while interacting with an MDF are written to a file (supplied as a CLI argument). The contents of the record file are written such that all user actions may be replayed by simply running the tclshcommand from privileged EXEC mode and viewing the record file.

EMM employs a minimum typing strategy. Once sufficient keystrokes have been entered to uniquely identify a desired action, the action is executed without the need to press the Enter key. For example, if the main menu of a particular MDF contains fewer than ten menu items, a single keystroke (number) is all that is needed to select a menu item.

If a default value is supplied by the MDF, EMM displays this value in brackets, for example, "Enter selection [8]:.". When a default is available, it may be selected by simply pressing the Enter key.

If running EMM from the router console, we recommend that you disable console logging during the EMM session. If a syslog message does occur while EMM is running, simply press an invalid keystroke (such as spacebar). EMM will inform you of the invalid keystroke, and then refresh the screen upon the next keystroke. (Press any key to continue).

MDFs can contain two types of help: general menu help and menu-item help. If the MDF contains general menu help, you will see the prompt "Enter ? for help" in the header section of the menu. To access the menu help, enter ?followed by the Enter key. If the MDF contains menu-item help (context specific), enter ? followed by the item number of interest. Again, if there are fewer than ten menu items, no Enter key is needed; otherwise, three keystrokes would be required to access help for a particular menu item.

EMM MDFs

EMM MDFs are written in XML with optional embedded Tcl. This document assumes you are familiar with XML and Tcl programming. The EMM is defined using an EMM XML schema definition (XSD). This schema is a set of rules to which an XML document must conform.

EMM Menus

XML elements are the constituent parts of an XML document. XML attributes provide additional information about XML elements. The root element of the EMM XSD is the Menu element. The table below describes the important required attributes of the Menu element. The complete EMM XSD is available for download at this website:

http://forums.cisco.com/eforum/servlet/EEM?page=main

Table 1 Important Required Attributes of Menu Element

Attribute

Definition 

                
                  schemaVersion

XSD version that this MDF adheres to. It must match the EMM engine in the Cisco IOS image. As of this writing, the current EMM XSD version is 1.1. 

                
                  MenuName

This is one of the few elements that must be static (non-Tcl) and is limited to 30 characters. It can contain spaces, but spaces are not recommended as this attribute is used to dynamically build a parse table for preloaded menus. It is best to choose a single word or acronym for this attribute.

The table below describes the required child elements of a Menu.

Table 2 Important Required Child Elements of a Menu

Child Element

Definition 

MenuTitle

Specifies the text displayed in the header section of the menu. The element can be static or derived via embedded Tcl. 

Item

Items are automatically numbered and displayed in the menu. Item justification defaults to LEFT, but can be changed via the ItemJustification attribute. The ContinuePrompt attribute instructs EMM to delay clearing and repainting a menu after this menu item action. This is useful when a menu item action results in information being printed to the tty that you should see prior to continuing, for example, the results of a Cisco IOS show command.

There are other optional Menu child elements that affect how a menu is displayed. One optional Menu child element that can be very useful is the GlobalTCL element. If the MDF uses embedded Tcl, either for dynamic menu elements or menu item actions, it is convenient to place common Tcl procedures in this element. This element is evaluated prior to the initial menu rendering.


Note
When embedding Tcl in XML, if there are conflicts due to special characters (for example, <,>) encapsulate the Tcl in the <![CDATA[ ]]> tags.

EMM Menu Items

The table below describes the two important required child elements of a Menu item.

Table 3 Important Required Child Elements of a Menu Item

Child Element

Definition 

ItemTitle

Specifies the text displayed in the menu item. The element can be static or derived via embedded Tcl.

One of the following four menu item actions:

IOSExecCommand

IOSConfigCommand

EmbeddedTCL

Menu

One of these four actions may be specified. If multiple actions are required, use the EmbeddedTCL element and perform the multiple actions in a script. If a single execution of a Cisco IOS configuration command is required, use the appropriate tag. If a sub-menu should result, the Menu element is used.

Note    It may be easier to define menus in a standalone manner if possible. Once satisfied with the menu behavior, the entire menu may be placed into a menu item action.

Omitting a menu item action tells EMM to exit the current menu. If in a sub-menu, the null-item-action will redisplay the parent menu.

EMM Menu Item Wizards

Menu items that perform an action without user interaction are of limited use. Normally menus are written to query for some variable input, and then perform actions based on that input. EMM allows the MDF writer to prompt you to answer any number of questions prior to taking an action. A query/response pair is referred to as a "Wizard."

The table below describes the two required child elements of a Wizard.

Table 4 Important Required Child Elements of a Wizard

Child Element

Definition 

QueryPrompt

Specifies the text displayed as a question. The element can be static or derived via embedded Tcl.

One of the following four response elements: 

                
                  ChoiceList
                
              
                
                  One or more Choice elements
              
                
                  Range
                
              
                
                  FreeForm

One of these child elements is required to instruct EMM as to the type of response required. A ChoiceList is an embedded Tcl script that produces a valid list of choices. A Choice element is a static or dynamically derived value for a single choice. A Range specifies that a numeric response is expected within a minimum and maximum value. FreeForm accepts any typed in value up to an optional maximum length. Again most all of these elements can be static or derived via embedded Tcl.

At runtime, user responses are recorded as strings (no matter which type of response) in a Tcl array named "r". The array is indexed by the wizard number. Thus, if the first wizard prompted you for a new hostname for the router, the corresponding action for this menu item would be as follows:

<IOSConfigCommand>"hostname $r(1)"</IOSConfigCommand>

The above elements are sufficient for defining basic Menus and Wizards. Please see the EMM XSD for the complete list of elements and attributes.

The table below describes the other EMM elements that are useful for defining menu systems.

Table 5 Other EMM Elements Useful for Defining Menu Systems

Element

Definition 

                
                  HelpString

Specifies the text displayed when you enters the ? key.

Note    In order to ensure the text is wrapped on the terminal screen as desired, it is best to break your sentences into individual HelpString elements. 
                
                  DefaultSelection

It makes Menu navigation much easier if defaults are supplied. The element can be static or derived via embedded Tcl. 

                
                  DefaultValue

When asking a question via a Wizard, if a default is possible, supply it via this element. The element can be static or derived via embedded Tcl. 

                
                  SkipCount

If during a series of questions, a user response causes some follow-up questions to become moot, use this element to skip those questions.

Example: 1) Enable or disable this interface? 2) What IP address shall I assign?

A SkipCount script in the above example will return "1" if the answer to the first question is "disable"; otherwise, it will return 0.

How to Configure the Embedded Menu Manager

Displaying MDFs

Perform this task to display any MDFs configured on the router.

SUMMARY STEPS

1.    enable

2.    show mdf


DETAILED STEPS
  Command or Action Purpose
Step 1
enable


Example:

Router> enable

 

Enables privileged EXEC mode.

  • Enter your password if prompted.
 
Step 2
show mdf


Example:

Router# show mdf

 

Displays MDFs configured on the router.

 

Examples

The following sample output displays MDFs configured on the router. 

Router# show mdf
Menu Name / URL:
BGP / disk0:bgp.mdf

Loading and Launching Preconfigured MDFs

Perform this task to allow preconfigured MDFs to be loaded (at any time or at router startup) into memory and launched. Once the MDFs are loaded, other users can launch these menus without having to enter privileged EXEC mode.

SUMMARY STEPS

1.    enable

2.    emm mdf mdf-url [ record replay-file-url]


DETAILED STEPS
  Command or Action Purpose
Step 1
enable


Example:

Router> enable

 

Enables privileged EXEC mode.

  • Enter your password if prompted.
 
Step 2
emm mdf mdf-url [ record replay-file-url]


Example:

Router# emm mdf disk:0:bgp.mdf

 

Loads the user-specified MDF into memory and launches the menu.

 

Examples

The following sample output displays steps required to load preconfigured MDFs into memory and launch them. 

Router# emm mdf disk:0:bgp.mdf

===============================================

BGP Diagnostics

Enter ? for help or ?# for item help

-----------------------------------------------

1. Install Diagnostic Scripts

2. Set Global Variables (email parameters)

3. Deploy BGP Neighbor Loss Diagnostic Script

4. Deploy BGP Neighbor Formation Problem Diagnostic Script

5. Deploy BGP Route Problem Diagnostic Script

6. Display Diagnostic Policy Configuration

7. Remove Diagnostic Policies

8. Exit 

Enter selection [8]:8

Launching EMM Menus

Perform this task to launch preconfigured EMM menus.

SUMMARY STEPS

1.    enable

2.    emm preconfigured-menu-name[ record replay-file-url]


DETAILED STEPS
  Command or Action Purpose
Step 1
enable


Example:

Router> enable

 

Enables privileged EXEC mode.

  • Enter your password if prompted.
 
Step 2
emm preconfigured-menu-name[ record replay-file-url]


Example:

Router# emm BGP

 

Launches the user specified menu.

 

Examples

The following sample output shows how to launch preconfigured EMM menus: 

Router# emm 
BGP

===============================================

BGP Diagnostics

Enter ? for help or ?# for item help

-----------------------------------------------

1. Install Diagnostic Scripts

2. Set Global Variables (email parameters)

3. Deploy BGP Neighbor Loss Diagnostic Script

4. Deploy BGP Neighbor Formation Problem Diagnostic Script

5. Deploy BGP Route Problem Diagnostic Script

6. Display Diagnostic Policy Configuration

7. Remove Diagnostic Policies

8. Exit 

Enter selection [8]:8

Debugging MDFs

Perform this task to debug MDF files. The syntax of the file is checked before loading. MDF files can also be checked offline using xmllint (an XML validation tool).


Note

Do not run this command on the same vty as the EMM menu.

>
SUMMARY STEPS

1.    enable

2.    debug emm


DETAILED STEPS
  Command or Action Purpose
Step 1
enable


Example:

Router> enable

 

Enables privileged EXEC mode.

  • Enter your password if prompted.
 
Step 2
debug emm


Example:

Router# debug emm

 

Debugs an EMM MDF.

 

Examples

The following sample output displays the debug information. 

Router# debug
 emm

EMM debugging is on
*Jun 10 15:45:42.043: Looking for MenuTitle, parent = Menu
*Jun 10 15:45:42.063: Looking for GlobalTCL, parent = Menu
*Jun 10 15:45:42.083: Looking for MenuTitle, parent = Menu

The following example shows how to check the status of the EMM debugging: 

Router# show debug
EMM debugging is on

Clearing the Terminal Screen

Perform this task to change the terminal clear-screen escape sequence for a terminal/terminal emulator that is not a DEC vt100 terminal/terminal emulator. The escape sequence is entered as an even number of character representations of ASCII hexadecimal data.


Note

Do not use this command on a DEC vt100 terminal/terminal emulator.

>
SUMMARY STEPS

1.    enable

2.    emm clear escape-sequence


DETAILED STEPS
  Command or Action Purpose
Step 1
enable


Example:

Router> enable

 

Enables privileged EXEC mode.

  • Enter your password if prompted.
 
Step 2
emm clear escape-sequence


Example:

Router(config)# emm clear 1B5B324A1B5B303B30480D

 

Changes the terminal clear-screen escape sequence.

 

Configuration Examples for the Embedded Menu Manager

Preconfiguring Loading and Launching an MDF Example

The following example shows the content of a preconfigured MDF (named abc.mdf). The example also shows how to use the EMM commands to clear the terminal screen, display the menu definition files currently configured on the router, and load and launch the preconfigured MDF.

<?xml version="1.0" encoding="UTF-8"?>
<Menu Standalone="true" TitleJustification="CENTER" Main="true"
MenuName="Test" schemaVersion="1.1">
	<MenuTitle>
		<EmbTCLValue>
			<TCLCommand>return [concat "Simple Example Menu for" [hostname]]
			</TCLCommand>
		</EmbTCLValue>
	</MenuTitle>
	<Item ContinuePrompt="true" ItemJustification="LEFT">
		<ItemTitle>
			<Constant String="Show Cisco IOS version" />
		</ItemTitle>
		<HelpString>
			<Constant String="This will run the exec command 'show
ver'"/>
			</HelpString>
			<IOSExecCommand>"show ver"</IOSExecCommand>
	</Item>
	<Item ContinuePrompt="false" ItemJustification="LEFT">
		<ItemTitle>
			<EmbTCLValue>
				<TCLCommand>return "Change hostname"</TCLCommand>
			</EmbTCLValue>
		</ItemTitle>
		<HelpString>
			<Constant String="Selecting this will change the router
		hostname."/>
		</HelpString>
		<Wizard>
			<QueryPrompt>
				<Constant String="Please enter new hostname"/>
			</QueryPrompt>
				<FreeForm MaxResponse="30" />
			</Wizard>
			<IOSConfigCommand>"hostname $r(1)"</IOSConfigCommand>
</Item>
<Item ContinuePrompt="false" ItemJustification="LEFT">
	<ItemTitle>
		<Constant String="Change enable password" />
	</ItemTitle>
	<HelpString>
		<Constant String="Selecting this will run enable password
0 'new_password'"/>
	</HelpString>
	<Wizard>
		<QueryPrompt>
			<Constant String="Please enter new password"/>
		</QueryPrompt>
		<FreeForm InputMask="TRUE" />
	</Wizard>
	<IOSConfigCommand>"enable password 0
$r(1)"</IOSConfigCommand>
	</Item>
	<Item ContinuePrompt="true" ItemJustification="LEFT">
		<ItemTitle>
			<Constant String="Exit" />
		</ItemTitle>
	</Item>
	<DefaultSelection>
		<Constant String="4" />
	</DefaultSelection>
</Menu>
Router> enable
Router# emm
 clear
 1B5B324A1B5B303B30480D
Router# show mdf
No menus configured!
Router# emm mdf disk:0:abc.mdf
------------------------------------------------------------------------------
Simple Example Menu for Router
                                                      Enter ?# for item help
------------------------------------------------------------------------------
1. Show Cisco IOS version
2. Change hostname
3. Change enable password
4. Exit
Enter selection [4]:4
Router# show mdf
Menu Name / URL:
ABC / disk0:abc.mdf
Router# emm ABC
------------------------------------------------------------------------------
Simple Example Menu for Router
                                                      Enter ?# for item help
------------------------------------------------------------------------------
1. Show Cisco IOS version
2. Change hostname
3. Change enable password
4. Exit
Enter selection [4]:4

Additional References

The following sections provide references related to the Embedded Menu Manager feature.

Related Documents

Related Topic

Document Title

Network Management commands (including Tcl and logging commands): complete command syntax, defaults, command mode, command history, usage guidelines, and examples.

Cisco IOS Network Management Command Reference

Standards

Standard

Title

No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.

--

MIBs

MIB

MIBs Link

No new or modified MIBs are supported by this feature, and support for existing MIBs has not been modified by this feature.

To locate and download MIBs for selected platforms, Cisco IOS releases, and feature sets, use Cisco MIB Locator found at the following URL:

http://www.cisco.com/go/mibs

RFCs

RFC

Title

No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.

--

Technical Assistance

Description

Link

The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies.

To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds.

Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.

http://www.cisco.com/techsupport

Feature Information for the Embedded Menu Manager

The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/go/cfn. An account on Cisco.com is not required.

Table 6 Feature Information for the Embedded Menu Manager

Feature Name

Releases

Feature Information

Embedded Menu Manager

12.4(20)T

The Embedded Menu Manager (EMM) provides a programmable framework that allows Cisco IOS software to present a custom, character-based menu or wizard user interface in order to guide you through complex configuration tasks.

The following commands were introduced or modified: debug emm, emm, emm clear, show mdf.

Glossary

CLI --command-line interface.

EMM --Embedded Menu Manager.

MDF --Menu Definition File.

Tcl --Tool Command Language.

XML --eXtensible Markup Language.

XML attribute --XML attributes provide additional information about XML elements.

XML element --XML elements are the constituent parts of an XML document.

XSD --XML Schema Definition.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

© 2012 Cisco Systems, Inc. All rights reserved.