Working with external script actions

External script actions are scripts or programs that perform external operations. The scripts reside in the /endorsed directory. You can reference substitution parameters in external script actions. External scripts actions are written using the system's XML scripting language. The following external operations are examples that could be executed as external script actions:

Archiving device trusted configuration files into a CVS system.
Updating a device database with configuration elements.
Resetting the password for all devices based on a dynamically generated password.
Adding a device record after a new module or virtual device context is provisioned.

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. Substitution parameters with the following prefixes are allowed as script arguments:

global: All the global substitution parameters: ${global.*}
runtime: All the runtime substitution 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 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}
  - trailName—name of the configuration trail.
  - On detecting this substitution parameter, the current configuration of the device would be stored in a temporary file and the parameter would be substituted with the temporary file name.
- ${file.osImage}: On detecting this substitution parameter, the OS image of the device would be stored in a temporary file and the parameter would be 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) would be stored in a temporary file and the parameter would be substituted with the temporary file name.
- ${file.adhocTemplate}: On detecting this substitution parameter, the ad-hoc template associated with the action would be stored in a temporary file, and the parameter would be substituted with the temporary file name. The contents of the ad-hoc template would be modified to resolve any device, agent, global, and runtime substitution parameters.

Defining external script actions

You must define new external script actions in an XML file whose syntax conforms to the schema defined in the file that is located in the following directory:

BCAN_HOME/public/bmc/bca-networks/xml

The schema file specifies all the available tags and attributes that you are allowed to use in an external script action XML file. 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	Name of the external script action. This name appears in the GUI and must be unique across all external script actions.
guid	Each external script action must have a unique GUID. Use the create_guid.sh or create_guid.bat script in the BCAN_HOME/tools directory to generate a new GUID.
groupName	Defines the group or category of external script action for organizing actions into submenus in the GUI (for example, Device Actions, Archive Config, Update CMDB, and so on)
spanSelection	Defines whether the action should prompt for span selection. Valid values are true and false. Note: If the value is set to false, the action will not prompt for span selection. In that case device, agent, or file substitution parameters must not be specified as script arguments and the spanFileFormat tag must not be defined.
scriptName	Defines the name of the external program located in the 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. Each script parameter is one of the following types: Constant-hardcoded 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 tag must be specified. Also, in that case, device, agent, and other file substitution parameters must not be specified as script arguments.
successReturnValues	Defines possible exit codes returned on successful execution of the script. Default value: 0
warningReturnValues	Defines possible exit codes returned in case of warnings. Note: An exit code different from declared success and warning exit codes is considered to be a failure.
runtimeParameters	Defines runtime parameters that could be used as script arguments. For more details, see Custom action runtime parameters.
spanFileFormat	Defines the format for each line in case ${file.spanList} is defined as a script parameter. The format should be a list of Device, Agent substitution parameters delimited by blank spaces. Note: Global, runtime, or file substitution parameters are not allowed.
timeoutSeconds	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.
approvable	If set to true, this 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. The administrator can control whether the command requires job approval and which users can perform the approval. Default value is false.
useAdhocTemplate	Defines whether or not an ad-hoc template can be entered into the action. When true, the external script edit page will include controls to create and edit an ad-hoc template. The adhoc template may contain device, agent, global, and runtime substitution parameters that will be resolved when the action is run. The contents of the template will be written to a file to be passed in to the external script. Default value is false.
classification	This 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 it generates various reports based on the types of jobs and external script actions that were performed. The valid 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. 2: Notification: The action does not access the device, but emits some sort of notification (such as an e-mail message or trap). 3: Other: The action does something other than deployment, snapshot, or notification. Default value is -1, which indicates that the action does not fall into any other classification.
browserExecutable	If set to true, this external script action can be executed from the GUI. Otherwise, it is available only through web services. Default value is false.
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	Defines whether temporary files (device configuration, OS image files, and the file created for ${file.spanList}) should be deleted after script execution. Valid values are true (default) and false.

Template external script action

The following example shows an external script action template that contains all the possible fields:

<externalScriptDeclaration>
  <name>replace with a unique name</name>
  <guid>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</guid>
  <groupName>group name for action</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>param1</prompt>
      <type>text</type>
    </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>
</externalScriptDeclaration>

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:

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

The external script action defined in 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:

Prompt for span selection.
Prompt for runtime parameter values (cvs host name, cvs port, user name, and password).
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. Execute the archiveTrustedDeviceConfig.sh script for each device.
  This script archives the trusted startup configurations for a device into the CVS system.

Updating the device database

The following example depicts a script that updates the device database:

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

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

Prompt for span selection.
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 the spanFileFormat and write them out to a temporary file.
2. Resolve global, runtime, and file substitution parameters and substitute the appropriate values as script arguments.
3. Execute the updateDeviceDatabase.sh script once.
  The updateDeviceDatabase.sh script updates the device database with the device/agent attributes present in the file passed as an argument.