Cisco Prime Network Customization Guide, 4.3.2

Controlling Who Can Run Command Scripts

Users can execute commands from the Vision GUI client when a device is in their scope and they have sufficient privileges. You specify the required privileges when you create the command’s basic information. However, the following two settings in the Administration GUI client will also affect command operation. (These are in the Administration GUI client under Global Settings > Security Settings > User Account Settings .)

For more information on these global settings, see the Cisco Prime Network 4.2.2 Administrator Guide .

Displaying a Warning Message When Users Run Commands

Prime Network can be configured to display a warning message whenever users execute commands. This affects Command Manager jobs, and any commands that are executed using the device right-click Commands menu in the Vision GUI client.

Users must acknowledge the message before proceeding. This feature is disabled by default. To enable it and specify a message, choose Global Settings > Commands in the Administration GUI client, enable the feature, and enter the message text. When users run commands, they will have to acknowledge the warning message or Prime Network will not allow them to proceed.

What is Command Manager?

Like Command Builder, Command Manager provides a GUI framework for creating programmable SNMP or Telnet commands. Commands can include multiple input screens and multiple input methods—text fields, check boxes, drop-down lists, and so forth. Commands can include parameters that are fixed. You can also perform bulk configurations using XLS or CSV files to populate the parameter values

Command Manager uses the Command Builder back-end, but it provides the following additional features:

• View the command repository, which contains all device-level commands available on the system
• Execute commands on multiple devices
• Use input from files to provide parameter substitution
• Apply versions to individual commands
• Create command packages

However, Command Manager commands can only be applied at the network element (IManagedElement) level, while Command Builder commands can be associated with any existing object group (IMO), type, or instance. This is why only device-level commands are listed in the command repository.

Once a command is created, it is added to the central repository and can be made available to other NEs of the same family, NE type, or software version, and can be executed from the Vision GUI client by users according to their device scope and privileges. Users with Configurator privileges can also create simple command sequences, although command sequences can only be run from the command repository (not from the Vision GUI client).

Command information is stored in XML files that can be organized into packages. The Command Manager repository always contains these two packages:

• Default —Contains all commands that are provided with the Prime Network product. Out-of-the-box commands in the Default package cannot be moved or exported.
• Production —Contains any user-created commands that were migrated from another installation. For a new installation, the Production package will be empty.

As you create new commands, you can place them in new packages and reorganize them as needed. You can also export and import command packages. Commands installed from Device Packages are listed only if Prime Network is restarted.

Command Manager jobs are purged according to the Prime Network job purging settings. Commands information (including rules, parameters, and script implementations) are stored on the gateway and are not purged; only Command Manager jobs are purged.

Commands created with Command Manager can be used by Transaction Manager. Commands can also be integrated into external configuration applications using the Prime Network API. For information on how to do this, see the Cisco Prime Network Integration Developer Guide .

Steps for Creating and Deploying Commands with Command Manager

The following table lists the steps you must follow to create a command or command sequence.

Command Manager Window and Repository

Launch the Command Manager from Change and Configuration Management, as shown in the following figure. You may have to expand the title bar by clicking the arrow at the top left.

When you select Command > Command Repository , Prime Network displays all of the device-level commands in the system. The Default package contains the out-of-the-box commands provided with Prime Network. The Production package is only populated in upgrade scenarios and contains the commands that were migrated from the older deployment. Commands can be executed from the repository or from the devices (in the Vision GUI client). Commands displayed in the repository are filtered according to the user’s access level.

The command repository only lists device-level commands (that is, commands at the IManagedElement level). For commands at other levels, use Command Builder.

Commands are indicated by a yellow lightning bolt and sequences by a blue lightning bolt. You can get the following information from the repository:

• Find out whether the command can be executed on different device types. This is indicated by a hyperlink in the Device Type column, as shown in the following figure. In this example, the Add DNS Server command can be executed on all CRS, ASR 9000, and 12000 routers. This also indicates that if those devices appear in a Vision GUI client map, the Add DNS Server command can be executed from the device’s right-click Commands menu.

Figure 4-1 Command Manager Repository Showing Applicable Device Types for a Command

• Find out if the command can be executed on multiple software versions (for a single device type). This is indicated by a hyperlink in the Software Version column. In the following example, the Create Lane command can be executed on a Cisco RF Gateway Series device that is running any of the software versions that are listed.

Figure 4-2 Command Manager Window Showing Applicable Software Versions for a Command

• Find out the number of jobs associated with the command. This is indicated by a hyperlink in the # Of Jobs column which displays the Command Manager Jobs page. Depending on the user access role the jobs are displayed for the selected command.
• Find out the last run result of the command. This is indicated by a hyperlink in the Last Run column, as shown in the following figure. In the following example, the details of each job and its result associated with the command Device Log is displayed.

Users with Administrator and Configurator privileges can perform all operations on all commands—editing, executing, deleting, moving, and so forth. All other users can perform these operations if they have the required privileges for the command, and the device is in their scope.

Creating and Testing a Command or Command Sequence

Commands and sequences must be created within a package. A best practice is to create a package with a name that describes the contents, such as the device series the command can be run on.

Commands can be duplicated and edited, but only if they are user-created commands. You cannot duplicate out-of-the-box commands that are packaged with Prime Network.

When you create a command (by clicking Create in the Command Implementations area), the command is saved to the database. It is not deployed to any NEs until you go to the repository, select the command, and click Run Command .

These topics provide the steps required to create, test, and deploy commands and command sequences:

• Creating a New Package
• Creating a New Command
• Creating a Command Sequence
• Previewing a Command Script and Checking Command Job Results

Creating a New Package

Use the package mechanism to organize your command scripts. Naming packages by device type is a good practice, as shown in the following figure. If you need to create a new package, click the New Package icon on the upper left side of the window and provide a name and optional description.

Figure 4-3 Command Packages

If you delete any of the user-created packages (such as CRS-1 or Nexus7000 in the previous figure), all commands associated with package are moved to the Default package. This ensures that there will be no problems if the command is part of a scheduled job.

New commands that are installed from a Device Package are not listed in the command repository unless Prime Network is restarted. (Remember that the command repository only lists device-level commands; that is, commands at the IManagedElement level.)

To create a new command, proceed to the next section. To create a command sequence, see Creating a Command Sequence.

Creating a New Command

These are the steps for creating a new command script with Command Manager:

• Defining a Command’s Basic Information
• Defining Execution Parameters for a Command
• Defining the Implementations (Scripts) for a Command

Defining a Command’s Basic Information

The basic information for a command includes the name that will appear in the Vision GUI client (in the NE right-click menu) the user authorization that is required to use the command.

Step 1 Select a package from the Commands Organization area.

Tip Do not use the Default package because it contains all commands provided by Prime Network. This makes it easier to your manage user-created commands.

Step 2 Click New Command to open the command wizard builder.

Step 3 Configure the command’s basic information in the Command Info area.

Step 4 Click Next to begin entering the command’s implementation parameters.

Defining Execution Parameters for a Command

Note If you are creating a command that requires no input—for example, a simple show command—skip this section and proceed to Defining the Implementations (Scripts) for a Command.

The Execution Parameters determine the structure and format of the input form and the data that users must supply. Each parameter has an associated input type which determines how information is entered (for example, typing in a number or string, checking a check box, choosing from a drop-down list). You can specify:

• Required parameters and optional parameters.
• Parameters with default values which can be visible or hidden in the input form.

A command can have one parameter, multiple parameters, and multiple input pages (tabs) with their own parameters.

Step 1 Define your first parameter by clicking New Parameter in the Execution Parameters area, and provide the basic information for the execution parameter.

Step 2 Define the input type for the parameter.

Tip Use TextArea for multi-line parameter values (e.g., license, banner, and so on). Do not use it to configure multiple commands in a single parameter. Doing so will download all commands to the device, but the command output will only be partial.

.

If you choose Combo , an Add button appears in the wizard. Click Add to create choices for the combo box.

The example in the previous table would create a combo box with the choices Up and Down.

Step 3 Define the rest of the execution parameter. The choices depend on what you specified in the Type field.

Step 4 If you want the input to be either validated or populated when the user runs the command, click the Validate tab.

– On Populate—When Run Command is clicked, the BeanShell script should populate the parameters values according the script logic.

– On Validate—When Preview or Execute Now is clicked, the BeanShell script should validate the parameters values according the script logic.

Note When creating or editing On Populate or On Validate BeanShell scripts, you must restart the Vision GUI client for the changes to take effect.

Step 5 Click OK , and the new parameter is added to the list of Execution Parameters.

Step 6 Create more parameters as needed by repeating Step 1 through Step 5.

Step 7 If you want to create additional pages (tabs) or adjust the order of parameters, use the tools illustrated in the following figure.

Step 8 When you have finished creating the parameters, click Next to begin entering the Command Implementations (the scripts that will be executed and the devices they can run on).

Defining the Implementations (Scripts) for a Command

Note All scripts are run at the network element level (IManagedElement).

The Command Implementations are the scripts that are run when the user executes the command. Implementations can use Bean Shell (Telnet or SNMP) or Cisco Prime Network Macro language (Telnet only). You can also specify a rollback script and the conditions that indicate the command has failed.

When you create an implementation you also define which device types the command applies to. You can choose different degrees of granularity:

• All devices
• Device family (such as routers)
• Device series (such as Cisco 7200 routers)
• Device model (Cisco 7207)

However, if you choose all devices, you cannot specify multiple software versions.

When a command is deployed, it overrides any inherited command from a higher level and automatically applies to elements below it. For example, the following tables shows how command versions can be overwritten:

Step 1 Define the scripts that will run by clicking New Implementation in the Implementations area.

Step 2 In the General tab, provide the following script information.

Step 3 Click the Script tab to define the command script, using these guidelines:

Tip A best practice is to create the script in a text editor, then cut and paste it into the Script area of the Script tab.

• To view all user-defined and built-in parameters in the Command Builder application, position the cursor in the Script or Rollback field and press Ctrl-Spacebar . A dialog box is displayed that lists all available arguments (containing both the user-defined input argument and the built-in properties of the IMO context). Also see Supported Pragmas.

Select an entry from the list and then click OK to add it to the Script or Rollback field.

• Enclose pragmas with square brackets: […].
• To enter a required carriage return in the command line, enter the escape sequence &cr .
• It is possible to use multiple pragmas in a single line, in which case all pragmas are analyzed. If the same type of pragma is repeated, only the last one is used.

Step 4 When you are finished with the implementation, click OK.

Step 5 Create more profiles as needed by repeating Step 2 through Step 4.

Step 6 Click Create when you are done. The newly created command is displayed in the command repository table. (It is not yet deployed to devices; that happens when you select Run Command .)

Step 7 Test the command locally before deploying it. See Testing the Command Locally Before Deploying It to Other NEs

Creating a Command Sequence

Users with Configurator privileges can create command sequences. Sequences can only be executed from the command repository (not from the Vision GUI client). You cannot specify different devices for the different commands in a sequence.

Step 1 Choose a package. If you need to create a new package, click the New Package icon on the upper left side of the window and provide a name and optional description.

Tip Do not use the Default package because it contains all commands provided by Prime Network. This makes it easier to your manage user-created commands.

Step 2 Click New Sequence to open the Create Command Sequence wizard.

Step 3 Configure the sequences’s basic information in the Command Sequence Info area. Note that there is no authorization level field; only users with Configurator privileges can create and run sequences. There is also no menu field because sequences can only be run from the command repository, not from the Vision GUI client.

Step 4 Add the commands to the sequence in the Define Sequence area by clicking Add Commands . A dialog opens that lists all device-level commands in the repository (from all packages, including the Default package).

Step 5 Select the commands you want to add to the sequence and click Add .

Step 6 Configure the commands in the sequence. (You cannot edit the command contents.)

• Ensure that each command is also configured with a rollback sequence in the Create Command Sequence area. You can add a rollback sequence from the command repository by clicking the Add link.
• Adjust the command order.

Step 7 Click Create when you are done. The newly-created command is displayed in the command repository and can be executed from the repository.

Step 8 Test the command locally. See Previewing a Command Script and Checking Command Job Results.

Previewing a Command Script and Checking Command Job Results

When you preview a command, you can see how it will appear to users. The preview feature allows you to see the expected script output without performing any real command executions.

Once you execute a command with Create Execution Job (at the end of the following procedure) Prime Network creates a command job and displays a dialog that contains a hyperlink to the job details. To check the job status for completed and schedule jobs, select Command > Jobs from the Change and Configuration Management menu.

Step 1 Select the command or sequence in the repository and click Run Command .

Step 2 In the Select Device page, choose one of the following options:

• By Devices—Choose this option to select the device(s) that you want to run the command.
• By Groups—Choose this option to select the device group(s) that you want to run the command. There must be at least one device added to a device group for the command to run on that group. If a device is added to multiple device groups that are selected, the command will run only once on that device. For information on how to set up a device group, see the Setting Up CCM Device Groups” section.

Step 3 From the command input forms that are generated, enter the required input.

Step 4 To verify the parameters that you entered and see what the executed scripts will look like, click Preview .

Note Preview action is disabled for commands that use TL1 protocol.

Step 5 If the result is satisfactory, click Create Execution Job to:

• For a command, deploy it to the selected NEs.
• For a command sequence, save it to the repository.

Step 6 Click the job hyperlink to view the job results. To get job details, select the job and click the hyperlink under the Last Run Result column. If the job was for a command sequence, as in the following example, you can check the results of each command in the sequence.

• If the job failed or was only partially successful, click the red X under Status to get details about the failure. By hovering over the Device Properties icon, you can get quick device details about the reachability of the device.

• If the job was successful, click the Transaction Log tab to see what scripts were sent to the device. Click the Debug Trace tab to view the information that was received from the device.

Enabling E-mail Notification for Command Scripts

Command Manager enables you to send automatic e-mail notifications about the status of jobs to users while executing the command or job scripts. To enable email notifications for the Command Manager, you need to add the SMTP host name in E-mail Settings pane of the Configurations Settings page in CCM.

Step 1 Choose Commands > Command Repository, select the command, and click Run Command.

Step 2 In the Run Command window, click the Create Execution Job pane, select the Email Id(s) checkbox, and enter the email id of the recipient, for example, user1@cisco.com. You can enter comma separated email ids for multiple recipients.

Step 3 Click Create Job. The e-mail is sent to the recipient with the following information:

• Job ID and Job spec ID
• Job name and type
• Job schedule time
• Job completion time
• Name of the device on which the job is executed
• Command name
• Status of the job executed

Step 4 Choose Commands > Jobs, select the job in the Command Manager Jobs page, and click Edit.

Step 5 In the Edit Job window, click Create Execution Job.

Step 6 In the Email Id(s) text box, enter the email ids of the recipient and click Save. You can enter comma separated email ids for multiple recipients. The e-mail is sent to the recipient with the following information:

• Job ID and Job spec ID
• Job name and type
• Job schedule time
• Job completion time
• Name of the device on which the job is executed
• Command name
• Status of the job executed

Running Commands Using Input Stored in a File

For bulk configurations, you can create an XLS or CSV files with parameter values and import the file into the command.

Step 1 Create a file that contains the parameter values.

a. Select the command from the repository and click Run Command .

b. Select the devices you want to configure and click the Export icon at the top right of the screen.

c. In the Export Execution Parameters dialog, click OK to continue with the export operation.

d. When your browser displays its file management dialog, download the file. The file is created with the name command .csv .

Step 2 Populate the command .csv file with your desired attribute values. One column is dedicated to each attribute.

Step 3 Run the command using your command .csv file as input.

a. Select the command in the repository and click Run Command .

b. Select the devices you want to configure. They must match the devices in your spreadsheet.

c. In the Execution Parameters area, click the import icon.

d. Navigate to the file that contains your input, and click OK .

e. In the Command Execution Job area, specify when the job needs to be executed (on daily, weekly, monthly, or on a specif time interval) and the e-mail ID(s) to which to send a notification after the scheduled job is complete. Click Create Job.

Step 4 Run the command.

Controlling Command Manager Jobs

Users with Configurator privileges can perform all job actions from the Command Manager Jobs window. This includes cancelling jobs, suspending jobs, rescheduling jobs, and editing job properties (such as changing the selected devices). Other users can only manage jobs that they own.

Command Manager jobs are automatically deleted according to the Prime Network job purging settings. By default, these jobs are never purged.

For examples of how to view job results, see Previewing a Command Script and Checking Command Job Results.

Moving, Importing, and Exporting Commands and Packages

Command Manager allows you to move, export, and import user-created commands. User-created commands are any commands that do not reside in the Default repository (which contains all commands that were provided with the Prime Network product).

To move user-created commands to a different package, select the commands in the repository, click the Move To icon, and choose the package.

You can also export and import user-created commands and packages. Exporting commands is useful when you want to clean up the repository or if you create commands that you plan to use at a later time. Figure 4-4 shows from where you should launch an import or export operation, depending on whether you are working with packages or individual commands.

Figure 4-4 Importing and Exporting Commands and Packages

Exported items, whether they are individual commands or a package of commands, are saved in a zip file on the client machine or on the gateway server. On the gateway server, commands are stored in NETWORKHOME /Command_Archive. If you do not supply a name in the export dialog box, Command Manager uses the following naming scheme:

Files you export to your local system are saved in your browser’s download directory.

Import operations will query you for the location of the zip file that contains the commands or package. If you try to import a command that already exists in the command repository, you are prompted to overwrite the command or exit.

Cancelling Command Manager Jobs

To cancel the job that is in the running state:

Step 1 Select the job in the Command Manager Jobs window.

Step 2 Click Cancel.
The Job Status displays as Cancelled and the Lastrun Status displays as Cancelled with a hyperlink in the Command Manager Jobs window.

Step 3 Click the Cancelled hyperlink in the Lastrun Status field to display the Command Manager Job Result window.
The job result display the information about successful, unsuccessful, and cancelled tasks.

Deleting Commands and Packages

The following procedures explain how to:

• Remove a command from the Vision GUI client
• Remove a command or package from the command repository

Removing a Command from the Vision GUI Client

If you want to remove a user-created command from the Vision GUI client, you can hide it without removing it from the repository. You cannot hide out-of-the-box commands that are provided with Prime Network.

Note This operation may take some time depending on the number of NEs that are will be affected.

To remove a command from the Vision GUI client:

Step 1 Select the command in the repository and click the Edit icon.

Step 2 In the Command Info page, deselect the Visible in Menu check box.

Step 3 Click Save . The command is hidden in the Vision GUI client.

Deleting Commands and Packages from the Prime Network Command Repository

You can only delete user-created commands and packages. Out-of-the-box commands cannot be deleted. In addition, user-created commands can only be deleted if they are not part of:

• A scheduled job
• A command sequence

When a command is successfully deleted, it is removed from the repository and the Vision GUI client, and all related command data is deleted from the gateway and database.

When you delete a package , none of the user-created commands in the package are deleted. Instead, the commands are moved to the Default package, from where you can delete them.

To delete a command, make sure that you are working from the right package in the Commands Organization area. Then choose the command and click the Delete button above the commands table.

To delete a package, select the package and use the Delete button in the Commands Organization area.

What is Command Builder?

Command Builder is an integral part of the Prime Network Vision GUI. It is used to create custom commands to be executed on specified devices. These commands can be tested and then published, which enables a wider scope of NEs to use them. You can publish commands to NEs of the same family, NE type, or software version.

Command Builder commands execute a programmable sequence of SNMP or Telnet command lines. Commands can be created using the BeanShell scripting language or the Prime Network Macro Language. Commands can be associated with any existing object group (IMO), type, or instance. This enables access to the live information of the network object with which the command is associated.

Only users with Administrator or Configurator privileges can create commands using Command Builder.

Commands can be used in a variety of ways:

• Using Command Builder, add the commands to the Prime Network Vision GUI client. Users will be able to run the commands by right-clicking an NE. When running the command, the user will be presented with a dialog for entering the input parameters that were defined during the command creation process.
• As building blocks in the creation of transactions (workflows) which can then be deployed to devices using Transaction Manager.
• Use the Prime Network API to integrate the commands into external configuration applications. For information on how to do this, see the Cisco Prime Network Integration Developer Guide .

Steps for Defining a New Command

These steps describe how to create a new command definition using Command Builder and the order in which the steps must be performed.

Figure 4-5 Steps for Defining a New Command

At any time after the command has been defined, it can be tested, executed, and published to a wider scope of managed elements and network elements.

For more information, see Creating a Command Using Command Builder.

Command Builder Window

Command Builder is launched by right-clicking a specific managed element or a selected object within a managed element and selecting Management > Command Builder .

The Command Builder window lists all existing commands that are available to the NE. (The technology-based commands that are packaged with Prime Network are not editable).

The commands that are listed depend on the NE type and the user’s access privileges.

Figure 4-6 Command Builder Window

Table 4-2 identifies the buttons that appear in the Command Builder window.

Creating a Command Using Command Builder

When you create a new command, you first create a local instance of the command. After you have tested the command, you can publish it to make it available to other NEs.

To create a command:

Step 1 Launch Command Builder by right-clicking a managed element and choose Management > Command Builder . The window lists all existing commands that are available to the NE. (The technology-based commands that are packaged with Prime Network are not editable).

Step 2 Click the New Element icon in the toolbar to open the New Command dialog box.

Step 3 Enter the following information for your new command:

Step 4 Click Next. The Command Authorizations dialog box is displayed.

Step 5 Select the security access roles that are authorized to execute the command.

Step 6 Click Next. The User Input Arguments dialog box is displayed.

You can define any number of input parameters. These parameters determine the structure and format of the input form.The input form is automatically generated when the command is executed.

You can use either of two types of command parameters: built-in parameters and user-defined parameters, both of which are replaced in runtime. All parameters (both built-in and user-defined) are available during command editing via a selection list. For more information about Prime Network Macro Language, see Prime Network Macro Language.

Step 7 To add a new argument, click New . The Add/Edit User Argument dialog box is displayed (Figure 4-7).

Figure 4-7 Add/Edit User Argument for Command Dialog Box

Step 8 Enter the required information:

Property	Explanation
Name	Parameter name. This entry must be unique and can contain only letters, numbers, hyphens (-), and underscores (_).
Caption	Parameter display name. This entry is displayed in the Command Builder execution window.
Type	The type of input that will be required upon execution of the command. Only input values that are valid for the selected type are accepted. These values are validated during runtime. String Integer IPSubnet Combo—For more information about defining a Combo field type, see Defining a Combo Field Type for a Command Builder Command. IP Address Float Long Text Area—Multi-line string field type into which you can cut and paste information, including end of line characters <CR><LF>. This is referenced in the script as a single attribute. Note This feature should be used only for multi-line parameter values (e.g., license, banner, and so on). It is not intended for configuration of multiple commands in a single parameter. Doing so will download all commands to the device, but present only a partial output in the command builder output
Width	Field width, in number of characters. Relevant for the Command Builder execution window.
Visible	Indicates whether this parameter appears in the Command Builder execution window. Check this check box to display the parameter, or uncheck the check box to hide the parameter from the user. If the argument is hidden, it can still be used in the command (with its default value). Note When the parameter is not visible and has been assigned a default value, it can serve as a constant argument.
Tooltip	Specifies a tooltip for the command parameter. This string is displayed for the parameter field in the input form (see Testing the Command Locally Before Deploying It to Other NEs). The tooltip can be a maximum of 256 characters.
Default	A default value for the parameter.
Required	Indicates whether the argument is mandatory or optional. The mandatory arguments are displayed in bold font in the input form (see Testing the Command Locally Before Deploying It to Other NEs).

Click the Advanced tab to open the Add Argument Advanced Controller dialog box.

The Advanced option enables you to do additional actions on the parameter values using BeanShell.

• On Populate—The BeanShell script, executed when you click Run Command, can be used to populate the parameters values according the script logic.
• On Validate—The BeanShell script, executed when you click Preview or Execute Now, can be used to validate the parameters values according the script logic.

Note When creating or editing On Populate or On Validate BeanShell scripts, you must restart the client for the changes to take effect.

Step 9 Click OK . The newly created argument is displayed in the User Input Arguments dialog box.

Step 10 To change sequence in which arguments appear in the input form, select an argument and click Move Up or Move Down .

Step 11 Click Next. The Tab Pages dialog box is displayed.

Use this feature if you want your input form to have different tabs. By default, all of the parameters are displayed in a single tab, General.

Step 12 If you want to use tabs, do the following:

a. Click New . The Add/Edit User Tab Page dialog box is displayed.

Figure 4-8 Add/Edit User Tab Page for Command Dialog Box

b. Enter a name for the Tab and select the required parameter.

You can define a maximum of 20 tabs for a command. The name of the tab can contain a maximum of 20 characters.

c. Repeat the steps for additional tabs.

Step 13 Click Next to define the command script, which can be either Prime Network Macro Language scripts or Beanshell scripts. For more information, see Command Manager and Command Builder: Macro Language and Beanshell Reference. The Script Lines dialog box is displayed, enabling you to add or edit a script line, as shown in Figure 4-9.

Note An efficient way to do this is to create the script in a text editor, then cut and paste it into the New Command dialog box.

Figure 4-9 Script Lines Dialog Box

Step 14 Enter the required information, using the following guidelines:

• To view all user-defined and built-in parameters in the Command Builder application, position the cursor in the Script or Rollback field and press Ctrl-Spacebar . A dialog box is displayed that lists all available arguments (containing both the user-defined input argument and the built-in properties of the IMO context). Select an entry from the list and then click OK to add it to the Script or Rollback field.
• Pragmas are enclosed with square brackets: […].
• It is possible to use multiple pragmas in a single line, in which case all pragmas are analyzed. If the same type of pragma is repeated, only the last one is used.
• If carriage returns are required in the command line, enter the escape sequence &cr .

Step 15 Click Finish. The Create Command dialog box is displayed.

A LED indicates the progress or status of the command as it is being saved to the registry:

• Blue — The command definition is being saved.
• Green — The command has been created or updated successfully.
• Red — Command Builder failed to create or update the command.

Step 16 Click Close when the command has been successfully saved. The newly created command is displayed in the Command Builder table.

See Testing the Command Locally Before Deploying It to Other NEs to test the command.

See Publishing Commands to Other NEs to publish the command.

Note If you plan to publish the command to multiple network elements so you can work on commands in bulk, be sure to delete your local copy of the command after it is published. Otherwise, when you choose multiple managed elements, the command will not be listed.

Defining a Combo Field Type for a Command Builder Command

If you want to use a combo box in your input form, choose Combo in the Add/Edit User Argument dialog box (Step 8 of the previous procedure), a Browse button is enabled. Use it to create a selection list (drop-down list) of valid options that will be displayed.

This example creates a combo box with Up and Down choices.

Step 1 Select Combo in the Type field of the Add/Edit User Argument for x Command dialog box.

Step 2 Click Browse. The Selection List dialog box is displayed.

Step 3 Enter the required information:

Step 4 Click Add .

Step 5 Repeat Steps 3 and 4 as needed until you have added all entries (such as 2 and Down ).

Step 6 Click Close .

End-to-End Example of Creating a Macro Language Command

This topic provides an example of how to create the command, addvrf , using Prime Network Macro Language.

Step 1 Select the element that you want to configure this command for in the Prime Network Vision tree pane, context pane, or Inventory window.

Step 2 Right-click the element, then choose Management > Command Builder . The Command Builder wizard is displayed.

Step 3 Click New. The New Command dialog box is displayed.

Step 4 Define the command identification information:

• Name—addvrf
• Caption—Add VRF
• Menu Visible—Checked
• Menu Path—VRF Commands
• Context IMO—Automatically displayed
• Timeout—180000
• Language—Prime Network Macro
• Protocol—Telnet is selected by default

Step 5 Click Next. The Command Authorizations dialog box is displayed.

Step 6 Select the security access role Administrator.

Step 7 Click Next. The User Input Arguments dialog box is displayed.

Step 8 Click New. The Add/Edit User Argument for addvrf Command dialog box is displayed.

Step 9 Using Table 4-3 , enter the information for the parameters.

Step 10 Click OK in the Add/Edit User Argument dialog box after each parameter. The new user-defined input parameters are displayed in the User Input Arguments dialog box (Figure 4-10).

Figure 4-10 User Input Arguments Dialog Box

Step 11 Click Next. The Tab Pages dialog box is displayed.

Step 12 Click New . The Add/Edit User Tab Page dialog box is displayed.

Step 13 Enter a VRF Name and select vrfname .

Step 14 Click OK . The newly added tab pages are displayed in Tab Pages dialog box.

Figure 4-11 Tab Pages Dialog Box

Step 15 Click Next. The Script Lines dialog box is displayed, enabling you to add the script lines.

Step 16 Add the script lines, as shown in Figure 4-12.

Figure 4-12 Script Lines Example

Step 17 Click Finish. The Create Command dialog box is displayed. LEDs indicate the progress or status of the command as it is being saved to the registry.

Step 18 Click Close when the command is complete. The newly created addvrf command is displayed in the Command Builder table.

Step 19 Select the addvrf command in the Command Builder table.

Step 20 Run the command in one of the following ways:

• Click Run Command in the toolbar.
• Choose Tools > Run Command .
• Right-click the command, then choose Run Command .

The input form is generated and displayed. The Route Distinguisher and Route Target are displayed in General tab and vrfname is displayed in a separate tab called VRF Name.

In the General tab, the Route Target is a mandatory field (bold font) and Route Distinguisher is an optional field.

Step 21 Enter values in the VRF Name, Route Distinguisher, and Route Target fields.

Step 22 Click Preview to see how the command, including variables, looks before it is executed.

Step 23 Click Execute Now to view the results of the addvrf command as it is being executed.

Step 24 Close the input form to return to the Command Builder window.

Testing and Publishing Commands

The following topics describe how to test and publish commands:

• Testing the Command Locally Before Deploying It to Other NEs
• Publishing Commands to Other NEs

Testing the Command Locally Before Deploying It to Other NEs

Before you publish a command and apply it to other NEs, test it on your local NE using the following procedure. Once you have done this, you can apply it manually to multiple managed NEs, or publish it and make it available to a larger group of NEs (by family, NE type, or software version).

Step 1 From the Command Builder window, right-click the command and choose Run Command . Command Builder generates your input form.

Step 2 Complete the input form and click Preview.

Step 3 Click the Result tab to verify the command and variables before executing the command on the NE.

Step 4 If the command is successful and you want to execute it on the local NE, click Execute Now .

Note You might be prompted to enter your device access credentials. Once you have entered them, these credentials will be used for every subsequent execution of a command in the same GUI client session. If you want to change the credentials, click Edit Credentials. The Edit Credentials button will be disabled if the command is scheduled to run at a later time or if it is an SNMP command.

The queued commands can be terminated, if required, by clicking Abort.

Alternatively, if you are authorized by the Administrator to schedule jobs, you can use the Scheduling tab to schedule the command to run at a later time. You can check the job results by selecting Tools > Scheduled Jobs from the Prime Network Vision Tools menu.

Every command that is executed is logged in the Prime Network event database. The command’s execution history can be viewed using Prime Network Events. For more information about Prime Network Events, see the Cisco Prime Network 4.2.2 User Guide .

Publishing Commands to Other NEs

Publishing is the process of applying a command to a wider scope of managed NEs, so that the other NEs can use the new command. The Command Builder Hierarchy Manager dialog box controls the publishing of commands across the inheritance hierarchy . Figure 4-13 shows an example of an inheritance hierarchy. In this example, the top level of the hierarchy is All devices and the lowest level of the hierarchy is Device XYZ.

Figure 4-13 Inheritance Hierarchy Example

When a command is published to a node in the hierarchy, it overrides any inherited command from a higher level and automatically applies to all its children. For example, if a command is published to Cisco 7200, it overrides any variant of this command it inherited from a higher level and is assigned to all NEs of type Cisco 7200 in the system. NEs above the Cisco 7200 class are not affected.

Note A user with a Configurator role can add and publish commands on all NEs regardless of their assigned device scopes.

To publish a command:

Step 1 From the Command Builder window, right-click the command and choose Hierarchy Manager .

Note The names displayed in the VNE Hierarchy Location column depends on the registry settings. It is determined by the VNE schema (which controls the NEs that are managed and modeled by Prime Network). For example, a user-friendly name is displayed if a hierarchy path has been defined in the registry.

Rows are displayed in descending order with the top row representing the highest level of the hierarchy and the bottom row representing the lowest level of the hierarchy. The following information is provided for each level:

• Exist—If checked, indicates that a local variant of the command exists for that VNE hierarchy location.
• Registry Key—The hierarchy path as defined in the registry.

Table 4-4 describes the tools that are displayed in the Hierarchy Manager dialog box.

Step 2 Select the node in the hierarchy from where you want to Copy/Cut the command.

Step 3 Click Copy or Cut in the toolbar to copy or cut the command.

Step 4 Select the node in the hierarchy where you want to publish the command.

Step 5 Click Paste on the toolbar to paste the command. The command is published to the selected node in the hierarchy.

Note If you plan to publish the command to multiple network elements so you can perform commands in bulk, be sure to delete your local copy of the command after it is published. Otherwise when you choose multiple NEs, the command will not be listed.

If you select a group of network elements but the command is not listed, it is likely due to one of the following reasons:

• The command was not published to at least one of the network elements. You must publish the command to that network element using the hierarchy manager.
• One of the network elements has a local copy of the command. You must delete the local copy of the command using the hierarchy manager.

Note If a network element has more than one command instance, the command instance that is executed will be the one in the lowest hierarchy node.

Exporting Commands with Command Builder

When you export a command, a file containing the full command definition is created on the client machine. This is normally done when you want to manually import the command file to other NEs rather than use the Hierarchy Manager and the publishing procedure. The file is not copied to any other NEs; it is created so it can be imported by other NEs.

Step 1 In the Command Builder window, right-click the command and choose Export Element .

Step 2 Command Builder lists all versions of the command. In other words, if you have a 7206 NE with one version, but all other 7200 NEs have a different version, Command Builder would display both versions because both have been saved on your client machine. Check the version you want to export and click OK.

Step 3 Browse to the directory where you want to save the command.

Step 4 In the File name field, enter a name and click Save. The command is saved in XML format on the local client machine.

Importing Commands with Command Builder

Importing commands makes new commands available to an NE. For example, if you created a new command for NE 1, you could export the command from NE 1, and then import it to NE 2. The export is performed by launching Command Builder from NE 1, and the import is done by launching Command Builder from NE 2, as long as NE 2 is the same NE type.

If the import operation will overwrite a command that already exists, one of the following will happen:

• For a local command, Prime Network overwrites the existing definition.
• For a published command, Prime Network generates an error message which states that the command already exists. You must delete the existing command instance using the procedure described in Deleting Commands.

You can import multiple commands using this procedure as long as all of the commands are associated with the same VNE.

To import commands:

Step 1 In the Command Builder window, choose Tools > Import Element .

Step 2 Browse to the directory that contains the commands that you want to import.

Step 3 Select the commands that you want to import. To select multiple commands, press Shift or Ctrl while choosing the commands.

Step 4 Click Open . The Import Elements dialog box is displayed.

If you select multiple files, Command Builder presents an Import Element dialog box for each command.

Step 5 In the Import Element dialog box, select the VNE hierarchy location for the specified command.

Step 6 Click OK. The Command Builder window is displayed.

Step 7 Click Close. The commands are imported and displayed in the Command Builder window.

Deleting Commands

The procedure for deleting commands depends on whether the command is local or has been published.

• Local commands can be deleted from the Command Builder window by right-clicking the command and choosing Delete .
• Published commands must first be deleted from the applicable nodes using the Hierarchy Manager (right-click the command, then choose Hierarchy Manager ). You must delete all instances from all applicable nodes.

You can delete multiple commands at a time as long as all of the commands are associated with the same VNE. You may want to keep a local copy of the command before you delete it.