Table of contents:
Legend of the table headers used in this section:
- Name: Field name
- Key: Technical key in API
- Description: Field description
- Mandatory: Set to “X” if it has to be set by the user at creation time.
- User Managed (through Management UI or Management API)
- (C)reate: Field can be set by the user at entity creation time.
- (U)pdate: Field can be updated by the user after creation time.
- empty: Field is set by the update server and cannot be managed by the user.
- Max Size: Maximum size in bytes for string fields.
- Filter/Sort Parameter: Set to “X” if it is possible to filter on or sort by that field. Examples can be found in the Target filtering and the FIQL syntax search query (see Query parameters).
Common fields
Entities have a set of common fields that are set by the update server automatically.
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Technical Identifier | id | Technical identifier of the entity. Note: It is also used in the API to identify the entity, except for the target. | X | |||
Entity created by | createdBy | Entity was originally created by (Bosch user, Rollout cloud user, controller, anonymous, etc.) | ||||
Entity last modified by | lastModifiedBy | Entity was last modified by (Bosch user, Rollout cloud user, controller, anonymous, etc.) | ||||
Entity created at | createdAt | Time stamp in UTC milliseconds of when the entity was originally created. | ||||
Entity last modified at | lastModifiedAt | Time stamp in UTC milliseconds of when the entity was last modified. |
User-manageable entities
Targets
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Target Controller ID | controllerId | Identifies the target of the controlling software instance on the Target. | X | C | X | |
Target Name | name | The name of the Target. Note: In the UI, if the target name is not set, we use the value of the controller ID | X | C,U | 64 | X |
Target Description | description | A description of the Target. | C,U | 512 | X | |
Target Update Status | updateStatus | The updated status of the Target, reflecting its current position in the Target state machine. Check potential states at the State machines. | X | |||
Target Security Token | securityToken | Pre-Shared key that allows _Target_s to authenticate at Direct Device Integration API if enabled in the tenant settings. | C,U | 128 | ||
Last poll time | lastControllerRequestAt | Last time the Target polled. In many scenarios, the Target will poll the update server regularly to check for potential updates. If that poll does not happen, it might imply that the Target is offline. | X | |||
Last known Target address URI | address | The last known address URI of the Target. Includes information on how the Target is connected either directly (DDI) through HTTP or indirectly (DMF) through AMQP. | C,U | |||
Name of assigned Tag | tag | The name of the Tag that was assigned to the Target. Can be used to filter based on the assigned Tag. | X | |||
Target controller attributes | attribute.* | The value of an attribute key for Targets. Can be used to filter based on a special Target attribute key, e.g. | X | |||
Name of assigned Distribution Set | assignedds.name | The name of the Distribution Set that is assigned to the Target. Can be used to filter based on assigned Distribution Sets. | X | |||
Version of assigned Distribution Set | assignedds.version | The name of the Distribution Set that is assigned to the Target. Can be used to filter based on assigned Distribution Sets. | X | |||
Name of installed Distribution Set | installedds.name | The name of the Distribution Set that is installed on the Target. Can be used to filter based on installed Distribution Sets. | X | |||
Version of installed Distribution Set | installedds.version | The name of the Distribution Set that is installed on the Target. Can be used to filter based on installed Distribution Sets. | X | |||
Metadata map of a Target | metadata.* | The value of a Metadata key for the Target. Target metadata is managed by the operator (as opposed to target attributes, which are controlled by the device itself). | C,U | key:128, value:4000 | X | |
Target Type | targetType | Target Type defined by its id field Can be used for compatibility checks between Targets and Distribution Sets | C,U | X |
Target Type
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Target Type name | name | The name of the Target Type | X | C,U | 64 | X |
Target Type description | description | A description of the Target Type | C,U | 512 | X | |
Target Type colour | colour | The Target Type colour that can be used in the Management UI for presentation. | C,U |
Distribution Set
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Distribution Set Name | name | The name of the Distribution Set. | X | C,U | 64 | X |
Distribution Set Description | description | A description of the Distribution Set | C,U | 512 | X | |
Distribution Set Version | version | A free-text version field of the Distribution Set | X | C,U | 64 | X |
Distribution Set Type | type | Distribution Set Type identified by its key field. | C | |||
Distribution Set Required Migration Step flag | requiredMigrationStep | True if the installation of this distribution set assignment involves migration steps, false otherwise. | C,U | |||
Distribution Set Module Set Complete flag | complete | True if the software module setup of this Distribution Set is completed (as defined by the Distribution SetType). | X | |||
Metadata map of Distribution Set | metadata.* | The value of a Metadata key for the Distribution Set. Can be used to filter based on a special Metadata key | X | |||
Name of assigned Tag | tag | The name of the Tag that was assigned to the Distribution Set. Can be used to filter based on the assigned Tag. | X | |||
Distribution Set valid flag | valid | True by default and false after the user invalidates the distribution set. | X |
Distribution Set Type
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Distribution SetType Name | name | The name of the Distribution SetType. | X | C,U | 64 | X |
Distribution SetType Description | description | A description of the Distribution SetType | C,U | 512 | X | |
Distribution SetType Key | key | Functional key of the distribution set type. | X | C | 64 | X |
Software Module
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Software Module Name | name | The name of the Software Module. | X | C,U | 64 | X |
Software Module Description | description | A description of the Software Module | C,U | 512 | X | |
Software Module Version | version | A free-text version field of the Software Module | X | C,U | 64 | X |
Software Module Type | type | Software Module Type identified by its key field. | X | C | X | |
Software Module Vendor | vendor | The software vendor. | C,U | 256 | ||
Metadata map of Software Module | metadata.* | The value of a Metadata key for a Software Module. Can be used to filter based on a Metadata key | C,U | key:128, value:4000 | X |
Software Module Type
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Software Module Type Name | name | The name of the Software Module Type. | X | C,U | 64 | X |
Software Module Type Description | description | A description of the Software Module Type | C,U | 512 | X | |
Software Module Type Key | key | Functional key of the Software Module Type. | X | C | 64 | X |
Software Module Type Max Assignments | maxAssignments | Software modules of that type can be assigned at this maximum number (e.g., operating system only once). | X | C | X |
Artifact
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Artifact File Name | filename | The name of the Artifact. | X | C | 256 | |
Artifact File MD5 hash sum | md5Hash | The MD5 hash sum of the Artifact. | 32 | |||
Artifact File SHA1 hash sum | sha1Hash | The SHA1 hash sum of the Artifact in base16 encoding. | 40 | |||
Artifact File SHA256 hash sum | sha256Hash | The SHA-256 hash sum of the Artifact in base16 encoding. | 64 | |||
Artifact File size | size | The size of the Artifact in bytes. |
Tag
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Tag Name | name | The name of the Tag. | X | C,U | 64 | X |
Tag Description | description | A description of the Tag | C,U | 512 | X | |
Tag Colour | colour | The Tag colour that can be used in the Management UI for presentation. | C,U | 16 | X |
Metadata
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Metadata key | key | Functional key of the metadata entry. | X | C | 128 | X |
Metadata value | value | The value of the metadata entry. | X | C,U | 4000 | X |
System managed (sub-)entities
Action
Name | Key | Description | Mandatory | User Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
Action type | type | Defines the type of action, i.e. an update or the cancel of a previously communicated update. Can be update or cancel. | ||||
Action status | status | Defines if action is still pending or finished. Can be pending or finished. | X | |||
Action force type | forceType | Specifies if the action is in soft or forced mode. Gives the device a hint on how and /or when to process the action. The mode forced means “as soon as possible” while soft means “optional, to be decided by the device user”. Can be soft, forced, or timeforced. | X | |||
Action time force | forceTime | Only applicable to the mode timeforced. Specifies the timestamp in UTC milliseconds at which the action should switch to forced mode. | X |
Action Status
Name | Key | Description | Mandatory | DDI/DMF Managed | Max Size | Filter/Sort Parameter |
|---|---|---|---|---|---|---|
ActionStatus type | type | Structured type information of the action status. Terminated actions can be in status finished, error, or canceled. Ongoing actions can be in status running, warning, retrieved (by target), or canceling. | X | X | X | |
ActionStatus messages list | message | List of messages for unstructured information as part of the status update. | X | 512 per entry. Will be automatically split into multiple entries if longer. | ||
ActionStatus was reported at | reportedAt | Time stamp in UTC milliseconds at which the ActionStatus was reported. | X |
Deleting and archiving Software Modules
In some cases, Software Modules (and their corresponding data) may not be fully removed if a Software Module is already assigned to a Distribution Set that was assigned to a target. Since Rollouts ensures the completeness of the device’s software history, this data needs to be persisted. However, the binary data of the artifacts is not necessary for this purpose and will be deleted.
The delete process, performed when there are historical connections to targets, is called a soft delete. This process marks the Software Module as deleted and removes the artifact, but it won’t delete the metadata that describes the Software Module and its associated Artifacts. Software Modules marked as deleted won’t be visible to the user when he requests all Software Modules.
If there are no connections to Distribution Sets or targets, the server performs a hard delete. This process deletes all stored data, including all meta information.
For further information about soft-delete and hard-delete, see Data model.