RMA Guide

Introduction

Return merchandise authorization (RMA) APIs simplify the workflow to replace a faulty device with an existing device with the same characteristics (model, platform, etc). Using this functionality, Cisco DNA Centers manages the configuration changes and all relevant logical tasks to replace the old device with the new one, minimizing human error and speeding up the recovery process.

Goal

The goals of this guide are:

1. Mark a device for replacement
2. Trigger the device replacement workflow

Endpoints and methods used

• POST /dna/intent/api/v1/device-replacement
• POST /dna/intent/api/v1/device-replacement/workflow

Prerequisites

For this guide, it is recommended that the developer is familiar with authenticating to Cisco DNA Center API, managing devices and getting devices onboard of Cisco DNA Center.

• Authentication and Authorization
• Devices
• Device Onboarding

Environment

This guide was developed using:

• Python 3.7.x

Authentication

First, we need to authenticate and retrieve a token from the API.

Do not use verify=False or urllib3.disable_warnings() if you are not sure of its purpose. Read Authentication and Authorization.

import requests
from requests.auth import HTTPBasicAuth
import urllib3
urllib3.disable_warnings()

BASE_URL = 'https://<IP Address>'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

response = requests.post(BASE_URL + AUTH_URL, auth=HTTPBasicAuth(USERNAME, PASSWORD), verify=False)
token = response.json()['Token']
headers = {'X-Auth-Token': token, 'Content-Type': 'application/json'}

RMA API

The RMA API is composed of 5 endpoints to mark devices for replacement, trigger the replacement workflow, get the list of devices in the replacement state or unmark devices.

Mark devices for replacement

Once the developer has access to the token, it is possible to mark a device for replacement which is the first step of the process

DEVICE_REPLACEMENT_URL = '/dna/intent/api/v1/device-replacement'
faulty_serial_id = ''
device_info = [
    {
        "faultyDeviceSerialNumber": faulty_serial_id
    }
]
response = requests.post(BASE_URL + DEVICE_REPLACEMENT_URL,
                            headers=headers, json=device_info,
                            verify=False)

Trigger device replacement workflow

With the device marked for replacement, we need to trigger the replacement workflow

DEVICE_REPLACEMENT_WORKFLOW_URL = '/dna/intent/api/v1/device-replacement/workflow'
replacement_serial_id = ''
device_info = [
    {
        "faultyDeviceSerialNumber": faulty_serial_id,
        "replacementDeviceSerialNumber": replacement_serial_id
    }
]
response = requests.post(BASE_URL + DEVICE_REPLACEMENT_WORKFLOW_URL,
                         headers=headers, json=device_info,
                         verify=False)

Code

The repository for this guide is here. The final code with functions is shown below.

# Modules import
import requests
from requests.auth import HTTPBasicAuth
import time
import sys

# Disable SSL warnings. Not needed in production environments with valid certificates
import urllib3
urllib3.disable_warnings()

# Authentication
BASE_URL = 'https://<IP Address>'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

# URLs
DEVICE_REPLACEMENT_URL = '/dna/intent/api/v1/device-replacement'
DEVICE_REPLACEMENT_WORKFLOW_URL = '/dna/intent/api/v1/device-replacement/workflow'

# Get Authentication token
def get_dnac_jwt_token():
    response = requests.post(BASE_URL + AUTH_URL,
                             auth=HTTPBasicAuth(USERNAME, PASSWORD),
                             verify=False)
    token = response.json()['Token']
    return token

# Mark device for replacement
def mark_device_for_replacement(headers, device_info):
    response = requests.post(BASE_URL + DEVICE_REPLACEMENT_URL,
                             headers=headers, json=device_info,
                             verify=False)
    return response.json()

# Trigger device replacement workflow
def trigger_device_replacement_workflow(headers, device_info):
    response = requests.post(BASE_URL + DEVICE_REPLACEMENT_WORKFLOW_URL,
                             headers=headers, json=device_info,
                             verify=False)
    return response.json()

def main():
    # obtain the Cisco DNA Center Auth Token
    token = get_dnac_jwt_token()
    headers = {'X-Auth-Token': token, 'Content-Type': 'application/json'}

    # Mark device for replacement
    faulty_serial_id = ''
    device_info = [
        {
            "faultyDeviceSerialNumber": faulty_serial_id
        }
    ]

    response = mark_device_for_replacement(headers, device_info)

    # Device replacement worklfow
    replacement_serial_id = ''
    device_info = [
        {
            "faultyDeviceSerialNumber": faulty_serial_id,
            "replacementDeviceSerialNumber": replacement_serial_id
        }
    ]

    response = trigger_device_replacement_workflow(headers, device_info)


if __name__ == "__main__":
    main()