Entity definitions

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 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 view and FIQL syntax search query (see Query parameters).

  • 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 at State machines.

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 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

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.

For further information about SoftDelete and HardDelete see Data model.