JOC API

/orders

POST

Returns a collection of orders filtered by workflow or order state

Parameters in the POST body schema

Name	Type	Description	Example	Default
`controllerId`	required, string	Controller ID	myController
`orderIds`	optional, array	Filtered response by a collection of orderIds If this parameter is specified then parameters such as `workflowIds`, `states`, `folders` and `regex` where applicable are ignored.	[ "myOrder", "myOrder2" ]
`workflowIds`	optional, object	Filtered response by a collection of workflows specified by its path and optional version If this parameter is specified then parameters such as `folders`, `states`, `regex` and `agentName` where applicable are ignored.	{ "path": "/path/to/workflow", "versionId": "c79caab4-4e72-4818-bae7-902f1037d8b6" }
`path`	required, string	Field for each item in `workflowIds` to specify the path of a workflow
`versionId`	optional, string	Field for each in `workflowIds` to specify the version of a workflow
`folders`	optional, array[object]	Limits the result to a collection of folders	[{ "folder": "/sos", "recursive": true }]
`compact`	optional, boolean	A compact response is returned if this parameter is true		false
`regex`	optional, string	Regular expression to filter the collection	.*
`states`	optional, array	Filtered all orders with states such as PENDING SCHEDULED INPROGRESS RUNNING SUSPENDED WAITING PROMPTING FAILED BLOCKED	["SUSPENDED"]
`stateDateFrom`	optional, string	The value has multiple formats Filters those orders whose current status is younger than the specified point in time See the `dateTo` parameter for the possible formats	1d
`stateDateTo`	optional, string	The value has multiple formats Filters those orders whose current status is older than the specified point in time See the `dateTo` parameter for the possible formats	1d
`dateTo`	optional, string	The value has multiple formats Filters Orders whose schedule is before 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
`timeZone`	optional, string	If this parameter is set then it beats the time offset of absolute dates in `dateTo` See here the list for available time zones.	Europe/Berlin
`limit`	optional, integer	Limits the number of resulting items, -1=unlimited	5000	10000

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": "orders filter for volatile information",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "javaType": "com.sos.joc.model.order.OrdersFilterV",
    "type": "object",
    "required": [
        "controllerId"
    ],
    "properties": {
        "controllerId": {
            "type": "string",
            "pattern": "^[^/\\<>?:\"|*]*$",
            "maxLength": 100,
            "minLength": 1
        },
        "orderIds": {
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "pattern": "^[^<>]*$",
                "maxLength": 255
            }
        },
        "workflowIds": {
            "type": "array",
            "uniqueItems": true,
            "items": {
                "javaType": "com.sos.controller.model.workflow.WorkflowId",
                "type": "object",
                "required": [
                    "path"
                ],
                "properties": {
                    "path": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255,
                        "minLength": 1
                    },
                    "versionId": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255
                    }
                },
                "additionalProperties": false
            }
        },
        "compact": {
            "description": "controls if the object's data is compact or detailed",
            "type": "boolean",
            "default": false
        },
        "regex": {
            "description": "regular expression to filter Controller objects by matching the path",
            "type": "string"
        },
        "states": {
            "type": "array",
            "items": {
                "javaType": "com.sos.joc.model.order.OrderStateText",
                "type": "string",
                "enum": [
                    "PLANNED",
                    "PENDING",
                    "SCHEDULED",
                    "RUNNING",
                    "INPROGRESS",
                    "PROMPTING",
                    "SUSPENDED",
                    "FAILED",
                    "WAITING",
                    "BLOCKED",
                    "CANCELLED",
                    "FINISHED",
                    "BROKEN",
                    "UNKNOWN"
                ]
            }
        },
        "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
            }
        },
        "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})?)?$"
        },
        "stateDateFrom": {
            "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})?)?$"
        },
        "stateDateTo": {
            "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"
        },
        "scheduledNever": {
            "description": "deprecated -> is State.PENDING",
            "type": "boolean",
            "default": false
        },
        "limit": {
            "description": "-1=unlimited",
            "type": "integer",
            "default": 10000
        }
    }
}

TODO

TODO

Responses

Code	Description	Body
200	Each order can have a compact or detailed response. It depends on the parameter `compact`. Required fields are orderId workflowId path version position state reason (if state is WAITING) The compact view has further optional fields arguments attachedState agentRefPath lastOutcome returnCode keyValues scheduledFor requirements if state is PENDING, SCHEDULED, BLOCKED or SUSPENDED The detailed view has the following optional fields in addition to the compact view historicOutcome	application/json model \| example { "title": "orders with delivery date (volatile part)", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.order.OrdersV", "type": "object", "required": [ "deliveryDate", "orders" ], "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" }, "orders": { "type": "array", "items": { "javaType": "com.sos.joc.model.order.OrderV", "type": "object", "required": [ "orderId", "workflowId", "state" ], "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" }, "orderId": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255 }, "arguments": { "description": "a map for arbitrary key-value pairs", "javaType": "com.sos.inventory.model.common.Variables", "type": "object", "additionalProperties": true }, "workflowId": { "javaType": "com.sos.controller.model.workflow.WorkflowId", "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255, "minLength": 1 }, "versionId": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255 } }, "additionalProperties": false }, "state": { "javaType": "com.sos.joc.model.order.OrderState", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.order.OrderStateText", "type": "string", "enum": [ "PLANNED", "PENDING", "SCHEDULED", "RUNNING", "INPROGRESS", "PROMPTING", "SUSPENDED", "FAILED", "WAITING", "BLOCKED", "CANCELLED", "FINISHED", "BROKEN", "UNKNOWN" ] }, "_reason": { "javaType": "com.sos.joc.model.order.OrderWaitingReason", "type": "string", "enum": [ "DELAYED_AFTER_ERROR", "FORKED", "EXPECTING_NOTICES", "WAITING_FOR_LOCK", "BETWEEN_CYCLES" ] } }, "additionalProperties": false }, "marked": { "javaType": "com.sos.joc.model.order.OrderMark", "type": "object", "required": [ "severity", "_text" ], "properties": { "severity": { "type": "integer" }, "_text": { "javaType": "com.sos.joc.model.order.OrderMarkText", "type": "string", "enum": [ "CANCELLING", "RESUMING", "SUSPENDING" ] } } }, "attachedState": { "javaType": "com.sos.controller.model.order.OrderAttachedState", "type": "object", "properties": { "TYPE": { "description": "Attaching, Attached, ...", "type": "string" }, "agentName": { "type": "string" } }, "additionalProperties": false }, "agentId": { "type": "string" }, "subagentId": { "type": "string" }, "cycleState": { "type": "object", "javaType": "com.sos.controller.model.order.OrderCycleState", "description": "set if state == BetweenCycles or processing inside a cycle", "properties": { "next": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "since": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "index": { "type": "integer" } }, "additionalProperties": false }, "expectedNotices": { "description": "if state._reason == EXPECTING_NOTICES", "type": "array", "items": { "type": "object", "javaType": "com.sos.controller.model.order.ExpectedNotice", "properties": { "boardName": { "alias": "boardPath", "type": "string" }, "noticeId": { "type": "string" } }, "additionalProperties": false } }, "label": { "description": "a label is only in the response if the request restricts the orders to one workflow", "type": "string", "pattern": "^[^<>]$", "maxLength": 255 }, "position": { "description": "Actually, each even item is a string, each odd item is an integer", "type": "array", "minItems": 1, "items": { "anyOf": [{ "type": "integer" }, { "type": "string" }] } }, "positionString": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255 }, "positionIsImplicitEnd": { "type": "boolean" }, "endPositions": { "type": "array", "items": { "anyOf": [{ "description": "Actually, each even item is a string, each odd item is an integer", "type": "array", "items": { "anyOf": [{ "type": "integer" }, { "type": "string" }] } }, { "type": "string" }] } }, "scheduledFor": { "type": "number", "format": "utc-millisec", "minimum": 0 }, "scheduledNever": { "description": "deprecated -> is State.PENDING", "type": "boolean", "default": false }, "question": { "description": "only relevant for state PROMPTING", "type": "string" }, "lastOutcome": { "javaType": "com.sos.controller.model.common.Outcome", "type": "object", "required": [ "TYPE" ], "properties": { "TYPE": { "description": "Succeeded, Failed, Disrupted, Cancelled, Killed, TimedOut", "type": "string" }, "namedValues": { "description": "a map for arbitrary key-value pairs", "javaType": "com.sos.inventory.model.common.Variables", "type": "object", "additionalProperties": true }, "outcome": { "description": "outcome-schema.json" } }, "additionalProperties": false }, "historicOutcome": { "description": "only for compact parameter is false", "type": "array", "items": { "type": "object", "javaType": "com.sos.controller.model.workflow.HistoricOutcome", "properties": { "position": { "description": "Actually, each even item is a string, each odd item is an integer", "type": "array", "items": { "anyOf": [{ "type": "integer" }, { "type": "string" }] } }, "outcome": { "javaType": "com.sos.controller.model.common.Outcome", "type": "object", "required": [ "TYPE" ], "properties": { "TYPE": { "description": "Succeeded, Failed, Disrupted, Cancelled, Killed, TimedOut", "type": "string" }, "namedValues": { "description": "a map for arbitrary key-value pairs", "javaType": "com.sos.inventory.model.common.Variables", "type": "object", "additionalProperties": true }, "outcome": { "description": "outcome-schema.json" } }, "additionalProperties": false } }, "additionalProperties": false } }, "requirements": { "javaType": "com.sos.inventory.model.workflow.Requirements", "type": "object", "alias": "orderRequirements", "properties": { "parameters": { "javaType": "com.sos.inventory.model.workflow.Parameters", "type": "object", "additionalProperties": { "javaType": "com.sos.inventory.model.workflow.Parameter", "type": "object", "required": [ "type" ], "properties": { "type": { "javaType": "com.sos.inventory.model.workflow.ParameterType", "type": "string", "enum": [ "String", "Number", "Boolean", "List" ], "javaEnumNames": [ "String", "Number", "Boolean", "List" ] }, "default": { "description": "this value has to have the data type of the 'type' attribute", "anyOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array" }], "javaType": "java.lang.Object" }, "final": { "type": "string" }, "listParameters": { "javaType": "com.sos.inventory.model.workflow.ListParameters", "type": "object", "description": "parameters only for parameter type 'List'", "additionalProperties": { "javaType": "com.sos.inventory.model.workflow.ListParameter", "type": "object", "required": [ "type" ], "description": "parameter type only Number, Boolean or String", "properties": { "type": { "javaType": "com.sos.inventory.model.workflow.ListParameterType", "type": "string", "enum": [ "String", "Number", "Boolean" ], "javaEnumNames": [ "String", "Number", "Boolean" ] } }, "additionalProperties": false } }, "facet": { "description": "a regular expression to check the value of the parameter", "type": "string" }, "list": { "description": "enumeration of possible parameter values", "type": "array", "items": { "type": "string" } }, "message": { "description": "a message if the value doesn't match the facet", "type": "string" } }, "additionalProperties": false } }, "allowUndeclared": { "type": "boolean", "default": false } }, "additionalProperties": false }, "cyclicOrder": { "type": "object", "javaType": "com.sos.joc.model.dailyplan.CyclicOrderInfos", "properties": { "count": { "type": "integer", "minimum": 0 }, "firstOrderId": { "type": "string", "pattern": "^[^<>]$", "maxLength": 255 }, "lastOrderId": { "type": "string", "pattern": "^[^<>]*$", "maxLength": 255 }, "firstStart": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "lastStart": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" } } }, "hasChildOrders": { "type": "boolean", "default": false } }, "additionalProperties": false } } } } TODO TODO
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 'orders'	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	'orders' 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": "orders failed!" } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "orders failed!" } }
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 }