Developer Toolkit GUI

About developer toolkit

The Catalyst Center platform provides you with these software developer tools to access and program with Catalyst Center, as well as to integrate Catalyst Center with other applications:

  • APIs: Available APIs organized within categories by functionality (for example, Operational Tasks or Site Management APIs).

  • Integration Flows: Available integration flows organized by category type.

  • Event Notifications: Lets you view and subscribe to specific events that may occur in your network.

Work with APIs

Follow this procedure to review available APIs, generate example code for using the APIs, and try out the APIs interactively on the Catalyst Center platform.

The Catalyst Center GUI displays documentation about each API call, including the request method and URL, query parameters, request header parameters, responses, and schema, and ways to preview or test the request.

For detailed information about the APIs, see the Cisco Catalyst Center APIs on Cisco DevNet.

Before you begin

  • Ensure that you have met the supported programming language and authentication prerequisites, as described in the previous section. For more information, see API prerequisites.

  • You must first enable the Rogue and aWIPS bundle to view these specific APIs. From the main menu, choose Platform > Manage > Bundles > Rogue and aWIPS > Enable. After enabling this bundle, you can view the APIs within the bundle under the Contents tab, or choose Platform > Developer Toolkit > APIs > Know Your Network > Devices.

Procedure

Step 1

From the main menu, choose Platform > Developer Toolkit > APIs.

Step 2

Review the list of supported APIs.

If necessary, click the > icon to display the API subdomains.

Step 3

Select the domain or subdomain to view the APIs.

This information about each API under that appears in columns:

  • Method: Supported methods include GET, POST, PUT, and DELETE.

  • Name: Link to access the slide-in pane and additional information, including description, features, tags, parameters, responses, model schemas, and so on. A Sunset, Deprecated or an Intent banner indicates status of the API. For more information about the API Lifecycle, see Cisco Catalyst Center APIs on DevNet.

  • Description: Brief description of the API.

  • URL: URL value for the API.

  • Actions: Create a code preview snippet with the Try option.

Note

 

A blue color-coded message may appear, stating that the specific API configuration is still in progress and to check back at a later time. The screen auto refreshes when the API is registered and you may proceed with your API activity. In the highly unlikely event that a red color-coded message appears stating that the API cannot be configured, contact your Catalyst Center administrator to contact Cisco for assistance in resolving the issue.

Step 4

Click the name (link) of an API method.

This information about the API method appears:

  • DESCRIPTION: Brief description of the API operation.

  • TAGS: API identifiers, including where and under what circumstances you would use the API. Note that some APIs may not have tags.

  • PARAMETERS: Parameters of API, including description, data type (Boolean or string), default value, and required value.

  • FEATURES: Objective of the API operation, information related to the Deprecated or Beta status of the API operation, and details of the alternative API operation.

  • RESPONSES: Possible HTTP responses. Schema presents response as a data model (Model tab) or JSON format of the actual response (Model Schema tab). Click Sample to view the sample code.

  • POLICIES: An API rate limiting feature, where policies are applied to certain APIs. These policies set the number of API calls per time interval per client IP address.

Step 5

(Optional) Generate a code preview by clicking Code Preview.

Note

 

If you are creating your own program, you can cut and paste the code preview sample into your own program.

Step 6

(Optional) In the Code Preview window, select a language from the drop-down to generate the code.

These languages are supported:

  • Shell

  • Node - HTTP

  • Node - Unirest

  • Node - Request

  • Python

  • Ruby

  • JavaScript

  • JQuery

  • PHP

  • Go

  • Ansible

After reviewing or copying the code preview sample for use, click Close.

Step 7

(Optional) Try the method by clicking Try.

Step 8

(Optional) In the Try window, fill in the requested values (for example, URL address or value) and click Run.

After reviewing the response and/or error code, click Close.

When Catalyst Center returns a 202 (Accepted) HTTP status code, the result body includes a task ID and a URL that you can use to query for more information about the asynchronous task that your original request spawned. For example, you can use this information to determine whether a lengthy task has completed.

Note

 

The response is a live response from Catalyst Center itself, and the results reflect the actual state of your network. In contrast, the code previews are static and contain placeholders for values that you must supply.

Work with integration flows

An integration flow defines the interaction between Catalyst Center platform and a third-party system, such as an ITSM system that is used to track, troubleshoot, and resolve network issues.

Catalyst Center platform supports schedule-based integration flows. This type of integration flow runs on a schedule, performs a task, and pushes the information to a REST endpoint or other vendor-specific destination. Schedule-based integration flows can be edited in the GUI using the Integration Flows window to specify the schedule on which they execute.


Note

The integration flows available in the Developer Toolkit are used by various bundles in Manage > Bundles. Bundles are used to integrate your own applications with Catalyst Center or to enhance the performance of Catalyst Center itself. You can view the integration flows used in a bundle by clicking the bundle in Manage and clicking the Contents tab. Integration flows for the bundle are listed under the Contents tab.

Before you begin

Before you can view and manage integration flows in the Integration Flows window, you must enable them. You enable integration flows from the individual bundles in the Catalyst Center platform. For example, click the menu icon and choose Platform > Manage > Bundles > Basic ITSM (ServiceNow) CMDB synchronization. Click the Contents tab and then click Enable.

Procedure

Step 1

From the main menu, choose Platform > Developer Toolkit > Integration Flows.

Step 2

Review the integration flows displayed by the GUI.

Step 3

Select an integration flow from the ITSM Integration group.

This information appears:

  • Name: Name of the integration flow and link to access a slide-in pane where additional information is available.

    If the integration flow is a REST-based trigger type, after you click the integration flow name additional data such as description, tags, parameters, responses, model schemas, and policies appear.

    If the integration flow is a schedule-based trigger type, after you click the integration flow name a slide-in pane for setting the schedule appears. This slide-in pane displays DESCRIPTION, TAGS, and HOW TO USE THIS FLOW content.

  • Description: Brief description of integration flow.

  • Trigger: REST-based or schedule-based.

  • Icon (…): Accesses links to create a code preview or the Try option. If the integration flow is schedule-based, this icon accesses a Schedule Flow option.

Step 4

For a REST-based integration flow, click on the name (link) of the integration flow.

A slide-in pane opens with details about the REST-based integration flow. Review the details and then close the slide-in pane.

Step 5

For a REST-based integration flow, generate a code preview snippet by mousing over the icon (…) and clicking Generate Code Preview.

These choices appear only for REST-based triggered integration flows. Schedule-based integration flows provide a Schedule Flow menu item on hover.

Step 6

In the Code Preview window, select a programming language from the drop-down to generate the code.

After reviewing or copying the code for use, click Close.

Step 7

To try a REST request path interactively, mouse over the icon (…) and click Try.

Step 8

In the Try window, fill in the requested values (for example, URL address or value) and click Run.

After trying the method, review the response and/or error code within the Try window, and click Close.

When Catalyst Center returns a 202 (Accepted) HTTP status code, the result body includes a task ID and a URL that you can use to query for more information about the asynchronous task that your original request spawned. For example, you can use this information to determine whether a lengthy task has completed. For more information, see Getting Information about Asynchronous Operations.

Note

 

For responses, Catalyst Center APIs use a task-based response architecture so that multiple requests and responses can be sent concurrently. Therefore, all PUT, POST, and DELETE requests have a task-based response. To view more details about the response, send a GET request to the task URL (either from a script or as a URL). For error codes, the Catalyst Center APIs follow the standard HTTP status codes.

Step 9

For the schedule-based integration flow, mouse over the icon (…) and click Schedule Flow.

Step 10

Review this data:

  • DESCRIPTION: Description and purpose of integration flow.

  • TAGS: Tags indicate what the Catalyst Center component is used for or affected by the bundle.

  • HOW TO USE THIS FLOW: Schedule configuration options.

You can schedule the integration flow using the GUI.

Step 11

Configure a schedule for the integration flow using these GUI options:

  • Run Now: Select Run Now and then click Schedule to run the integration flow.

  • Run Later: Select Run Later and then enter a date, time, and time zone. Click Schedule to run the integration flow at the specified date, time, and time zone.

  • Recurring: Select Recurring and then configure these options:

    • Repeats: Select daily or weekly repeating occurrences for the integration flow

    • Run at Interval: Set the time interval between integration flows.

    • Set Schedule Start: Set a start date.

    • Set Schedule End: Set an end date.

    Click Schedule to run the integration at the configured times.

Work with event notifications

You can associate a notification to specific events that may occur in your network. After the notification is associated with event and even if the event does occur, you receive a notification by REST API or email. You associate a notification to an event by using the Event Notifications window in the Catalyst Center platform GUI.

Before you begin

  • For a REST API notification, you configured the webhook destination in the Webhook tab in Catalyst Center. To access the Webhook tab, click the menu icon and choose System > Settings > External Services > Destinations > Webhook. For detailed information about configuring a webhook destination, see Configure a webhook destination.

  • For email notification of events, you configured the email destination in the Email tab in Catalyst Center. To access the Email tab, click the menu icon and choose System > Settings > External Services > Destinations > Email. For detailed information about configuring an email destination, see Configure an email destination.

  • For a syslog server notification of events, you configured the syslog server destination in the Syslog tab in Catalyst Center. To access the Syslog tab, click the menu icon and choose System > Settings > External Services > Destinations > Syslog. For detailed information about configuring a syslog server destination, see Configure a syslog server destination.

  • For an SNMP trap notification of events, you configured the SNMP trap destination in the SNMP tab in Catalyst Center. To access the SNMP tab, click the menu icon and choose System > Settings > External Services > Destinations > SNMP. For detailed information about configuring a trap destination, see Configure a trap notification.

  • You have accessed the Event Settings window and reviewed or edited the list of events that may occur within your network for ITSM integration and can be captured by Catalyst Center. To access the Event Settings window, click the menu icon and choose Platform > Manage > Configurations > Event Settings.

Procedure

Step 1

From the main menu, choose Platform > Developer Toolkit > Event Notifications.

The Events Notifications window appears.

Step 2

Click the Notifications tab to view the notification tiles.

Each notification is represented by a tile and contains a link to view notification details.

Step 3

From the CHANNELS area in the left pane, click the radio button next to the channels for which you want to view the respective notification tiles.

The supported channels are REST, PAGERDUTY, SNMP, SYSLOG, WEBEX and EMAIL. Assurance events do not support SNMP.

Note

 

  • You must create a notification for an event with respective channels and trigger the notification. For more information, see Create an Event Notification in the Cisco Catalyst Center User Guide.

  • One event notification supports more than one channel.

Step 4

Click a notification tile link for which you want to view the notification details.

The Notification Details slide-in pane displays these notification details based on the selected channel:

  • Name: Name of the event.

  • Description: Event description

  • Sites

  • Events

  • REST: Appears only when you want to view REST notification details. The REST area shows this information:

    • URL: URL address of the REST API endpoint that event will be sent to.

    • Method: Either the PUT or POST method.

    • Trust certificate: Whether a trust certificate is required for REST API endpoint notification.

    • Headers: The Header Name and Header Value.

  • PAGERDUTY: Appears only when you want to view PAGERDUTY notification details. The PAGERDUTY area shows this information:

    • PagerDuty Events API URL

    • PagerDuty Integration Key

    • PagerDuty Events API Version

  • SNMP: Appears only when you want to view SNMP notification details.

  • SYSLOG: Appears only when you want to view SYSLOG notification details.

  • WEBEX: Appears only when you want to view WEBEX notification details.

  • EMAIL: Appears only when you want to view EMAIL notification details. The EMAIL area shows the email recipients From and To along with email Subject.

Step 5

In the Notification Details slide-in pane, click the toggle button at the top-right corner to enable or disable the respective notification.

Step 6

To edit a particular notification, click the Actions drop-down list and select Edit.

Step 7

In the EDIT NOTIFICATION window, do this configuration based on the selected channel:

  1. In the Name field, enter a unique name.

  2. In the Description field, enter the description of respective event.

  3. Expand the Site and Events and select a site from the Select a site drop-down list.

  4. Click the plus icon next to an event, or click Add All to add all the events to the respective notification.

  5. To remove an event from the notification, click the cross icon next to an event that you want to remove, or click Remove All to remove all events from the respective notification.

  6. Expand Configuration to edit the configuration of the selected notification channel.

    To specify details in the Configuration area, see Create an Event Notification in the Cisco Catalyst Center User Guide.

    Note

     

    In the Configuration area, the fields shown depend on the type of selected notification channel.

Step 8

Click the toggle button at the top-right corner to toggle between the tile view and list view.

Step 9

Click the Event Catalog tab to view the list of created events.

Note

 

You can adjust the events that appear by entering a keyword in the Search field.

Step 10

Review the data on an individual event within the table.

This Event Details tab data appears:

  • Description: Brief description of the event and how it is triggered.

  • Event ID: Identification number of the event.

  • Version: Version number of the event.

  • Namespace: Namespace of the event.

  • Severity: 1 through 5.

    Note

     

    Severity 1 is the most important or critical priority and should be assigned for this type of an event.

  • Domain: REST API domain to which the event belongs.

  • Subdomain: Subgroup under the REST API domain to which the event belongs.

  • Category: Error, Warn, Info, Alert, Task Progress, Task Complete.

  • Note: Additional information about the event or to assist in further understanding the event.

  • Event Link: Event broadcast using REST URL.

  • Tags: Tags indicate what Catalyst Center component is affected by the event.

  • Channels: What channels are supported for the event notifications (REST API, email, webex, and so on).

  • Model Schema: Presents model schema about the event:

    • Details: Example of model schema detail for the event.

    • REST Schema: REST schema format for the event.

Step 11

Click the Notifications tab to view the active notification associated to the respective event.

When you associate a notification to an event, a Try-It Now button appears in the Event Catalog tab. To run an event notification simulation, click Try-It Now. For information, see Work with Event Notification Simulations.

Work with event notification simulations

Catalyst Center platform supports event simulation, which lets you test an event's subscription (email, REST API, SNMP trap notification, syslog server, or Webex). After running an event simulation, the results (success or failure) are displayed in the GUI.

Before you begin

  • For a syslog server notification of events, you configured the syslog server destination in the Syslog tab in Catalyst Center. To access the Syslog tab, click the menu icon and choose System > Settings > External Services > Destinations > Syslog. For detailed information about configuring a syslog server destination, see Configure a syslog server destination.

  • For an email notification, you configured the email destination in the Email tab in Catalyst Center. To access the Email tab, click the menu icon and choose System > Settings > External Services > Destinations > Email. For detailed information about configuring an email destination, see Configure an email destination.

  • For a REST API notification, you configured the webhook destination in the Webhook tab in Catalyst Center. To access the Webhook tab, click the menu icon and choose System > Settings > External Services > Destinations > Webhook. For detailed information about configuring a webhook destination, see Configure a webhook destination.

  • You have accessed the Event Settings window and reviewed or edited the list of events that may occur within your network for ITSM integration and can be captured by Catalyst Center. To access the Event Settings window, click the menu icon and choose Platform > Manage > Configurations > Event Settings.

Procedure

Step 1

From the main menu, choose Platform > Developer Toolkit > Event Notifications > Event Catalog.

Step 2

In the Event Catalog tab, click an event. The slide-in pane shows a Try-It Now button if Catalyst Center is subscribed to that event. Click Try-It Now.

When this data appears, you can edit only the Details field:

  • Event Name: Catalyst Center system name for the event.

  • Event ID: Identification number of the event.

  • Instance ID: Identification number of the event's instance.

  • Name: Name of the event.

  • Description: Brief description of the event and how it is triggered.

  • Namespace: Namespace of the event.

    For this release, the default value for all events is ASSURANCE.

  • Context: Event context field.

    The default value is EXTERNAL.

  • Source: Source field.

    The default value is EXTERNAL.

  • Type: Network, App, System, Security, or Integrations type of event.

  • Category: Error, Warn, Info, Alert, Task Progress, Task Complete.

  • Severity: 1 through 5.

  • Domain: REST API domain to which the event belongs.

  • Sub Domain: Subgroup under the REST API domain to which the event belongs.

  • Details: Field for additional user detail about the event.

Step 3

Click X to exit from the field.

Step 4

Click Publish to run the event simulation and review results.

These results appear:

  • Subscription Name: User-created subscription name.

  • Connector Type: Email, REST API, SNMP trap, or Syslog.

  • Status: Loading, Success, or Fail.

  • Message: For a REST connector type (REST API subscription), an HTTPS response appears.