Understanding custom action runtime parameters

Custom actions can prompt users for runtime parameters used by the script. The examples provided in this topic describe the usage of runtime parameters.

Action

Example

Specifying menu-based runtime parameter by using the menu options supplied inline

Specifying menu-based runtime parameter by using the menu options supplied in a file

Specifying menu-based runtime parameter by using the menu options supplied in an SQL database

Specifying text-based runtime parameter by validating if a value exists

Specifying text-based runtime parameter by setting the maximum size

Specifying text-based runtime parameter  by validating the input format

Specifying password runtime parameter by sorting parameters on the user Interface

Runtime parameters are defined in the device command declaration as follows:

<runtimeParameters>
 <runtimeParameter>
   <name>show</name>
   <prompt>What to Show</prompt>
   <type>menu</type>
 </runtimeParameter>
</runtimeParameters>

The following table describes the tags used in the device command declaration:

Tag

Description

Required

<name>

Is used in the custom action to reference the parameter value. For a Predefined job with a custom action that requires runtime parameters,
specify the value of <prompt> as the value for <name> in the name:value pair.

For example, in the following Traceroute custom action, specify the value for <name> as directed by the comment:

<xsd:runtimeParams>
  <xsd1:name>IP address of the destination node</xsd1:name>
  /* Although the name of the parameter is 'node', you must
specify the prompt value */
  <xsd1:value>10.10.10.10</xsd1:value>
</xsd:runtimeParams>

Yes

<prompt>

Is displayed on the Custom Action window for the parameter.

Yes

<type>

Specifies whether the parameter is a text, password, menu-based, or integer value. A password type causes the system to hide the entered value.

Yes

 Based on the parameter type, you can specify additional parameter attributes as listed in the following table:

type tag value

Supported attributes

Specify if the
parameter is
required

Import menu
values from
SQL database
or file

Assign a
default
value

Set maximum
size (number
of characters)

Set maximum
and/or
minimum
values

Validate
input
format

Sort the
parameter
on the user
interface

text

X

 

X

X

 

X

X

password

X

 

X

X

 

 

X

menu

X

X

X

 

 

 

X

integer

X

 

X

 

X

X

X

Back to top

The XML tags listed in the following table specify parameter attributes:

XML tag

Description

<name>

Enter the name of the parameter for referencing by the Custom Action script. By convention (not mandatory), the name value does not contain any spaces.

<prompt>

Enter the prompt displayed on the Custom Action window where the user enters a value for the parameter.

<type>

Set the type tag to text, password, menu, or integer. Other attributes are supported based on the type, as shown in the above table.

Important: If you choose menu as the type, do not specify the following tags: defaultValue, maxSize, minValue, maxValue, mask, and errorMessage.

<required>

Default is true. Set to true/false to specify if the parameter is required/optional.

<sortOrder>

Specify the order (integer) in which to display the parameter on the Custom Action window.

If a sort order is not specified, parameters are sorted alphabetically by the value set in the prompt tag.

<defaultValue>

Specify a default value for the parameter.

<maxSize>

When the type tag is set to text or password, specify the maximum size of the parameter (1-2000 characters). Default is 40 characters.

<mask>

When the type tag is set to text, you can specify a mask (in the form of a regular expression) for validating the text format. For example, this mask validates the mask parameter is in proper IPv4 address format:

d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}

<minValue>

When the type tag is set to is integer, you can specify a minimum value for validating the integer. (32 bit integer value).

<maxValue>

When the type tag is set to integer, you can specify a maximum value for validating the integer. (32 bit integer value).

<errorMessage>

When you use any type tag, if the validation fails you can specify the error message to display to the user.

For example, the following might represent an error message for an incorrectly formatted IP address:

Value must be an IP address in the format: nnn.nnn.nnn.nnn

<menuValues>

  <inline>

    <menuValue>

      <menuValue>

When the type tag is set to menu, you can enumerate the menu values inline in the XML.

<menuValues>

  <jdbc>

    <dbURL>

      <dbQuery>

When the type tag is set to menu, you can specify the menu values by querying an SQL database. Only the first selected column is used for the menu value. If the query fails, the menu displays an empty list. See the example in the Menu-based runtime parameter: menu options supplied in an SQL database section.

<menuValues>

  <file>

    <filename>      

When the type tag is set to menu, you can specify the menu values in a file. The file must be placed in the BCAN_DATA/endorsed directory. If the file is missing, the menu displays an empty list. The file must be line delimited to specify the menu options. See the example below.

Back to top

Example: Menu-based runtime parameter: menu options supplied inline

The custom action page displayed to the user contains a menu labeled What to Show, with menu options configuration and memory (in that order). Since the runtime parameter is set to required, the user must choose one of the two menu options. If the runtime parameter had been optional instead of required, the menu would have included a blank option to allow the user to make no selection.

<customDeviceCommandDeclaration>
  <name>Show Using Inline Menu Values</name>
  <guid>590FBB15-FB00-48AB-803A-9F928A7BAEFE</guid>
  <browserExecutable>true</browserExecutable>
  <inspectionOnly>true</inspectionOnly>
  <runtimeParameters>
    <runtimeParameter>
      <name>show</name>
      <prompt>What to Show</prompt>
      <type>menu</type>
      <required>true</required>
      <menuValues>
        <inline>
          <menuValue>configuration</menuValue>
          <menuValue>memory</menuValue>
        </inline>
      </menuValues>
    </runtimeParameter>
  </runtimeParameters>
</customDeviceCommandDeclaration>

<deviceCommand>
  <guid>590FBB15-FB00-48AB-803A-9F928A7BAEFE</guid> <!-- show -->
  <interaction>
    <prompt>%prompt%</prompt>
    <command>show %runtime.show%</command>
    <response>%prompt%</response>
    <error>Invalid input</error>
  <interaction>
</deviceCommand>

Back to top

Example: Menu-based runtime parameter: menu options supplied in a file

In this example, the custom action page displayed to the user will contain a menu labeled What to Show, with menu options that are specified in the ShowmenuOptions.txt file. The text file is located in the BCAN_DATA/endorsed directory. Since the runtime parameter is set to required, the user must choose from the presented options. If the runtime parameter had been optional instead of required, the menu would have included a blank option to allow the user to make no selection.

<customDeviceCommandDeclaration>
  <name>Show Using CSV Menu Values</name>
  <guid>590FBB15-FB00-48AB-803A-9F928A7BAEFE</guid>
  <browserExecutable>true</browserExecutable>
  <inspectionOnly>true</inspectionOnly>
  <runtimeParameters>
    <runtimeParameter>
      <name>show</name>
      <prompt>What to Show</prompt>
      <type>menu</type>
      <required>true</required>
      <menuValues>
        <file>
          <fileName>ShowMenuOptions.txt</fileName>
        </file>
      </menuValues>
    </runtimeParameter>
  </runtimeParameters>
</customDeviceCommandDeclaration>

<deviceCommand>
  <guid>590FBB15-FB00-48AB-803A-9F928A7BAEFE</guid> <!-- show -->
  <interaction>
    <prompt>%prompt%</prompt>
    <command>show %runtime.show%</command>
    <response>%prompt%</response>
    <error>Invalid input</error>
  </interaction>
</deviceCommand>

Note

  • The file named ShowMenuOptions.txt must be placed in the BCAN_DATA/endorsed directory.
  • If the file is missing, empty, or not readable by the web server, the menu displays an empty list.
  • The file must contain one menu option per line, in the order you want them to appear in the menu. For example:
    Menu Option 1
    Menu Option 2
    Menu Option 3

Back to top

Example: Menu-based runtime parameter: menu options supplied in an SQL database

In this example, the custom action page displayed to the user will include a menu with options derived from querying a database table.

In this example, the database requires a user name and password embedded in the HTTP query. The user name and password are encoded in the following form:

user=bcan&amp;password=mypassword

bcan represents the database user name and mypassword represents the actual password. The &amp; entity encodes the ampersand (&).

<customDeviceCommandDeclaration>
  <name>Show Using JDBC Menu Values</name>
  <guid>C296EB5E-69C2-42A3-AE42-964DE35AAD27</guid>
  <browserExecutable>true</browserExecutable>
  <inspectionOnly>true</inspectionOnly>
  <runtimeParameters>
    <runtimeParameter>
      <name>show</name>
      <prompt>What to Show</prompt>
      <type>menu</type>
      <required>true</required>
      <menuValues>
        <jdbc>
          <dbUrl>jdbc:postgresql://localhost:5432/bcan?user=bcan&amp;
          password=mypassword</dbUrl>
          <dbQuery>SELECT name FROM menu_data WHERE location = 'ATL'</dbQuery>
        </jdbc>
      </menuValues>
    </runtimeParameter>
  </runtimeParameters>
</customDeviceCommandDeclaration>

<deviceCommand>
  <guid>590FBB15-FB00-48AB-803A-9F928A7BAEFE</guid> <!-- show -->
  <interaction>
    <prompt>%prompt%</prompt>
    <command>show %runtime.show%</command>
    <response>%prompt%</response>
    <error>Invalid input</error>
  </interaction>
</deviceCommand>
  • Only the first selected column is used for the menu value.
  • The options in the menu will be displayed in the order the database server returns the rows. Include an order clause in the SQL statement to ensure a readable ordering.
  • If the query fails (for example, the database is unreachable, the query has a syntax error, or the query returns no rows), the menu displays an empty list.
  • Errors reaching the database, or in the query, will be reported in detail in the web server's log file.

Back to top

Example: Text-based runtime parameter: validating if a value exists for the parameter

If you do not specify a value for an optional runtime parameter in custom actions, the parameter does not exist. Therefore, to ensure that a runtime parameter actually has a value, check for -EXISTS- condition before you use the runtime parameter. Consider the following example in which the optional runtime parameter node is defined in the custom action:

<runtimeParameters>
  <runtimeParameter>                       
    <name>node</name>                                                           
    <prompt key="customAction.runtimeParameter.nodeIPAddress"/>
    <type>text</type>
    <required>false</required>
  </runtimeParameter>                             
</runtimeParameters>

<!--Use the following code snippet to check for -EXISTS- before
using the runtime parameter -->
<condition test="-EXISTS- runtime.node">
  <interaction>
    <prompt>%prompt%</prompt>
    <command>ping %runtime.node%</command>
    <response>%prompt%</response>
  </interaction>                         
</condition>

Back to top

Example: Text-based runtime parameter: setting maximum size

In this example, the custom action page displayed to the user will include a free-form text entry field labeled What to Show. The user can then enter up to ten characters in this field.

<customDeviceCommandDeclaration>
  <name>Show Using Text Field with Max Size</name>
  <guid>C296EB5E-69C2-42A3-AE42-964DE35AAD27</guid>
  <browserExecutable>true</browserExecutable>
  <inspectionOnly>true</inspectionOnly>
  <runtimeParameters>
    <runtimeParameter>
      <name>show</name>
      <prompt>What to Show</prompt>
      <customDeviceCommandDeclaration>
        <type>text</type>
        <required>true</required>
        <maxSize>10</maxSize>
    </runtimeParameter>
  </runtimeParameters>
</customDeviceCommandDeclaration>

<deviceCommand>
  <guid>C296EB5E-69C2-42A3-AE42-964DE35AAD27</guid> <!-- show -->
  <interaction>
    <prompt>%prompt%</prompt>
    <command>show %runtime.show%</command>
    <response>%prompt%</response>
    <error>Invalid input</error>
  </interaction>
</deviceCommand>

Back to top

Example: Text-based runtime parameter: validating input format

In this example, the custom action page displayed to the user includes a free-form text entry field labelled IP Address. The user can enter any text, but when the action is saved, the system validates whether it matches the format that is specified by the mask.

<customDeviceCommandDeclaration>
  <name>Ping Using Text Field with Mask and Error Message</name>
  <guid>5D9F2C80-01FA-42AB-A9B1-1ABE4FE90E97</guid>
  <browserExecutable>true</browserExecutable>
  <inspectionOnly>true</inspectionOnly>
  <runtimeParameters>
    <runtimeParameter>
      <name>ipAddress</name>
      <prompt>IP Address</prompt>
      <type>text</type>
      <required>true</required>
      <mask>\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}</mask>
      <errorMessage>Value must be an IP address in the format: nnn.nnn.nnn.nnn
</errorMessage>
    </runtimeParameter>
  </runtimeParameters>
</customDeviceCommandDeclaration>

<deviceCommand>
  <guid>5D9F2C80-01FA-42AB-A9B1-1ABE4FE90E97</guid> <!-- show -->
  <interaction>
  <prompt>%prompt%</prompt>
  <command>ping %runtime.ipAddress%</command>
  <response>%prompt%</response>
  <error>Invalid input</error>
  </interaction>
</deviceCommand>

Back to top

Example: Password runtime parameter: Sorting parameters on the user interface

In this example, the custom action page displayed to the user includes three text entry fields. These fields appear in the order specified by the sortOrder tags.

<customDeviceCommandDeclaration>
  <name>Set Local Password (CatOS)</name>
  <guid>958DF9D3-DA5D-4791-958A-B92F91F7F787</guid>
  <browserExecutable>true</browserExecutable>
  <inspectionOnly>false</inspectionOnly>
  <runtimeParameters>
    <runtimeParameter>
      <name>oldPassword</name>
      <prompt>Old Password</prompt>
      <type>password</type>
      <required>true</required>
      <sortOrder>1</sortOrder>
    </runtimeParameter>
    <runtimeParameter>
      <name>newPassword</name>
      <prompt>New Password</prompt>
      <type>password</type>
      <required>true</required>
      <sortOrder>2</sortOrder>
    </runtimeParameter>
    <runtimeParameter>
      <name>confirmPassword</name>
      <prompt>Confirm New Password</prompt>
      <type>password</type>
      <required>true</required>
      <sortOrder>3</sortOrder>
    </runtimeParameter>
  </runtimeParameters>
</customDeviceCommandDeclaration>

<deviceCommand>
  <guid>958DF9D3-DA5D-4791-958A-B92F91F7F787</guid>
<!-- set local password -->
  <interaction>
    <prompt>%prompt%</prompt>
    <command>set password</command>
    <response>Enter old password:</response>
    <error>Unknown command</error>
    <error>Usage:</error>
  </interaction>
  <interaction>
    <prompt>Enter old password:</prompt>
    <command>%runtime.oldPassword%</command>
    <response>Enter new password:</response>
    <error>Sorry password incorrect</error>
  </interaction>
  <interaction>
    <prompt>Enter new password:</prompt>
    <command>%runtime.newPassword%</command>
    <response>Retype new password:</response>
  </interaction>
  <interaction>
    <prompt>Retype new password:</prompt>
    <command>%runtime.confirmPassword%</command>
    <response>%prompt%</response>
    <error>Mismatch - password unchanged</error>
  </interaction>
</deviceCommand>

Back to top

 

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