Getting Started

TThis guide provides example workflows for using the CNC Fault API. It is intended for network administrators and developers integrating external systems with CNC to manage faults and alarms effectively. The scenarios and examples in this guide demonstrate workflows for fault management, including acknowledging, unacknowledging, clearing, and annotating alarms. These workflows can help maintain network health and ensure prompt responses to potential issues.

Prerequisites

Before using the examples in this guide, ensure that:

1. CNC is set up with the required release version and applications.
2. NSO is configured and integrated with CNC.
3. Devices are onboarded in CNC. For detailed setup instructions, refer to the Crosswork Network Controller Installation and Administration guides.

Download and set up example scripts

Follow these instructions to set up the scripts to execute against the target CNC setup.

1. Download cnc-fault-api-examples.tar.gz and unzip in user home directory for the example scripts used in this guide.
   • After unzipping cnc-fault-api-examples.tar.gz, you should see a folder containing example scripts, environment files, one input and output dir.
2. Edit cnc-fault-api-examples/env file to update the target CNC server host, port and user credentials
   • If you encounter errors while running the scripts, ensure that the CNC server host, port, and credentials are correctly configured in the env file.
3. Invoke the get-cnc-jwt.sh to obtain the jwt for authenticating the api calls
4. Invoke each usecase script after optionally updating the input files according to the cnc environemnt.

Authentication and Authorization

Accessing the CNC Northbound (NB) API requires JWT-based authentication and role-based access control (RBAC). JWT tokens can be obtained using a two-step process. API-level access is controlled by RBAC policies configured in CNC.

Script Details

get_jwt() {
    #The get_jwt\(\) script retrieves a JWT in two steps:
    #It obtains a Ticket Granting Ticket (TGT) using the CNC server credentials.
    #It exchanges the TGT for a JWT, which is then stored in a file for use in API calls.
 
    # 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 required for running the use-case scripts. These variables include CNC server details, user credentials, and root contexts for API endpoints. Ensure that you update the environment variables in the files as indicated below:

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

# Standard CNC URL ROOT CONTEXTS
# Alarms and Events API Endpoint Root Context
# CNC_FAULT_API_CTX: Base URL for the CNC Fault API used for alarms and events.
export CNC_FAULT_API_CTX="https://$CNC_HOST:$CNC_PORT/crosswork/alarm/v1"