JOC API

/orders/add

POST

Add orders

this resource can be used in the GUI for three functions

start immediatly

start at (with scheduledFor)

start at parametrised (with scheduledFor and arguments)

Parameters in the POST body schema

Name	Type	Description	Example	Default
`controllerId`	required, string	Controller ID	myController
`orders`	required, array	Specified the orders which should be modified.	[{ "workflowPath":"/myWorkflow", "orderName":"daily" "scheduledFor":"now+10" }]
`orderName`	required, string (max. 30 characters) field of each `orders` item	`orderName` is only a part of the orderId in the form "#<date>#T<uniqueId>-<orderName>"
`workflowPath`	required, string field of each `orders` item
`scheduledFor`	optional, string field of each `orders` item	A start time in ISO format "yyyy-mm-dd HH:MM[:SS]" or "now" or "now + HH:MM[:SS]" or "now + SECONDS" or "never" is expected	now+10	now
`timeZone`	optional, string field of each `orders` item	This parameter set the time zone for the time stamp in the `scheduledFor` parameter. See here the list for available time zones.	Europe/Berlin	Etc/UTC
`arguments`	optional, object field of each `orders` item	An object with key-value pairs. The value can be a string, number or boolean	"arguments": { "myString": "stringValue", "myNumber": 3.14, "myBoolean": true }
`startPosition`	optional, array or string field of each `orders` item	The order starts with the first instruction per default. The position can also be specified by the label of the instruction.	[0] or "job1"
`endPositions`	optional, array[array or string] field of each `orders` item	The order ends on one of these positions The position can also be specified by the label of the instruction.	[[1]] or ["lastJob"]
`blockPosition`	optional, array or string	The order runs only inside the specified block instruction. The position can also be specified by the label of the block instruction.	[1, "lock"]
`forceJobAdmission`	optional, boolean field of each `orders` item	If true then any admission times at a Job instruction will be ignored		false
`auditLog`	optional, object	Object that contains `comment`, `timeSpent` and `ticketLink`.	{ "comment": "Operational requirement!", "timeSpent": 2 }
`comment`	optional, string	Field in `auditLog` to comment this action, e.g. the reason.
`timeSpent`	optional, integer	Field in `auditLog` to enter the time spent in minutes.
`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

Body

application/json

model | example

{
    "title": "add order commands",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "javaType": "com.sos.joc.model.order.AddOrders",
    "type": "object",
    "required": [
        "controllerId",
        "orders"
    ],
    "properties": {
        "controllerId": {
            "type": "string",
            "pattern": "^[^/\\<>?:\"|*]*$",
            "maxLength": 100
        },
        "orders": {
            "type": "array",
            "minLength": 1,
            "items": {
                "javaType": "com.sos.joc.model.order.AddOrder",
                "type": "object",
                "required": [
                    "workflowPath"
                ],
                "properties": {
                    "orderName": {
                        "type": "string",
                        "maxLength": 30
                    },
                    "workflowPath": {
                        "type": "string",
                        "pattern": "^[^<>]*$",
                        "maxLength": 255,
                        "minLength": 1
                    },
                    "scheduledFor": {
                        "description": "ISO format yyyy-mm-dd HH:MM[:SS] or now or now + HH:MM[:SS] or now + SECONDS or empty",
                        "type": "string",
                        "pattern": "^(now(\\s*\\+\\s*(\\d{1,2}:\\d{1,2}(:\\d{1,2})?|\\d+)?)?||never|\\d{4}-\\d{2}-\\d{2}\\s\\d{1,2}:\\d{1,2}(:\\d{1,2})?)$"
                    },
                    "timeZone": {
                        "description": "see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones",
                        "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
                    },
                    "startPosition": {
                        "anyOf": [{
                            "description": "Actually, each even item is a string, each odd item is an integer",
                            "type": "array",
                            "minItems": 1,
                            "items": {
                                "anyOf": [{
                                    "type": "integer"
                                }, {
                                    "type": "string"
                                }]
                            }
                        }, {
                            "type": "string",
                            "pattern": "^[^<>]*$",
                            "maxLength": 255,
                            "minLength": 1
                        }]
                    },
                    "endPositions": {
                        "type": "array",
                        "items": {
                            "anyOf": [{
                                "description": "Actually, each even item is a string, each odd item is an integer",
                                "type": "array",
                                "minItems": 1,
                                "items": {
                                    "anyOf": [{
                                        "type": "integer"
                                    }, {
                                        "type": "string"
                                    }]
                                }
                            }, {
                                "type": "string",
                                "pattern": "^[^<>]*$",
                                "maxLength": 255,
                                "minLength": 1
                            }]
                        }
                    },
                    "blockPosition": {
                        "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",
                            "pattern": "^[^<>]*$",
                            "maxLength": 255,
                            "minLength": 1
                        }]
                    },
                    "forceJobAdmission": {
                        "type": "boolean",
                        "default": false
                    }
                },
                "additionalProperties": false
            }
        },
        "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
                }
            }
        }
    }
}

{ "controllerId": "myController", "orders": [{ "orderId": "order1", "workflowPath": "/test/testWorkflow", "scheduledFor": "now + 60" }, { "orderId": "order2", "workflowPath": "/test/testWorkflow" }, { "orderId": "order3", "workflowPath": "/test/testWorkflow" }, { "orderId": "order4", "workflowPath": "/test/testWorkflow" }, { "orderId": "order5", "workflowPath": "/test/testWorkflow" }] }

{
    "controllerId": "myController",
    "orders": [{
        "orderId": "order1",
        "workflowPath": "/test/testWorkflow",
        "scheduledFor": "now + 60"
    }, {
        "orderId": "order2",
        "workflowPath": "/test/testWorkflow"
    }, {
        "orderId": "order3",
        "workflowPath": "/test/testWorkflow"
    }, {
        "orderId": "order4",
        "workflowPath": "/test/testWorkflow"
    }, {
        "orderId": "order5",
        "workflowPath": "/test/testWorkflow"
    }]
}

Responses

Code	Description	Body
200	Returns the orderIds that are tried to add.	application/json model \| example { "title": "OrderIds", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.order.OrderIds", "type": "object", "required": [ "deliveryDate" ], "properties": { "deliveryDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "orderIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[^<>]*$", "maxLength": 255 } } } } { "deliveryDate": "2020-11-20T21:13:35Z", "orderIds": [ "#2020-11-20#T835857946-Test0000000055" ] } { "deliveryDate": "2020-11-20T21:13:35Z", "orderIds": [ "#2020-11-20#T835857946-Test0000000055" ] }
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 'add'	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 }
419	It returns an array of error items for each failed command at bulk operations.	application/json model \| { "title": "errors", "$schema": "http://json-schema.org/draft-04/schema#", "javaType": "com.sos.joc.model.common.Errs", "type": "object", "required": [ "deliveryDate", "errors" ], "properties": { "deliveryDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "errors": { "type": "array", "items": { "javaType": "com.sos.joc.model.common.Err419", "type": "object", "required": [ "surveyDate", "path", "code", "message" ], "properties": { "surveyDate": { "description": "Value is UTC timestamp in ISO 8601 YYYY-MM-DDThh:mm:ss.sZ or empty", "type": "string", "format": "date-time" }, "path": { "description": "absolute path of an object.", "type": "string", "pattern": "^(/\|(/[^/\\\\<>?:\"\|*]+)+)$", "maxLength": 255, "minLength": 1 }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }
420	'add' 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": "add failed!" } } { "deliveryDate": "2016-05-05T21:13:35Z", "surveyDate": "2016-05-05T21:13:33Z", "error": { "code": "JOC-420", "message": "add 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 }