.. _command-builders-overview: Command builders ----------------- .. tip:: :ref:`use-action-search-to-navigate-automate` Overview ......... You can build a repository of IOS commands to be run when certain events occur, such as adding an IOS device. Each set of IOS commands and associated event is known as a *command builder*. For a list of events with default set of IOS commands and available variables, see *Local Break Out and Analog Gateway Events, IOS Commands, and Variables*. The default command builders exist at the ``sys.hcs`` hierarchy level. You can define customized command builders at any hierarchy node. When an event occurs, command builders nearest (at or above) the hierarchy node of the event are checked first. For instance, if an event occurs at a customer hierarchy level, command builders at the customer level are checked before command builders at the provider or sys.hcs level. Command builders at a higher level are checked only if no builders match at a nearer hierarchy level. If no customized command builders are defined, the default command builders at sys.hcs are checked. Multiple command builders may be run for the same event at the same hierarchy node. .. _set-up-a-command-builder: Set up a command builder .......................... This procedure sets up a command builder that contains an IOS commands template for an event. .. note:: One event can trigger multiple command builders. 1. Log in as provider, reseller, or customer administrator. 2. Set the hierarchy path to the level where you want to define your command builder. 3. Go to **Command Builder**, then click the Plus icon (+) to add a new record. 4. Configure the following - the table describes the options: .. tabularcolumns:: |p{3.5cm}|p{12cm}| +------------------------+------------------------------------------+ | Field | Description | +========================+==========================================+ | Name | Enter a unique name for the builder. | | | This field is mandatory. | +------------------------+------------------------------------------+ | Event Name | Select the event that triggers the | | | builder. This field is mandatory | +------------------------+------------------------------------------+ | Description | Enter a description for the builder. | +------------------------+------------------------------------------+ | | Enter the IOS Commands template for the | | Command Template | event, one command per line. You can use | | | macros in the IOS Commands template for | | | variable substitution. | +------------------------+------------------------------------------+ | | Clear the **Enabled** check box to create| | Enabled | a builder but not have it available to | | | run. | +------------------------+------------------------------------------+ | Applicable Device Type | Select the device type that the commands | | | can run on. This field is mandatory. | +------------------------+------------------------------------------+ 6. Click **Save**. .. _clone-a-command-builder: Clone a command builder ........................ This procedure clones (copies) a command builder that contains an IOS commands template for an event. For instance, use this procedure to modify one of the default command builders to suit your needs. .. note:: One event can trigger multiple command builders. 1. Log in as provider, reseller, or customer administrator. 2. Set the hierarchy path to the level where you want to clone an existing Command Builder. 3. Go to **Command Builder**. 4. Select the name of the command builder name you wish to clone. 5. Choose **Action > Clone**. 6. Modify the following information as needed: .. tabularcolumns:: |p{3.5cm}|p{12cm}| +------------------------+------------------------------------------+ | Field | Description | +========================+==========================================+ | Name | Enter a unique name for the builder. | | | This field is mandatory. | +------------------------+------------------------------------------+ | Event Name | Select the event that triggers the | | | builder. This field is mandatory | +------------------------+------------------------------------------+ | Description | Enter a description for the builder. | +------------------------+------------------------------------------+ | | Enter the IOS Commands template for the | | Command Template | event, one command per line. You can use | | | macros in the IOS Commands template for | | | variable substitution. | +------------------------+------------------------------------------+ | | Clear the **Enabled** check box to create| | Enabled | a builder but not have it available to | | | run. | +------------------------+------------------------------------------+ | Applicable Device Type | Select the device type that the commands | | | can run on. This field is mandatory. | +------------------------+------------------------------------------+ 7. Click **Save**. .. _view-ios-commands-log: View IOS commands log ....................... Using the IOS Commands log, an administrator can see a list of command sets that were triggered by different events. An administrator can copy the IOS Commands template and paste it into the IOS device CLI to be executed. By default, the command sets are listed with the most recent at the top. .. note:: Deleting a hierarchy node, such as a site, deletes all IOS Command Builders and associated IOS Commands templates configured at the hierarchy node. 1. Log in as provider, reseller, or customer administrator. 2. Set the hierarchy path to the level for which you want to view IOS Commands. 3. Go to the **Commands** page. 4. View the table the command builders that have been triggered. The table contains the following information: .. tabularcolumns:: |p{4cm}|p{11cm}| +-----------------+--------------------------------------------------+ | Column | Description | +=================+==================================================+ | Timestamp | The time of the event that triggered the Command | | | Builder. | +-----------------+--------------------------------------------------+ | Device Name | The IOS device associated with the event that | | | fired the Command Builder. | +-----------------+--------------------------------------------------+ | Gateway Name | The SIP Local Gateway or Analog Gateway | | | associated with the event that fired the Command | | | Builder. | +-----------------+--------------------------------------------------+ | | The name of the Command Builder that was | | | triggered. | | | | | Command Builder | To view the IOS Commands template associated | | | with a Command Builder, click the Command | | | Builder name. The Command Builder configuration | | | is displayed, including the IOS Commands | | | template. | +-----------------+--------------------------------------------------+ | Description | The description of the Command Builder that was | | | triggered. | +-----------------+--------------------------------------------------+ | Device Deleted | Select this check box if the associated device | | | has been deleted. | +-----------------+--------------------------------------------------+ | Hierarchy | The hierarchy level of the event that triggered | | | the Command Builder. | +-----------------+--------------------------------------------------+ .. _consolidate-ios-commands: Consolidate IOS commands ......................... To copy IOS commands to an IOS device CLI that is generated by multiple events, follow these steps: .. rubric:: Copy IOS commands 1. Log in as provider, reseller, or customer administrator. #. Set the hierarchy path to the customer or site for which you want to consolidate IOS commands. #. Go to **Consolidate Commands**. #. Click the Plus icon (+) to add a new record. #. On the **Consolidate Commands** page, fill out at minimum the mandatory configuration. See :ref:`consolidate-commands-fields`. #. Click the required command templates listed in the **Available** list, and click **Select** to move them to the **Selected** list. Click **Remove** to unselect a command template. .. note:: You can change the order of the command templates by clicking **Move Up** and **Move Down**. However, the consolidated commands are generated in chronological order regardless of the order of the selected command templates. #. Click **Save**. The new command consolidation instance appears in the list. #. Click the command consolidation instance you created. In the **Command Template** field, all the commands from the command templates you selected appear in one window. Comments are used to separate and identify the source command templates. You can edit the consolidated commands. Any modifications to the Command consolidation, displays the entire list of commands in a single instance. The commands present earlier to the modification cannot be viewed separately as the commands from the earlier events are treated as a single instance. .. rubric:: Next steps After you have consolidated the IOS commands you want, copy them from the Commands Template field to the IOS device CLI. .. _consolidate-commands-fields: Consolidate commands settings '''''''''''''''''''''''''''''' .. tabularcolumns:: |p{3.5cm}|p{12cm}| +---------------+----------------------------------------------------+ | Field | Description | +===============+====================================================+ | Name \* | Enter a unique name for the command consolidation. | | | This field is mandatory. | +---------------+----------------------------------------------------+ | Description | Enter an optional description for the command | | | consolidation. | +---------------+----------------------------------------------------+ | IOS Device \* | Choose the IOS device from which you want to | | | consolidate commands. | +---------------+----------------------------------------------------+ | | Choose the device types for which you want to | | | consolidate commands. | | | | | | **IOS Device** | | | | | | Choose this to get commands for the IOS device | | Device Type \*| and any SIP Local Gateway or Analog Gateway hosted | | | on that device. | | | | | | **SIP Local Gateway** | | | | | | Choose this to get commands only for the SIP Local | | | Gateway. | | | | | | **Analog Gateway** | | | | | | Choose this to get commands only for the Analog | | | Gateway. | | | | | | You do not get commands for devices that have been | | | deleted. | | | | | | Note: | | | | | | If you select site hierarchy, only specific | | | commands such as IOS Device or SIP Local gateway | | | are displayed. To view both the IOS and Analog | | | gateway commands, choose the customer hierarchy | | | path. | +---------------+----------------------------------------------------+ .. _regenerate-ios-commands: Regenerate IOS commands ........................ This procedure regenerates IOS commands for events that occurred for the selected device, and removes all old IOS commands for the selected device. .. note:: Since the variables used in generating IOS commands may change, you may want to regenerate IOS commands with the latest configuration. IOS commands can be regenerated for the following devices: * IOS Device * SIP Local gateway * Analog Gateway Regenerating commands for an IOS Device also regenerates commands for any SIP Local gateway or Analog Gateway hosted on the IOS Device. 1. Log in as provider, reseller, or customer administrator. 2. Choose one of the following options, depending on the device for which you want to regenerate IOS commands: * Go to **IOS Devices** for an IOS device and any gateways it hosts. * Go to **SIP Local Gateways** for a SIP local gateway. * Go to **Analog Gateways** for an analog gateway. 3. Click the device for which you want to regenerate commands. 4. Choose **Action > Regenerate IOS Commands**. IOS commands for the events that had occurred for the selected device are regenerated. All old IOS commands for the selected device are removed. .. rubric:: Next steps * View the regenerated commands in the IOS Commands log. See :ref:`view-ios-commands-log`.