Retrieve Collection Job Task Status

Scenario Overview

Retrieving the task status for a collection job provides detailed insights into the progress and results of data collection from devices. This information is useful for troubleshooting, monitoring, and validating collection operations.

The GetCollectionTaskStatus API provides a detailed, granular view of the task status for each device within a collection job. Task status is reported on a per-device, per-sensor basis, indicating whether collection occurred either from the device to the collector or from the collector to the destinations.

Only the most recent reported values are retained, and the status is updated based on on-change notifications in the backend.

This API requires the CollectionTaskStatusSection to specify either Collections or Distributions:

• Collections: Refers to data collected from devices.
• Distributions: Refers to data sent from the collector to destinations. If any failures occurred during input or output, error messages will describe the failures and device status. If no status is available from the collector, the response may be empty.

You must supply either an ApplicationContext or a device ID with the request to retrieve the task status.

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

• Retrieve Collection Job Task Status API

Prerequisites

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

Get Collection Job Task Status

To retrieve the task status for a collection job, update the collection_job_taskstatus_query.json input file with the required details (e.g., ApplicationContext or device ID), then run the collection_job_taskstatus_query.sh script from the example directory.

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

cd cnc-collections-api-examples;./collection_job_taskstatus_query.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

collection_job_taskstatus_query() {
    # 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 for which we want task status in the file CNC_API_INPUT
    # STEP 3 :  Retrieve task status for collection job from the server and store the output in CNC_API_OUTPUT file

    CNC_COLLECTION_API=$CNC_COLLECTION_API_CTX/collectionjob/taskstatus/query
    CNC_API_INPUT="@$PRJ/input/collection_job_taskstatus_query.json"	 
    CNC_API_OUTPUT="$PRJ/output/collection_job_taskstatus_query.json"

    # Step 4: Send a POST request to retrieve the task status and store the response in the output file.
    http_post $CNC_COLLECTION_API $CNC_API_INPUT $CNC_API_OUTPUT
    
}
collection_job_taskstatus_query