jobId

string

Specify the job GUID to identify the job.

name

(optional)

string

The name of the job.

During job creation, if the name parameter is not set, then name will be automatically set to the job globally unique identifier (GUID).

Example of setting the job name:

   {"name": "my-sample-job"}

If you do not want to specify any parameters for creating a job, you must still provide an empty JSON body element when using the POST operation:

   POST /receive/metrics/jobs

   { }

parameters

(optional, depending on the metrics custom endpoint)

Array of name-value pairs

The job parameters element is an array of "name", "value" pairs that you can provide in the request body.

The "parameters" element needs to be provided in the following JSON format:

"parameters":

[

   {"name": <string>,

    "value": <string>},

    ...

 ]

The parameters required during job creation is dependent on the metrics custom endpoint used. Below is an example of setting optional parameters during job creation:

In an update parameters request, you need to provide the complete list of parameters, including the updated ones and the non-updated ones. The new list of parameters used for the update command overwrites the entire old list of parameters.

file

multipart/form-data

To upload a file into an existing job, attach the file into the file form-data key in the body of the POST request.

lines_to_tail_in_logs

(optional)

integer

Specify the number of lines from the bottom of the log files to display.

For example, to display the last 100 lines of logs, you would specify the following:

  lines_to_tail_in_logs=100

The default value of -1 denotes that the entire log files will be displayed.

execute

(optional)

string

The job execute option specifies whether the job should be executed with the uploaded file.

Possible values for the execute option:

• true—The job is executed at the scheduled time provided by the time parameter. If time is not set and you specify execute=true, then the job is executed immediately.
• false—The file is uploaded with no job execution. This is the default behavior if no execute option is specified. You can use the execute=false option to upload multiple files to the job before executing the bulk job.

time

(optional)

string

The job time option is used in conjunction with the execute option to specify when the job is to be executed next.

The time value must be in HH:mm 24-hr format.

file

(optional)

string

The file option allows you to download a specific file.

You must specify the exact download filename in order for this operation to succeed. For example, to download a file named "output.txt", the following call is made:

GET /receive/metrics/jobs/455fa7bb-10fb-41a7-96a9-f4b13bd7a05c/download/files?file=output.txt

Here is an example to download a log file named "output.log":

GET /receive/metrics/jobs/455fa7bb-10fb-41a7-96a9-f4b13bd7a05c/logs/files?file=output.log

jobId

string

The globally unique identifier (GUID) assigned to the job.

name

string

The name of the job.

During job creation, if the [name] parameter is not set, then it will be automatically set to the job globally unique identifier (GUID).

parameters

Array of

• name
• value

The job parameters element is an array of "name", "value" pairs that is dependent on the data management tool used. The Metrics tool is the default data management tool for the Receive Metrics Jobs resource.

audit_info

• audit name
• audit date
• audit path
• target audit
• target failed
• audit end date
• load date
• load end date
• load status

If the job has uploaded metric files which have been audited, the last audit details are displayed.

The audit_info element displays the following information:

"audit_info": {

    "audit_name": <string>,

    "audit_date": <string>,

    "audit_path": <string>,

    "target_audit": <int>,

    "targets_failed": <int>,

    "audit_end_date": <string>,

    "load_date": <string>,

    "load_end_date": <string>,

    "load_status": <string>,

}

input_files

Array of:

• name
• size

If the job has uploaded files, details of those files are displayed:

lines_to_tail_in_logs

integer

Specifies the number of lines from the bottom of the log file to display.

The default value of -1 denotes that the entire log file will be displayed.

logs

• name
• contents

Contains the details of each file in the job's log directory. For each log file available, the following information is displayed:

• name—displays the log filename;
• contents—displays the tail end contents of the log file, depending on the lines_to_tail_in_logs parameter.

job_status

• code
• message
• files

An element that provides the status of the executed Metrics job operation, which contains the following items:

• code—Displays the status code from the statuscode.txt file in the job status folder. If the statuscode.txt file does not exist, then the last audit load code is displayed:
• 0—successful operation;
• -1—an error with loading the job.
• message—Displays the contents of the statusmessage.txt file in the job status folder. If the statusmessage.txt file does not exist, then the last audit load status message is displayed (e.g. Loaded, Loaded_Error).
• files—Displays the details of each non-status file from the job status folder.

The job_status element is displayed in the following form:

{"code": <int>,

"message": <string>,

"files": [

  {

    "name": <string>, // filename

    "size": <int>, /size in bytes

  },

   ...

  ]

}

Below is a response example if there are additional non-status files in the job status folder:

The default Metrics data management tool produces a statusmessage.txt file, a corresponding statuscode.txt file, and other status files in the job status directory for each job execution. The Data Ingestion API framework provides flexibility for a custom data management tool to produce their own status message, code, and files by generating files with the exact name (i.e. statusmessage.txt, statuscode.txt) in the custom tool's job status directory.

Note: File names are case sensitive. Both message and code files must exist in the job status directory for the framework to override the job_status element.

Download Files Response

Download Files

octet-stream zipped file containing files

The response for a file or log download request is an octet-stream zipped file containing all the files produced when executing the job. For a single file download, the zipped file will contain only one file. The suggested filename (in the response Content-Disposition) is in the following format:

• for download logs request:

{jobId}_logs.zip

• for download file request:

{jobId}_download.zip

Where {jobId} is the job GUID.

Messages and Error Handling

message

string

A response message for the request from the job_status element.

The job_status: message string can be one of the following:

• AccessDeniedException: "Access Denied! Unable to create temporary file or directory"—Check file permissions on file system.
• IngestionJobDirectoryDoesNotExistException—Job file structure does not exist in the system.
• IngestionJobDirectoryNotReadbleException—Job file structure permission is possibly set to read-only.
• IngestionJobInvalidArgumentException—Invalid arguments in the file upload request.
• IOException: "There is not enough space on the disk. IO Exception"— Check disk space.
• IOException—Any I/O exception that occurred on the system, such as when the specified filename cannot be found.
• Exception—Any other error that occurred during the processing of the upload request.

status

integer

The status code of the job request.

Possible "status" values are:

• 200—job action successful (i.e. delete action was successful);
• 404—the job does not exist;
• 409—the job is currently running, request action canceled;
• 400—the job files are not accessible or permissions are invalid;
• 500—the job is corrupt or any other exception.

HTTP Code 400

HTTP error

Request is malformed. For example, when the time format is invalid, the following error message is displayed:

HTTP Code 403

HTTP error

"Limit number of active jobs has been reached."

The number of active jobs on the server exceeds the Densify configuration setting of maximum job limit.

HTTP Code 404

HTTP error

The job does not exist in the system.

HTTP Code 500

HTTP error

• "Working directory does not exist."—The Data Ingestion API root working directory does not exist.
• "OS error message."—Failed to create directory structure due to insufficient storage..