Executing custom actions

This topic describes how to execute custom actions and view the results of custom actions.

Custom actions are scripts for executing native device commands. BMC delivers a set of out-of-the-box custom actions. You can also develop your own custom actions. The out-of-the-box actions can be used as examples for developing your own actions. Custom actions are written by using the BMC Network Automation system's XML scripting language. The XML scripting language is easy to learn and hides complex I/O operations so you can focus on the task at hand. For details of out-of-the-box custom actions supported for various device types, see Device Adapter Capabilities report.

Custom actions are most commonly used to:

• Execute show commands to collect device information for reporting and analysis
• Get device information for use by a subsequent job span action

For detailed information about default custom actions and how to create new custom actions, see Developing a custom action adapter.

Additional default custom actions are included in the product installation. These actions initially are disabled and do not appear in the job Actions menu. An administrator can enable these actions by using the Admin > Device Adapters facilities as described in Managing device adapters.

To execute device adapter custom actions

1. On the Add Job page, select a custom action (for example, IOS Show UDP Drops) from Add Action > Custom Actions > Diagnostics > IOS Show UDP Drops.
   
   

2. Enter information in the following fields:

   Field	Description
   Annotation	(Optional) Annotation assigned to the configurations created by the action.
   Network Span	Select a realm, group, multiple devices, or a single device for the action. When the Network Span is Realm or Group, you can use Filter Devices to select which devices to include in the action. When the action is triggered in an event-based Policy, additional options include: Same as Triggering Realm, Same as Triggering Group, Same as Triggering Device.
   Runtime parameters	The dialog box displays various additional runtime parameters that are declared in the script definition.

3. If the custom action performs a configuration change, select any of the following options, as relevant:

   Option	Description
   Mark as Trusted	If the custom action completes successfully, mark the resulting Running and Startup configurations as trusted.
   Commit	If the custom action completes successfully, copy the device's Running configuration to the Startup. This ensures that if the device reboots, the changes have been committed.
   Reboot	If the custom action completes successfully, reboot the device after executing the custom action.
   Use Auxiliary Interface	When the selected network span is a device, this option selects the auxiliary interface for connecting to the device. When not checked or when the span is not a device, the primary interface is used.

4. Click OK to add the action to the job.

Viewing the results of custom actions

The results of custom actions can be directed to the following places:

• Dynamic fields
• Captured results in Job Details
• Transcript

The Job Details report can be emailed automatically when the job completes and the report can include the Transcript(s). For example, certain custom actions (for example, show ip route) generate lengthy outputs where it does not make sense to display in the report's Captured results. It would be easier to look at the Job Details report and view the show ip route output in the Transcripts.

When determining which result location to direct the captured results, here are some recommendations:

• Dynamic fields: For persistent information that does not change much (that is, serial numbers, uplink interfaces, and so forth).
• Captured results: For small amounts of data you want parsed out of longer show command results and presented nicely in the Job Details; also for custom actions that you use often (for example, show current VLANs defined on all switches). A captured result is limited to 2000 characters, though you may capture as many results as you like.
• Transcripts: For long lists, for when there is lots of data you want to peruse, for transient reports (for example, run a show ipc queue every two hours and send the results). Custom action transcripts can be attached to job email notifications and included in the Job Details Export and Email options.

The custom action captured results can also be viewed by clicking the Results link in the Job Details page.

Note: In version 8.9.01 and later, the Send Email option has been replaced with Send Notification. 

The captured results are displayed in a view page with the action number and custom action name appearing in the title, as shown in the following figure:

In the view page, the captured results can be sorted by device name, index, captured property name, and captured property value.

The default view of the captured results groups the captured property names and captured property values by index, where each index value represents one component (for example, interface, process, port, or protocol). You can use this default view to compare the values captured for one component. For example, in the above screenshot, you can compare multiple properties (such as drop, protocol, and remote) for a particular UDP process.

You can use the Pivot button to generate a pivoted view, in which each property is represented by its own column. This view lets you easily compare the same type of values captured from different components against each other. The following figure shows the pivoted view for multiple UDP processes.

The view page has the following menu options: