Create Template Collection Job - Crosswork Network Controller 7.1 APIs

{"type":"api","title":"Create Template Collection Job","meta":{"id":"/apps/pubhub/media/crosswork-network-controller-7-1/f445c17e25a1120e8fbde4bd413083d0fd88b2b3/b44e8ba1-6566-34bf-b4f1-d28c15d76254","info":{"title":"Crosswork Collection Service APIs","description":"Crosswork Collector Services APIs manage application intents for collection jobs across multiple devices and different collection types, including SNMP, CLI, TRAP, MDT, GNMI, and SYSLOG.","version":"1.0.0","contact":{"name":"Crosswork Team, Cisco","email":"support@cisco.com"},"license":{"name":"Cisco Software License Agreement","url":"http://www.cisco.com/public/sw-license-agreement.html"}},"x-parser-conf":{"overview":{"markdownPath":"reference/INFRA/COLLECTIONS/collection-service-overview.md"}},"swagger":"2.0","basePath":"/crosswork/collection/v1","schemes":["https","http"],"securityDefinitions":{"bearerAuth":{"type":"apiKey","description":"bearer auth","name":"Authorization","in":"header"}}},"spec":{"summary":"Create Template Collection Job","description":"Use CreateTemplateCollectionJob to a create a collection job for a single device using sensor templates.\nA sensor template is a first-class object that contains a templatized sensor path (that is, a GNMI path or set of parametrized CLI commands, in addition to collection type and parameters applicable to the sensor path). \nAn application sends a request with a list of sensor templates and associated parameters as applicable to the device.\nThe ApplicationContext is expected to be globally unique. The app_context is the \u003cdeviceuuid\u003e_\u003ccollect_type\u003e.\nYou can associate an application context with only one CollectType at a time. \nRecreation of the application context will result in failure.\nOnce created, any future updates to the template collection job on the device should be done by submitting a patch request using PatchTemplateCollectionJob.\nYou can’t change a collection job's collect type and device once it is accepted into the system; successive create calls will result in rejection unless you first call DeleteTemplateCollectionJob. \nYou are responsible for specifying a valid template_id and corresponding parameter combination as applicable to the device. \nThe DeviceId is the UUID of the device as specified in Crosswork Device Lifecycle Manager (DLM).","operationId":"CollectionService_CreateTemplateCollectionJob","responses":{"200":{"description":"OK. The request was successful. The result is contained in the response body","schema":{"type":"object","properties":{"result":{"type":"object","properties":{"request_result":{"description":"The result values indicates whether the request was accepted or rejected, not the outcome of the work itself.","type":"string","enum":["UNKNOWN_RESULT","REJECTED","ACCEPTED"],"default":"UNKNOWN_RESULT","$$ref":"#/definitions/collection_serviceRequestResult"},"error":{"description":"A text message describing the reason for rejection. It can be safely passed on to the operator through logs or the UI.","type":"object","properties":{"error":{"type":"string","description":"Message is a textual description of the reason for rejection. You can safely pass it on to the operator through logs or the UI."}},"title":"Error associated with an object","$$ref":"#/definitions/collection_serviceError"}},"description":"Result is used to convey whether an operation (individual or in a batch) has been accepted or rejected.\nFor sync APIs, an error or rejection indicates failure of the operation.\nA string error message accompanies rejection to support troubleshooting.\nFor notification objects, rejection represents failure to do intended operation.","$$ref":"#/definitions/collection_serviceResult"}},"example":{"result":{"request_result":"ACCEPTED","error":{"error":""}}},"$$ref":"#/definitions/collection_serviceCreateTemplateCollectionJobResponse"}},"default":{"description":"An unexpected error response.","schema":{"type":"object","properties":{"result":{"type":"object","properties":{"request_result":{"description":"The result values indicates whether the request was accepted or rejected, not the outcome of the work itself.","type":"string","enum":["UNKNOWN_RESULT","REJECTED","ACCEPTED"],"default":"UNKNOWN_RESULT","$$ref":"#/definitions/collection_serviceRequestResult"},"error":{"description":"A text message describing the reason for rejection. It can be safely passed on to the operator through logs or the UI.","type":"object","properties":{"error":{"type":"string","description":"Message is a textual description of the reason for rejection. You can safely pass it on to the operator through logs or the UI."}},"title":"Error associated with an object","$$ref":"#/definitions/collection_serviceError"}},"description":"Result is used to convey whether an operation (individual or in a batch) has been accepted or rejected.\nFor sync APIs, an error or rejection indicates failure of the operation.\nA string error message accompanies rejection to support troubleshooting.\nFor notification objects, rejection represents failure to do intended operation.","$$ref":"#/definitions/collection_serviceResult"}},"example":{"result":{"request_result":"REJECTED","error":{"error":"empty request"}}},"$$ref":"#/definitions/createtemplatecollectionjobErrorResponse"}}},"parameters":[{"name":"body","in":"body","description":"Create Template Collection Job.","required":true,"schema":{"type":"object","properties":{"create_collection_template_job":{"title":"CollectionJobConfiguration describing a template collection job, with ApplicationContext as key","type":"object","properties":{"application_context":{"description":"The application_context is a handle that uniquely identifies your application's collection job. It serves as the key to the object on which CRUD operations are performed.\nThe combination of application_id and context_id should be unique globally.","type":"object","properties":{"application_id":{"type":"string","description":"The application_id is a unique ID that identifies your application. Crosswork applications always prefix the application_id with “cw“."},"context_id":{"type":"string","description":"The context_id is a unique ID that identifies your application subscription across all collection jobs. We recommend that you use the device UUID for the context_id."}},"$$ref":"#/definitions/collection_serviceApplicationContext"},"collection_mode":{"description":"The style of collection: persistent or non-persistent.\nNote that Recurrent and Transient jobs are not applicable to any collection that involves a device configuration change.","type":"object","properties":{"lifetime_type":{"title":"The lifetime of the job","type":"string","enum":["UNKNOWN_TEMPORAL_TYPE","APPLICATION_MANAGED","CALENDAR_MANAGED","AUTO_DELETE_AFTER_N_SAMPLES","APPLICATION_MANAGED_WITH_AUTO_DELETE_ON_DEVICE_DELETE"],"default":"UNKNOWN_TEMPORAL_TYPE","description":"- UNKNOWN_TEMPORAL_TYPE: Invalid Lifetime\n - APPLICATION_MANAGED: The application manages the creation and deletion of the collection job.\n - CALENDAR_MANAGED: A calendaring service tied to a calendar schedule manages the creation and deletion of the collection job.\nThis JobLifetimeType is currently not supported.\n - AUTO_DELETE_AFTER_N_SAMPLES: The collection job is automatically deleted after N collections.\n - APPLICATION_MANAGED_WITH_AUTO_DELETE_ON_DEVICE_DELETE: The application manages the creation and deletion of the collection job, but the job is deleted and cleaned up automatically if the associated device is deleted.","$$ref":"#/definitions/collection_serviceJobLifetimeType"},"collector_type":{"title":"Collection Type","type":"string","enum":["UNKNOWN_COLLECTOR","MDT_COLLECTOR","SNMP_COLLECTOR","CLI_COLLECTOR","TRAP_COLLECTOR","GNMI_COLLECTOR","SYSLOG_COLLECTOR"],"default":"UNKNOWN_COLLECTOR","$$ref":"#/definitions/common_collection_dataCollectionType"},"schedule_id":{"type":"string","description":"Calendar-ID: Calendar schedule to follow for CALENDAR_DRIVEN jobs. Currently NOT supported."},"n_collections":{"type":"integer","format":"int64","description":"The number of collections to run before auto-deletion.\nUsed only when lifetime_type is AUTO_DELETE_AFTER_N_SAMPLES.\nThe number of collections represents the cadence cycle of each collection, irrespective of the outcome (SUCCESS, FAILED).\nSupported only for collections where the collector intiates the connection to the device (that is, SNMP or CLI)."},"track_collect_n_job":{"type":"boolean","description":"Job response tracking flag, sets the tracking option to true or false. The default is false.\nThis flag is relevant only to transient collection jobs."}},"$$ref":"#/definitions/collection_serviceCollectionMode"},"device_id":{"type":"string","description":"The ID of the device for which collection needs to be set up."},"sensor_template_input_configs":{"type":"array","items":{"type":"object","properties":{"sensor_template_id":{"type":"string","title":"Specify the sensor template ID to be used for collection"},"cadence_in_millisec":{"type":"string","format":"uint64","title":"Input Cadence"},"parameter_values":{"title":"Sensor template parameter combination values","type":"object","properties":{"template_param_values":{"type":"array","items":{"type":"object","properties":{"template_param_value":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"bytes_value":{"type":"string","format":"byte"},"string_value":{"type":"string"},"bool_value":{"type":"boolean"},"uint32_value":{"type":"integer","format":"int64"},"uint64_value":{"type":"string","format":"uint64"},"sint32_value":{"type":"integer","format":"int32"},"sint64_value":{"type":"string","format":"int64"},"double_value":{"type":"number","format":"double"},"float_value":{"type":"number","format":"float"},"null_value":{"type":"boolean"},"list_value":{"type":"object","properties":{"value":{"type":"array","items":{"type":"object","properties":{"bytes_value":{"type":"string","format":"byte"},"string_value":{"type":"string"},"bool_value":{"type":"boolean"},"uint32_value":{"type":"integer","format":"int64"},"uint64_value":{"type":"string","format":"uint64"},"sint32_value":{"type":"integer","format":"int32"},"sint64_value":{"type":"string","format":"int64"},"double_value":{"type":"number","format":"double"},"float_value":{"type":"number","format":"float"},"null_value":{"type":"boolean"}},"$$ref":"#/definitions/common_collection_dataValue"},"title":"list items must be of same type"}},"$$ref":"#/definitions/common_collection_datalist"}},"title":"Generic Key value message","$$ref":"#/definitions/common_collection_dataKeyValue"},"title":"Parameters values for sensor template variables"}},"title":"Specify parameter values for template parameters","$$ref":"#/definitions/common_collection_dataParameterValue"},"title":"Parameters value combinations set for sensor template variables\nfor ex: \n\"template_param_values\": [\n {{\"vrf\":\"vrf1\"}, {\"neighbor-ip\":\"ip1\"}},\n {{\"vrf\":\"vrf1\"}, {\"neighbor-ip\":\"ip2\"}},\n {{\"vrf\":\"vrf1\"}, {\"neighbor-ip\":\"ip3\"}}\n ]"}},"$$ref":"#/definitions/common_collection_dataParameterValues"}},"title":"SensorTemplateInputConfig contains a sensor template, cadence and parameter values","$$ref":"#/definitions/collection_serviceSensorTemplateInputConfig"},"title":"SensorTemplateInputConfig represents a sensor template and corresponding collection parameters applicable to the device"},"sensor_template_output_configs":{"type":"array","items":{"type":"object","properties":{"sensor_template_id":{"type":"string","title":"Specify Sensor template"},"destination":{"type":"array","items":{"type":"object","properties":{"destination_id":{"type":"string","title":"Unique identifier for a Destination Provider in Inventory"},"context_id":{"type":"string","description":"Destination context identifier.\nIt could be topic name if the destination is message bus.\nThe combination of destination_id and context_id needs to be unique for a Destination.\nWhat context id means depends on the destination type of the destination provider.\nIf \"GRPC\" is the destination type, context_id is not used and will be ignored."},"destination_name":{"type":"string","description":"The name of the destination. Not used during write operations, but optionally filled when using GET APIs.\nIt maps to the destination provider name in Crosswork Device Lifecycle Manager (DLM)."}},"description":"Use the destination identifier to uniquely identify a destination.\nThe output encoding format for the destination is derived from the Inventory destination_id.","$$ref":"#/definitions/collection_serviceDestination"},"description":"The destinations to which sensor data is written."}},"title":"SensorTemplateOutputConfig contains a sensor template and its destination details","$$ref":"#/definitions/collection_serviceSensorTemplateOutputConfig"},"description":"SensorTemplateOutputConfig represents a sensors template and its destination."}},"description":"Use TemplateCollectionJobConfiguration to create template collection jobs for applications with high-cardinality collection jobs. (Internal Use ONLY.)\nTo support this set of requirements, the collection service uses the concept of templatized sensors that specify sensor paths, cadence,\nand parameters to be substituted at runtime for collection per device. Applications must create Sensor Templates per CollectType first.\nThey can then create jobs per device with the corresponding templatized sensor and parameters specified.\nApplications create a single job, per device and per CollectType, where all templates for the specific collection type and their parameters are specified. \nNo job status or job metrics will be available for these type of jobs. \nTemplateCollectionJobConfiguration is used to \"CREATE\" Template collection jobs\nThe key is device_id, application_context (app_id,collection_type).","$$ref":"#/definitions/collection_serviceTemplateCollectionJobConfiguration"}},"example":{"create_collection_template_job":{"application_context":{"application_id":"proto_template_test_app","context_id":"proto_template_test_context"},"collection_mode":{"lifetime_type":"APPLICATION_MANAGED_WITH_AUTO_DELETE_ON_DEVICE_DELETE","collector_type":"CLI_COLLECTOR"},"device_id":"8e326ec1-5562-40e5-92d6-eefd0d646603","sensor_template_input_configs":[{"sensor_template_id":"template-test-version-template","cadence_in_millisec":"60000","parameter_values":{"template_param_values":[{"template_param_value":[{"key":"command","string_value":"test"}]}]}}],"sensor_template_output_configs":[{"sensor_template_id":"template-test-version-template","destination":[{"destination_id":"c2a8fba8-8363-3d22-b0c2-a9e449693fae","context_id":"dest_context2"}]}]}},"title":"CreateTemplateCollectionJobRequest","$$ref":"#/definitions/collection_serviceCreateTemplateCollectionJobRequest"}}],"tags":["CollectionService"],"__originalOperationId":"CollectionService_CreateTemplateCollectionJob","consumes":["application/json"],"produces":["application/json"],"method":"post","path":"/templatecollectionjob"}}