Entity Definitions

Legend:

  • 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 user at entity creation time.
    • (U)pdate: Field can be updated by user after creation time.
    • empty: Field is set by the update server and not manageable 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 on Target Filters and FIQL syntax search query.
  • Notes: Additional remarks

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 Notes
Technical Identifier id Technical identifier of the entity. X Is with the exception of target also used in the API to identify the entity.
Entity created by createdBy Entity was originally created by (Bosch IoT Permission user, Rollout cloud user, ampq controller, anonymous etc.)
Entity last modified by lastModifiedBy Entity was last modified by (Bosch IoT Permission user, Rollout cloud user, ampq controller, anonymous etc.)
Entity created at createdAt Time stamp in UTC milliseconds the entity was originally created at.
Entity last modified at lastModifiedAt Time stamp in UTC milliseconds the entity was last modified at.

User manageable entities

Targets

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
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. X C,U 64 X Is in the UI set to the value of controller ID if not set.
Target Description description A description of the Target. C,U 512 X
Target Update Status updateStatus The update status of the Target that reflects the current position in the Target state machine. X Check potential states here.
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 on a regular basis to look 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 of 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. X Can be used to filter based on assigned Tag
Target controller attributes attribute.* The value of a attribute key for Targets. X Can be used to filter based on a special Target attribute key e.g. attribute.revision==1.1
Name of assigned Distribution Set assignedds.name The name of the Distribution Set that is assigned to the Target. X Can be used to filter based on assigned Distribution Sets
Version of assigned Distribution Set assignedds.version The name of the Distribution Set that is assigned to the Target. X Can be used to filter based on assigned Distribution Sets
Name of installed Distribution Set installedds.name The name of the Distribution Set that is installed on the Target. X Can be used to filter based on installed Distribution Sets
Version of installed Distribution Set installedds.version The name of the Distribution Set that is installed on the Target. X Can be used to filter based on installed Distribution Sets
Metadata map of a Target metadata.* The value of a Metadata key for the Target. C,U key:128, value:4000 Target meta data are managed by the operator (as opposed to target attributes which are controlled by the device itself).

Distribution Set

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
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. X Can be used to filter based on a special Metadata key e.g. * is=metaKey. Then query is: metadata.metaKey==metaValue
Name of assigned Tag tag The name of the Tag that was assigned to the Distribution Set. X Can be used to filter based on assigned Tag

Distribution Set Type

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
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 Notes
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 Software Module. C,U key:128, value:4000 X Can be used to filter based on a Metadata key e.g. * is=metaKey. Then query is: metadata.metaKey==metaValue. The optional targetVisible=true flag allows providing a Metadata element to the target as part of an update. This is supported by DDI and DMF API.

Software Module Type

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
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 Notes
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 size size The size of the Artifact in bytes.

Tag

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
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 Management UI for presentation. C,U 16 X

Metadata

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
Meta data key key Functional key of the meta data entry. X C 128 X
Meta data value value The value of the meta data entry. X C,U 4000 X

System managed (sub-)entities

Action

Name Key Description Mandatory User Managed Max Size Filter/Sort Parameter Notes
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. X Can be pending or finished.
Action force type forceType Specifies if the action is in soft or forced mode. Gives the device a hint how and /or when to process the action. The mode forced means “as soon as possible” while soft means “optional, to be decided by device user”. X Can be soft, forced or timeforced.
Action time force forceTime Only applicable to mode timeforced. Specifies the time stamp in UTC milliseconds when the action should be switched to mode forced. X

Action Status

Name Key Description Mandatory DDI/DMF Managed Max Size Filter/Sort Parameter Notes
ActionStatus type type Structured type information of the action status. X X X Terminated actions can be in status finished, error, or canceled. Ongoing actions can be in status running, warning, retrieved (by target), or canceling.
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 the ActionStatus was reported at. 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 which is performed when there are historical connections to targets is called SoftDelete. This process marks the Software Module as deleted and removes the artifact, but it won’t delete the meta data, which describes the Software Module and the associated Artifacts. Software Modules which are marked as delete won’t be visible for the user, when he is requesting all Software Modules.

Just in case there are no connections to Distribution Sets and targets the server performs a HardDelete. This process deletes all stored data, including all meta information.