Manage Add-ons

Add-ons

An add-on is a customizable Cisco Crosswork Planning component that

  • extends the Cisco Crosswork Planning Design UI functionality, enabling you to meet your specific needs

  • allows you to run the scripts like any other tools and view generated output plan files and reports, and

  • enhances Cisco Crosswork Planning with additional features and integrations that are not included in the base installation.

Add-ons can invoke Python executable scripts that can modify the network models. These scripts are executed as an asynchronous job and you can view the results in Cisco Crosswork Planning Design.

Requirements and limitations for add-on configuration

Ensure you adhere to these requirements and limitations while configuring add-ons.

  • You can enable a maximum of 15 add-ons at a time for each user.

  • Only Python scripts are supported for add-ons.

  • You must migrate the existing Cisco WAE add-on scripts to Python3.

  • Add-on scripts must be compatible with the provided Python libraries. Installing additional libraries is not supported.

  • All add-on scripts run using the design_api_python binary. Executing them within other Python wrapper is not supported.

  • You can import add-ons from other systems, such as Cisco WAE, if they meet the requirements described.

User role permissions for add-ons

On the Manage Add-ons page of Cisco Crosswork Planning:

  • Any user can create, view, and enable any add-on.

  • Only the creator of the add-on or a user with the "CW Planning Design Settings APIs" role permission can edit or delete it.

This table shows which actions users can perform on add-ons.

Action

Any user

Add-on creator

User with the "CW Planning Design Settings APIs" role permission

Create add-ons

View add-ons

Enable add-ons

Edit add-ons

Delete add-ons

Create add-ons

This topic describes how to add a new customizable add-on to automate or enhance tasks in Cisco Crosswork Planning Design.

Use this process to create an add-on for use within the system, supplying your own script and customizing the UI.

Before you begin

Review the requirements in Requirements and limitations for add-on configuration.

Procedure

Step 1

Open the Manage Add-ons page using one of these options:

  • On the Network Design page, click Manage add-ons.

  • From the toolbar, select Actions > Add-ons > Manage add-ons.

Step 2

Click Add icon to open the Add-on Settings page.

Step 3

Enter the basic details.

  1. Enter the name of the add-on.

  2. In File, upload the compressed file containing your add-on script.

  3. In Specify executable, enter the name of the add-on script file within the uploaded zip folder that will be executed when the add-on runs.

  4. Click Proceed to form builder.

    The Form Builder page opens.

Step 4

(Optional) To make any changes to the add-on name, executable name, or description, click Edit in the Add-on settings section.

Note

 

You cannot upload a different add-on file using this option.

Step 5

On the Form Builder page, drag the required component from the left pane to the main area. Configure the steps and input controls for your add-on’s user interface. For descriptions of all the fields, see Add-on controls.

  1. Use the Step element to create new pages. Click to rename the label of the page.

  2. Use the Section element to create new sections in a page. Click to rename the label of your section.

  3. Use the elements under the Fields section to configure the required fields. Click to specify name, label, default values, or limitations for your fields.

Step 6

Ensure that each configured field meets the minimum required settings. The fields must display . If you have not met the requirements, an alert () appears. In this situation, click and specify the required fields.

Step 7

Click Preview to preview the add-on configuration. Verify all the details you configured.

Step 8

When you are satisfied with the changes, click Back to editor at the top to go back to the Form Builder page.

Step 9

Click Create add-on to create the add-on.

The new add-on appears on the Manage Add-ons page and is ready for use.

Add-on controls

This topic describes the fields you can use while configuring add-ons.

Table 1. Add-on controls

Field

Description

Step (new page)

Creates new pages.

Section

Groups fields together that are created within a step (page).

Field

Type of field.

  • Text Box: Text field.

  • Number: Numeric value. Supported format includes both whole and decimal numbers.

  • Dropdown: Selection of items to appear in a drop-down menu.

  • Check Box: Toggle entry. If selected, it is true and if not selected, it is false.

  • Table Selection: Select objects in a specified table. The selected objects are written to a file and then passed to the script.

    For example, if you select Circuits in the Select Table field, you need to select the required circuit objects while running the add-on.

  • Table Entry: Select a table column in a specified table.

  • File: Select a file. You can browse with a browse button to a different directory. The complete path is passed to the script.

  • Password: Text string. Characters entered are hidden. This field is used to pass sensitive text to script.

Run an add-on on a plan file

This topic describes how to execute a selected add-on on a plan file to generate required outputs or reports.

Before you begin

  • Ensure the required add-on is available and enabled on the Manage Add-ons page.

  • You can enable a maximum of 15 add-ons for each user.

Procedure

Step 1

Enable the required add-on from the Manage Add-ons page.

  1. Select the add-on on the Manage Add-ons page.

  2. Click More actions > Enable add-on.

The enabled add-on appears under the Actions > Add-ons menu on the visualization toolbar in the Network Design page.

Step 2

Select the enabled add-on from the Actions > Add-ons menu on the Network Design page.

Step 3

Enter the required input fields as defined by the add-on controls.

Step 4

On the Run Settings page, enter a job name and schedule when to run the add-on.

Optionally, set these options:

  • Priority: Select the priority of the task.

  • Engine profiles: Select the engine profile as needed. This section lists all available asynchronous engine profiles.

  • Schedule: Set the time at which you want to run the tool.

Note

 
Ensure that you save the plan file before you schedule the job. Any unsaved changes in the plan file are ignored when you run the tool as a scheduled job.

Step 5

Submit the job.

The add-on runs at the scheduled time using the selected engine profile. You can track the job status on the Job Manager page (from the main menu, choose Job Manager).

Step 6

Once the job completes, import the output plan file into user space to visualize it. For more information, refer to Access output plan files from Job Manager.

Step 7

(Optional) Access the generated report to view the changes caused by the add-on.

  1. Open the newly imported plan file in the Network Design page.

  2. From the toolbar, click Actions > Reports > Generated reports.

  3. Click the name of the add-on to view the summary and details of the changes.

Import an add-on

This topic describes how to import an existing add-on to your Cisco Crosswork Planning Design application.

Use this procedure when you have an add-on that was created in a different Cisco Crosswork Planning system or the Cisco WAE Design application.

Before you begin

  • Ensure that the add-on package is a .tar file.

  • Ensure that the add-on package contains the addon.json file if the add-on was created with Cisco Crosswork Planning, or the addon.txt file if it was created with Cisco WAE.

Procedure

Step 1

Open the Manage Add-ons page using one of these options:

  • On the Network Design page, click Manage add-ons at the top right.

  • From the toolbar, select Actions > Add-ons > Manage add-ons.

Step 2

Click to open the Add-on Settings page.

Step 3

Click Browse and select the add-on package file.

Step 4

Click Generate form to import the add-on.

Step 5

Configure or update any fields or options as needed. For descriptions of all the fields, see Add-on controls.

Step 6

Click Create add-on.

The imported add-on is available on the Manage Add-ons page and is ready for use.

Export an add-on

This topic describes how to export add-ons and their configurations from the Cisco Crosswork Planning Design application.

Use this procedure to move add-ons between Cisco Crosswork Planning instances. First, export the add-on, then import it into another instance.

Procedure

Step 1

Open the Manage Add-ons page using one of these options:

  • On the Network Design page, click Manage add-ons at the top right.

  • From the toolbar, select Actions > Add-ons > Manage add-ons.

Step 2

Select the add-on you want to export and click More actions > Export.

Step 3

Save the package containing the add-on configurations and scripts.

The selected add-on is exported to your local machine and is available for use.

What to do next

To use this add-on in another Cisco Crosswork Planning instance, log in to that instance and follow the steps in Import an add-on.

Edit an add-on

This topic describes how to modify user interface or input controls of an existing add-on.

Procedure

Step 1

Open the Manage Add-ons page using one of these options:

  • On the Network Design page, click Manage add-ons at the top right.

  • From the toolbar, select Actions > Add-ons > Manage add-ons.

Step 2

To use a different add-on file, select the add-on you want to edit and click More actions > Update add-on file. Then, upload the new add-on file.

Step 3

To modify any UI controls, select the add-on you want to edit and click Edit.

  1. Update UI controls, default values, or other UI-related properties as needed. For descriptions of all the fields, see Add-on controls.

  2. Ensure that each configured field meets the minimum required settings. The fields must display . If you have not met the requirements, an alert () appears. In this situation, click and specify the required fields.

  3. Click Preview to preview the add-on configuration. Verify all the details you configured.

  4. When you are satisfied with the changes, click Back to editor at the top to go back to the Form Builder page.

  5. Click Save add-on to save the changes.

Sample add-on

Cisco Crosswork Planning includes a Sample Addon on the Manage Add-ons page. This add-on updates the description of the selected interfaces to "sample description". The Sample Add-on is provided to serve as a practical example, allowing you to explore and better understand how add-ons function within Cisco Crosswork Planning. By experimenting with the Sample Add-on, you can safely familiarize themselves with the process of configuring and managing add-ons.

When you run this add-on, Cisco Crosswork Planning performs these actions.

  • An output plan file named "sample-addon-output-planfile.txt" is generated.

  • In the newly created plan file, the description of each interface you selected while executing the add-on is updated to "sample description".

  • A report named "Sample Addon" is generated. This report includes two sections: Summary and UpdatedInterfaces.

    • The Summary section displays the number of interfaces updated with a new description.

    • The UpdatedInterfaces section lists the interfaces whose descriptions have been updated.