Skip to content

Deployment Workflow Service

Idea

This service provides interfaces for creating, maintaining and executing user defined workflows to enable handshaking processes with devices.

Info

The Deployment Workflow Service is currently only available in region Europe 1.

Access

For accessing this service you need to have the respective roles listed in Deployment Workflow Service roles and scopes.

Basics

Workflow Models

Device related workflows are typically used to track the progress of a job, e.g. file upload. These workflows are based on state machines. They define the possible states and allowed transitions between those states.

The Deployment Workflow Service provides an interface to define and instantiate custom workflow models. The workflow models serve as templates for workflows. When creating an instance of a workflow model, the workflow can be customized to differ from the workflow model.

Each state of a workflow model can be assigned user defined labels. This allows users to query for jobs with a specific label. E.g. if a label exists for the state "open", it is possible to query for all open jobs.

Predefined Workflow Models

MindSphere provides three predefined workflow models, which can be instantiated for software installation and configuration workflows using the model keys:

Workflow Model Model Key Description
App installation mdsp-core-applicationInstallation This workflow is instantiated by the Edge App Deployment Service for tracking the installation status. The workflow is defined by the state machine shown here.
App removal mdsp-core-applicationRemoval This workflow is instantiated by the Edge App Deployment Service for tracking the deinstallation status. The workflow is defined by the state machine shown here.
Firmware installation mdsp-core-firmwareInstallation This workflow is instantiated by the Firmware Deployment Service for tracking the installation status. The workflow is defined by the state machine shown here.
Configuration Deployment mdsp-core-configurationDeployment This workflow is instantiated by the Device Configuration Service for tracking the configuration deployment status. The workflow is defined by the state machine shown here.

Workflow Instances

Workflow instances are used for status synchronization with devices. When creating a workflow instance, its workflow can be customized to differ from the workflow model: The user can add custom transitions or use the data field to provide workflow related information. This information can be interpreted by devices to perform the desired operation.

When a device shall perform a job, a workflow instance is sent to the device. The transition rules of the workflow instance tell the device how to act. When a transition depends on the device to perform an action, the device must send a message to the backend. This triggers the backend to update the state of the state machine.

If multiple jobs are sent to a device which does not support parallel execution, it is recommended that the device executes them in the order they are reported by the backend.

Status Messages

Devices must acknowledge the receipt of jobs to trigger the transition of the state machine which transfers the ownership of the job to the device. Failing to do so will cause problems, if the job is canceled or time triggered installations are used.

Devices should repeatedly update the job status with new progress information to inform the operator about the progress.

Devices must update the job status after executing a job. This status update can typically report success, failure, or cancellation, e.g. after a timeout. When a job ends with status CANCELED, it signals to the backend that a retry is reasonable. The status FAILED might occur due to an invalid input file. In this case, the device should send an informative message and additional status details.

Features

The Deployment Workflow Service exposes its API for realizing the following tasks:

  • create, read and delete workflow models for devices
  • create and update workflows for devices

Limitations

  • Workflow instances older than 90 days are automatically cleaned up.

Example Scenario

The producer of a sensor, which uploads data to MindSphere, has developed an app for communication with the sensor. They define a handshaking model for communication between the device and the backend. This model is used whenever the app establishes a connection with the sensor.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.