RMA Guide

Introduction

Return merchandise authorization (RMA) APIs streamline replacing a faulty device with an existing one of the same model and platform. Using this functionality, Catalyst Center handles configuration changes and related tasks, reducing human error and speeding up recovery.

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, we recommend that the developer becomes familiar with authenticating to the Catalyst Center API, managing devices, and onboarding devices to Catalyst Center.

• Authentication and Authorization
• Devices
• Device Onboarding

Environment

This guide was developed using:

• Python 3.7.x

Authentication

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

Notes: 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 consists 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 must 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 appears as 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 Catalyst 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()