JOC API

/job

POST

job (volatile part)

Parameters in the POST body schema

Name	Type	Description	Example	Default
`jobschedulerId`	required, string	JobScheduler Master ID	scheduler
`compact`	optional, boolean	Response has a compact version if this parameter is true		false
`job`	required, string	Path of a job	/sos/reporting/Inventory

Request

Name

Description

Example

Type

Constraints

Default

Headers

X-Access-Token*

Request requires authentication!

550e8400-e29b-11d4-a716-446655440000

string

access_token*

Request requires authentication! This header is deprecated. Please use X-Access-Token

550e8400-e29b-11d4-a716-446655440000

string

Body

application/json

model | example

{
    "title": "jobFilter",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "javaType": "com.sos.joc.model.job.JobFilter",
    "type": "object",
    "required": [
        "jobschedulerId",
        "job"
    ],
    "properties": {
        "jobschedulerId": {
            "type": "string",
            "pattern": "^[^/\\<>?:\"|*]*$",
            "maxLength": 100
        },
        "job": {
            "description": "absolute path based on live folder of a JobScheduler object.",
            "type": "string",
            "pattern": "^(/|(/[^/\\<>?:\"|*]+)+)$",
            "maxLength": 255
        },
        "compact": {
            "description": "controls if the object view is compact or detailed",
            "type": "boolean",
            "default": false
        },
        "compactView": {
            "type": "boolean",
            "default": false
        }
    }
}

{ "jobschedulerId": "scheduler", "compact": true, "job": "/sos/housekeeping/scheduler_restart" }

{
    "jobschedulerId": "scheduler",
    "compact": true,
    "job": "/sos/housekeeping/scheduler_restart"
}

Responses

Code	Description	Body
200	Each job can have a compact or detailed response. It depends on the parameter `compact`. Required fields are surveyDate path name state stateText ordersSummary (only for order jobs) numOfRunningTasks numOfQueuedTasks The compact view have further optional fields locks configurationStatus error The detailed view has the following required fields in addition to the compact view allTasks allSteps The detailed view has the following optional fields in addition to the compact view runningTasks taskQueue params nextStartTime delayUntil (only for standalone jobs) A job object as child of a job chain node in the response have only the following required fields path state and one optional field configurationStatus	application/json model \| example { "title": "job with delivery date (volatile part)", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.job.JobV200", "type": "object", "properties": { "deliveryDate": { "description": "Date time. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "job": { "javaType": "com.sos.joc.model.job.JobV", "type": "object", "oneOf": [{ "description": "as child of nodes only path and state are required; only configurationStatus is optional", "required": [ "path", "state" ] }, { "description": "parameter compact=true; only locks and configurationStatus are optional", "required": [ "surveyDate", "path", "name", "state", "stateText", "ordersSummary", "numOfRunningTasks", "numOfQueuedTasks", "runTimeIsTemporary" ] }, { "description": "parameter compact=false or undefined; all other fields below are optional", "required": [ "surveyDate", "path", "name", "state", "stateText", "ordersSummary", "numOfRunningTasks", "numOfQueuedTasks", "runTimeIsTemporary", "allTasks", "allSteps" ] }], "properties": { "surveyDate": { "description": "Current date of the JobScheduler Master/Agent. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "path": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "name": { "type": "string" }, "orderQueue": { "description": "Only for /job/orderQueue", "type": "array", "items": { "javaType": "com.sos.joc.model.order.OrderV", "type": "object", "allOf": [{ "description": "compact=true then ONLY path, id, jobChain, _type, surveyDate, state, processingState, runTimeIsTemporary, job(except blacklisted orders) are required and only title, processedBy, configurationStatus are optional", "required": [ "path", "orderId", "jobChain", "surveyDate", "state", "processingState", "_type", "runTimeIsTemporary" ] }, { "oneOf": [{ "description": "pending order", "required": [ "nextStartTime" ] }, { "description": "running order", "required": [ "historyId", "startedAt", "taskId", "inProcessSince" ] }, { "description": "suspended, waitingForResource, blacklist order", "required": [ "historyId", "startedAt" ] }, { "description": "setback order", "required": [ "historyId", "startedAt", "setback" ] }] }], "properties": { "path": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "orderId": { "type": "string" }, "jobChain": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "priority": { "type": "integer", "minimum": 0 }, "params": { "type": "array", "items": { "javaType": "com.sos.joc.model.common.NameValuePair", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255 }, "value": { "type": "string", "pattern": "^(?s)((?!<script( \|>)\|<svg/on).)$" } } } }, "_type": { "javaType": "com.sos.joc.model.order.OrderType", "type": "string", "description": "the type of the order", "enum": [ "PERMANENT", "AD_HOC", "FILE_ORDER" ] }, "surveyDate": { "description": "Current date of the JobScheduler Master/Agent. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "state": { "description": "the name of the node", "type": "string" }, "title": { "type": "string" }, "job": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "stateText": { "type": "string" }, "configurationStatus": { "javaType": "com.sos.joc.model.common.ConfigurationState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "4=ok; 5=replacement_is_standing_by,removing_delayed; 2=error_in_configuration_file,changed_file_not_loaded,resource_is_missing", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.common.ConfigurationStateText", "type": "string", "enum": [ "ERROR_IN_CONFIGURATION_FILE", "CHANGED_FILE_NOT_LOADED", "REMOVING_DELAYED", "RESOURCE_IS_MISSING", "REPLACEMENT_IS_STANDING_BY", "OK" ] }, "message": { "description": "contains e.g. error message", "type": "string" } } }, "endState": { "description": "the name of the end node", "type": "string" }, "processingState": { "javaType": "com.sos.joc.model.order.OrderState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "0=running, 4=active, 3=initialized, 2=under_construction/stopped/not_initialized", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.order.OrderStateText", "type": "string", "enum": [ "PENDING", "RUNNING", "SUSPENDED", "SETBACK", "BLACKLIST", "JOB_NOT_IN_PERIOD", "NODE_DELAY", "WAITING_FOR_LOCK", "WAITING_FOR_PROCESS", "WAITING_FOR_AGENT", "JOB_CHAIN_STOPPED", "NODE_STOPPED", "JOB_STOPPED", "WAITING_FOR_TASK" ] }, "manually": { "type": "boolean" } } }, "nextStartTime": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "nextStartNever": { "type": "boolean" }, "historyId": { "description": "for all orders except pending orders", "type": "string" }, "startedAt": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "processedBy": { "description": "ONLY for running or blacklist order, contains Host/port of an active cluster member or URL of a JobScheduler Agent", "type": "string" }, "taskId": { "description": "ONLY for running order", "type": "string" }, "inProcessSince": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "setback": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "lock": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "processClass": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "runTimeIsTemporary": { "type": "boolean", "default": false }, "documentation": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 } } } }, "allTasks": { "type": "integer", "minimum": 0 }, "allSteps": { "type": "integer", "minimum": 0 }, "state": { "javaType": "com.sos.joc.model.job.JobState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "0=running; 1=pending; 2=not_initialized/waiting_for_agent/stopping/stopped/error, 3=initialized/loaded/waiting_for_process/waiting_for_lock/waiting_for_task/not_in_period, 4=disabled/unknown", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.job.JobStateText", "type": "string", "enum": [ "INITIALIZED", "NOT_INITIALIZED", "LOADED", "PENDING", "RUNNING", "WAITING_FOR_PROCESS", "WAITING_FOR_LOCK", "WAITING_FOR_AGENT", "WAITING_FOR_TASK", "NOT_IN_PERIOD", "STOPPING", "STOPPED", "DISABLED", "ERROR", "UNKNOWN" ] }, "manually": { "type": "boolean" } } }, "stateText": { "type": "string" }, "locks": { "type": "array", "items": { "javaType": "com.sos.joc.model.job.LockUseV", "type": "object", "required": [ "path", "exclusive", "available" ], "properties": { "path": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "available": { "type": "boolean" }, "exclusive": { "type": "boolean" } } } }, "temporary": { "type": "boolean" }, "numOfRunningTasks": { "type": "integer", "minimum": 0 }, "runningTasks": { "type": "array", "items": { "type": "object", "javaType": "com.sos.joc.model.job.RunningTask", "description": "task object of an order job which is running", "required": [ "taskId", "startedAt" ], "properties": { "taskId": { "type": "string" }, "pid": { "type": "integer" }, "startedAt": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "enqueued": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "idleSince": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "steps": { "type": "integer" }, "_cause": { "description": "For order jobs only cause=order possible", "javaType": "com.sos.joc.model.job.TaskCause", "type": "string", "enum": [ "NONE", "MIN_TASKS", "PERIOD_ONCE", "PERIOD_SINGLE", "PERIOD_REPEAT", "QUEUE", "QUEUE_AT", "DIRECTORY", "DELAY_AFTER_ERROR", "ORDER" ] }, "order": { "description": "Only relevant for order jobs; cause=order resp.", "javaType": "com.sos.joc.model.job.OrderOfTask", "type": "object", "required": [ "path", "orderId", "jobChain", "state" ], "properties": { "path": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "orderId": { "type": "string" }, "jobChain": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "title": { "type": "string" }, "state": { "description": "name of the current node", "type": "string" }, "inProcessSince": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" } } } } } }, "numOfQueuedTasks": { "type": "integer", "minimum": 0 }, "taskQueue": { "type": "array", "items": { "javaType": "com.sos.joc.model.job.QueuedTask", "type": "object", "required": [ "taskId", "enqueued" ], "properties": { "taskId": { "type": "string" }, "enqueued": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "plannedStart": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" } } } }, "params": { "type": "array", "items": { "javaType": "com.sos.joc.model.common.NameValuePair", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255 }, "value": { "type": "string", "pattern": "^(?s)((?!<script( \|>)\|<svg/on).)$" } } } }, "configurationStatus": { "javaType": "com.sos.joc.model.common.ConfigurationState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "4=ok; 5=replacement_is_standing_by,removing_delayed; 2=error_in_configuration_file,changed_file_not_loaded,resource_is_missing", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.common.ConfigurationStateText", "type": "string", "enum": [ "ERROR_IN_CONFIGURATION_FILE", "CHANGED_FILE_NOT_LOADED", "REMOVING_DELAYED", "RESOURCE_IS_MISSING", "REPLACEMENT_IS_STANDING_BY", "OK" ] }, "message": { "description": "contains e.g. error message", "type": "string" } } }, "error": { "javaType": "com.sos.joc.model.common.Err", "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "pattern": "^[^<>]*$", "maxLength": 255 }, "message": { "type": "string" } } }, "ordersSummary": { "description": "only relevant for order jobs and is empty if job's order queue is empty", "javaType": "com.sos.joc.model.order.OrdersSummary", "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "suspended": { "type": "integer", "minimum": 0 }, "setback": { "type": "integer", "minimum": 0 }, "waitingForResource": { "type": "integer", "minimum": 0 }, "blacklist": { "type": "integer", "minimum": 0 } } }, "nextStartTime": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "nextStartNever": { "type": "boolean" }, "delayUntil": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "runTimeIsTemporary": { "type": "boolean", "default": false } } } } } { "deliveryDate": "2016-09-23T11:13:22Z", "job": { "nextPeriodBegin": "", "name": "JobA", "numOfQueuedTasks": 0, "allTasks": 0, "stateText": "", "state": { "_text": "PENDING", "severity": 1 }, "numOfRunningTasks": 0, "path": "/examples/55_JobSchedulerLaunchQueue/01_JQLJobChain1/JobA", "surveyDate": "2016-09-23T11:13:32Z", "allSteps": 0 } } { "deliveryDate": "2016-09-23T11:13:22Z", "job": { "nextPeriodBegin": "", "name": "JobA", "numOfQueuedTasks": 0, "allTasks": 0, "stateText": "", "state": { "_text": "PENDING", "severity": 1 }, "numOfRunningTasks": 0, "path": "/examples/55_JobSchedulerLaunchQueue/01_JQLJobChain1/JobA", "surveyDate": "2016-09-23T11:13:32Z", "allSteps": 0 } }
401	Unauthorized!	application/json model \| example { "title": "security", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "isAuthenticated" ], "properties": { "user": { "type": "string" }, "accessToken": { "type": "string" }, "message": { "type": "string" }, "hasRole": { "type": "boolean", "default": false }, "isAuthenticated": { "type": "boolean" }, "isPermitted": { "type": "boolean", "default": false }, "sessionTimeout": { "type": "integer", "default": 1800 }, "enableTouch": { "type": "boolean", "default": true } } } { "user": "root", "message": "Oops!", "hasRole": false, "isAuthenticated": false, "isPermitted": false } { "user": "root", "message": "Oops!", "hasRole": false, "isAuthenticated": false, "isPermitted": false }
403	Forbidden! The user doesn't have sufficient permissions for 'job'	application/json model \| example { "title": "security", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "isAuthenticated" ], "properties": { "user": { "type": "string" }, "accessToken": { "type": "string" }, "message": { "type": "string" }, "hasRole": { "type": "boolean", "default": false }, "isAuthenticated": { "type": "boolean" }, "isPermitted": { "type": "boolean", "default": false }, "sessionTimeout": { "type": "integer", "default": 1800 }, "enableTouch": { "type": "boolean", "default": true } } } { "user": "root", "message": "You don't have sufficient permissions for ...", "hasRole": false, "isAuthenticated": true, "isPermitted": false } { "user": "root", "message": "You don't have sufficient permissions for ...", "hasRole": false, "isAuthenticated": true, "isPermitted": false }
420	'job' failed!	application/json model \| example { "title": "error object with delivery date", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.common.Err420", "type": "object", "required": [ "deliveryDate", "error" ], "properties": { "deliveryDate": { "description": "Date time. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "surveyDate": { "description": "is also required for permanent or volatile requests", "type": "string", "format": "date-time" }, "error": { "javaType": "com.sos.joc.model.common.Err", "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "pattern": "^[^<>]*$", "maxLength": 255 }, "message": { "type": "string" } } } } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "job failed!" } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "job failed!" } }
440	Login Timeout! The client's session has expired and must log in again.	application/json model \| example { "title": "security", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "isAuthenticated" ], "properties": { "user": { "type": "string" }, "accessToken": { "type": "string" }, "message": { "type": "string" }, "hasRole": { "type": "boolean", "default": false }, "isAuthenticated": { "type": "boolean" }, "isPermitted": { "type": "boolean", "default": false }, "sessionTimeout": { "type": "integer", "default": 1800 }, "enableTouch": { "type": "boolean", "default": true } } } { "user": "root", "message": "Session has expired. Please log in again", "hasRole": false, "isAuthenticated": false, "isPermitted": false } { "user": "root", "message": "Session has expired. Please log in again", "hasRole": false, "isAuthenticated": false, "isPermitted": false }