Developing a custom action adapter

A custom action device adapter adds a new function to what the system can do to or on a device. A custom action wraps a unit of work done on a device during a login session. You can run any command or request that the device allows, or any combination of multiple commands or requests. You can then run a job that runs the custom action on the devices where the custom action has been implemented. This topic describes the basics of a custom action adapter and XML template for a custom action adapter. It provides a reference to all available XML elements relevant to custom actions. Examples-of-custom-action-adapters provides examples and more detailed explanations of various parts of a custom action adapter.

Custom action adapter basics

Create a new custom action if you need to gather the settings or change the behavior of a device in a new way that is not already present in the system. You need to be able to express the work that you want to do within the confines of the device adapter XML syntax supported by the <deviceCommand> or <httpDeviceCommand> elements that send commands to a device and process the responses, with simple conditional and looping constructs.

A custom action is made up of the declaration, followed by the per-device-type implementation. A custom action might examine features or components or statistics in a device (that is, inspect a device without making changes), or it can make changes (for example, you can wrap commonly performed update commands in a custom action to relieve your users from knowing obscure command syntax, especially across different device types).

When you first import a new custom action, the system ensures that you are able to run that action, to perform debugging of your XML code. If you already have full network rights, you can access all actions by default. But if you do not have full network rights, the system creates a new role that grants the right to run the new custom action and adds you as a user to that new role. Once you finish debugging and want to publish the custom action to other users, you can use the role the system created or you can include the custom action right into other roles.

Template for a custom action adapter

Use the following template for the XML for a custom action adapter:

Adapter template
<?xml version="1.0" encoding="UTF-8"?>
<deviceTypeMap>
   <customDeviceCommandDeclaration>
       <name>display name</name>
        <guid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</guid>
       <groupName></groupName>
       <description></description>
       <generalInfo></generalInfo>
       <browserExecutable>true</browserExecutable>
       <approvable>true</approvable>
       <inspectionOnly>true</inspectionOnly>
       <hideMakeTrustedOption>false</hideMakeTrustedOption>
       <classification>3</classification>
       <dynamicField>
           <name></name>
           <sourceResult></sourceResult>
           <rejectUnknownMenuOption>false</rejectUnknownMenuOption>
           <onBadValue>failActionMajor</onBadValue>
       </dynamicField>
       <importedHardware>
           <sourceResult></sourceResult>
       </importedHardware>
       <runtimeParameters>
           <runtimeParameter>
               <name></name>
               <prompt></prompt>
               <type>text</type>
               <required>true</required>
               <sortOrder>1</sortOrder>
               <defaultValue></defaultValue>
               <maxSize>40</maxSize>
               <mask></mask>
               <errorMessage></errorMessage>
           </runtimeParameter>
       </runtimeParameters>
    </customDeviceCommandDeclaration>
   <deviceType>
       <guid>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyy</guid>
       <extension>true</extension>
       <deviceCommand>
           <guid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</guid>
       </deviceCommand>
   </deviceType>
</deviceTypeMap>

The legal XML elements in a custom action adapter are:

Tag

Description

<name>

(Required) Name of the custom action, up to 255 characters in length

This name appears in the GUI and must be unique across all custom actions.

<guid>

(Required) A globally unique ID (GUID)

Run the create_guid.sh or create_guid.bat script in the BCAN_HOME\tools directory to generate a new GUID for use here.

<groupName>

String that defines the group or category of custom action for organizing actions into submenus in the GUI (for example, VLAN Management and Interface Monitoring)

You can invent your own groups or you can use groups shared with the out-of-the-box content (such as Diagnostics, Hardware, or Topology).

Default value is null, so the custom action appears in the first level of the cascaded menu.

<description>

String that contains a message to display to users when they are creating or editing this action, to provide instructions or more detailed information about what the action does

Default value is null.

<generalInfo>

String containing general notes, warnings, quirks, or anything else special about this custom action that might affect how users use it

Use a CDATA tag to enclose HTML elements that format this information for display in the Device Adapter Capabilities report. Refer to Common concepts and XML elements for more information about CDATA.

Default value is null.

<browserExecutable>

Indicates if this custom action can be executed from the GUI. Otherwise, it is available only through web services.

Valid values are true and false (default).

<approvable>

Indicates if the custom action is available in the list of actions for the Enable Job Approval For Action system parameter on the Admin > System Parameters page

The administrator can control whether the action requires job approval and which users can perform the approval.

Valid values are true and false (default).

<inspectionOnly>

Indicates if the custom action makes no changes to the device

Valid values are true and false (default). If it is flagged as false (meaning changes are made), the system automatically takes a snapshot to keep track of the changes. If it is flagged as true, no snapshot is taken.

This setting also affects when the discover-core device command is run, which is usually used to discover the model and operating system version. When true, discover-core is not executed at all. When false, it is executed after the custom action logic and before the automatic snapshot. In either case, your custom action logic cannot depend on properties being present that are normally populated by discover-core.

<hideMakeTrustedOption>

Indicates if the GUI presents the Mark As Trusted option for this custom action (which controls what happens to the configurations taken during the snapshot). Ignored if <inspectionOnly> is true.

Valid values are true and false (default).

<classification>

Number that 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 it generates various reports based on the types of jobs and actions that were performed. Otherwise, this value does not affect any processing

Valid numeric values are:

  • 0: Deployment: The action makes a modification to the device.
  • 1: Snapshot: The action takes a snapshot of some settings in the device, but makes no changes.
  • 2: Notification: The action does not access the device, but emits a notification (such as an email message or trap).
  • 3: Other: The action does something other than deployment, snapshot, and notification.
  • -1 (Default): Indicates that the action does not fall into any other classification.
<dynamicField>
<name>
<sourceResult>
<rejectUnknownMenuOptions>
<onBadValue>

Indicates that custom action results are to be populated into a device dynamic field

The <dynamicField> element contains the following sub-elements:

  • <name>: (Required) String containing the name of the dynamic field to be populated. The dynamic field must exist at the time the custom action is executed by a job. If the dynamic type does not exist, value assignment is silently skipped.
  • <sourceResult>: (Required) String containing the name of the property this custom action populates, whose value is to be the value for the dynamic field. If the property is not populated by the custom action and the dynamic field is system assigned, then any current value in the device is removed.
  • <rejectUnknownMenuOptions>: true or false to indicate if menu option not already present in a single-select or multi-select type of dynamic field is rejected. When true, only known menu options are accepted, with error handling per the <onBadValue> element. When false, new values are automatically added to the menu of the dynamic field. Default value is false.
  • <onBadValue>: One of logEvent, failActionMinor, or failActionMajor, indicating how the system should handle invalid values. The value pulled from the specified property is checked against the constraints imposed by the specified dynamic field. For example, a Text type field imposes a maximum length; an Integer type of field can impose minimum and maximum values; a Single-Select and Multi-Select Menu restricts values to those in its menu options. Default value is null, meaning silently ignore bad values.
    • logEvent: Log the warning event, Custom action captured an invalid value for a dynamic field.
    • failActionMinor: Report this as a minor failure of the custom action, which results in the job completion with warning.
    • failActionMajor: Report this as a minor failure of the custom action, which results in the job completion with error.
<importedHardware>
<sourceResult>

Indicates that custom action results are to be populated into the device's imported hardware inventory, which is displayed when you view the device or the Device Inventory report. You can specify multiple <importedHardware> elements, in which case the property values are concatenated together. This element contains the following child element:

  • <sourceResult>: (Required) String containing the name of the property this custom action populates, whose value is to be the value for the imported hardware inventory. If the property is not populated by the custom action, then this element is ignored.
<runtimeParameters>
<runtimeParameter>
<name>
<prompt>
<type>
<required>
<sortOrder>
<defaultValue>
<maxSize>
<mask>
<minValue>
<maxValue>
<errorMessage>
<menuValues>
<file>
<fileName>
<inline>
<menuValue>
<jdbc>
<dbUrl>
<dbQuery>

Specifies a value that is passed from the user into the custom action XML logic, for use in running the command or the request on the device. Each value is populated into a property named runtime followed by a dot followed by the specified name. The XML code refers to the value through a keyword, such as %runtime.parameter1%.

The <runtimeParameter> element contains the following child elements:

  • <name>: (Required) String containing the name of the property to be populated with the data you entered. By convention (not mandatory), this name does not include any spaces, which makes the XML code more readable.
  • <prompt>: (Required) String containing the prompt to be displayed in the GUI, telling the user what needs to be entered.
  • <type>: (Required) One of the following values, indicating the type of data you can provide as the value:
    • text: Enter a plain text value.
    • password: Enter a plain text value, whose data entry control prevents the data from being seen.
    • integer: Enter a number.
    • menu: Select value from a menu.
      Important: If you choose menu as the type, do not specify the following tags: defaultValue, maxSize, minValue, maxValue, mask, and errorMessage.
  • <required>: true or false to indicate if you need to supply a value for this parameter. Default value is true.
  • <sortOrder>: Number indicating where this parameter should appear among the rest of the parameters, when displaying the data entry controls to you in the GUI. Default value is 1.
  • <defaultValue>: The value to appear into the data entry control when the page is initially presented to the user. Default value is null, meaning data entry controls are initially empty.
  • <maxSize>: For a text or password type of parameter, number indicating the maximum number of characters you can supply for the value. Default value is 40. Text values are limited to a maximum of 2000 characters; password values are limited to a maximum of 255 characters.
  • <mask>: For a text type of parameter, string containing a regular expression that the user-entered text must match in order to be considered valid. Default value is null (no validation done beyond length check).
  • <minValue>: For an integer type of parameter, number indicating the minimum value you can enter. Default is no minimum defined. Supports numbers in the range of a 32-bit integer.
  • <maxValue>: For an integer type of parameter, number indicating the maximum value you can enter. Default is no maximum defined. Supports numbers in the range of a 32-bit integer.
  • <errorMessage>: String containing the error message to display to you when the supplied value is not valid. Default is a canned error message that varies by the type of error detected.
  • <menuValues>: Specifies the values to be displayed for selection in a drop-down menu. Include one of the following elements:
    • <file>: Read a file and treat each line as a menu option. The required <filename> child element specifies the name of the file, located in the BCAN_DATA\endorsed directory. If the file does not exist or cannot be read, the menu will be empty.
    • <inline>: The menu options are provided here, one in each child <menuValue> element.
    • <jdbc>: Perform an SQL query in a database. The required <dbUrl> child element specifies the path to the database server. The required <dbQuery> child element specifies the SQL query to be executed. The first column from each returned row becomes a menu option, arranged in the order the query generated its rows (so use an ORDER BY clause if necessary). If the URL or the query are invalid or the database server is unreachable, the menu is empty.
<deviceType>
<guid>
<extension>
<deviceCommand>
<guid>

Implementation of the custom action for a particular device type. The first <guid> identifies the device type. The second <guid> identifies which custom action you are implementing, using the GUID you created in the declaration. Follow this second GUID with interactions and other elements that perform the logic of interacting with the device and parsing its output to gather results.

The elements allowed here are <deviceCommand> and <httpDeviceCOmmand> and their child elements. See Device-type-CLI-interaction-XML-element-reference for a CLI based device type, and Device-type-HTTP-interaction-XML-element-reference for an HTTP or HTTPS based device type.

You can implement your custom action in as many device types as you like. Simply include a <deviceType> section for each one.

<extension>: true or false to indicate if this extends an existing device type. Set this to true for all custom actions (else, errors will ensue).

 

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