Get Started

This section contains the key workflows and an overview of Change Automation and Health Insights dashboard:

Getting Started with Change Automation

This procedure covers the initial setup of the application post installation of the Change Automation and Health Insights applications. For more information, see the Cisco Crosswork Network Controller Installation Guide.

Change Automation can be used independently or as part of workflows that leverage Health Insights or other applications. In this procedure, we will present workflows that demonstrate some of these capabilities to illustrate the flexibility of the Crosswork solution. You can use these concepts and examples to build a virtually unlimited combination of tools to meet your operational needs.

Before you begin:

Configure Change Automation Settings

Configuring Change Automation settings is a post-installation activity and is the first task to be performed after installing Change Automation. This section explains the initial settings that must be configured before you can start using Change Automation.

As you configure Change Automation settings, remember that Crosswork provides several ways to run Playbooks.

  • Manually ("on demand") or via scheduled execution. These two methods are typically used for Playbooks that accomplish data collection, configuration changes, or SMU deployment independent of any KPI-related fault detected in the network.

  • Manually or automatically when the Playbook is tied to a KPI. These methods are typically used when you want to run a Playbook intended to remediate a fault detected in the network. Key parameters needed to run the Playbook are populated when the alert tied to the KPI is triggered.


Note

The Change Automation settings can only be configured once. If you want to modify the settings, Change Automation must be re-installed. Before re-installing, export any Plays or Playbooks you have created, and after re-installing, import them. For more information, see Export Plays, Import Custom Plays, Export Playbooks, and Import Playbooks.

System Settings

After you install Change Automation, check that you can access the Change Automation application from the main menu: Go to Network Automation > Dashboard. Crosswork displays the Change Automation window, prompting you to complete the Change Automation application's configuration.

Once initial setup is done, navigate to Administration > Settings > System Settings > Network Automation > Device Override Credentials to review the Change Automation settings:

  • Playbook Job Scheduling: Enable or disable the ability to schedule Playbook jobs.

  • Credential Prompt: If enabled, users will be prompted to enter the credentials (device override credentials) before each Playbook execution. If disabled, you must create the relevant credential profile and provider settings for the override credentials to work. Follow the prompts on the window to meet each requirement.

    As you make these changes, please note the following special considerations:

    • If you want to enable automatic Playbook execution, you must ensure that Playbook Job Scheduling is enabled and that Credential Prompt is disabled. For more guidance, see Enable Automatic Playbook Execution.

    • If Credential Prompt is enabled: While executing Device Config plays, entering incorrect device override credentials will cause the playbook execution to fail. However, for a Check play or Data Collection play, the device override credentials are not validated and the Playbook will execute successfully irrespective of their accuracy.

    • If Credential Prompt is disabled: Only user IDs with write permissions for Administration APIs under Change Automation can complete the credential profile and provider setup tasks. If you are unsure if your user ID has the required privileges, you can check by selecting Administration > Users and Roles > Roles and inspecting the ID's privileges.

    • If Playbook Job Scheduling is disabled, the Credential Prompt is enabled by default. You cannot disable the credential prompt if you disable Playbook job scheduling.

  • Click Save after you configure the above settings.

Enable Automatic Playbook Execution

In addition to running KPI-linked Playbooks manually, at the network operator's discretion, Change Automation and Health Insights permits you to run one or more of your KPI-linked Playbooks automatically whenever the KPI linked to that Playbook raises an alert of sufficient severity.

To enable this option, Playbook Job Scheduling must be enabled, and Credential Prompt must be disabled. As noted above, you must have Crosswork system administrator privileges to change these settings.


Warning

Once these settings are saved, changes cannot be made unless you first use the Crosswork Manager to uninstall and then reinstall both the Change Automation and Health Insights applications.

  1. From the main menu, choose Administration > Settings > System Settings > Network Automation > Device Override Credentials. The Device Override Credentials page opens.

  2. Under Playbook Job Scheduling, click the Enabled button. Under Credential Prompt click the Disabled radio button.

    When you are finished, the window should look like the illustration below.

    Figure 1. System Settings
    System Settings

  3. Click Save to commit to these settings.

Assign Change Automation User Access Levels

Once the Change Automation system settings are completed, an admin user must review other user roles to ensure that all the users who need them have the proper level of access to run, import, and create Plays and Playbooks. Only users with write permissions for Administration APIs can disable or enable Playbook execution access and assign labels.

To provide this access, the admin user must:

  1. Go to Administration > Users and Roles > Roles.

  2. Under the Roles pane, select the role to which you want to grant access.

  3. In the right panel, under Global API Permissions, enable Read and Write check boxes (as necessary) for Play APIs and Playbook APIs under Change Automation.

    Figure 2. Global API Permissions
    Global API Permissions

Using Change Automation

The following table describes the steps to start using the Change Automation application once you have configured the Change Automation settings.

Table 1. Getting started with Change Automation
Workflow Action

1. Run the Playbooks manually with the available Playbooks.

See About Running Playbooks

2. Schedule Playbooks to perform routine maintenance.

See Schedule Playbooks

3. If any existing Plays or Playbooks do not meet the requirements fully or partially, build new Plays or Playbooks with new or existing Plays, as necessary.

See Develop Custom Playbooks

4. Link a Playbook to a Health Insights triggered KPIs

See Closed-Loop Automation

Schedule Playbooks

The workflow below describes the steps to follow when using Change Automation to automate routine network tasks and verify that each routine change is completed correctly.


Note

This workflow is applicable only if scheduling is enabled in the Change Automation settings. For more information, see Configure Change Automation Settings.

Step Action

1. Identify routine maintenance tasks (such as throughput checks, software upgrades, SMU installs, and so on) that you perform on a regular schedule, and that may be suitable for automation using one or more Change Automation Playbooks.

See About Running Playbooks and View the Playbook List.

2. Configure Playbooks to perform these tasks at the desired time.

See About Running Playbooks and Schedule Playbook Runs.

3. Review the Change Automation Job History to review the current status of the Playbook. If the job fails, the details will be available.

See Use the Change Automation Dashboard and View or Abort Playbook Jobs.

Develop Custom Playbooks

The following workflow describes the steps to follow when developing a Change Automation custom Play or Playbook.

Step Action

1. Review the existing Plays and Playbooks to see if they fully or partially meet your needs.

From the main menu, choose Network Automation > Play List or Playbook List.

2. If required, build new plays and then a new Playbook with new or existing Plays, as necessary, to meet your requirements.

See About Custom Plays and About Customizing Playbooks.

3. For a Playbook you have developed that meets your needs, you can optionally:

  • Link to a KPI for manual or automated execution.

  • Schedule the playbook to run automatically.

  • Manually run the playbook as needed.

See:

Getting Started with Health Insights

Before you begin:

Make sure to confirm if the Yang modules we have provided include the data point you want to evaluate. If yes, then review whether the available KPI templates are adequate to evaluate the data point.

If the Yang module has the data you need and we have an existing KPI, you can create a new KPI profile.

If the Yang module has the data that you need and doesn't have an existing KPI, then you can build a new KPI.

Build a new KPI based on the below requirements:

  • If the data you want to gather can be collected or evaluated using one of the four templates we provide, then build the KPI.

  • If the data you want to gather can not be collected or evaluated using one of the four templates we provide, then build a new KPI with the tools available in the developer network (developer.cisco.com).

In the instance, if the module does not include the data point that you need, you have to get the new Yang module and load it on the data collection UI and then you can build KPI.

The following table describes the steps to get started with Health Insights application.

Table 2. Getting started with Health Insights

Workflow

 Actions

1. Create KPI Profiles to monitor device Key Performance Indicators (KPIs) for issues and anomalies.

See Monitor Key Performance Indicators

2. Enable KPI profiles for the devices.

See Enable KPI Profiles on Devices

3. Make sure that the collections are provisioned on the device (MDT collections).

See Verify the Deployment Status of Enabled KPIs

4. Make sure collections are gathering data.

Monitor Key Performance Indicators

Once you have completed the initial setup, use Health Insights to begin device performance monitoring using KPI Profiles.

Step Action

1. (Optional) Tag all the devices whose KPIs you plan to monitor with a tag indicating the function they perform, per your plan.

See Manage Tags in the Cisco Crosswork Network Controller Administration Guide.

2. Plan which Cisco-supplied KPIs you want to begin using based on each device's function and the device performance characteristics you want to monitor.

See List of Health Insights KPIs.

To create a new KPI that fits your requirements, see Create a New KPI.

3. Based on your experience or by using the recommendation engine, group the KPIs to form KPI Profiles.

See Create a New KPI Profile.

4. Enable the appropriate KPI Profiles on the devices you want to monitor.

See Enable KPI Profiles on Devices.

Develop Custom KPIs

The following workflow describes the steps to follow when considering whether or not to develop Health Insights custom KPIs for your special needs and how to proceed if you decide to do so.

Step Action

1. Review the existing KPIs to ensure the telemetry you want to monitor is not already available.

See List of Health Insights KPIs.

2. Review the data available from the devices you want to monitor to see if they can supply the needed information:

  • If they can, proceed with building a custom KPI.

  • If they cannot, we must load a new Yang module.

See Create a New KPI.

3. Determine if the Yang module we have provided includes the data point you wish to evaluate. If it does, determine whether one of the available KPI templates can evaluate it. If it can, proceed with building a new KPI.

If not, you must build the KPI with the tools available in the dev network (developer.cisco.com) and then import it into Crosswork. Once you import the KPI, you can add it to your profile.

If the module does not include the data point you need, you have to get the new Yang module and load it on the data collection UI, and then you can build the KPI.

4. Build the custom KPI and add it to a KPI Profile.

See Create a New KPI and Create a New KPI Profile.

5. Enable the new KPI Profile on a test device.

See Enable KPI Profiles on Devices.

6. Confirm that collections are working.

7. Confirm that the data reported matches your expectations and, if necessary, investigate the alarms raised by the new KPI. Be aware that KPIs that depend on data over time to establish baseline performance will need some time to establish a baseline before they provide meaningful data.

See View Alerts for Network Devices.

8. If the KPI Profile meets expectations, enable it on all devices where applicable.

Warning

 

When enabling KPI profiles on many devices, ensure that sufficient capacity is available on Cisco Crosswork Data Gateway. If adequate capacity is not available and if you enable the KPI profiles on a large number of devices, it may cause overload and outage. To check Cisco Crosswork Data Gateway load, see Health Insights CDG load calculator at Cisco Crosswork Network Automation APIs.

Follow the steps in Enable KPI Profiles on Devices.

9. Make sure the KPI Profile was deployed on the device (MDT only) and that the collection jobs are functioning.

See Verify the Deployment Status of Enabled KPIs.

Closed-Loop Automation

The following workflow describes the steps to follow when using Health Insights to run a remediation Playbook from Change Automation in response to the performance challenges detected in the network by a KPI. A remediation Playbook can be:

  • Linked to a KPI, alerting the operator to run the Playbook and make the remediation easier.

  • Linked to a KPI and selected for automatic execution without operator intervention.

Step Action

1. Research the KPIs that are triggering alerts and determine the best corrective action to take for the situation your network has experienced.

Follow the instructions in Monitor Network Health and KPIs, using the View Alerts for Network Devices to research the alerts and their possible causes.

2. Review the plays and Playbooks to determine which will best address the alerting KPI.

For example:

  • Look for an existing Playbook that could resolve the issue.

  • Look for existing plays that could be combined to resolve the issue. Create a new Playbook with those plays.

Review the list of Plays, Playbooks, and generic parameters in the "Playbooks" and "Plays" references in the Change Automation Developer Guide on Cisco Devnet.

See Create a Custom Play Using Templates and Create a Custom Playbook Through the UI.

3. Try out the selected Playbooks and see if they are applicable to your purposes. As you experiment, adjust the Playbook parameters as needed.

See:

Perform a Dry Run of a Playbook

Run Playbooks In Single Stepping Mode

Run Playbooks In Continuous Mode

4. If required, build new plays and then build new playbooks with the combination of plays needed to make the desired change(s) to the network.

See Create a Custom Play Using Templates and Create a Custom Playbook Through the UI.

5. (Optional) For frequently triggered KPIs with a known remediation Playbook, link the Playbook to the KPI to make executing the Playbook easier for the operator.

Follow the steps for linking and triggering Playbook runs under operator control in Link KPIs to Playbooks and Run Them Manually. Use the Remediation icon shown in View Alerts for Network Devices to trigger a run of a linked Playbook from a device or KPI alert.

6. (Optional) For frequently triggered KPIs with a known remediation Playbook and no danger of runaway execution, link the Playbook to the KPI and set it to run automatically.

Follow the steps in Link KPIs to Playbooks and Run Them Automatically to trigger an automatic run of a linked Playbook upon receipt of a device or KPI alert.