Developer Toolkit GUI

About Developer Toolkit

The Cisco DNA Center platform provides you with the following software developer tools to access and program with Cisco DNA Center, as well as to integrate Cisco DNA 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

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

The Cisco DNA 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.

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. Click the menu icon () and 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

Click the menu icon () and 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

Choose an API from the domains and subdomains.

After choosing an API, the following information is displayed 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.

  • Description: Brief description of the method.

  • URL: URL value for the method.

  • 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 Cisco DNA Center administrator to contact Cisco for assistance in resolving the issue.

Step 4

Click the name (link) of an API method.

The following information about the API method is displayed:

  • DESCRIPTION: Brief description of API.

  • FEATURES: Method and URL information.

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

  • RESPONSES: Possible HTTP responses.

  • MODEL SCHEMAS: Presents response as a data model (Model tab) or JSON format of the actual response (Model Schema tab). Sample code is available from the Code Preview button.

  • 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, choose a language from the drop-down to generate the code.

The following 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 Cisco DNA 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

 

The response is a live response from Cisco DNA 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 Cisco DNA Center platform and a third-party system, such as an ITSM system that is used to track, troubleshoot, and resolve network issues.

Cisco DNA 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 Cisco DNA Center or to enhance the performance of Cisco DNA 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 Cisco DNA 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

Click the menu icon () and choose Platform > Developer Toolkit > Integration Flows.

Step 2

Review the integration flows displayed by the GUI.

Step 3

Choose an integration flow from the ITSM Integration group.

The following information is displayed:

  • 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, choose 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 Cisco DNA 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, Cisco DNA 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 Cisco DNA 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 the following displayed data:

  • DESCRIPTION: Description and purpose of integration flow.

  • TAGS: Tags indicate what the Cisco DNA 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 the following GUI options:

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

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

  • Recurring: Choose Recurring and then configure the following options:

    • Repeats: Choose 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 the Schedule button 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 Cisco DNA Center platform GUI.

Before you begin

  • For a REST API notification, you configured the webhook destination in the Webhook tab in Cisco DNA 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 Cisco DNA 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 Cisco DNA 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 Cisco DNA 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 Cisco DNA Center. To access the Event Settings window, click the menu icon ( ) and choose Platform > Manage > Configurations > Event Settings.

Procedure

Step 1

Click the menu icon () and 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 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 DNA 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 the following 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 the following 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 the following 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 choose Edit.

Step 7

In the EDIT NOTIFICATION window, configure the following 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 choose 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 DNA 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 are displayed by entering a keyword in the Search field.

Step 10

Review the data on an individual event within the table.

The following Event Details tab data is displayed:

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

  • Sub Domain: 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 Cisco DNA Center component is affected by the event. The default value for tags for this release is ASSURANCE with additional syntax for the specific Assurance issue.

  • Supported Endpoints: What endpoint types are supported for the event notifications (email, REST API, or SNMP trap, and webex).

  • 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 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, Work with Event Notification Simulations.

Work with Event Notification Simulations

Cisco DNA 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 Cisco DNA 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 Cisco DNA 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 Cisco DNA 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 Cisco DNA Center. To access the Event Settings window, click the menu icon ( ) and choose Platform > Manage > Configurations > Event Settings.

Procedure

Step 1

Click the menu icon () and choose Platform > Developer Toolkit > Event Notifications.

Step 2

In the Event Notifications window, review the events table that is displayed.

Note

 

You can adjust the events that are displayed by entering a keyword in the Find field.

Step 3

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

The following data is displayed; you can edit only the Details field:

  • Event Name: Cisco DNA 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 4

Click X to exit from the field.

Step 5

Click Publish to run the event simulation and review results.

The following results are displayed:

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