Getting Started

This guide provides an example usage of the API based on user scenarios. The examples provided in the guide are for demonstration purpose which can be used as a reference for external systems' integration with CNC. The scenarios and examples in this guide demonstrate workflow and sequence API execution for creation and deployment of device configuration templates. Template deployment enables users to automate common network management tasks, such as adding hostnames or configuring routing protocols, on one or more devices using system-defined or user-defined templates.

Prerequisites

Before using the examples in this guide, ensure that:

CNC is installed and configured with the corresponding release version.
Required applications and NSO are properly set up and integrated with CNC.
Devices are onboarded to CNC. Refer to the CNC Installation and Administration guides for detailed setup instructions.

Download and set up example scripts

Follow these steps to set up the scripts for execution on the target CNC setup.

Download cnc-device-config-templates-api-examples.tar.gz and unzip it in the home directory for the example scripts used in this guide.
After unzipping cnc-device-config-templates-api-examples.tar.gz, you should see a folder containing example scripts "device-config-template-creation.sh" and "device-config-template-deployment.sh", environment variables file "env", JWT token authentication scripts "get-cnc-jwt.sh" and "cnc-api-common.sh", input directory for input request payload and output directory for output response.
Edit cnc-device-config-templates-api-examples/env file to update the target CNC server host, port and user credentials.
Invoke the get-cnc-jwt.sh to obtain the JWT for authenticating the API calls
Invoke each use-case script after optionally updating the input files according to the cnc environment.

Authentication and Authorization

Accessing the CNC Device Config API requires Authentication and Authorization. CNC uses a JWT based authentication which can be obtained using two-step process. Authorization of each API is controlled by API level access control as well as Role Based Access Control (RBAC) defined and configured in CNC.

Script Details

get_jwt() {
    # The get_jwt.sh script retrieves a JWT token for authenticating API calls. The process involves two steps:  
    # Obtaining a Ticket Granting Ticket (TGT) using CNC server credentials.
    # Exchanging the TGT for a JWT token, which is stored in a file for later use.
    # Step 1. invoke this url with the username,password in the post payload
    export CNC_API_TGT_URL="https://$CNC_HOST:$CNC_PORT/crosswork/sso/v1/tickets"
    response=$(curl $CURL_OPTS -X POST $CNC_API_TGT_URL \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Accept: text/plain' \
    -d "username=${CNC_USER}&password=${CNC_PASSWORD}" \
    )

    # Step 2: invoke the jwt url with the jwt and forwarding service url in the post payload
    export CNC_API_JWT_URL="https://$CNC_HOST:$CNC_PORT/crosswork/sso/v2/tickets/jwt"
    response=$(curl $CURL_OPTS -X POST $CNC_API_JWT_URL \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "tgt=$response&service=https://$CNC_HOST:$CNC_PORT/app-dashboard" \
    )
 
    # Step 3. only for example purpose. store it in ~/.cnc-jwt file
    echo $response > $CNC_JWT_FILE
 
}
get_jwt

Example Script Environment Variables

The example scripts use a set of environment variables to define CNC server details, user credentials, and API endpoint root contexts required for running the use-case scripts. Ensure that you update the environment variables in the files as indicated below:

CNC Server host, port and user credentials in the cnc-device-config-templates-api-examples/env file
API endpoints root contexts that you want to reuse in the cnc-device-config-templates-api-examples/cnc-api-commons.sh file

# Standard CNC URL ROOT CONTEXTS
# Alarms and Events API Endpoint Root Context
export CNC_DEVICE_CONFIG_API_CTX="https://$CNC_HOST:$CNC_PORT/crosswork/config"