Introduction to the artifact repository

The Artifact Repository can manage artifacts, such as software or setup files, as well as store device-specific files, such as backup or diagnostic files.

In addition, artifacts such as software or setup files can be shared with others, so that a central Artifact Repository provides the same artifacts to multiple device owners.

The Artifact Repository is available in two variants:

The Private Artifact Repository , which allows the customer to operate the Artifact Repository in their own Azure subscription.
The Managed Artifact Repository, which enables the customer to use an Artifact Repository hosted in the Device Portal.

The private Artifact Repository allows customers to run their own Artifact Repository within their own Azure subscription.

The managed Artifact Repository, on the other hand, is operated within the Device Portal, which eliminates the effort for customers to operate it themselves.

The Artifact Repository is administered via APIs. These APIs can be used to upload and manage artifacts, e.g. to make new versions of software available to customers.

In addition, depending on the Artifact Repository variant, additional functions are available, such as defining the approved manufacturers or device certificates or specifying with whom the artifacts are to be shared.

The authorizations for accessing the Artifact Repository are enabled via the authorization solution of the Device Portal: MACMA.

This documentation shows how to create and manage artifacts in the Private or Managed Artifact Repository using the Insomnia Tool. A specially prepared collection and environment is already available. It is also possible to use another tool to interact with the APIs of the Artifact Repository.

Set the correct artifact property and artifact for your software or configuration

Various types of artifacts can be managed in the Artifact Repository. The properties of an artifact are defined on two levels or by two objects:

Artifact Property
Contains information such as a name, link to documentation, and a description
The artifact itself
Contains the version, one or more channels, the version note and the actual file

The first step is to define the Artifact Property property. The properties determine the type of artifact, such as whether the artifact is software or a configuration. It also defines additional information that remains the same for all versions of the artifact.

The artifact is then defined for an Artifact Property. The file itself is uploaded along with the individual information such as: the software version, channel or the device type for which this artifact is to be displayed later for the roll-out in the Device Portal.

The name forms a connection between the artifact and the Artifact Property. There can be several artifacts for a single Artifact Property and typically different versions.

However, there is only one artifact per channel. For example, if a new artifact is uploaded with the channel latest/ stable , the artifact currently marked as latest/stable is removed from the channel.

Defining the correct channel for the artifact

In the Artifact Repository, a channel is the combination of a track and a risk level :

Channel name = <track>/<risk-level> (e.g. latest/stable, 1.2/stable, 1.1/beta,…)

Tracks

The tracks allow developers to publish multiple supported versions of their application under the same name (for example, latest, 1.0, 2.1,…).

A track can be used to track minor updates (2.0.1, 2.0.2), major updates (2.1, 2.2), or releases that are held for long-term support (3.2, 4.1).

Supported tracks:

"latest"
Each string with the following characters: a-zA-Z0-9_.:+ -/ and spaces

Risk level

The risk levels allow you to control, for example, that only released/stable versions can be used by customers productively and that at the same time beta versions are available in a development environment, for example.

The following supported risk levels are possible:

Stable
For the vast majority of users running in production environments.
Candidate
For users who need to test updates from a deployment or verify that a specific issue has been resolved.
Beta
For users who want to test the latest features, typically outside of a production environment.
Edge
For users who want to follow the development closely.

The channel is displayed in the web interface in the following order:

latest
then semantic versioning
then alphanumeric

Example approach for channels:

latest/stable
Contains the latest, stable and tested version
latest/beta
Contains the latest version with the latest features
1.2/stable
Includes Long-Term Support Version 1.2 with bug fixes
latest/edge
Contains the latest nightly build

If the tenant is linked to the Artifact Repository, it must be defined which risk levels are to be displayed in the web interface of the Device Portal. For example, if the risk levels are stable and edge , all software artifacts with this risk level are displayed in the software list. To remove a software artifact from this list, its channel must be updated and deleted.

Determining how devices access artifacts from the private artifact repository

To determine which devices have access to the Private Artifact Repository , the corresponding devices, once set up via the APIs, must be enabled for access via the device certificates.

In the Private Artifact Repository , devices are authenticated by means of a device certificate ( X.509 certificates ). The certificates have the file extension.cer,.crt or.pem without a private key.
This corresponds to the same device authorization as in the Device Portal. However, the two authorization processes are completely independent of each other.

The certificate management API of the Private Artifact Repository determines which certificates and thus which devices are allowed to access the repository and which devices are not.

The certificates can be placed on the whitelist or blacklist.

There are two ways to add certificates to the whitelist :

Upload device certificates directly.
In this case, it is necessary to upload each individual device certificate.
Recommended procedure:
Intermediate certificates used by the device manufacturer to sign the device certificates.
These certificates must be requested from the device manufacturer.

If a device is no longer allowed to download software from the Private Artifact Repository , it is possible to blacklist the corresponding device certificate.

Determining how devices access artifacts from the managed artifact repository

In contrast to the Private Artifact Repository , the Managed Artifact Repository is integrated into the Device Portal solution.

In this case, when a device attempts to download an artifact, it uses the device certificate (X.509 certificate) on the Device Portal to authenticate the artifact.

The Device Portal checks whether the artifact belongs to the tenant of the device that requested the file. In this case, access is granted directly.

However, when the device attempts to request an artifact associated with another tenant , it checks whether the owner of the other tenant has granted access to the device.

The owner of a tenant can configure their Managed Artifact Repository accordingly. Release of artifacts in a Managed Artifact Repository

Prerequisites for rolling out the artifacts

Device Portal web interface

For software artifacts: Devices have the category Software Management so that users can see the software list and the Artifact Roll-Out Wizard in the web interface of the Device Portal.
Artifacts are compatible with the type of devices selected
Commands are defined for each artifact type
- The tenant is configured to display the information from the repository.

Private Artifact Repository

The Artifact Repository is provided in a separate Azure subscription
The Artifact Repository is accessible to devices and the Device Portal backend.
The Artifact Repository is configured as described, including Device Type Mapping and supported Artifact Types
The device certificate or intermediate certificate of the manufacturer is on the whitelist of the Artifact Repository

Managed Artifact Repository

The Artifact Repository is connected to a tenant — it can be requested via the Helpdesk

Specific for device endpoints:

Device certificate or intermediate certificate of the manufacturer are on the whitelist of the Device Portal.

Display the software available for a device in the web interface of the Device Portal

The artifacts available in a connected Artifact Repository are displayed in the Device Portal web interface.

Software list

Clicking on a device displays the software list:

In the software list, one line corresponds to one piece of software.

An additional line is only displayed if a software artifact has been uploaded and the device has a compatible device type.

Update software

When updating software, the following dialog appears. The software artifacts to be updated with the version number are displayed here.

Install software

Clicking on the multifunction menu of a device opens the Artifact Roll-out Wizard. The corresponding software can be installed via the wizard.

Access to the API documentation

The API documentation for the Private Artifact Repository can be accessed from the repository landing page:

<URL-des Private Artifact Repository>/index.html

The API documentation for the Managed Artifact Repository is also available on the landing page:

<URL des Managed Artifact Repository>/index.html

Downloading the insomnia collection

To use the Artifact Repository APIs to manage the software, it is necessary to use the OAUth2 protocol for authentication.

In addition, the following requirements must be taken into account.

This manual was written based on Insomnia v8.3.0.

Call up the landing page of the Managed or Private Artifact Repository: <URL Artifact Repository>/index.html
Click on here to download the Insomnia Collection and Environment.

Once downloaded, the collection must be imported into Insomnia. Configuring Insomnia — Importing the Artifact Repository Collection

Configuring insomnia — importing the artifact repository collection

The Insomnia Collection contains a template that has already been filled out, with all the information required to query the API

Example of the Create Software request

Variables such as the URL or the tenantId are defined in this environment.

Start Insomnia.
Click on Use local Scratch Pad (1). This setting is recommended because it does not require the creation of an account and is sufficient for our purposes.
Open the Scratch Pad (1) drop-down menu and select Import (2) to import the Insomnia Artifact Repository Collection.
Select Device Portal Artifact Repository from the drop-down menu (1).
Open the settings (2).

The Manage Environment window opens.

Enter the actual values for the two placeholder values (1, 2).

Field Value

Field	Value
artifact- repository.baseurl	Enter the private repository URL: E.g. `https://myArtifactRepository.azurewebsites.net`
tenantId	Enter the tenant ID. This is located in the Help menu of the Device Portal web interface.
clientId	5qe6qztg4qqc1x65gp93te32g front end
callbackUrl	https://deviceportal.bosch.com
iam.baseurl	https://portal.bosch-nexeed.com/iam

artifact- repository.baseurl

Enter the private repository URL:

E.g. https://myArtifactRepository.azurewebsites.net

tenantId

Enter the tenant ID.
This is located in the Help menu of the Device Portal web interface.

clientId

5qe6qztg4qqc1x65gp93te32g front end

callbackUrl

https://deviceportal.bosch.com

iam.baseurl

https://portal.bosch-nexeed.com/iam

If a company proxy is used, it must be set accordingly:
Click on Preferences and select Network Proxy and set the appropriate proxy.

Once all the necessary values have been set, click on Close to return to the main view.
Select the imported collection (1) and click on Send (2) to trigger the generation of the access token.
Log into the login window with the Bosch Device Portal access data.

The user must be assigned to the MANAGER_SOFTWARE_REPOSITORY group. The group contains the following roles: * DP_CAN_MANAGE_REPOSITORY_SOFTWARE
Required to use endpoints in conjunction with artifact management. * DP_CAN_MANAGE_REPOSITORY_CERTIFICATES
Required to use the endpoints in conjunction with certificate management.

+ image::238014.png[238014]

After a successful login, Insomnia automatically uses the generated token for the requests. Requests can be sent as long as the token is valid.

If the HTTP status code 401 is sent in response to a request, it indicates that the access token is no longer valid.
Insomnia should normally update the tokens automatically before they expire. However, it is possible to manually update the tokens for the request (2) under the OAuth2 tab (1).

Some call-ups use prompts, for example, for an ID:

Release of artifacts in a private artifact repository

To make all or some of the artifacts of the Private Artifact Repository available to other tenants, contact the Help Desk.

To grant a device access to its own Private Artifact Repository , the device certificates and IP addresses must be placed on the whitelist.

Release of artifacts in a managed artifact repository

To share artifacts with other tenants and registered devices, the Managed Artifact Repository must be configured accordingly. This process involves defining access permissions for each tenant based on the type and risk level of the artifact.

Managing, granting, and creating access rights

To manage access rights through the Artifact Management API provided by the Artifact Repository service, users must be assigned the role DP_CAN_MANAGE_REPOSITORY_SOFTWARE in their tenant.

A customer can grant access to certain types of artifacts to another tenant, with the exception of backups and diagnostic data, as these cannot be shared between tenants.

AccessRight {
String id;
String sourceTenant;
Set<String> authorizedTenants;
Set<String> artifactTypes;
Set<String> riskLevels;
}

Manage access rights for the artifacts

Users with the DP_CAN_MANAGE_REPOSITORY_SOFTWARE role can use the appropriate REST endpoints that are part of the Artifact Management API to manage access for their artifacts by creating one or more entries for their (source) tenant.

It is possible to use the following API endpoints to create, read, update and delete access right configurations for other tenants.

POST /v1/access-rights//grant access
{
 "authorizedTenants":["<tenant-id-1", "<tenant-id-2>"],
 "artifactsTypes":["SOFTWARE" ],
 "riskLevels": ["stable"]
}

GET /v1/access-rights//list all entries of the authorized macma tenants

PATCH /v1/access-rights/{id}//update tenants and/or artifact types
{
 "authorizedTenants":["<tenant-id-2", "<tenant-id-3>"],
 "artifactsTypes":["SOFTWARE", "SETUP" ],
 "riskLevels": ["stable", "candidate"]
}

DELETE /v1/access-rights/{id}//delete access

Use the APIs to manage the artifacts

The API documentation contains the necessary information for using the Private Artifact Repository. Only a few important points are listed here:

The Artifact Property and artifact are linked by name. This name must be unique in all repositories connected to the tenant.
The Device Portal and the associated repositories are synchronized every 15 minutes.
Small artifacts , such as software or configuration, are supported up to 500 MB by default: If larger files are to be used, contact the Helpdesk.
Large artifacts , such as backup and setup files, are supported up to 4 GB, but this requires an Azure Blob Storage to be connected in the case of a Private Artifact Repository installation.

Creating artifact properties and their artifacts

There are 2 cases to consider when managing artifacts:

Case 1 — Managing a completely new artifact

To upload a completely new artifact to a Private Artifact Repository, you must perform the following steps:

Create the new Artifact Properties with the endpoint /artifact-properties (POST).
Create the new artifact with the name of the Artifact Property.
- In the case of a setup file, create the artifact with the endpoint /artifact-properties/setup-files (POST) and upload the file to the uploadUrl specified in the response.
- For all other artifact types , create the artifact and upload the file with a call at the endpoint /artifact-properties/artifacts (POST)

Case 2 — Managing a new version of an existing artifact

To upload a new version of an existing artifact, you must create a new artifact with the name of the Artifact Property in the appropriate endpoint.

An error message may occur when uploading artifacts: Error: Socket hang up or error: ECONNRESET with a corresponding HTTP status 502.

The error message can arise for two reasons:
The file is larger than 500 MB or

The access token is out of date. This can happen if the upload takes too long.