JOC API

/tasks/history

POST

Task history

Parameters in the POST body schema

Name	Type	Description	Example	Default
`controllerId`	optional, string	Controller ID	myController
`jobs`	optional, array[object]	Filtered response by a collection of jobs specified by its workflow path and an optional job name. If "job" is undefined then the answer contains all jobs of the specified workflow. If this parameter is specified then the parameters `folders`, `excludeJobs`, `jobName` and `workflowPath` are ignored.	[{ "workflowPath":"/path/to/workflow", "job":"myJob" }]
`excludeJobs`	optional, array[object]	Response contains all jobs except the jobs that are specified in this collection. A job is specified by its workflow path and an optional job name. If "job" is undefined then all jobs of the specified workflow are excluded in the response. This parameter will be ignored if `jobs` parameter is set.	[{ "workflowPath":"/path/to/workflow", "job":"myJob" }]
`dateFrom`	optional, string	The value has multiple formats Filters items starting from a date. an ISO 8601 date format with the time offset and milliseconds being optional, e.g. YYYY-MM-DDThh:mm:ss[.s][Z (Z means +00)] YYYY-MM-DDThh:mm:ss[.s][+01:00] YYYY-MM-DDThh:mm:ss[.s][+0100] YYYY-MM-DDThh:mm:ss[.s][+01] a format for a period relative to the current time, e.g. 6h, 12h, 1d, 1w that specifies the quantity followed by a qualifier: s (seconds) m (minutes) h (hours) d (days) w (weeks) M (months) y (years) a time offset is optional (e.g. 2d+02:00) it can also be specified with the parameter `timeZone` if `timeZone` is undefined then UTC is used the value 0 indicates the current time	1d
`dateTo`	optional, string	The value has multiple formats similiar to the `dateFrom` parameter Filters items ending before a date.	0
`completedDateFrom`	optional, string	The value has multiple formats Filters items starting from a date. an ISO 8601 date format with the time offset and milliseconds being optional, e.g. YYYY-MM-DDThh:mm:ss[.s][Z (Z means +00)] YYYY-MM-DDThh:mm:ss[.s][+01:00] YYYY-MM-DDThh:mm:ss[.s][+0100] YYYY-MM-DDThh:mm:ss[.s][+01] a format for a period relative to the current time, e.g. 6h, 12h, 1d, 1w that specifies the quantity followed by a qualifier: s (seconds) m (minutes) h (hours) d (days) w (weeks) M (months) y (years) a time offset is optional (e.g. 2d+02:00) it can also be specified with the parameter `timeZone` if `timeZone` is undefined then UTC is used the value 0 indicates the current time	1d
`completedDateTo`	optional, string	The value has multiple formats similiar to the `completedDateFrom` parameter Filters items ending before a date.	0
`timeZone`	optional, string	If this parameter is set then it beats the time offset in `dateFrom` and `dateTo` See the list for available time zones.	Europe/Berlin
`jobName`	optional, string	Limits result to a specified glob pattern of a Job name that supports '' and '?' as wildcards where : match zero or more characters ? : match any single character	"test"
`workflowPath`	optional, string	Limits result to a specified glob pattern of a Workflow path that supports '' and '?' as wildcards where : match zero or more characters ? : match any single character	"a/b/my*Workflow"
`workflowName`	optional, string	Limits result to a specified glob pattern of a Workflow name that supports '' and '?' as wildcards where : match zero or more characters ? : match any single character	"my*Workflow"
`folders`	optional, array[object]	Limits the result to a collection of folders	[{ "folder": "/sos", "recursive": true }]
`limit`	optional, integer	Limits the number of resulting items, -1=unlimited	5000	10000
`historyStates`	optional, array[string] contains SUCCESSFUL, FAILED and/or INCOMPLETE	Limits result to specified states	["SUCCESSFUL"]
`criticalities`	optional, array[string]	Possible values are NORMAL and MINOR Only records with these criticalities are responsed	["NORMAL"]
`taskIds`	optional; array[integer]	The history ids of tasks If "taskIds" is specified then all other optional parameters except `controllerId` are ignored.	[4711]

Request

Name

Description

Example

Type

Constraints

Default

Headers

X-Access-Token*

Request requires authentication!

550e8400-e29b-11d4-a716-446655440000

string

Body

application/json

model | example

{
    "title": "jobsFilter",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "javaType": "com.sos.joc.model.job.JobsFilter",
    "type": "object",
    "properties": {
        "controllerId": {
            "type": "string",
            "pattern": "^[^/\\<>?:\"|*]*$",
            "maxLength": 100
        },
        "jobs": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.job.JobPath",
                "type": "object",
                "required": [
                    "workflowPath"
                ],
                "properties": {
                    "workflowPath": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255
                    },
                    "job": {
                        "description": "if job undefined or empty then all jobs of specified workflow are requested",
                        "type": "string"
                    }
                }
            }
        },
        "excludeJobs": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.job.JobPath",
                "type": "object",
                "required": [
                    "workflowPath"
                ],
                "properties": {
                    "workflowPath": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255
                    },
                    "job": {
                        "description": "if job undefined or empty then all jobs of specified workflow are requested",
                        "type": "string"
                    }
                }
            }
        },
        "jobName": {
            "type": "string",
            "pattern": "^[^<>]*$",
            "maxLength": 255
        },
        "workflowPath": {
            "description": "pattern with wildcards '*' and '?' where '*' match zero or more characters and '?' match any single character",
            "type": "string",
            "pattern": "^[^<>]*$",
            "maxLength": 255
        },
        "workflowName": {
            "description": "pattern with wildcards '*' and '?' where '*' match zero or more characters and '?' match any single character",
            "type": "string",
            "pattern": "^[^<>]*$",
            "maxLength": 255
        },
        "dateFrom": {
            "description": "0 or [number][smhdwMy] (where smhdwMy unit for second, minute, etc) or ISO 8601 timestamp",
            "type": "string",
            "pattern": "^([+-]?0|([+-]?[0-9]+[smhdwMy])+|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}([,.]\\d{1,3})?)(Z|[+-]\\d{2}(:?\\d{2})?)?$"
        },
        "dateTo": {
            "description": "0 or [number][smhdwMy] (where smhdwMy unit for second, minute, etc) or ISO 8601 timestamp",
            "type": "string",
            "pattern": "^([+-]?0|([+-]?[0-9]+[smhdwMy])+|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}([,.]\\d{1,3})?)(Z|[+-]\\d{2}(:?\\d{2})?)?$"
        },
        "completedDateFrom": {
            "alias": "endDateFrom",
            "description": "0 or [number][smhdwMy] (where smhdwMy unit for second, minute, etc) or ISO 8601 timestamp",
            "type": "string",
            "pattern": "^([+-]?0|([+-]?[0-9]+[smhdwMy])+|\\d{4}-\\d{2}-\\d{2}(?:T| )\\d{2}:\\d{2}:\\d{2}([,.]\\d{1,3})?)(Z|[+-]\\d{2}(:?\\d{2})?)?$"
        },
        "completedDateTo": {
            "alias": "endDateTo",
            "description": "0 or [number][smhdwMy] (where smhdwMy unit for second, minute, etc) or ISO 8601 timestamp",
            "type": "string",
            "pattern": "^([+-]?0|([+-]?[0-9]+[smhdwMy])+|\\d{4}-\\d{2}-\\d{2}(?:T| )\\d{2}:\\d{2}:\\d{2}([,.]\\d{1,3})?)(Z|[+-]\\d{2}(:?\\d{2})?)?$"
        },
        "timeZone": {
            "description": "see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones",
            "type": "string",
            "pattern": "^[^<>]*$",
            "maxLength": 255
        },
        "folders": {
            "type": "array",
            "items": {
                "type": "object",
                "javaType": "com.sos.joc.model.common.Folder",
                "required": [
                    "folder"
                ],
                "properties": {
                    "folder": {
                        "description": "absolute path of an object.",
                        "type": "string",
                        "pattern": "^(/|(/[^/\\\\<>?:\"|*]+)+)$",
                        "maxLength": 255,
                        "minLength": 1
                    },
                    "recursive": {
                        "type": "boolean",
                        "default": true
                    }
                },
                "additionalProperties": false
            }
        },
        "limit": {
            "description": "only for db history urls to restrict the number of responsed records; -1=unlimited",
            "type": "integer",
            "default": 10000
        },
        "historyStates": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.common.HistoryStateText",
                "type": "string",
                "enum": [
                    "SUCCESSFUL",
                    "INCOMPLETE",
                    "FAILED"
                ]
            }
        },
        "criticalities": {
            "type": "array",
            "items": {
                "javaType": "com.sos.inventory.model.job.JobCriticality",
                "type": "string",
                "enum": [
                    "NORMAL",
                    "CRITICAL"
                ]
            }
        },
        "taskIds": {
            "type": "array",
            "items": {
                "type": "number",
                "format": "utc-millisec",
                "minimum": 0
            }
        },
        "historyIds": {
            "type": "array",
            "items": {
                "description": "Only relevant for order jobs; cause=order resp.",
                "javaType": "com.sos.joc.model.job.TaskIdOfOrder",
                "type": "object",
                "required": [
                    "historyId",
                    "position"
                ],
                "properties": {
                    "historyId": {
                        "type": "number",
                        "format": "utc-millisec",
                        "minimum": 0
                    },
                    "position": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

TODO

TODO

Responses

Code	Description	Body
200	TODO	application/json model \| example { "title": "history collection of tasks", "$schema": "http://json-schema.org/draft-04/schema#", "description": "one item per started task", "javaType": "com.sos.joc.model.job.TaskHistory", "type": "object", "required": [ "deliveryDate", "history" ], "properties": { "deliveryDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "history": { "type": "array", "items": { "javaType": "com.sos.joc.model.job.TaskHistoryItem", "type": "object", "required": [ "surveyDate", "workflow", "job", "startTime", "position", "sequence", "retryCounter", "state", "criticality", "taskId", "agentUrl" ], "properties": { "surveyDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "controllerId": { "type": "string" }, "job": { "type": "string" }, "label": { "type": "string" }, "workflow": { "type": "string" }, "orderId": { "type": "string" }, "startTime": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "endTime": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "position": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0 }, "retryCounter": { "type": "integer", "minimum": 0 }, "state": { "javaType": "com.sos.joc.model.common.HistoryState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "description": "0=successful, 1=incomplete, 2=failed with a green/yellow/red representation", "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.common.HistoryStateText", "type": "string", "enum": [ "SUCCESSFUL", "INCOMPLETE", "FAILED" ] } } }, "criticality": { "type": "string" }, "taskId": { "type": "number", "format": "utc-millisec", "minimum": 0 }, "agentUrl": { "type": "string" }, "exitCode": { "type": "integer", "minimum": 0 }, "error": { "javaType": "com.sos.joc.model.common.Err", "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "arguments": { "description": "a map for arbitrary key-value pairs", "javaType": "com.sos.inventory.model.common.Variables", "type": "object", "additionalProperties": true } } } }, "workflowTagsPerWorkflow": { "description": "a map of workflowName -> tags-array", "javaType": "com.sos.joc.model.common.WorkflowTags", "type": "object", "additionalProperties": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[^<>]*$", "maxLength": 255 } } } }, "additionalProperties": false } { "deliveryDate": "2021-02-19T13:46:32.757+0000", "history": [{ "surveyDate": "2021-02-19T13:08:40.000+0000", "controllerId": "controller.js7", "job": "test1", "workflow": "/my_workflow", "orderId": "ORDER-ID11", "startTime": "2021-02-19T13:08:10.000+0000", "endTime": "2021-02-19T13:08:40.000+0000", "position": "0/lock/0", "sequence": 0, "retryCounter": 0, "state": { "severity": 6, "_text": "SUCCESSFUL" }, "criticality": "normal", "taskId": 21, "agentUrl": "http://localhost:4445", "exitCode": 0, "arguments": { "my_string_var": "my_value", "my_boolean_var": false, "my_numeric_var": 123 } }] } { "deliveryDate": "2021-02-19T13:46:32.757+0000", "history": [{ "surveyDate": "2021-02-19T13:08:40.000+0000", "controllerId": "controller.js7", "job": "test1", "workflow": "/my_workflow", "orderId": "ORDER-ID11", "startTime": "2021-02-19T13:08:10.000+0000", "endTime": "2021-02-19T13:08:40.000+0000", "position": "0/lock/0", "sequence": 0, "retryCounter": 0, "state": { "severity": 6, "_text": "SUCCESSFUL" }, "criticality": "normal", "taskId": 21, "agentUrl": "http://localhost:4445", "exitCode": 0, "arguments": { "my_string_var": "my_value", "my_boolean_var": false, "my_numeric_var": 123 } }] }
401	Unauthorized!	application/json model \| example { "title": "authentication", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "isAuthenticated" ], "properties": { "user": { "type": "string" }, "accessToken": { "type": "string" }, "message": { "type": "string" }, "role": { "type": "string" }, "isAuthenticated": { "type": "boolean" }, "isPermitted": { "type": "boolean", "default": false }, "sessionTimeout": { "type": "integer", "default": 1800 }, "enableTouch": { "type": "boolean", "default": true } } } { "user": "root", "message": "Oops!", "isAuthenticated": false, "isPermitted": false } { "user": "root", "message": "Oops!", "isAuthenticated": false, "isPermitted": false }
403	Forbidden! The user doesn't have sufficient permissions for 'history'	application/json model \| example { "title": "authentication", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "isAuthenticated" ], "properties": { "user": { "type": "string" }, "accessToken": { "type": "string" }, "message": { "type": "string" }, "role": { "type": "string" }, "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 ...", "role": "all", "isAuthenticated": true, "isPermitted": false } { "user": "root", "message": "You don't have sufficient permissions for ...", "role": "all", "isAuthenticated": true, "isPermitted": false }
420	'history' 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": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "surveyDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "error": { "javaType": "com.sos.joc.model.common.Err", "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "history failed!" } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "history failed!" } }
433	4-eyes principle: Forbidden! The user needs approval process for 'history'	application/json model \| example { "title": "FourEyesResponse", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.security.foureyes.FourEyesResponse", "type": "object", "extends": { "javaType": "com.sos.joc.model.security.foureyes.ApprovalBase", "type": "object", "properties": { "requestor": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255, "minLength": 1 }, "requestUrl": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255, "minLength": 1 }, "requestBody": { "type": "object", "javaType": "com.sos.joc.model.security.foureyes.RequestBody", "additionalProperties": true }, "category": { "javaType": "com.sos.joc.model.audit.CategoryType", "type": "string", "enum": [ "INVENTORY", "CONTROLLER", "DAILYPLAN", "OTHERS", "DEPLOYMENT", "DOCUMENTATIONS", "CERTIFICATES", "IDENTITY", "SETTINGS", "MONITORING", "UNKNOWN" ] } }, "additionalProperties": false }, "properties": { "deliveryDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "message": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255, "minLength": 1 }, "approvers": { "type": "array", "items": { "javaType": "com.sos.joc.model.security.foureyes.Approver", "type": "object", "required": [ "accountName", "firstName", "lastName" ], "properties": { "accountName": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255, "minLength": 1 }, "firstName": { "type": "string", "pattern": "^[^<>]$", "maxLength": 30, "minLength": 1 }, "lastName": { "type": "string", "pattern": "^[^<>]$", "maxLength": 30, "minLength": 1 }, "email": { "type": "string", "pattern": "^[^<>]*$", "maxLength": 255 } }, "additionalProperties": false } } }, "additionalProperties": false } { "deliveryDate": "2025-05-12T21:13:35Z", "accountName": "user1", "request": "./orders/add", "requestBody": { "controllerId": "standalone", "orders": [{ "workflowPath": "myWorkflow", "scheduledFor": "now" }] }, "category": "CONTROLLER", "objectType": "WORKFLOW" "objectName": "myWorkflow", "numOfObjects": 1, "action": "add orders" } { "deliveryDate": "2025-05-12T21:13:35Z", "accountName": "user1", "request": "./orders/add", "requestBody": { "controllerId": "standalone", "orders": [{ "workflowPath": "myWorkflow", "scheduledFor": "now" }] }, "category": "CONTROLLER", "objectType": "WORKFLOW" "objectName": "myWorkflow", "numOfObjects": 1, "action": "add orders" }
440	Login Timeout! The client's session has expired and must log in again.	application/json model \| example { "title": "authentication", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "isAuthenticated" ], "properties": { "user": { "type": "string" }, "accessToken": { "type": "string" }, "message": { "type": "string" }, "role": { "type": "string" }, "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", "role": "all", "isAuthenticated": false, "isPermitted": false } { "user": "root", "message": "Session has expired. Please log in again", "role": "all", "isAuthenticated": false, "isPermitted": false }