Developing an external script action adapter

External script actions are ways to invoke scripts or programs that perform external operations. The scripts reside in the BCAN_DATA\endorsed directory. BMC delivers a set of out-of-the-box external script actions. You can also develop your own external script actions by using out-of-the-box actions as examples and this topic as a reference.

Create a new external script action if what you need to accomplish requires a powerful programming language (such as Python, Perl, or Java) to interface with other systems or to manipulate data in a complex way. For example, you might want to populate another database with values extracted from BMC Network Automation. You might want to use the REST API to inject values into BMC Network Automation either from an external system or from computations based on the extracted configurations, perhaps combining information from multiple devices.

When you first import a new external script action, the system ensures that you are able to run that action, to perform debugging of your XML code and the program or script. If you already have full network rights, you are able to 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 external script action and adds you as a user to that new role. Once you finish debugging and want to publish the external script action to other users, you can use the role the system created (add your other users to the role) or you can include the external script action right into other roles.

This topic discusses the external script action template and examples of external script actions.

Template for external script actions

The following snippet shows an external script action template that contains all the possible elements:

Adapter template
<?xml version="1.0" encoding="UTF-8"?>
<deviceTypeMap>
<externalScriptDeclaration>
   <name>replace with a unique name</name>
   <guid>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</guid>
   <groupName></groupName>
   <classification>3</classification>
   <browserExecutable>true</browserExecutable>
   <approvable>false</approvable>
   <spanSelection>true</spanSelection>
   <scriptName>replace with the name of the script</scriptName>
   <scriptArgs>
       <scriptArg>
            ${global.localhostName}
       </scriptArg>
       <scriptArg>
            ${runtime.param1}
       </scriptArg>
       <scriptArg>
            ${file.spanList}
       </scriptArg>
   </scriptArgs>
   <runtimeParameters>
       <runtimeParameter>
           <name>param1</name>
           <prompt>Enter Parameter 1</prompt>
           <type>text</type>
           <required>false</required>
           <sortOrder>1</sortOrder>
           <defaultValue></defaultValue>
           <maxSize>40</maxSize>
           <mask></mask>
           <errorMessage></errorMessage>
        </runtimeParameter>
       <runtimeParameter>
           <name>param2</name>
           <prompt>Enter Parameter 2</prompt>
           <type>integer</type>
           <required>false</required>
           <sortOrder>2</sortOrder>
           <defaultValue></defaultValue>
           <minValue></minValue>
           <maxValue></maxValue>
       </runtimeParameter>
    </runtimeParameters>
   <spanFileFormat>
        ${device.name} ${agent.name}
   </spanFileFormat>
   <successReturnValues>
       <value>0</value>
   </successReturnValues>
   <warningReturnValues>
       <value>2</value>
   </warningReturnValues>
   <timeoutSeconds>60</timeoutSeconds>
   <temporaryFileLocation>replace with temporary directory location</temporaryFileLocation>
   <deleteTemporaryFilesOnCompletion>true</deleteTemporaryFilesOnCompletion>
   <useAdhocTemplate>false</useAdhocTemplate>
</externalScriptDeclaration>
</deviceTypeMap>

Defining external script actions

You must define new external script actions in an XML file whose syntax conforms to the schema defined in the DeviceTypeMap.xsd file, located in the BCAN_HOME\public\bmc\bca-networks\xml directory.

The schema file specifies all the available tags and attributes that you are allowed to use in an external script action XML file, and the order in which they must appear. The following table describes the elements in the external script action declaration:

Tag

Description

<externalScriptDeclaration>

Container for the declaration of the external script action

<name>

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

This name appears in the GUI and must be unique across all external script 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 external script action for organizing actions into submenus in the GUI (for example, Device Actions, Update CMDB, and so on)

<spanSelection>

(Required) Indicates whether the action includes the selection of a network span. Valid values are true and false. When true, the GUI displays a span selection list and the system validates that action includes a span selection.
If the value is set to false, device, agent, or file substitution parameters must not be specified as script arguments and the <spanFileFormat> element must not be used.

<scriptName>

(Required) String that specifies the name of the external program located in the BCAN_DATA\endorsed directory.
Note: The script must be non-empty and readable and executable by the BCAN_USER account on Windows, UNIX, and Linux.

<scriptArgs>
<scriptArg>

Defines the script parameters or the arguments passed in to the script at execution time. Each script argument is one of the following types:

  • A constant or hard-coded parameter
  • Any of the global, device, agent, or file substitution parameters
  • Any of the runtime parameters

Note: If ${file.spanList} is one of the script arguments, then the <spanFileFormat> element must be specified. Also, in that case, device, agent, and other file substitution parameters must not be specified as script arguments.

<successReturnValues>
<value>

Defines possible numeric exit codes returned on successful execution of the script

Default value is 0.

<warningReturnValues>
<value>

Defines possible numeric exit codes returned in case of warnings, which is reflected in the action and job status

Note: An exit code different from the declared success and warning exit codes is considered to be a failure.

<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 in to the script as arguments

Each value is populated into a substitution parameter named runtime followed by a dot followed by the specified name. The script arguments refer to the value as a substitution parameter, such as ${runtime.parameter1}. The <runtimeParameter> element contains the following sub-elements:

  • <name>: (Required) String containing the name of the runtime substitution parameter to be populated with the data you entered. By convention (not mandatory), this name does not include any spaces, which makes the XML more readable.
  • <prompt>: (Required) String containing the prompt to be displayed on the GUI, telling you what needs to be entered.
  • <type>: (Required) One of following values, indicating the type of data that you can provide as the value.
    • text: Indicates that you can enter a plain text value.
    • password: Indicates that you can enter a plain text value, whose data entry control prevents the data from being seen.
    • integer: Indicates that you can enter a number.
    • menu: Indicates that you can select options from a menu.
  • <required>: Indicates whether you are required to supply a value for this parameter. Valid values are true (default) and false.
  • <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 you. Default value is null, meaning data entry control is initially empty.
  • <maxSize>: For a text or password type of parameter, number indicating the maximum number of characters that you can supply for the value. Default value is 40. Text values are limited to a maximum of 2000 characters and 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 that 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 that 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 a value that is supplied 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 list. 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 is empty.
    • <inline>: The menu options are provided here, one in each child <menuValue> element.
    • <jdbc>: Perform an SQL query on 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.
<spanFileFormat>

String that specifies the format for each line in case ${file.spanList} is defined as a script parameter. The format should be a list of device and agent substitution parameters delimited by blank spaces.
Note: Global, runtime, or file substitution parameters are not allowed.

<timeoutSeconds>

Number that defines the timeout period (in seconds) of script execution. The script is aborted if it takes longer than the specified time.

Default value is 60 seconds. A value of zero or anything less than zero sets no timeout on the script.

<approvable>

Indicates whether the external script action is available in the list of actions for the Enable Job Approval For Action system parameter on the Admin > System Parameters page. Valid values are true and false (default).

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

<useAdhocTemplate>

Indicates whether or not an ad-hoc template can be entered into the action. Valid values are true and false (default). When true, the external script edit page includes controls to create and edit an ad-hoc template. The ad-hoc template might contain device, agent, global, and runtime substitution parameters that are resolved when the action is run. The contents of the template is written to a file to be passed in to the external script as the ${file.adhocTemplate} argument.

<classification>

(Required) 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 external script 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, or notification.
  • -1 (Default): The action does not fall into any other classification.
<browserExecutable>

Indicates whether this external script action can be executed from the GUI. Otherwise, the action is available only through web services. Valid values are true and false (default).

<temporaryFileLocation>

Defines the location where temporary files (device configuration, OS image files, and the file created for ${file.spanList}) are created. The temporary directory must be readable and writable by the BCAN_USER account on Windows, UNIX, and Linux.

Default value is java.io.tmpdir system property.

<deleteTemporaryFilesOnCompletion>

Indicates whether temporary files (device configuration, OS image files, and the file created for ${file.spanList}) created by the system to pass into the script should be deleted by the system after script execution. Valid values are true (default) and false. You might have some sort of asynchronous processing using these files that the script has initiated, or your script deletes the files as it uses them, in which case you would set this to false; the script is then responsible for cleaning up these files.

Back to top

Referencing substitution parameters in external script actions

A script argument can include one or more substitution parameters. The system resolves the substitution parameters and substitutes the appropriate values at run time. See About-substitution-parameters for more information.

Substitution parameters with the following prefixes are allowed in script arguments:

  • global: All the global substitution parameters: ${global.*}
  • runtime: All the runtime parameters declared in the external script action definition: ${runtime.*}
  • device: All the device substitution parameters: ${device.*}
  • agent: All the device agent substitution parameters: ${agent.*}
  • file: All of the following file substitution parameters, which are applicable only in the context of external script actions:
    • ${file.running.trusted}: On detecting this substitution parameter, the trusted running configuration of the device is stored in a temporary file, and the parameter is substituted with the temporary file name.
    • ${file.startup.trusted}: On detecting this substitution parameter, the trusted startup configuration of the device is stored in a temporary file, and the parameter is substituted with the temporary file name.
    • ${file.trailName.current}: On detecting this substitution parameter, the current configuration of the device is stored in a temporary file and the parameter is substituted with the temporary file name. trailName indicates the name of the configuration trail.
    • ${file.osImage}: On detecting this substitution parameter, the OS image of the device is stored in a temporary file and the parameter is substituted with the temporary file name.
    • ${file.spanList}: On detecting this substitution parameter, the device and agent attributes for the devices (as specified in the <spanFileFormat> tag of external script action definition) are stored in a temporary file and the parameter is substituted with the temporary file name.
    • ${file.adhocTemplate}: On detecting this substitution parameter, the ad-hoc template associated with the action is stored in a temporary file, and the parameter is substituted with the temporary file name. The contents of the ad-hoc template are modified to resolve any device, agent, global, and runtime substitution parameters.

Example: Archiving trusted configuration files of devices into a CVS system

The following example depicts a script that archives the trusted configuration files of a device into the CVS system:

<?xml version="1.0" encoding="UTF-8"?>
<deviceTypeMap>
<externalScriptDeclaration>
   <name>Archive Trusted Device Configs</name>
   <guid>AE89A898-34A4-40D9-8B3C-207F6322CAC8</guid>
   <groupName>Device Actions</groupName>
   <classification>2</classification>
   <browserExecutable>true</browserExecutable>
   <spanSelection>true</spanSelection>
   <scriptName>archiveTrustedDeviceConfigs.sh</scriptName>
   <scriptArgs>
       <scriptArg>
            ${global.localhostName}
       </scriptArg>
       <scriptArg>
            ${runtime.cvs host name}
       </scriptArg>
       <scriptArg>
            ${runtime.cvs port}
       </scriptArg>
       <scriptArg>
            ${runtime.user name}
       </scriptArg>
       <scriptArg>
            ${runtime.password}
       </scriptArg>
       <scriptArg>
            ${device.name}
       </scriptArg>
       <scriptArg>
            ${agent.name}
       </scriptArg>
       <scriptArg>
            ${file.startup.trusted}
       </scriptArg>
   </scriptArgs>
   <runtimeParameters>
       <runtimeParameter>
           <name>cvs host name</name>
           <prompt>cvs host name </prompt>
           <type>text</type>
       </runtimeParameter>
       <runtimeParameter>
           <name>cvs port</name>
           <prompt>cvs port </prompt>
           <type>integer</type>
       </runtimeParameter>
       <runtimeParameter>
           <name>user name</name>
           <prompt>user name </prompt>
           <type>text</type>
       </runtimeParameter>
       <runtimeParameter>
           <name>password</name>
           <prompt>password </prompt>
           <type>password</type>
       </runtimeParameter>
   </runtimeParameters>
</externalScriptDeclaration>
</deviceTypeMap>

The external script action defined in the preceding example uses the following parameters as script arguments:

  • ${global.localhostName}
  • ${runtime.cvs host name}
  • ${runtime.cvs port}
  • ${runtime.user name}
  • ${runtime.password}
  • ${device.name}
  • ${device.host}
  • ${file.startup.trusted}

The following actions are performed:

  1. Prompt for span selection.
  2. Prompt for runtime parameter values (cvs host name, cvs port, user name, and password).
  3. For each device in the selected span:
    1. Resolve global, runtime, device, and file substitution parameters, and substitute the appropriate values as script arguments.
    2. Write the trusted startup configuration to the temporary directory.
    3. Execute the archiveTrustedDeviceConfig.sh script.
      This script archives the trusted startup configurations for a device into the CVS system.

Back to top

Example: Updating an external device database

The following example depicts a script that updates an external device database, by reading in device information from a file, parsing the lines (example shows device information delimited by two slashes), and runs SQL queries to update a database using the parsed device values.

<?xml version="1.0" encoding="UTF-8"?>
<deviceTypeMap>
<externalScriptDeclaration>
   <name>Update device database </name>
   <guid>AE89A898-34A4-40D9-8B3C-207F6322CAC8</guid>
   <groupName>Device Actions</groupName>
   <classification>2</classification>
   <browserExecutable>true</browserExecutable>
   <spanSelection>true</spanSelection>
   <scriptName>updateDeviceDatabase.sh</scriptName>
   <scriptArgs>
       <scriptArg>
            ${global.localhostName}
       </scriptArg>
       <scriptArg>
            ${runtime.database host name}
       </scriptArg>
       <scriptArg>
            ${runtime.database port}
       </scriptArg>
       <scriptArg>
            ${runtime.user name}
       </scriptArg>
       <scriptArg>
            ${runtime.password}
       </scriptArg>
       <scriptArg>
            ${file.spanList}
       </scriptArg>
   </scriptArgs>
   <runtimeParameters>
       <runtimeParameter>
           <name>database host name</name>
           <prompt> database host name </prompt>
           <type>text</type>
       </runtimeParameter>
       <runtimeParameter>
           <name>database port</name>
           <prompt>database port </prompt>
           <type>integer</type>
       </runtimeParameter>
       <runtimeParameter>
           <name>user name</name>
           <prompt>user name </prompt>
           <type>text</type>
       </runtimeParameter>
       <runtimeParameter>
           <name>password</name>
           <prompt>password </prompt>
           <type>password</type>
       </runtimeParameter>
   </runtimeParameters>
   <spanFileFormat>
        ${device.name} // ${device.host} // ${agent.name}
   </spanFileFormat>
</externalScriptDeclaration>
</deviceTypeMap>

The preceding external script action accepts the following parameters as script arguments:

  • ${global.localhostName}
  • ${runtime.database host name}
  • ${runtime.database port}
  • ${runtime.user name}
  • ${runtime.password}
  • ${file.spanList}

The following actions are performed:

  1. Prompt for span selection.
  2. Prompt for runtime parameter values (database host name, database port, user name, and password).

For each device in the selected span:

  1. Read in the device or agent attributes as specified in <spanFileFormat> and write them out to a temporary file (so there is one line per device in this file).
  2. Resolve global, runtime, and file substitution parameters, and substitute the appropriate values as script arguments.
  3. Execute the updateDeviceDatabase.sh script.
    This script parses the passed-in file and updates the external device database with the device or agent attributes parsed from the file.

Back to top

 

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