Developing a custom action adapter using XML

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

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

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.

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.

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.

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

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

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.

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

Indicates whether the custom action requires a file to be uploaded to device.

Message to be prompted to the user (executing the custom action job) for attaching the file if <deploysFile> is set to true.

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.

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.

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.

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