swagger: '2.0' basePath: /api/firmwaredeployment/v3 info: title: Firmware Deployment API version: '3.0.0' x-visibility: 'external' description: | Firmware Deployment API helps to coordinate installation of firmware to devices. The provided operations do not trigger any actions themselves, but are meant to be used by northbound applications to coordinate user and device efforts. Installation tasks consist of different states that require the app user and the target device to participate in order to complete a task. Devices cannot use this API to participate in installation tasks. Instead, devices must use the Deployment Workflow API. Firmware Deployment Service is based on Deployment Workflow Service and reflects all changes applied through Deployment Workflow API. Once a task is created in this API, it will be available also through Deployment Workflow API. In order to be able to create an installation task, users first need to accept the terms and conditions for a specific device and firmware release ID. For this purpose, applications must present the corresponding terms and conditions to a user and forward the user's acceptance to this API. 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 StateInfo: &stateProperties entered: description: date and time when the state was first entered type: string format: date-time updated: description: date and time the state was last updated, will differ from "entered" if state is updated repeatedly type: string format: date-time 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 Errors: invalidRequestError: &invalidRequestError code: mdsp.core.firmwaredeployment.invalidRequest logref: b16ac2e970c4c7329778c79b3e64e8ac message: Request is invalid firmwareReleaseWithGivenIdNotFoundError: &firmwareReleaseWithGivenIdNotFoundError code: mdsp.core.firmwaredeployment.firmwareReleaseWithGivenIdNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Firmware release is not found for release id deviceTypeIdOfDeviceAndFirmwareNotMatchedError: &deviceTypeIdOfDeviceAndFirmwareNotMatchedError code: mdsp.core.firmwaredeployment.deviceTypeIdOfDeviceAndFirmwareNotMatchedError logref: b16ac2e970c4c7329778c79b3e64e8ac message: Device type id of the firmware is not matched with device type id of the device for task creation termsAndConditionsNotAcceptedError: &termsAndConditionsNotAcceptedError code: mdsp.core.firmwaredeployment.termsAndConditionsNotAccepted logref: b16ac2e970c4c7329778c79b3e64e8ac message: Installation task will not be created since terms and conditions document is not accepted for device id and release id deviceNotFoundError: &deviceNotFoundError code: mdsp.core.firmwaredeployment.deviceNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Device is not found with given device id modelKeyNotFoundWithActionTypeAndTaskTypeError: &modelKeyNotFoundWithActionTypeAndTaskTypeError code: mdsp.core.firmwaredeployment.modelKeyNotFoundWithActionTypeAndTaskType logref: b16ac2e970c4c7329778c79b3e64e8ac message: ModelKey not found with actionType , taskType paths: /installationTasks: post: summary: Deploy firmware release to device. description: | Creates a new deployment task for the specified software release. The newly created task can be monitored and controlled # Constraints # This endpoint performs a lot of consistency checks. * All ids must refer to existing entities. * The referenced software release must be compatible with the device. It is possible to create an installation task for a software already installed on the device. It is dependent on the device implementation what will happen in this case. Devices may re-install the software or cancel / abort the task with an error message. # Task Execution # Tasks created via this endpoint are executed in a fire&forget fashion. Execution will start immediately after creation and will run without further user interaction. Progress monitoring is however available. tags: - Firmware Installation security: - firmwareDeployment: - fwdplymnt.c - workflowInstances: - dwf.wfinst.c - deviceInventory: - dinv.r - firmwareReleaseManagement: - fwmng.r consumes: - application/json produces: - application/json parameters: - in: body name: taskDefinition description: content of the new task required: true schema: $ref: '#/definitions/InstallationTaskInfo' responses: 'default': description: Other error with any status code and response body format. '201': description: The newly created task schema: $ref: '#/definitions/InstallationTask' '400': description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation: errors: - <<: *invalidRequestError - <<: *modelKeyNotFoundWithActionTypeAndTaskTypeError '404': description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation: errors: - <<: *deviceNotFoundError '409': description: Conflict schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation: errors: - <<: *deviceTypeIdOfDeviceAndFirmwareNotMatchedError - <<: *termsAndConditionsNotAcceptedError - <<: *firmwareReleaseWithGivenIdNotFoundError get: summary: Lists installation tasks for a device. description: > Returns a paginated list of all installation tasks for the given device id ordered in descending order of creation date (newest task first). Convenience method, equivalent to /search?deviceId={deviceId} It is possible to create an installation task for a software already installed on the device. It is dependent on the device implementation what will happen in this case. Devices may re-install the software or cancel / abort the task with an error message. # Filter Criteria # Filter criteria can be specified as query parameters. Supported parameters are * *type*: filter for tasks of a specific type (firmware, app, etc) * *status*: filter based on task progress, one of "closed" or "open" (closed tasks are tasks in ACTIVATED, CANCELED or FAILED states, open are all other) tags: - Firmware Installation security: - firmwareDeployment: - fwdplymnt.r - workflowInstances: - dwf.wfinst.r - deviceInventory: - dinv.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/deviceId_p' - $ref: '#/parameters/type' - $ref: '#/parameters/status' - $ref: '#/parameters/size' - $ref: '#/parameters/page' - $ref: '#/parameters/history' responses: 'default': description: Other error with any status code and response body format. '200': description: paginated list of tasks schema: $ref: '#/definitions/PaginatedInstallationTask' '400': description: Bad request 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: errors: - <<: *deviceNotFoundError /installationTasks/{id}: get: summary: Get installation task. description: | Returns a task by id. tags: - Firmware Installation security: - firmwareDeployment: - fwdplymnt.r - workflowInstances: - dwf.wfinst.r - deviceInventory: - dinv.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/taskId' - $ref: '#/parameters/history' responses: 'default': description: Other error with any status code and response body format. '200': description: OK schema: $ref: '#/definitions/InstallationTask' '404': description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation: errors: - <<: *deviceNotFoundError patch: summary: Update installation task. description: > Updates the task specified by the given device and task id. This endpoint should be used to perform backend triggered state transitions by advancing the task to the desired target state. # State Machine # The task system uses a state machine to synchronize the state of the device with the state of the backend (see general documentation for more details). All task updates must adhere to the state machine defined in the task. Failing to do so will cause a 409 Conflict error. tags: - Firmware Installation security: - firmwareDeployment: - fwdplymnt.u - workflowInstances: - dwf.wfinst.u - deviceInventory: - dinv.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/taskId' - $ref: '#/parameters/history' - in: body name: updateTaskInfo description: update message required: true schema: $ref: '#/definitions/TaskUpdate' responses: 'default': description: Other error with any status code and response body format. '200': description: The new state of the task schema: $ref: '#/definitions/InstallationTask' '400': description: Bad Request 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: errors: - <<: *deviceNotFoundError '409': description: Conflict '412': description: if If-Match header does not match with current state of the resource, current state is returned in body schema: $ref: '#/definitions/InstallationTask' /termsAndConditions: get: summary: Check acceptance of terms and conditions description: > Checks whether terms and conditions have been accepted for a specific device and release tags: - Terms and Conditions security: - termsAndConditions: - trmsandcnd.r produces: - application/json parameters: - $ref: '#/parameters/deviceId_p' - $ref: '#/parameters/releaseId' responses: 'default': description: Other error with any status code and response body format. '200': description: Acceptance record schema: $ref: '#/definitions/TermsAndConditionsRecord' '204': description: >- if no acceptance record is found, i.e., terms and conditions have not been accepted '400': description: Bad request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError /acceptTermsAndConditions: post: summary: Accept terms and conditions description: > Accepts terms and conditions for a specific device and release. Has no effect if the terms and conditions have already been accepted earlier tags: - Terms and Conditions security: - termsAndConditions: - trmsandcnd.c consumes: - application/json produces: - application/json parameters: - in: body name: acceptance description: acceptance notification required: true schema: $ref: '#/definitions/TermsAndConditionsAcceptance' responses: 'default': description: Other error with any status code and response body format. '201': description: Acceptance record schema: $ref: '#/definitions/TermsAndConditionsRecord' '400': description: Bad request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError definitions: TermsAndConditionsAcceptance: type: object properties: deviceId: type: string releaseId: type: string TermsAndConditionsRecord: type: object properties: deviceId: type: string releaseId: type: string firstAccepted: type: string format: date-time softwareId: type: string bundleId: type: string InstallationTaskInfo: type: object required: - softwareType - softwareId - softwareReleaseId properties: deviceId: type: string description: 'optional, id of the device; will be taken from path if omitted' example: 7d018c... softwareType: description: type of software artifact (firmware, app, etc); list will be extended in future releases type: string enum: - FIRMWARE - APP softwareId: description: globally unique id of the software product (version independent id) type: string example: 7d018c... softwareReleaseId: description: globally unique id of the specific release (version dependent) type: string example: 7d018c... transitions: description: custom transitions type: array maxItems: 100 items: $ref: '#/definitions/Transition' customData: type: object description: optional; arbitrary, user defined block of json containing additional information for the device additionalProperties: type: object example: { "userDefined": {} } TaskUpdate: description: backend sent progress update type: object required: - state - progress properties: state: description: the new state of the task (might be same as current state) type: string enum: - CREATED - DOWNLOAD - DOWNLOADING - DOWNLOADED - INSTALL - INSTALLING - INSTALLED - ACTIVATE - ACTIVATING - ACTIVATED - CANCELED - FAILED 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: 'optional; status message / info, free text from backend' 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 InstallationTask: description: single task type: object properties: id: description: globally unique id of the task type: string example: 7d018c... deviceId: description: id of the device owning the task type: string example: 7d018c... softwareType: description: >- type of software artifact: firmware, app, etc; list will be extended in future releases type: string enum: - FIRMWARE - APP softwareId: description: globally unique id of the software product (version independent id) type: string example: 7d018c... softwareReleaseId: description: globally unique id of the specific release (version dependent) type: string example: 7d018c... softwareVersion: description: the version of the software as human readable string type: string example: '2.1' actionType: description: >- Indicates whether to install or remove the software type: string enum: - INSTALL - REMOVE example: INSTALL shouldCancel: description: if set to true, task is going to be cancelled type: boolean example: FALSE transitions: description: possible set of transitions type: array maxItems: 100 items: $ref: '#/definitions/Transition' history: description: previously passed states of task type: array maxItems: 100 items: $ref: '#/definitions/InstallationStateInfo' artifacts: type: array maxItems: 50 items: $ref: '#/definitions/InstallationArtifact' customData: type: object description: >- optional; arbitrary, user defined block of json containing additional information for the device additionalProperties: type: object example: { "userDefined": {} } createdAt: description: date and time when the task was created type: string format: date-time currentState: $ref: '#/definitions/InstallationStateInfo' InstallationArtifact: type: object required: - checksum - name - uri properties: name: type: string description: name of the file example: myFile.txt uri: type: string description: download URI example: 'http://...' checksum: type: string description: 'hash of the file in format `:`' example: 'sha1:cf23...' validUntil: type: string description: expiry time for `uri` format: date-time InstallationStateInfo: type: object description: information about a single state of the state machine properties: <<: *stateProperties state: type: string example: DOWNLOAD description: name of the state enum: - CREATED - DOWNLOAD - DOWNLOADING - DOWNLOADED - INSTALL - INSTALLING - INSTALLED - ACTIVATE - ACTIVATING - ACTIVATED - CANCELED - FAILED PaginatedInstallationTask: type: object description: paginated list of configuration update tasks properties: content: type: array maxItems: 50 items: $ref: '#/definitions/InstallationTask' <<: *pageProperties Transition: type: object description: Information about the transition status properties: type: type: string description: type of the transition from: type: string example: DOWNLOAD description: name of the state enum: - CREATED - DOWNLOAD - DOWNLOADING - DOWNLOADED - INSTALL - INSTALLING - INSTALLED - ACTIVATE - ACTIVATING - ACTIVATED - CANCELED - FAILED to: type: string example: INSTALL description: name of the state enum: - CREATED - DOWNLOAD - DOWNLOADING - DOWNLOADED - INSTALL - INSTALLING - INSTALLED - ACTIVATE - ACTIVATING - ACTIVATED - CANCELED - FAILED details: type: object 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: taskId: name: id in: path description: id of the task required: true type: string deviceId_p: name: deviceId in: query description: id of the device required: true type: string id: name: id in: path description: Task Id required: true type: string type: name: type in: query description: Task Type required: false type: string status: name: status in: query description: Task status required: false type: string enum: - closed - open history: name: history in: query type: boolean description: Show task history releaseId: name: releaseId in: query description: releaseId required: true 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: Firmware Installation description: Monitor, plan, create and update installation tasks - name: Terms and Conditions description: Query and accept terms and conditions securityDefinitions: firmwareDeployment: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: fwdplymnt.c: Permission to create new deployment tasks fwdplymnt.r: Permission to view / list deployment tasks fwdplymnt.u: Permission to modify / update deployment tasks termsAndConditions: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: trmsandcnd.r: Permission to view / list terms and conditions acceptance trmsandcnd.c: Permission to create terms and conditions acceptance workflowInstances: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dwf.wfinst.c: (Transitive scope) Permission to create new workflow instances dwf.wfinst.u: (Transitive scope) Permission to update workflow instances dwf.wfinst.r: (Transitive scope) Permission to view / list workflow instances deviceInventory: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dinv.r : Transitive scope firmwareReleaseManagement: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: fwmng.r : Transitive scope