Getting Started

This guide provides example usage of the CNC Collection API based on common user scenarios. The examples in this guide are for demonstration purposes and serve as a reference for integrating external systems with CNC. The scenarios and examples in this guide demonstrate the workflow and sequence of API executions for collection operations. Crosswork Collector Services APIs manage application intents for collection jobs across multiple devices and collection types, including SNMP, CLI, TRAP, MDT, GNMI, and SYSLOG.

Prerequisites

Before using the examples in this guide, ensure the following prerequisites are met:

  1. CNC is set up with the correct release version, required applications, and NSO.
  2. Devices are onboarded to CNC (added to the inventory and their details collected).

Download and set up example scripts

Follow these instructions to set up the scripts for execution against the target CNC setup:

  1. Download cnc-collections-api-examples.tar.gz and unzip it in the user's home directory.
  2. After unzipping cnc-collections-api-examples.tar.gz, you should see a folder containing example scripts, environment files, one input and output dir.
  3. Edit the cnc-collections-api-examples/env file to update the CNC server's host, port, and user credentials.
  4. Run the get-cnc-jwt.sh script to obtain the JWT for authenticating API calls.
  5. Run each use case script, optionally updating the input template json files to match the CNC environment.

Authentication and Authorization

Accessing the CNC Northbound API requires authentication and authorization. CNC uses JWT-based authentication, which can be obtained using a two-step process. API authorization is managed through API-level access control and Role-Based Access Control (RBAC) configured in CNC.

Script Details

get_jwt() {
    # Getting the JWT for use in CNC API authentication is a two-step process:
    # Step 1: Obtain the Ticket Granting Ticket (TGT)
    # Step 2: Use the TGT to get the JWT
 
    # Step 3. Invoke this URL with the username and 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 4: Invoke the JWT URL with the TGT 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 5. For demonstration purposes, store the JWT in ~/.cnc-jwt
    echo $response > $CNC_JWT_FILE
 
}
get_jwt

Example Script Environment Variables

The example scripts define a set of environment variables required to run the use case scripts:

  1. CNC server host, port, and user credentials are defined in cnc-collections-api-examples/env.
  2. API endpoint root contexts are defined in cnc-collections-api-examples/cnc-api-commons.sh for reuse
# Standard CNC URL ROOT CONTEXTS
# Alarms and Events API Endpoint Root Context
export CNC_COLLECTION_API_CTX="https://$CNC_HOST:$CNC_PORT/crosswork/collection/v1"