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
Product name | Version |
---|---|
Cisco DNAC | 1.0.0 |
Anypoint Studio | 7.8.0 |
Mule | 4.0 |
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:
- Download and add the connector to MuleSoft Anypoint Studio
- Create a MuleSoft project and add the connector to the project
- Create the files required for the connector configuration
- Configure the connector
After you complete the configuration, you define a workflow and add the following activities:
Operation name | Description |
---|---|
Create event subscription | Creates a subscription endpoint to a list of registered events. |
Update event subscription | Updates a subscription endpoint for a list of registered events. |
Get event subscription | Gets a list of subscriptions that are based on the offset and limit provided. |
Delete event subscription | Deletes a subscription endpoint for a list of registered events. |
Get events | Gets a list of registered events with event IDs, or tags set to Mandatory. |
Get issues | Gets a list of global issues, issues for a specific device, or issues for a specific MAC address for a client device. |
Get issue enrichment details | Provides information about a specific network issue; for example, an issue ID, an end user's MAC address. The operation provides information such as issue details, list of impacted hosts, and suggested actions to remediate the issues. |
Update Issue Status | Updates the status of an issue to Resolved or Ignored. |
Get Webhook Subscription Details | Gets the list of subscription details for the specified connector type. |
Task 1: To download and add the connector to MuleSoft Anypoint Studio
- Log in to BMC Support by using your BMC support ID.
- 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.
- Extract the .jar file to a local directory.
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"
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
- Log in to Anypoint Studio.
- Select File > New > Mule Project.
- Enter a name for your project and click Finished.
- From the Mule Palette, click Add Modules.
- From the list displayed, drag Cisco DNAC to the palette.
The Cisco DNAC connector is listed in the Mule Palette for your project. 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>
- Click the Save icon on the application toolbar.
Task 3: To create the files required for the connector configuration
Create a properties file for the project.
- Right-click the src/main/resources branch and select New > File.
- Enter a name for the file; for example: project.properties.
- 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.
- Create a configuration file to define the connector configuration:
- Right-click the src/main/mule branch and select New > Mule Configuration File.
- In the General Information dialog box, enter config.xml in the Name field and click Finish.
- Click Global Elements and then click Create.
- Select Global Configurations > Configuration Properties.
- On the General tab, select the project.properties file that you created and then click OK.
- Click the Save icon on the application toolbar.
Task 4: To configure the connector
- From the Package Explorer pane, double-click the <projectName>.xml file.
- To run the workflow when specific conditions are met, configure HTTP Listener as the source:
From the Mule Palette, select HTTP > Listener.
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.
To verify the configuration values, click Test Connection.
- Define the connector configuration.
- From the Mule Palette, select Cisco DNAC, and drag a Cisco DNAC activity to the Message Flow tab.
- On the Message Flow tab, select the Cisco DNAC activity.
To define the connector configuration, in the Basic Settings section, click the + icon for Connector configuration.
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 - To verify the defined configuration values, click Test Connection.
- Click OK.
- 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.
Important
When using a Cisco DNAC activity in a flow, to get data from an external source, define the payload metadata in the Transform message element. Select the JSON data format from the type, and then select Example from the dropdown. Then select the JSON file for the input metadata.
For more information about adding the metadata, see
Create metadata class
.
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
- From the Mule Palette, select Cisco DNAC > Create Event Subscription.
- Drag the Create Event Subscription option to the Message Flow tab.
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 "
}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
- From the Mule Palette, select Cisco DNAC > Update Event Subscription.
- Drag the Update Event Subscription option to the Message Flow tab.
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 "
}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
- From the Mule Palette, select Cisco DNAC > Get Event Subscription.
- Drag the Get Event Subscription option to the Message Flow tab.
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"
}]
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
- From the Mule Palette, select Cisco DNAC > Delete Event Subscription.
- Drag the Delete Event Subscription option to the Message Flow tab.
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"
}
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
- From the Mule Palette, select Cisco DNAC > Get Events Subscription.
- Drag the Get Events Subscription option to the Message Flow tab.
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"
}
]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
- From the Mule Palette, select Cisco DNAC > Get Issues.
- Drag the Get Issues option to the Message Flow tab.
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
}
]
}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
- From the Mule Palette, select Cisco DNAC > Get Issues Enrichment Details.
- Drag the Get Issues Enrichment Details option to the Message Flow tab.
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": []
}
]
}
}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
- From the Mule Palette, select Cisco DNAC > Update Issue Status.
- Drag the Update Issue Status option to the Message Flow tab.
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"
]
}
}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
- From the Mule Palette, select Cisco DNAC > Get Webhook Subscription.
- Drag the Get Webhook Subscription option to the Message Flow tab.
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
}]
Click the Save icon on the application toolbar.
Comments
Log in or register to comment.