Understanding custom actions

BMC delivers a set of factory-installed custom actions. You can also develop your own custom actions. The factory-installed 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.

Custom actions are most commonly used to:

Syntax of the custom actions

The syntax of custom actions must conform to the schema defined in the DeviceTypeMap.xsd file, which is located in the BCAN_HOME\public\bmc\bca-networks\xml directory.

The schema file specifies all available tags and attributes that you are allowed to use in a custom action XML file.

Get device information using the Show VLANs custom action

The Show VLANs custom span action runs a single command and captures the output for display in the transcript.

To define this custom action, perform the following tasks:

  1. Create the DeviceTypeMap-showvlan.xml file that contains the following XML code. The action runs two commands on the device and captures the output in the transcript.

    <?xml version="1.0" encoding="UTF-8" ?>
    <deviceTypeMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <customDeviceCommandDeclaration>
        <name>ShowVLANs</name>
        <guid>69A30B43-A3EF-4BD5-A989-26977934595E</guid>
        <browserExecutable>true</browserExecutable>
        <approvable>true</approvable>
        <inspectionOnly>true</inspectionOnly>
        <classification>3</classification>
      </customDeviceCommandDeclaration>
      <!-- ========================================================= -->
      <deviceType>
        <guid>BE2B2D21-1CAA-53C3-05C3-CBB0A5D151B8</guid> <!-- IOS -->
        <extension>true</extension>
        <deviceCommand>
          <guid>69A30B43-A3EF-4BD5-A989-26977934595E</guid><!-- Show VLANs -->
          <interaction>
            <prompt>%prompt%</prompt>
            <command>show vlan brief</command>
            <response>%prompt%</response>
          </interaction>
          <interaction>
            <prompt>%prompt%</prompt>
            <command>show vlan summary</command>
            <response>%prompt%</response>
          </interaction>
        </deviceCommand>
      </deviceType>
    </deviceTypeMap>
  2. Use the Import function to import this file.

The following table describes the tags used in the preceding custom span action:

Tag

Description

<customDeviceCommandDeclaration>

Wrapper around the declaration of the custom action.

<name>

Name of the custom action. This name appears on the GUI and must be unique across all custom span actions.

<guid>

Each custom action must have a globally unique ID (GUID). Customer-created custom actions should use a newly-generated GUID. Use the create_guid.sh or create_guid.bat script in the BCAN_HOME/tools directory to generate a new GUID.

<browserExecutable>

If this tag is set to true, the specified span action can be executed from the GUI. Otherwise, it is available only through web services.

<approvable>

If this tag is set to true, the specified span action is available for approval on the GUI. The administrator can control whether the command requires approval and which users can approve.

<inspectionOnly>

If this tag is set to true, the specified span action skips backing up the device’s running and startup configurations. This tag should be set to true only if the command does not change the configuration of the device.

<classification>

The optional attribute specifies the category or type of the action. The classification is based on how the action manipulates the device.

BMC Decision Support – Network Automation uses this information when generating various reports based on the types of jobs and span actions that are performed.

Valid values include:

  • 0 (Deployment): The action modifies a device. If the <inspectionOnly> flag is set to false, the classification must be 0.
  • 1 (Snapshot): The action takes a snapshot of some settings in the device.
  • 2 (Notification): The action does not access the device but sends notification in the form of an e-mail or trap. This value only applies to the built-in notification actions. You cannot develop a custom action with this value.
  • 3 (Other): The action does some task other than deployment, snapshot, or notification.
  • -1: If no classification is specified, a default value of -1 is used indicating that the action does not belong to any other classification.

<deviceType>

In this example, you only implement the custom action for a single device type (Cisco IOS). To add support for additional device types, add additional <deviceType> wrappers and specify the <guid> tag of the device type.

<guid>

GUID of the device type that is implementing the specified span action. This tag contains interactions specific to this device type.

<extension>

For custom actions, this tag must be set to true. This allows the software to augment the device commands defined in the main Device Adapter definition.

<deviceCommand>

The <deviceCommand> tag wraps the device interactions. In this case, you are defining a single device command for the Show VLANs custom action, identified by the GUID of the command.

<guid>

GUID of the command you are implementing. In this case, the GUID should match the custom action GUID specified at the start of the code.

<interaction> ...</deviceTypeMap>

The device <prompt> - <command> - <response> interactions. See Device type map for details on defining device interactions. In this example, you are executing two commands, show vlan brief and show vlan summary on the device.

The preceding example does not handle error conditions such as the command failing or not being supported by a device.

Back to top

Capture device information using the Ping custom action

The Ping custom action is a basic example of how to request input from a user, with runtime parameters. The user’s input will be plugged into the command executed at the device. For information about runtime parameters, see Understanding-custom-action-runtime-parameters.

If the ping fails, the completion status of span action depends on the result of the ping (Success on complete success, Failed on complete failure, or Succeeded with warning on a partial failure). 

This example is actually a simplified version of the standard IOS Ping custom action, which is available on the Device Adapters page from within the system.

  1. Create the DeviceTypeMap-ping.xml file that contains the following XML code:

    <?xml version="1.0" encoding="UTF-8" ?>
    <deviceTypeMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <customDeviceCommandDeclaration>
        <name>Ping</name>
        <guid>F6D4804A-EF08-4D89-98CC-74E540492001</guid>
        <description>Your description about this custom action</description>
        <browserExecutable>true</browserExecutable>
        <inspectionOnly>true</inspectionOnly>
        <runtimeParameters>
          <runtimeParameter>
            <name>node</name>
            <prompt>IP address of node to ping:</prompt>
            <type>text</type>
            <required>true</required>
            <mask>\d+\.\d+\.\d+.\d+</mask>
          </runtimeParameter>
        </runtimeParameters>
      </customDeviceCommandDeclaration>
      <deviceType>
        <guid>BE2B2D21-1CAA-53C3-05C3-CBB0A5D151B8</guid>
        <extension>true</extension>
        <deviceCommand>
          <guid>F6D4804A-EF08-4D89-98CC-74E540492001</guid>
          <interaction regex="true">
            <prompt>%prompt%</prompt>
            <command>ping %runtime.node%</command>
            <response property="cmd.pingSuccess">Success rate is 100 percent</response>
            <response property="cmd.pingWarning">Success rate is (20|40|60|80)percent</response>
            <response property="cmd.pingAbort">Success rate is 0 percent</response>
          </interaction>
          <assert condition="((-EXISTS- cmd.pingSuccess) -OR- (-EXISTS- cmd.pingWarning))"
    onFailure="abort">
          Ping returned success rate of 0 percent.
          </assert>
          <assert condition="(-EXISTS- cmd.pingSuccess)" onFailure="warning">
          Ping returned success rate of greater than 0 but less than 100 percent.
          </assert>
        </deviceCommand>
      </deviceType>
    </deviceTypeMap>
  2. Use the Import function to import this file.

The following table describes the tags used in the preceding custom span action:

Tag

Description

<customDeviceCommandDeclaration>

Wrapper around the declaration of the custom action.

<name>

Name of the custom action. This name appears on the GUI and must be unique across all custom span actions.

<guid>

Each custom action must have a globally unique ID (GUID). Customer-created custom actions should use a newly-generated GUID. Use the create_guid.sh or create_guid.bat script in the BCAN_HOME/tools directory to generate a new GUID.

<description>

If provided, description is displayed on top of the respective custom action in the Jobs > Add Action > Custom Actions menu.

A description value may include HTML text. For example, Custom Action &gt;b&lt;Ping&gt;/b&lt;

In this example, the word “Ping” is displayed in bold format.

Note: If a description field is present in the DeviceTypeMap, it cannot be empty. It should include either a default value or a key that can retrieve a value from a resource file. Otherwise, an exception occurs.

<browserExecutable>

If this tag is set to true, the specified span action can be executed from the GUI. Otherwise, it is available only through web services.

<inspectionOnly>

If this tag is set to true, the specified span action skips backing up the device’s running and startup configurations. This should be set to true only if the command does not change the configuration of the device.

<runtimeParameters>

Wrapper around the runtime parameters section.

<runtimeParameter>

Wrapper around the runtime parameter section.

<name>

The name that will refer to this value of the parameter in the deviceCommand section described below.

<prompt>

The prompt that will be displayed to the user when creating the custom action in a job or policy.

<type>

The type of input the user needs to supply; “text” means the user is presented with a text field in which to enter data.

<required>

Whether or not the user must supply a value. When true, the user must fill in the text field. When false, it can be left blank.

<mask>

The format the user supplied data must conform to, in the form of a regular expression. In this case, the user must supply input that is formatted like an IP address (for example, dotted-decimal notation).

<deviceType>

In this example, you only implement the custom action for a single device type (CiscoIOS). To add support for additional device types, add additional <deviceType> wrappers and specify the <guid> tag of the device type.

<guid>

GUID of the device type that is implementing the specified span action. This tag contains interactions specific to this device type. See the 

<extension>

For custom actions, this tag must be set to true. This allows the software to augment the device commands defined in the main Device Adapter definition.

<deviceCommand>

The <deviceCommand> tag acts as a wrapper for the device interactions. In this case, you are defining a single device command for the Ping custom action, identified by the GUID of the command.

<guid>

GUID of the command you are implementing. In this case, the GUID should match the custom action GUID specified at the start of the code.

<command>

The command to be executed on the device. %runtime.node% indicates that the value that you specify for "node", the runtime parameter is used.

<response property>

Sets a property based on the output of the Ping action.

<assert condition>

Checks whether the cmd.pingSuccess or cmd.pingWarning property has been set. When neither is set, the span action aborts and displays the specified error message.

Back to top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*