JOC API

/jobscheduler/agent_clusters

POST

Collection of JobScheduler Agent Clusters with volatile information

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
`agentClusters`	optional, array	Filters response by a collection of agent cluster specified by its path	[{ "agentCluster":"/agents/galadriel-4445" }]
`state`	optional, integer	0=all Agents of the cluster are running 1=some Agents of the cluster are unreachable but not all 2=all Agents of the cluster are unreachable	2
`regex`	optional, string	Regular expression to filter JobScheduler objects by matching the path.	.*
`folders`	optional, array	collection of folder objects	[{ "folder": "/sos", "recursive": true }]

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": "agent cluster filter",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "javaType": "com.sos.joc.model.jobscheduler.AgentClusterFilter",
    "type": "object",
    "required": [
        "jobschedulerId"
    ],
    "properties": {
        "jobschedulerId": {
            "type": "string",
            "pattern": "^[^/\\<>?:\"|*]*$",
            "maxLength": 100
        },
        "agentClusters": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.jobscheduler.AgentClusterPath",
                "type": "object",
                "required": [
                    "agentCluster"
                ],
                "properties": {
                    "agentCluster": {
                        "description": "absolute path based on live folder of a JobScheduler object.",
                        "type": "string",
                        "pattern": "^(/|(/[^/\\<>?:\"|*]+)+)$",
                        "maxLength": 255
                    }
                }
            }
        },
        "regex": {
            "description": "regular expression to filter JobScheduler objects by matching the path",
            "type": "string",
            "pattern": "^((?!<script( |>)|<svg/on).)*$"
        },
        "state": {
            "type": "integer"
        },
        "compact": {
            "description": "controls if the object view is compact or detailed",
            "type": "boolean",
            "default": false
        },
        "folders": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.common.Folder",
                "type": "object",
                "required": [
                    "folder"
                ],
                "properties": {
                    "folder": {
                        "description": "absolute path based on live folder of a JobScheduler object.",
                        "type": "string",
                        "pattern": "^(/|(/[^/\\<>?:\"|*]+)+)$",
                        "maxLength": 255
                    },
                    "recursive": {
                        "type": "boolean",
                        "default": true
                    }
                }
            }
        }
    }
}

{ "jobschedulerId": "scheduler", "compact": true, "agentClusters": [{ "agentCluster": "/agents/galadriel-4445" }] }

{
    "jobschedulerId": "scheduler",
    "compact": true,
    "agentClusters": [{
        "agentCluster": "/agents/galadriel-4445"
    }]
}

Responses

Code	Description	Body
200	Each agent cluster can have a compact or detailed response. It depends on the parameter `compact`. Required fields are surveyDate path name state maxProcesses numOfAgents _type The compact view doesn't have further optional fields The detailed view has in addition the following required field to the compact view agents The detailed view has the optional field processes	application/json model \| example { "title": "agent clusters", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.jobscheduler.AgentClusters", "type": "object", "required": [ "deliveryDate", "agentClusters" ], "properties": { "deliveryDate": { "description": "Date time. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "agentClusters": { "type": "array", "items": { "javaType": "com.sos.joc.model.jobscheduler.AgentCluster", "type": "object", "oneOf": [{ "description": "if parameter compact=false or undefined", "required": [ "surveyDate", "path", "name", "state", "numOfAgents", "maxProcesses", "_type", "agents" ] }, { "description": "response without agents collection if parameter compact=true, configurationStatus optional", "required": [ "surveyDate", "path", "name", "state", "numOfAgents", "maxProcesses", "_type" ] }], "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" }, "maxProcesses": { "type": "integer", "minimum": 0 }, "_type": { "javaType": "com.sos.joc.model.jobscheduler.AgentClusterType", "type": "string", "description": "the type of agent cluster", "enum": [ "SINGLE_AGENT", "FIX_PRIORITY", "ROUND_ROBIN" ] }, "state": { "javaType": "com.sos.joc.model.jobscheduler.AgentClusterState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "0=all Agents are running, 1=some Agents are unreachable but not all, 2=all Agents are unreachable", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.jobscheduler.AgentClusterStateText", "type": "string", "enum": [ "ALL_AGENTS_ARE_RUNNING", "ONLY_SOME_AGENTS_ARE_RUNNING", "ALL_AGENTS_ARE_UNREACHABLE" ] } } }, "numOfAgents": { "type": "object", "javaType": "com.sos.joc.model.jobscheduler.NumOfAgentsInCluster", "required": [ "any", "running" ], "properties": { "any": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 } } }, "agents": { "type": "array", "items": { "javaType": "com.sos.joc.model.jobscheduler.AgentOfCluster", "type": "object", "required": [ "surveyDate", "version", "host", "url", "os", "state", "startedAt" ], "properties": { "surveyDate": { "description": "Date of the inventory data. Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ", "type": "string", "format": "date-time" }, "version": { "type": "string" }, "host": { "type": "string" }, "url": { "description": "url can be different against host/port if agent behind a proxy", "type": "string", "pattern": "^https?://.+$" }, "os": { "javaType": "com.sos.joc.model.jobscheduler.OperatingSystem", "type": "object", "required": [ "name", "architecture", "distribution" ], "properties": { "name": { "description": "Windows, Linux, AIX, Solaris, other", "type": "string" }, "architecture": { "type": "string" }, "distribution": { "description": "e.g. Windows 2012, CentOS Linux release 7.2.1511 (Core)", "type": "string" } } }, "state": { "javaType": "com.sos.joc.model.jobscheduler.JobSchedulerState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "0=running/starting, 1=paused, 3=waiting_for_activation/terminating, 2=waiting_for_database/dead/unreachable", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.jobscheduler.JobSchedulerStateText", "type": "string", "enum": [ "STARTING", "RUNNING", "PAUSED", "WAITING_FOR_ACTIVATION", "TERMINATING", "WAITING_FOR_DATABASE", "DEAD", "UNREACHABLE", "UNKNOWN_AGENT" ] } } }, "startedAt": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "runningTasks": { "type": "integer", "minimum": 0 } } } }, "numOfProcesses": { "type": "integer", "minimum": 0 }, "processes": { "type": "array", "items": { "javaType": "com.sos.joc.model.processClass.Process", "type": "object", "required": [ "job", "taskId", "pid", "runningSince" ], "properties": { "job": { "description": "absolute path based on live folder of a JobScheduler object.", "type": "string", "pattern": "^(/\|(/[^/\\<>?:\"\|]+)+)$", "maxLength": 255 }, "taskId": { "type": "string" }, "pid": { "type": "integer", "minimum": 0 }, "runningSince": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "agent": { "description": "url", "type": "string", "pattern": "^https?://.+$" } } } }, "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" } } } } } } } } { "deliveryDate": "2016-05-05T20:34:51Z", "agentClusters": [{ "surveyDate": "2016-05-05T20:34:51Z", "path": "/agents/galadriel", "state": { "severity": 1, "_text": "only_some_agents_are_running" }, "numOfAgents": { "any": 2, "running": 1 }, "agents": [{ "surveyDate": "2016-05-05T20:34:51Z", "version": "1.11.0", "host": "galadriel", "port": 4445, "url": "http://galadriel:4445", "os": { "name": "linux", "architecture": 64, "distribution": "CentOS Linux release 7.2.1511" }, "state": { "severity": 0, "_text": "running" }, "startedAt": "2016-04-20T23:55:00Z", "runningTasks": 2 }, { "surveyDate": "2016-05-05T20:34:51Z", "url": "http://galadriel:4447", "state": { "severity": 2, "_text": "unreachable" } }] }, { "surveyDate": "2016-05-05T20:34:51Z", "path": "/agents/galadriel-4445", "state": { "severity": 0, "_text": "all_agents_are_running" }, "numOfAgents": { "any": 1, "running": 1 }, "agents": [{ "surveyDate": "2016-05-05T20:34:51Z", "version": "1.11.0", "host": "galadriel", "port": 4445, "url": "http://galadriel:4445", "os": { "name": "linux", "architecture": 64, "distribution": "CentOS Linux release 7.2.1511" }, "state": { "severity": 0, "_text": "running" }, "startedAt": "2016-04-20T23:55:00Z", "runningTasks": 0 }] }, { "surveyDate": "2016-05-05T20:34:51Z", "path": "/agents/frodo-4445", "state": { "severity": 2, "_text": "all_agents_are_unreachable" }, "numOfAgents": { "any": 1, "running": 0 }, "agents": [{ "url": "http://frodo.proxy", "state": { "severity": 2, "_text": "unreachable" } }] }] } { "deliveryDate": "2016-05-05T20:34:51Z", "agentClusters": [{ "surveyDate": "2016-05-05T20:34:51Z", "path": "/agents/galadriel", "state": { "severity": 1, "_text": "only_some_agents_are_running" }, "numOfAgents": { "any": 2, "running": 1 }, "agents": [{ "surveyDate": "2016-05-05T20:34:51Z", "version": "1.11.0", "host": "galadriel", "port": 4445, "url": "http://galadriel:4445", "os": { "name": "linux", "architecture": 64, "distribution": "CentOS Linux release 7.2.1511" }, "state": { "severity": 0, "_text": "running" }, "startedAt": "2016-04-20T23:55:00Z", "runningTasks": 2 }, { "surveyDate": "2016-05-05T20:34:51Z", "url": "http://galadriel:4447", "state": { "severity": 2, "_text": "unreachable" } }] }, { "surveyDate": "2016-05-05T20:34:51Z", "path": "/agents/galadriel-4445", "state": { "severity": 0, "_text": "all_agents_are_running" }, "numOfAgents": { "any": 1, "running": 1 }, "agents": [{ "surveyDate": "2016-05-05T20:34:51Z", "version": "1.11.0", "host": "galadriel", "port": 4445, "url": "http://galadriel:4445", "os": { "name": "linux", "architecture": 64, "distribution": "CentOS Linux release 7.2.1511" }, "state": { "severity": 0, "_text": "running" }, "startedAt": "2016-04-20T23:55:00Z", "runningTasks": 0 }] }, { "surveyDate": "2016-05-05T20:34:51Z", "path": "/agents/frodo-4445", "state": { "severity": 2, "_text": "all_agents_are_unreachable" }, "numOfAgents": { "any": 1, "running": 0 }, "agents": [{ "url": "http://frodo.proxy", "state": { "severity": 2, "_text": "unreachable" } }] }] }
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 'agent_clusters'	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	'agent_clusters' 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": "agent_clusters failed!" } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "agent_clusters 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 }