Getting Started

This guide provides example usage of the CNC SWIM API based on common user scenarios. The examples in this guide are for demonstration purposes and can 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 SWIM-related operations, including collection, distribution, and job management.

Prerequisites

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

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

Download and set up example scripts

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

1. Download cnc-swim-api-examples.tar.gz and unzip it in the user's home directory.
2. After unzipping cnc-swim-api-examples.tar.gz, you should see a folder containing example scripts image_query.sh, image_collection.sh, image_distribution.sh, image_activation.sh, device_commit.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.
3. Edit the cnc-swim-api-examples/env file to update the CNC server host, port, and user credentials.
4. Run get-cnc-jwt.sh to obtain the JWT for authenticating API calls.
5. Run each use case script, optionally updating the input files to match the CNC environment.

Authentication and Authorization

Accessing the CNC SWIM API requires authentication and authorization. CNC uses JWT-based authentication, which can be obtained using a two-step process. Each API's authorization is controlled by 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 1. 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 2: 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 3. 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-swim-api-examples/env.
2. API endpoint root contexts are defined in cnc-swim-api-examples/cnc-api-commons.sh for reuse.

# Standard CNC URL ROOT CONTEXTS
# SWIM API Endpoint Root Context
export CNC_SWIM_API_CTX="https://$CNC_HOST:$CNC_PORT/crosswork/swim/v1"