swagger: '2.0' basePath: /api/deploymentworkflow/v3 info: title: 'Deployment Workflow API' version: '3.0.0' x-visibility: 'external' description: | This API allows to create and execute reusable deployment worfklows for devices defined by Device Management. Each workflow is modeled as a state machine running in the backend, with tasks to be executed against devices. Examples of tasks are installation of firmware or other types of commands issued to devices. The API offers model resources to be used to set up workflow templates, which define possible workflow states and transistions between them. While device builders can define custom models, predefined models are available for default installation and removal tasks. Instance resources represent instantiated workflows and allow to trigger state transitions. Only a subset of the operations in this API is meant for use by agents, defined in the following table. | Path | Method | Audience | |--------|------|----------| | models | POST | Northbound | | models | GET | Northbound | | models | DELETE | Northbound | | instances | POST | Northbound | | instances | GET | Northbound, Southbound | | instances/{id} | GET | Northbound, Southbound | | instances/{id} | PATCH | Northbound, Southbound | | instances/{id}/cancel | POST | Northbound, Southbound | Northbound: The term stands for interactive or technical users which initiate the request Southbound: The term stands for agents which initiate the request x-templates: Pagination: &pageProperties page: type: object properties: size: type: integer format: int64 description: the number of records per page example: 20 totalElements: type: integer format: int64 description: the total number of rows/records example: 1 totalPages: type: integer format: int64 description: the total number of pages example: 1 number: type: integer format: int64 description: the current page number example: 0 Errors: invalidRequestError: &invalidRequestError code: mdsp.core.deploymentworkflow.invalidRequest logref: b16ac2e970c4c7329778c79b3e64e8ac message: Request processor can identify the request as neither AGENT nor USER modelCycleDetectedError: &modelCycleDetectedError code: mdsp.core.deploymentworkflow.modelCycleDetected logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model should not have cycle. Detected cycle is modelStatesNotReachableError: &modelStatesNotReachableError code: mdsp.core.deploymentworkflow.modelStatesNotReachable logref: b16ac2e970c4c7329778c79b3e64e8ac message: All states must be reachable from initial state. Listed states are not reachable modelStateHasNoOutgoingTransitionError: &modelStateHasNoOutgoingTransitionError code: mdsp.core.deploymentworkflow.modelStateHasNoOutgoingTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: If no outgoing transition, state should be final. state has no outgoing transition modelFinalStateHasOutgoingTransitionError: &modelFinalStateHasOutgoingTransitionError code: mdsp.core.deploymentworkflow.modelFinalStateHasOutgoingTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: Final state should not have outgoing transition. has outgoing transitions which are modelCancelStateHasOutgoingTransitionError: &modelCancelStateHasOutgoingTransitionError code: mdsp.core.deploymentworkflow.modelCancelStateHasOutgoingTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: Cancel state should not have outgoing transition. has outgoing transitions which are stateOfGroupNotExistInModelError: &stateOfGroupNotExistInModelError code: mdsp.core.deploymentworkflow.stateOfGroupNotExistInModel logref: b16ac2e970c4c7329778c79b3e64e8ac message: state in group doesn't exist in model modelHasNoFinalStateError: &modelHasNoFinalStateError code: mdsp.core.deploymentworkflow.modelHasNoFinalState logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model should have at least one final state modelHasMultipleInitialStatesError: &modelHasMultipleInitialStatesError code: mdsp.core.deploymentworkflow.modelHasMultipleInitialStates logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model should have one initial state. Listed states have been defined as initial modelHasMultipleCancelStatesError: &modelHasMultipleCancelStatesError code: mdsp.core.deploymentworkflow.modelHasMultipleCancelStates logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model should have one cancel state. Listed states have been defined as cancel modelStateNameNotUniqueError: &modelStateNameNotUniqueError code: mdsp.core.deploymentworkflow.modelStateNameNotUnique logref: b16ac2e970c4c7329778c79b3e64e8ac message: State name must be unique. state has already been created modelHasMultipleInstantaneousStateTransitionError: &modelHasMultipleInstantaneousStateTransitionError code: mdsp.core.deploymentworkflow.modelHasMultipleInstantaneousStateTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: There may not be more than one instantaneous state transition from state modelTransitionKeyNotUniqueError: &modelTransitionKeyNotUniqueError code: mdsp.core.deploymentworkflow.modelTransitionKeyNotUnique logref: b16ac2e970c4c7329778c79b3e64e8ac message: There must be only one transition from to . Please check transitions in the model. stateNotFoundInModelError: &stateNotFoundInModelError code: mdsp.core.deploymentworkflow.stateNotFoundInModel logref: b16ac2e970c4c7329778c79b3e64e8ac message: State names given in transition cannot be found in the model. Please check the state names in transition from - to deviceNotFoundForCreateInstanceError: &deviceNotFoundForCreateInstanceError code: mdsp.core.deploymentworkflow.deviceNotFoundForCreateInstance logref: b16ac2e970c4c7329778c79b3e64e8ac message: Instance can not be created since device for id in request does not exist modelNotFoundForCreateInstanceError: &modelNotFoundForCreateInstanceError code: mdsp.core.deploymentworkflow.modelNotFoundForCreateInstance logref: b16ac2e970c4c7329778c79b3e64e8ac message: Instance can not be created since model for key in request does not exist deviceNotFoundError: &deviceNotFoundError code: mdsp.core.deploymentworkflow.deviceNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Device for device id does not exist agentNotAllowedError: &agentNotAllowedError code: mdsp.core.deploymentworkflow.agentNotAllowed logref: b16ac2e970c4c7329778c79b3e64e8ac message: Agent for id is not allowed to access device data for device for id instanceNotFoundError: &instanceNotFoundError code: mdsp.core.deploymentworkflow.instanceNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Instance is not found for id invalidCustomTransitionError: &invalidCustomTransitionError code: mdsp.core.deploymentworkflow.invalidCustomTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: Given custom transition type %s is not in allowed types for the transition of given model (from state to state modelNotFoundForGivenKeyError: &modelNotFoundForGivenKeyError code: mdsp.core.deploymentworkflow.modelNotFoundForGivenKey logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model not found for key customTransitionNotExistInModelError: &customTransitionNotExistInModelError code: mdsp.core.deploymentworkflow.customTransitionNotExistInModel logref: b16ac2e970c4c7329778c79b3e64e8ac message: The given custom transition does not exist in model transitions (from state ) duplicateCustomTransitionsError: &duplicateCustomTransitionsError code: mdsp.core.deploymentworkflow.duplicateCustomTransitions logref: b16ac2e970c4c7329778c79b3e64e8ac message: There is duplicate custom transition from state to state invalidInstanceTransitionError: &invalidInstanceTransitionError code: mdsp.core.deploymentworkflow.invalidInstanceTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: There is no transition from to ) transitionTypeNotAllowedError: &transitionTypeNotAllowedError code: mdsp.core.deploymentworkflow.transitionTypeNotAllowed logref: b16ac2e970c4c7329778c79b3e64e8ac message: Invalid state transition ( -> ) is attempted. modelStateIsInitialAndFinalError: &modelStateIsInitialAndFinalError code: mdsp.core.deploymentworkflow.modelStateIsInitialAndFinal logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model state should be of one state type, it should not be initial and final simultaneously modelStateIsInitialAndCancelError: &modelStateIsInitialAndCancelError code: mdsp.core.deploymentworkflow.modelStateIsInitialAndCancel logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model state should be of one state type, it should not be initial and cancel simultaneously modelStateIsFinalAndCancelError: &modelStateIsFinalAndCancelError code: mdsp.core.deploymentworkflow.modelStateIsFinalAndCancel logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model state should be of one state type, it should not be final and cancel simultaneously modelKeyNotUniqueError: &modelKeyNotUniqueError code: mdsp.core.deploymentworkflow.modelKeyNotUnique logref: b16ac2e970c4c7329778c79b3e64e8ac message: Model with key already exists. paths: /models: post: summary: Add a new workflow model description: > Add a new workflow model tags: - Workflow Models security: - workflowModels: - dwf.wfmodels.c consumes: - application/json produces: - application/json parameters: - in: body name: Model description: Workflow model object that needs to be added required: true schema: $ref: '#/definitions/Model' responses: 'default': description: Other error with any status code and response body format. '201': description: Workflow model created schema: $ref: '#/definitions/Model' '400': description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *modelCycleDetectedError - <<: *modelStatesNotReachableError - <<: *modelStateHasNoOutgoingTransitionError - <<: *modelFinalStateHasOutgoingTransitionError - <<: *modelCancelStateHasOutgoingTransitionError - <<: *stateOfGroupNotExistInModelError - <<: *modelHasNoFinalStateError - <<: *modelHasMultipleInitialStatesError - <<: *modelHasMultipleCancelStatesError - <<: *modelStateNameNotUniqueError - <<: *modelHasMultipleInstantaneousStateTransitionError - <<: *modelTransitionKeyNotUniqueError - <<: *stateNotFoundInModelError - <<: *modelStateIsInitialAndFinalError - <<: *modelStateIsInitialAndCancelError - <<: *modelStateIsFinalAndCancelError - <<: *modelKeyNotUniqueError /models/{modelKey}: get: summary: Model description for a given key description: > Model description for a given key tags: - Workflow Models security: - workflowModels: - dwf.wfmodels.r consumes: - application/json produces: - application/json parameters: - name: modelKey in: path description: Unique key for the model required: true type: string responses: 'default': description: Other error with any status code and response body format. '200': description: Model description with the provided key schema: $ref: '#/definitions/Model' '400': description: if request is invalid schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError '404': description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation while querying a non-existent model: errors: - <<: *modelNotFoundForGivenKeyError delete: summary: Deletes a model with a given key description: > Deletes a model with a given key tags: - Workflow Models security: - workflowModels: - dwf.wfmodels.d consumes: - application/json produces: - application/json parameters: - name: modelKey in: path description: Key for the model required: true type: string responses: 'default': description: Other error with any status code and response body format. '204': description: No content '400': description: if request is invalid schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError /instances: post: summary: Add a new workflow instance description: > Add a new workflow instance tags: - Workflow Instances security: - workflowInstances: - dwf.wfinst.c - deviceInventory: - dinv.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/modelDetails' - $ref: '#/parameters/history' - in: body name: Workflow Instance description: Workflow instance that needs to be created required: true schema: $ref: '#/definitions/InstanceRequest' responses: 'default': description: Other error with any status code and response body format. '201': description: Workflow instance created schema: $ref: '#/definitions/Instance' '400': description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError - <<: *invalidCustomTransitionError - <<: *customTransitionNotExistInModelError - <<: *duplicateCustomTransitionsError '409': description: Conflict schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *deviceNotFoundForCreateInstanceError - <<: *modelNotFoundForCreateInstanceError get: summary: List of instance descriptions belonging to the caller's tenant description: > List of instance descriptions belonging to the caller's tenant By default, this endpoint returns the list of instances in a specific order and predetermined paging properties. These defaults are: - Hide model details. Equivalent of query parameter modelDetails = flase - Hide history Equivalent of query parameter history = false - Ascending sort on createdAt date - 10 entries per page tags: - Workflow Instances security: - workflowInstances: - dwf.wfinst.r - southboundAccess: - edge.use consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/modelDetails' - $ref: '#/parameters/history' - $ref: '#/parameters/currentState' - $ref: '#/parameters/stateGroup' - $ref: '#/parameters/deviceId' - $ref: '#/parameters/modelKey' responses: 'default': description: Other error with any status code and response body format. '200': description: Instance description for a given id schema: $ref: '#/definitions/PaginatedInstanceList' '400': description: if request is invalid schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError /instances/{id}: get: summary: Instance description for a given id description: > Instance description for a given id tags: - Workflow Instances security: - workflowInstances: - dwf.wfinst.r - southboundAccess: - edge.use consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/instanceId' - $ref: '#/parameters/modelDetails' - $ref: '#/parameters/history' responses: 'default': description: Other error with any status code and response body format. '200': description: Instance description for for a given id schema: $ref: '#/definitions/Instance' '400': description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError - <<: *transitionTypeNotAllowedError '404': description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation while querying a non-existent instance: errors: - <<: *instanceNotFoundError patch: summary: Modify current state of a workflow instance description: > Modify current state of a workflow instance tags: - Workflow Instances security: - workflowInstances: - dwf.wfinst.u - deviceInventory: - dinv.r - southboundAccess: - edge.use consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/instanceId' - $ref: '#/parameters/history' - $ref: '#/parameters/model' - in: body name: State Info description: State to be used for advancing the workflow instance to. This is going to be used as progress report from devices or backend. required: true schema: $ref: '#/definitions/StateInfo' responses: 'default': description: Other error with any status code and response body format. '200': description: Current state modified successfully schema: $ref: '#/definitions/Instance' '400': description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError - <<: *invalidCustomTransitionError '403': description: Forbidden schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation while updating a non-existent instance: errors: - <<: *agentNotAllowedError '404': description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation while updating a non-existent instance: errors: - <<: *instanceNotFoundError '409': description: Conflict schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *deviceNotFoundError - <<: *invalidInstanceTransitionError /instances/{id}/cancel : post: summary: Cancels the workflow instance if the transition from canceled to current state is defined and available description: > Cancels the workflow instance if the transition from canceled to current state is defined and available tags: - Workflow Instances security: - workflowInstances: - dwf.wfinst.u - deviceInventory: - dinv.r - southboundAccess: - edge.use consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/instanceId' - $ref: '#/parameters/history' - $ref: '#/parameters/model' responses: 'default': description: Other error with any status code and response body format. '200': description: Current state modified successfully schema: $ref: '#/definitions/Instance' '400': description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError - <<: *agentNotAllowedError - <<: *invalidCustomTransitionError - <<: *invalidInstanceTransitionError - <<: *transitionTypeNotAllowedError '403': description: Forbidden schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation while updating a non-existent instance: errors: - <<: *agentNotAllowedError '404': description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation while updating a non-existent instance: errors: - <<: *instanceNotFoundError '409': description: Conflict schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *deviceNotFoundError definitions: Model: type: object properties: key: type: string description: User provided unique model name example: com.siemens.nano.fwupdate states: type: array maxItems: 50 items: $ref: '#/definitions/State' transitions: type: array maxItems: 100 items: $ref: '#/definitions/Transition' groups: type: array maxItems: 5 items: $ref: '#/definitions/StateGroup' State: type: object required: - name - description properties: name: type: string description: type: string initial: type: boolean final: type: boolean cancel: type: boolean Transition: type: object required: - from - to - type properties: from: type: string to: type: string type: $ref: '#/definitions/TransitionType' allowedTypes: type: array maxItems: 20 items: $ref: '#/definitions/TransitionType' CustomTransition: type: object required: - from - to - type properties: from: type: string to: type: string type: $ref: '#/definitions/TransitionType' details: type: object additionalProperties: type: object example: { "userDefined": {} } TransitionType: type: string enum: - INSTANTANEOUS - BACKEND_TRIGGER - DEVICE_TRIGGER - BACKEND_TIME_TRIGGER - DEVICE_TIME_TRIGGER StateGroup: type: object properties: name: type: string states: type: array maxItems: 50 items: type: string ModelCustomization: type: object properties: key: type: string customTransitions: type: array maxItems: 100 items: $ref: '#/definitions/CustomTransition' InstanceRequest: type: object properties: deviceId: type: string model: $ref: '#/definitions/ModelCustomization' data: type: object additionalProperties: type: object example: { "userDefined": {} } InstanceModel: type: object properties: key: type: string states: type: array maxItems: 50 items: $ref: '#/definitions/State' transitions: type: array maxItems: 100 items: $ref: '#/definitions/CustomTransition' stateGroups: type: array maxItems: 5 items: $ref: '#/definitions/StateGroup' Instance: type: object properties: id: type: string deviceId: type: string createdAt: description: date and time when the instance was created type: string format: date-time currentState: $ref: '#/definitions/StateInfo' history: type: array maxItems: 100 items: $ref : '#/definitions/StateInfo' model: $ref: '#/definitions/InstanceModel' data: type: object additionalProperties: type: object example: { "userDefined": {} } StateInfo: type: object description: information about a single state of the state machine properties: entered: description: date and time when the state was first entered type: string format: date-time readOnly: true updated: description: date and time the state was last updated, will differ from "entered" if state is updated repeatedly type: string format: date-time readOnly: true progress: description: 'progress in current state as value in [0.0, 1.0]' type: number format: float minimum: 0 maximum: 1 message: type: string description: 'status message / info, free text from device' minLength: 0 maxLength: 200 details: type: object description: arbitrary block of json data, should be used to report additional information such as error details, stack traces, etc; max size in string representation is 20k minLength: 0 maxLength: 20000 additionalProperties: type: object example: { "userDefined": {} } state: type: string example: DOWNLOAD description: name of the state PaginatedInstanceList: type: object description: paginated list of instances properties: content: type: array maxItems: 50 items: $ref: '#/definitions/Instance' <<: *pageProperties ErrorResponse: type: object properties: errors: type: array maxItems: 10 items: $ref: '#/definitions/Error' Error: type: object properties: code: type: string description: identifier code for the reason of the error logref: type: string description: log correlation ID message: type: string description: error message parameters: modelDetails: name: model in: query description: Boolean flag to include the model used for the instance required: false type: boolean history: name: history in: query description: Boolean flag to include the transition history of the instance required: false type: boolean currentState: name: currentState in: query description: Filter instances based on the current state value required: false type: string stateGroup: name: group in: query description: Filter instances based on the state group they are in required: false type: string deviceId: name: deviceId in: query description: Filter instances belonging to a specific device with deviceId required: false type: string modelKey: name: modelKey in: query description: Filter instances that are created from a given key required: false type: string model: name: model in: query description: Boolean flag to include the model of the instance in response required: false type: boolean instanceId: name: id in: path description: Instance id required: true type: string owner: name: owner in: query description: Owner tenant required: false type: string size: name: size in: query type: integer format: int32 default: 10 maximum: 50 description: The maximum number of elements returned in one page page: name: page in: query type: integer format: int32 default: 0 description: The (0-based) index of the page sort: name: sort in: query type: string required: false description: 'The order of returned elements.
Multiple fields could be used separated by commas (e.g. ''field1,field2'').
Descending order could be requested by appending '',desc'' at the end of parameter.(e.g. ''field1,field2,desc'')' tags: - name: Workflow Models description: Workflow models to describe the templates for workflow instances - name: Workflow Instances description: Instantiate and specialize workflows from existing models and execute them securityDefinitions: workflowModels: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dwf.wfmodels.c: Permission to create new workflow models dwf.wfmodels.r: Permission to view / list workflow models dwf.wfmodels.d: Permission to delete workflow models workflowInstances: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dwf.wfinst.c: Permission to create new workflow instances dwf.wfinst.u: Permission to update workflow instances dwf.wfinst.r: Permission to view / list workflow instances southboundAccess: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: edge.use: Permission to get/update instances with agent token deviceInventory: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dinv.r : Transitive scope