Cisco DNA Center connector powered by MuleSoft

The Cisco DNA Center connector (Cisco DNAC connector), powered by MuleSoft provides a connection between the MuleSoft connector engine and Cisco DNAC. You can use the connector to create, get, update, and delete event subscription, get events, get issues, get issue enrichments, get webhook details, and update issues in Cisco DNAC. Also, configure multiple Cisco DNAC activities that can be used as a source or target within operations defined for the connection. 

Before you begin

Make sure you have:

• Required permissions to get and update events in the Cisco DNAC.
• Required access to use MuleSoft Anypoint Studio.
• Installed MuleSoft Anypoint Studio version 7.8.0.
• Installed Apache Maven and have working knowledge of it.
• Organization ID and user name and password for your MuleSoft account.

Supported product versions

Configuring the Cisco DNAC connector in Anypoint Studio

Use Anypoint Studio to configure the connector and then publish it to the cloud platform for distribution. You can design and update your application, properties, and configuration files for the connector. 

Complete the following procedures to configure the connector in Anypoint Studio:

1. Download and add the connector to MuleSoft Anypoint Studio
2. Create a MuleSoft project and add the connector to the project
3. Create the files required for the connector configuration
4. Configure the connector

After you complete the configuration, you define a workflow and add the following activities:

Task 1: To download and add the connector to MuleSoft Anypoint Studio

1. Log in to BMC Support by using your BMC support ID.
2. Download the  Cisco DNA Connector 2022-07-01 file from the BMC Helix iPaaS for MuleSoft 22.1.00 page on the Electronic Distribution Site.
3. Extract the .jar file to a local directory.

4. From the command prompt, enter the following commands:

   mulesoft-ciscodnac-connector-1.0.0-mule-plugin.jar

   mvn install:install-file "-Dfile=mulesoft-ms-ciscodna-connector-1.0.0-mule-plugin.jar" "-DgroupId=org.mule.bmc.connector.ms.ciscodna" "-DartifactId=mulesoft-ms-ciscodna-connector" "-Dversion=1.0.0" "-DgeneratePom=true" "-Dpackaging=mule-extension"

5. Navigate to the C:\Users\<userName>\.m2\repository\org\mule\bmc\connector\ms\ciscodnac\mulesoft-ms-ciscodnac-connector\1.0.0 directory and paste the downloaded .jar file in this directory. 

After you add the connector, it is available in the Mule Palette of MuleSoft Anypoint Studio.

Task 2: To create a MuleSoft project and add the connector to the project 

1. Log in to Anypoint Studio.
2. Select File > New > Mule Project.
3. Enter a name for your project and click Finished. 
4. From the Mule Palette, click Add Modules. 
5. From the list displayed, drag Cisco DNAC to the palette.
   The Cisco DNAC connector is listed in the Mule Palette for your project. 

6. On the Package Explorer tab, open the pom.xml file for your project and verify that the following dependency is included in the file:

   <dependency>
         <groupId>org.mule.bmc.connector.cisco.dnac</groupId>
          <artifactId>mulesoft-cisco-dnac-connector</artifactId>
          <version>1.0.0</version>
       <classifier>mule-plugin</classifier>
   </dependency>             

7. Click the Save icon on the application toolbar.

Task 3: To create the files required for the connector configuration

1. Create a properties file for the project. 

   1. Right-click the src/main/resources branch and select New > File.
   2. Enter a name for the file; for example: project.properties.
   3. Enter the following variable values in the file and save it: 

      • hostName — Enter the URL of the Cisco DNAC instance; for example, https://hostname-dsom-platform.trybmc.com/.

      • username—Enter the user name that has access to the Cisco DNAC instance.

      • password—Enter the password for the username that you provided earlier.
      These variables are used to configure your connector.
2. Create a configuration file to define the connector configuration:
   1. Right-click the src/main/mule branch and select New > Mule Configuration File.
   2. In the General Information dialog box, enter config.xml in the Name field and click Finish.
   3. Click Global Elements and then click Create.
   4. Select Global Configurations > Configuration Properties.
   5. On the General tab, select the project.properties file that you created and then click OK.
3. Click the Save icon on the application toolbar.

Task 4: To configure the connector

1. From the Package Explorer pane, double-click the <projectName>.xml file.
   
2. To run the workflow when specific conditions are met, configure HTTP Listener as the source: 
   

   1. From the Mule Palette, select HTTP > Listener. 

   2. Select the Listener element, and add the following details: 

      Field name	Actions
      Display name	Enter a short display name for the source.
      Connector configuration	Click the + sign to add the connector configuration and add the following details: Name—Enter a name for the configuration. Protocol—Select HTTP or HTTPS. Host—Select the default value. Port—For HTTP, enter 8081 and for HTTPS, enter 8082. Important: If the selected port is in use, enter a different value. Base path—Enter a path for the flow. Listener interceptors—Select None.

   3. To verify the configuration values, click Test Connection. 

3. Define the connector configuration.
   1. From the Mule Palette, select Cisco DNAC, and drag a Cisco DNAC activity to the Message Flow tab. 
   2. On the Message Flow tab, select the Cisco DNAC activity.

   3. To define the connector configuration, in the Basic Settings section, click the + icon for Connector configuration.

   4. Enter the following variables defined in the project.properties file in Task 2:

      Important

      Create a properties file for the proxy configuration and add the variable values instead of the actual values.

      Field name	Value
      Name	Name for the connector configuration.
      General tab
      Host Name	${hostName}
      Personal Access Token	${personalAccessToken}
      Organization	${organization}
      Version	${version}
      Proxy Config
      Host	URL of the proxy server
      Port	Port number for the proxy server
      Username	User name to connect to the proxy server
      Password	User's password to connect to the proxy server
      NTLM Domain	Domain name of the NT LAN Manager (NTLM) active directory server

   5. To verify the defined configuration values, click Test Connection.
   6. Click OK.
   7. To save your updates, click the Save icon on the application toolbar.

The connector configuration is used for all the Cisco DNAC activities in your flow. After you set up the project configuration files and configure the Cisco DNAC connector for MuleSoft, you can create flows between Cisco DNAC and other applications.

Workflow examples

A typical flow requires the source configuration, for example HTTP > Listener, a request Transform Message that writes information to the Cisco DNAC operation, the activity configuration, a response Transform Message that receives the information from the activity and a final logger element to write data to your target application. 

After you create the workflow, run the project (right-click project name and select Run Project As > Mule Application), and then run the flow by using an application like Postman.

The following images show sample flows created for the Cisco DNAC operations:

Create Event Subscription activity

The Create Event Subscription activity gathers the data to create a new event subscription for the list of registered events at the Cisco DNAC subscription endpoint. It is intended to be used as a target to consume data in an operation in a workflow. 

To configure the Create Event Subscription activity

1. From the Mule Palette, select Cisco DNAC > Create Event Subscription. 
2. Drag the Create Event Subscription option to the Message Flow tab. 

3. Select the Create Event Subscription brick and on the Create Event Subscription tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip}/DNAC/intent/api/v1/event/subscription
   HTTP Method	POST
   Request Body	[     {         "subscriptionId": "string",         "version": "string",         "name": "string",         "description": "string",         "subscriptionEndpoints": [             {                 "instanceId": "string",                 "subscriptionDetails": {                      "name": "string",                     "connectorType": "string",                     "url": "string",                     "method": "string"                 }             }         ],         "filter": { "eventIds": ["string"] }     } ]
   Headers	X-Auth-Token: {{token}} Content-type: application/json
   Response Schema	{     "statusUri": "/DNAC/intent/api/v1/event/api-status/67bd64e3-0ffc-4438-a73e-102f6aac5140" } Then we call the GET STATUS API and pass on statusUri in the base url, i.e. https://{server-ip}/{statusUri} and will get the Response as mentioned below  {     "errorMessage": {         "errors": []     },     "apiStatus": "SUCCESS",     "statusMessage": "Subscription's <name> created " }

4. Click the Save icon on the application toolbar.

Update Event Subscription activity

The Update Event Subscription activity gathers the data to update an event subscription for the list of registered events at the Cisco DNAC subscription endpoint. It is intended to be used as a target to consume data in an operation in a workflow. 

To configure the Update Event Subscription activity

1. From the Mule Palette, select Cisco DNAC > Update Event Subscription. 
2. Drag the Update Event Subscription option to the Message Flow tab. 

3. Select the Update  Event Subscription brick and on the Update Event Subscription tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip}/DNAC/intent/api/v1/event/subscription
   HTTP Method	PUT
   Request Body	[     {         "subscriptionId": "string",         "version": "string",         "name": "string",         "description": "string",         "subscriptionEndpoints": [             {                 "instanceId": "string",                 "subscriptionDetails": {                      "name": "string",                     "connectorType": "string",                     "url": "string",                     "method": "string"                 }             }         ],         "filter": { "eventIds": ["string"] }     } ]
   Headers	X-Auth-Token: {{token}} Content-type: application/json
   Response Schema	{     "statusUri": "/DNAC/intent/api/v1/event/api-status/67bd64e3-0ffc-4438-a73e-102f6aac5140" } Then we call the GET STATUS API and pass on statusUri in the base url, i.e. https://{server-ip}/{statusUri} and will get the Response as mentioned below  {     "errorMessage": {         "errors": []     },     "apiStatus": "SUCCESS",     "statusMessage": "Subscription's <name> created " }

4. Click the Save icon on the application toolbar.

Get Event Subscription activity

The Get Event Subscription activity gathers the data to get the list of subscriptions based on the offset and limit provided. It is intended to be used as a target to consume data in an operation in a workflow. 

To configure the Get Event Subscription activity

1. From the Mule Palette, select Cisco DNAC > Get Event Subscription. 
2. Drag the Get Event Subscription option to the Message Flow tab. 

3. Select the Get Event Subscription brick and on the Get Event Subscription tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip}/DNAC/intent/api/v1/event/subscription
   HTTP Method	GET
   Query Param	eventIds(String)—List of subscriptions related to the respective event IDs. offset(Number)—The number of subscriptions to offset in the resultset whose default value is 0. limit(Number)—The number of subscriptions to limit in the resultset whose default value is 10. sortBy(String)—SortBy field name order(String)—order(asc/desc)
   Headers	X-Auth-Token: {{token}} Content-type: application/json
   Response Schema	[   {         "version": "1.0.0",         "subscriptionId": "ES137",         "name": "event subscription testing",         "description": "event subscription testing",         "subscriptionEndpoints": [             {                 "instanceId": "f5b1c511-9206-46dc-968c-4f5e94589dfb",                 "subscriptionDetails": {                     "connectorType": "REST",                     "instanceId": "f5b1c511-9206-46dc-968c-4f5e94589dfb",                     "name": "webhookinstance",                     "description": "",                     "connectorType": "REST",                     "url": "https://webhook.site/d901b408-ce66-42b4-85ac-90088c1c6add",                     "basePath": null,                     "resource": null,                     "method": "POST",                     "trustCert": false,                     "headers": [],                     "queryParams": [],                     "pathParams": [],                     "body": null,                     "connectTimeout": 10,                     "readTimeout": 10                 },                 "connectorType": "REST"             }         ],         "filter": {             "eventIds": [                 "NETWORK-DEVICES-3-103"             ],             "others": [],             "domainsSubdomains": [],             "types": [],             "categories": [],             "severities": [],             "sources": [],             "sites": []         },         "isPrivate": false,         "tenantId": "6111a80c760a3a11cc592889"     } ]

4. Click the Save icon on the application toolbar.

Delete Event Subscription activity

The Delete Event Subscription activity gathers the data to delete event subscriptions. It is intended to be used as a target to consume data in an operation in a workflow. 

To configure the Delete Event Subscription activity

1. From the Mule Palette, select Cisco DNAC > Delete Event Subscription. 
2. Drag the Delete Event Subscription option to the Message Flow tab. 

3. Select the Delete Event Subscription brick and on the Delete Event Subscription tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip} /DNAC/intent/api/v1/event/subscription
   HTTP Method	DELETE
   Query Param	subscriptions(String)—List of Event Subscription IDs for removal
   Headers	X-Auth-Token: {{token}} Content-type: application/json
   Response Schema	{     "statusUri": "string" }

4. Click the Save icon on the application toolbar.

Get Events activity

The Get Events Subscription activity gathers the data to get the list of subscriptions based on the offset and limit provided. It is intended to be used as a target to consume data in an operation in a workflow. 

To configure the Get Events Subscription activity

1. From the Mule Palette, select Cisco DNAC > Get Events Subscription. 
2. Drag the Get Events Subscription option to the Message Flow tab. 

3. Select the Get Events Subscription brick and on the Get Events Subscription tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip} /DNAC/intent/api/v1/events
   HTTP Method	GET
   Query Param	eventIds(String)—List of subscriptions related to the respective event IDs. tags(String)—The registered tags should be provided. offset(Number)—The number of subscriptions to offset in the resultset whose default value is 0. limit(Number)—The number of subscriptions to limit in the resultset whose default value is 10. sortBy(String)—SortBy field name order(String)—order(asc/desc)
   Headers	X-Auth-Token: {{token}} Content-type: application/json
   Response Schema	[     {         "version": null,         "eventId": "NETWORK-DEVICES-3-154",         "namespace": "ASSURANCE",         "name": "WLC Memory High Utilization",         "description": "WLC is experiencing high memory utilization",         "category": "WARN",         "domain": "Know Your Network",         "subDomain": "Devices",         "type": "NETWORK",         "source": null,         "severity": 3,         "details": {             "Type": "$eventSource$",             "Assurance Issue Priority": "$priority$",             "Assurance Issue Details": "Memory utilization in the WLC $wlcName$ memory has exceeded the $threshold$% threshold for the past 15 minutes.",             "Device": "$eventUniqueId$",             "Assurance Issue Category": "$category$",             "Assurance Issue Name": "This WLC $wlcName$ is experiencing high memory utilization",             "Assurance Issue Status": "$status$"         },         "additionalDetails": {},         "subscriptionTypes": [],         "tags": [             "ASSURANCE",             "wlc_memory_high"         ],         "tenantId": "SYS0"     } ]

4. Click the Save icon on the application toolbar.

Get Issues activity

The Get Issues activity uses the Intent API to get a list of global issues, issues for a specific device, or issue for a specific client device's MAC address. This API gets a list of issues in a time window.

By default, the time window is last 24 hours ending at the time the API is used.

The Intent API supports the following filters:

• Site ID—Gets a list of global issues that have occurred in a specific site. When a site ID value is not provided, the API returns global issues of the Global site.
• Device ID—Gets a list of issues that have occurred for a specific device.
• Client MAC address—Gets a list of issues that have occurred for a specific client device that is identified by the MAC address of the device.
• Priority—Gets a list of issues that have specific priority value. The API supports the P1, P2, P3, and P4 priority values only if the site ID is provided. 
  By default, the API gets all the issues regardless of their priority. Supported priority is 
• Issue Status—Gets a list of issues that have specific status values. The API supports the following statuses:
  • Ignored
  • Resolved
  • Active
• AI Driven— Supports the following values only with site ID:
  • Yes
  • No

To configure the Get Issues activity

1. From the Mule Palette, select Cisco DNAC > Get Issues. 
2. Drag the Get Issues option to the Message Flow tab. 

3. Select the Get Issues brick and on the Get Issues tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip} /DNAC/intent/api/v1/issues
   HTTP Method	GET
   Query Param	startTime(Number)—Starting epoch time in milliseconds of query time window endTime(Number)—Ending epoch time in milliseconds of query time window siteId(String)—Assurance UUID value of the site in the issue content deviceId(String)—Assurance UUID value of the device in the issue content macAddress(String)—MAC address of the client device of the issue in the following format: xx:xx:xx:xx:xx:xx priority(String)—The priority value of the issue (P1, P2, P3, or P4) Important: Use this parameter only when the macAddress and deviceId values are not provided. aiDriven(String)—The AI driven value of the issue (Yes or No) Important: Use only when the macAddress and deviceId values are not provided. issueStatus(String)—The status value of the issue (ACTIVE, IGNORED, RESOLVED)
   Headers	X-Auth-Token: {{token}} Content-type: application/json
   Response Schema	{     "version": "1.0",     "totalCount": 1,     "response": [         {             "issueId": "8dae0a0c-b643-4fe1-b192-cef4fb6097de",             "name": "The RADIUS server '10.4.48.19:1812,1813' is not responding to requests being made from the network device 'D3-4507.cisco.local'",             "siteId": "",             "deviceId": "261f3770-c2ba-4fcc-9d40-953d9a491767",             "deviceRole": "",             "aiDriven": "",             "clientMac": "",             "issue_occurence_count": 24,             "status": "active",             "priority": "",             "category": "",             "last_occurence_time": 1633074425235         }     ] }

4. Click the Save icon on the application toolbar.

Get Issues Enrichment Details activity

The Get Issues Enrichment Details activity enriches a given network issue context (an issue id or end user’s Mac Address) with details about the issue, impacted hosts, and suggested actions for remediation.

To configure the Get Issues Enrichment Details activity

1. From the Mule Palette, select Cisco DNAC > Get Issues Enrichment Details. 
2. Drag the Get Issues Enrichment Details option to the Message Flow tab. 

3. Select the Get Issues Enrichment Details brick and on the Get Issues Enrichment Details tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip} /DNAC/intent/api/v1/issue-enrichment-details
   HTTP Method	GET
   Headers	X-Auth-Token— {{token}} Content-type—application/json entity_type—String Fetch the issue enrichment details based on either the issue ID or client MAC address. Enter issue_id or mac_address in this parameter. entity_value—String Contains the actual value for the entity type that has been defined.
   Response Schema	{     "issueDetails": {         "issue": [             {                 "issueId": "8dae0a0c-b643-4fe1-b192-cef4fb6097de",                 "issueSource": "Cisco DNAC",                 "issueCategory": "Device",                 "issueName": "radius_error_trigger",                 "issueDescription": "The RADIUS server '10.4.48.19:1812,1813' is not responding to requests being made from the network device 'D3-4507.cisco.local', or the responses are not being received by the network device.",                 "issueEntity": "network_device",                 "issueEntityValue": "261f3770-c2ba-4fcc-9d40-953d9a491767",                 "issueSeverity": "HIGH",                 "issuePriority": "P2",                 "issueSummary": "The RADIUS server '10.4.48.19:1812,1813' is not responding to requests being made from the network device 'D3-4507.cisco.local'",                 "issueTimestamp": 1633074425235,                 "deviceId": "261f3770-c2ba-4fcc-9d40-953d9a491767",                 "suggestedActions": [                     {                         "message": "Check connectivity between the RADIUS server and network device and ensure the port is open along the path."                     },                     {                         "message": "If using ISE then use the TCP Dump diagnostic tool to check if ISE is receiving the request and replying."                     },                     {                         "message": "The ISE live logs may suggest reasons for a lack of reply."                     }                 ],                 "impactedHosts": []             }         ]     } }

4. Click the Save icon on the application toolbar.

Update Issue Status activity

The Update Issue Status activity changes the status of an issue to Resolved or Ignored.

To configure the Update Issue Status activity

1. From the Mule Palette, select Cisco DNAC > Update Issue Status. 
2. Drag the Update Issue Status option to the Message Flow tab. 

3. Select the Update Issue Status brick and on the Update Issue Status tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip}/api/assurance/v1/issue/status/bulk
   HTTP Method	POST
   Headers	X-Auth-Token—{{token}} Content-type—application/json
   Request Body	{     "issueIds": [         "3d7d00e4-0084-4674-999f-f95a6c7c4ab6"     ],     "updatedBy": "neha",     "status": "resolved",     "ignoreStartTime": 1634536571809,     "ignorePeriod": "PT1H" }
   Response Schema	{     "version": "1.0",     "response": {         "successful": [             "3d7d00e4-0084-4674-999f-f95a6c7c4ab6"         ]     } }

4. Click the Save icon on the application toolbar.

Get Webhook Subscription Details activity

The Get Webhook Subscription activity gets the list of subscription details for the specified connector type.

To configure the Get Webhook Subscription activity

1. From the Mule Palette, select Cisco DNAC > Get Webhook Subscription. 
2. Drag the Get Webhook Subscription option to the Message Flow tab. 

3. Select the Get Webhook Subscription brick and on the Update Issue Status tab, enter the following configuration details:

   Parameter	Value
   REST Endpoint	https://{server-ip}/DNAC/intent/api/v1/event/subscription-details/rest
   HTTP Method	GET
   Headers	X-Auth-Token—{{token}} Content-type—application/json
   Query Param	connectorType—String; for example, Connector Type [REST] name—String Enter the name of the specific configuration. instanceId—String Enter the instance Id of the specific configuration.
   Response Schema	[     {         "instanceId": "58a02102-37b5-48ed-b72d-febcfbd12dff",         "name": "Mywebook",         "description": "",         "connectorType": "REST",         "url": "https://webhook.site/9c4f3329-572e-4e2c-bf0c-1600c719d736",         "basePath": null,         "resource": null,         "method": "POST",         "trustCert": false,         "headers": [],         "queryParams": [],         "pathParams": [],         "body": null,         "connectTimeout": 10,         "readTimeout": 10     } ]

4. Click the Save icon on the application toolbar.