JOC API

/jobs/start

POST

Starts jobs

this resource can be used in the GUI for three functions

start task immediatly

start task at (with at)

start task at parametrised (with at and params)

This is only available for standalone jobs.

Parameters in the POST body schema

Name	Type	Description	Example	Default
`jobschedulerId`	required, string	JobScheduler Master ID	scheduler
`jobs`	required, array	Specified the jobs which should be modified and the modification.	[{ "job":"/sos/reporting/Inventory", "at":"now+10" }]
`at`	optional, string field of each `jobs` item	start time in ISO format yyyy-mm-dd HH:MM[:SS] or now or now + HH:MM[:SS] or now + SECONDS	now+10	now
`timeZone`	optional, string field of each `jobs` item	This parameter set the time zone for an absolute time stamp in the `at` parameter. This parameter is ignored for relative times in `at` such as "now+10" See here the list for available time zones.	Berlin/Europe	Time zone of the JobScheduler
`params`	optional, array field of each `jobs` item	Parameters	params:[{"name":"...","value":"..."}]
`environment`	optional, array field of each `jobs` item	Environment variables	environment:[{"name":"...","value":"..."}]
`auditLog`	optional, object	Object which contains `comment`, `timeSpent` and `ticketLink`.	{ "comment":"It was not really necessary!", "timeSpent":2 }
`comment`	optional, string	Field in `auditLog` to comment this action, e.g. the reason.
`timeSpent`	optional, string	Field in `auditLog` to enter the time spent in minutes.	5
`ticketLink`	optional, string	Field in `auditLog` to enter a link to a corresponding ticket.

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": "start job commands",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "javaType": "com.sos.joc.model.job.StartJobs",
    "type": "object",
    "required": [
        "jobschedulerId"
    ],
    "properties": {
        "jobschedulerId": {
            "type": "string",
            "pattern": "^[^/\\<>?:\"|*]*$",
            "maxLength": 100
        },
        "jobs": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.job.StartJob",
                "type": "object",
                "required": [
                    "job"
                ],
                "properties": {
                    "job": {
                        "description": "absolute path based on live folder of a JobScheduler object.",
                        "type": "string",
                        "pattern": "^(/|(/[^/\\<>?:\"|*]+)+)$",
                        "maxLength": 255
                    },
                    "at": {
                        "description": "ISO format yyyy-mm-dd HH:MM[:SS] or now or now + HH:MM[:SS] or now + SECONDS",
                        "type": "string",
                        "pattern": "^(now(\\s*\\+\\s*(\\d{1,2}:\\d{1,2}(:\\d{1,2})?|\\d+)?)?|\\d{4}-\\d{2}-\\d{2}\\s\\d{1,2}:\\d{1,2}(:\\d{1,2})?)$"
                    },
                    "jobStream": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255
                    },
                    "timeZone": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255
                    },
                    "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).)*$"
                                }
                            }
                        }
                    },
                    "environment": {
                        "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).)*$"
                                }
                            }
                        }
                    }
                }
            }
        },
        "auditLog": {
            "javaType": "com.sos.joc.model.audit.AuditParams",
            "type": "object",
            "properties": {
                "comment": {
                    "type": "string",
                    "pattern": "^[^<>]*$",
                    "maxLength": 255
                },
                "timeSpent": {
                    "type": "integer",
                    "minimum": 0
                },
                "ticketLink": {
                    "type": "string",
                    "pattern": "^[^<>]*$",
                    "maxLength": 255
                }
            }
        }
    }
}

{ "jobschedulerId": "scheduler", "jobs": [{ "job": "/test/testJob1", "at": "now" }, { "job": "/sos/housekeeping/scheduler_rotate_log", "at": "now + 60", "params": { "file_age": "7" } }, { "job": "/test/testJob2", "at": "now" }, { "job": "/test/testJob3", "at": "now" }] }

{
    "jobschedulerId": "scheduler",
    "jobs": [{
        "job": "/test/testJob1",
        "at": "now"
    }, {
        "job": "/sos/housekeeping/scheduler_rotate_log",
        "at": "now + 60",
        "params": {
            "file_age": "7"
        }
    }, {
        "job": "/test/testJob2",
        "at": "now"
    }, {
        "job": "/test/testJob3",
        "at": "now"
    }]
}

Responses

Code	Description	Body
200	It returns an ok and a collection of tasks with the new taskId. . This reply code comes only for bulk operations if all commands were successful.	application/json model \| example { "title": "start task response", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.job.StartedTasks", "type": "object", "description": "if ok=true then tasks collection is required", "required": [ "deliveryDate" ], "properties": { "deliveryDate": { "description": "Date time. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "tasks": { "type": "array", "items": { "javaType": "com.sos.joc.model.job.TaskPath200", "type": "object", "required": [ "job", "taskId", "surveyDate" ], "properties": { "job": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "taskId": { "type": "string" }, "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" } } } }, "ok": { "type": "boolean" }, "errors": { "type": "array", "items": { "javaType": "com.sos.joc.model.common.Err419", "type": "object", "required": [ "surveyDate", "path", "code", "message" ], "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 }, "code": { "type": "string" }, "message": { "type": "string" } } } } } } { "deliveryDate": "2016-05-05T21:13:35Z", "ok": true, "tasks": [{ "surveyDate": "2016-05-05T21:13:34Z", "job": "/path/to/job", "taskId": "4711" }] } { "deliveryDate": "2016-05-05T21:13:35Z", "ok": true, "tasks": [{ "surveyDate": "2016-05-05T21:13:34Z", "job": "/path/to/job", "taskId": "4711" }] }
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 'start'	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 }
419	It returns an array of error items for each failed command and the new taskId in an tasks collection for each successful command at bulk operations.	application/json model \| { "title": "start task response", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.job.StartedTasks", "type": "object", "description": "if ok=true then tasks collection is required", "required": [ "deliveryDate" ], "properties": { "deliveryDate": { "description": "Date time. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "tasks": { "type": "array", "items": { "javaType": "com.sos.joc.model.job.TaskPath200", "type": "object", "required": [ "job", "taskId", "surveyDate" ], "properties": { "job": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "taskId": { "type": "string" }, "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" } } } }, "ok": { "type": "boolean" }, "errors": { "type": "array", "items": { "javaType": "com.sos.joc.model.common.Err419", "type": "object", "required": [ "surveyDate", "path", "code", "message" ], "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 }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }
420	'start' 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": "start failed!" } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "start 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 }