Create Collection Job

Scenario Overview

A collection job allows you to gather data from devices using various methods (e.g., SNMP, CLI, GNMI). This data can then be used for monitoring, analytics, or other operations within CNC.

The CreateCollectionJob API allows you to create a collection job for a set of devices. An application sends a request specifying a list of sensor paths, where each path can be identified by:

A YANG model path (for example, Cisco-IOS-XR-infra-statsd-oper:infra-statistics/interfaces/interface/latest/data-rate, which identifies the device OS type and YANG model). An SNMP YANG path (for example, SNMPv2-MIB:SNMPv2-MIB/system/sysName or OID:1.2.3.4). A CLI command (for example, show clock). A Trap YANG path (for example, snmp-trap-raw-oper:traps/data). A Syslog path. A GNMI path. In addition, you can specify a cadence for push or poll operations. Note that the cadence specified in your request may be optimized or overwritten if other applications also request the same path.

The CreateCollectionJob API configures sensor paths in the Collection Service based on the application context, for either a list of devices or a single device group.

Key Points to Consider

The following considerations apply:

• The ApplicationContext must be globally unique and can only be associated with one CollectType at a time.
• Recreating the ApplicationContext during the NOT_READY, TERMINATING, or TERMINATION_FAILED phases will result in failure.
• The Collection Service optimizes cadence requests to the lowest common denominator across all services requesting the same path.
• A collection job's CollectType and device set cannot be changed once the request is accepted.
• Successive Create calls will result in updates to the devices unless you perform a DeleteCollectionJob first.
• Ensure that the proper paths associated with the specified CollectType are included in your request.
• Device IDs must match the UUIDs specified in the Crosswork Device Lifecycle Manager (DLM).
• Device groups are identified using device tags defined in DLM.

The operations in the following API references are used in this example.

• Create Collection Job API

Prerequisites

Before running this example, ensure that you have obtained an access token. Refer to the 'Getting Started' section for instructions.

Create Collection Job

To create a collection job, update the create_collection_job.json input file with the required job details (for example, device IDs, sensor paths, and cadence), then run the create_collection_job.sh script from the example directory.

Navigate to the cnc-collections-api-examples directory and run the create_collection_job.sh script using the following command:

cd cnc-collections-api-examples;./create_collection_job.sh

Script Details

#!/bin/bash
# Import common API functions and environment variables
# This script reads input from the .json file located in the input directory.
# Upon successful execution, the output is saved to the .json file in the output directory.
. ./cnc-api-common.sh

create_collection_job() {
    # Step 1: Ensure the CNC JWT is obtained by running the get-cnc-jwt.sh script.
    # Read the JWT from the file and export it as the AUTH_TOKEN_HDR environment variable.
     export_jwt

    # STEP 2 :  Update input json with details of job to be created in the file CNC_API_INPUT
    # STEP 3 :  Trigger the createCollectionJob API
    # STEP 4 :  Store the output in CNC_API_OUTPUT file

    CNC_COLLECTION_API=$CNC_COLLECTION_API_CTX/collectionjob
    CNC_API_INPUT="@$PRJ/input/create_collection_job.json"	 
    CNC_API_OUTPUT="$PRJ/output/create_collection_job.json"

    # Step 5: Send a PUT request to create the collection job and store the response in the output file.
    http_put $CNC_COLLECTION_API $CNC_API_INPUT $CNC_API_OUTPUT
    
}
create_collection_job