Embedded Menu Manager

First Published: July 11, 2008
Last Updated: March 10, 2009

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 feature information and caveats, see 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 for the Embedded Menu Manager" section.

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

Contents

•Prerequisites for the Embedded Menu Manager

•Restrictions for the Embedded Menu Manager

•Information About the Embedded Menu Manager

•How to Configure the Embedded Menu Manager

•Configuration Examples for the Embedded Menu Manager

•Additional References

•Feature Information for the Embedded Menu Manager

•Glossary

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

To configure EMM, you should understand the following concepts:

•EMM Overview

•EMM MDFs

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 tclsh command 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. Table 1 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.


Table 2 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

Table 3 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."

Table 4 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.

Table 5 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

This section contains the following tasks:

•Displaying MDFs (optional)

•Loading and Launching Preconfigured MDFs (required)

•Launching EMM Menus (required)

•Debugging MDFs (optional)

•Clearing the Terminal Screen (optional)

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).

Restrictions

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.

Restrictions

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

This section provides the following configuration example:

•Preconfiguring, Loading and Launching an MDF: Example

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

Table 6 lists the release history for this feature.

Not all commands may be available in your Cisco IOS software release. For release information about a specific command, see the command reference documentation.

Use Cisco Feature Navigator to find information about platform support and software image support. Cisco Feature Navigator enables you to determine which Cisco IOS and Catalyst OS software images support a specific software release, feature set, or platform. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.

Note Table 6 lists only the Cisco IOS software release that introduced support for a given feature in a given Cisco IOS software release train. Unless noted otherwise, subsequent releases of that Cisco IOS software release train also support that feature.

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 of Cisco Systems, Inc. and/or its affiliates in the U.S. and other countries. A listing of Cisco's trademarks can be found at 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. (1005R)

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

© 2008-2009 Cisco Systems, Inc. All rights reserved.