Developer Toolkit GUI

Developer toolkit

Use a developer toolkit to access software development tools that

  • offers APIs organized by specific functionality,

  • provides integration flows sorted by category type, and

  • enables event notifications for subscribing to and viewing network events.

Developer toolkits helps you access Catalyst Center, support programming tasks, and and make it easy to integrate with other applications through a standardized interface. These toolkits provide ease of use and interoperability.

Examples

  • APIs: available API operations organized within categories by functionality, such as Operational Tasks or Site Management API operations.

  • Integration Flows: workflow integrations organized by category type.

  • Event Notifications: subscribe to network events for proactive management.

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. This includes the request method and URL, query parameters, request header parameters, responses, schema, and methods for previewing or testing the request.

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

Before you begin

  • Ensure you meet programming language and authentication prerequisites. For more information, see API prerequisites.

  • Enable the Rogue and aWIPS bundle in Catalyst Center to access specific APIs. To enable the Rogue and aWIPS bundle, navigate to Platform > Manage > Bundles > Rogue and aWIPS and select Enable.

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 a domain or subdomain to view the APIs.

Information about each API in that domain appears in columns.

  • Method: supported methods that 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.

    Note

     

    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: a brief description of the API.

  • URL: the URL value for the API.

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

Note

 

A blue color-coded message may appear. This message indicates that the specific API configuration is still in progress. You should check again later. The screen refreshes automatically when the API is registered, enabling you to proceed with your API activity. If a red color-coded message appears stating that the API cannot be configured, contact your Catalyst Center administrator. The administrator should contact Cisco for help resolving the issue.

Step 4

Click the name (link) of an API method.

This information about the API method appears:

  • DESCRIPTION: a 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: the 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.

  • REQUEST BODY: details of the data you must provide in the body of an HTTP request when interacting with an API endpoint.

  • 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. 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.

Manage 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. It performs a task and pushes the information to a REST endpoint or another 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. Bundles also 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

  • Ensure integration flows are enabled for the required bundles in 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.

  • Verify access to the Developer Toolkit and necessary permissions.

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, clicking the integration flow name displays extra data. This data includes the description, tags, parameters, responses, model schemas, and policies.

    If the integration flow is a schedule-based trigger type, clicking the integration flow name opens a slide-in pane for setting the schedule. The slide-in pane displays DESCRIPTION, TAGS, and HOW TO USE THIS FLOW content.

  • Description: brief description of integration flow.

  • Trigger: schedule-based or REST-based.

  • Icon (…): provides links to create a code preview or access 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). The Catalyst Center APIs use standard HTTP status codes to represent error conditions.

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: 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.

Configure event notifications for network events

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

Before you begin

  • Ensure webhook destination is configured for REST API notifications 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.

  • Configure email destination for email notifications 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 email destinations for event and report notifications.

  • Set up syslog server destination for syslog notifications 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.

  • Configure an SNMP trap destination for SNMP notifications 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.

  • Access the Event Settings window and review or edit 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: the 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 email destinations for event and report notifications.

  • 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.