Upload files

File upload between Bosch IoT Device Management and devices implementing the uploadable function block (e.g. Bosch IoT Edge) can enable a variety of use cases related to device diagnostics and monitoring, as well as system backup and restore. The file upload functionality gives the ability to explicitly trigger uploads of various types of files such as texts, logs, videos, audio or images from the device to the cloud through Bosch IoT Manager, our solution's device management layer. Another added value is that with this new functionality operators will be able to view logs of all connected devices which support the uploadable or autoUploadable features from a single point.

See our BLOB upload conceptual page for more general information.

You already know how to create and trigger mass management rules via the Bosch IoT Manager UI. This guide will demonstrate how to use rules to initiate the upload of log files from a virtual device (running Bosch IoT Edge Services in our case) to Microsoft Azure. This guide will show you how should the Groovy script look like, what are the needed arguments and once the upload has finished successfully how to download the files via the Bosch IoT Manager UI.

Device-side actions

Only devices that support the uploadable or autoUploadable features can upload files through this mechanism.

Bosch IoT Edge supports upload of OSGi and container log files out-of-the-box. This guide continues with a virtual device running Bosch IoT Edge with enabled Bosch IoT Edge Services.

Obtain the upload.exe executable, part of the Bosch IoT Edge Agent assembly. Learn how to configure it and its capabilities from the Bosch IoT Edge user documentation.

Create the rule

The mass management rule you create here will be triggered by an uploadRequest event coming from the device and will request the credentials or the pre-defined URL from the cloud storage infrastructure. By listening for uploadRequest events it triggers the actual upload from the device:

  1. Enter the Rule Management perspective of the Bosch IoT Manager Web UI and click Create Management Rule.

    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_createRule.png
  2. On the first dialogue enter a user-friendly name and the Groovy script, which will be executed by the rule.
    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_groovyScript.png
    Here is an example groovy script, which requests a pre-signed URL from Azure:

    String jsonConfig = '{"targetTemplate" : "blob-upload-test/${deviceId}/${yyyy-MM-dd}/${options.key}"
     
    presignedUrlConfig = new AzurePresignedURLConfig("https://...",
    "tenantId",
    "clientId",
    "clientSecret", jsonConfig)
     
    azureBlobUpload.handleRequest(presignedUrlConfig);

    • targetTemplate is the template that the device follows for the destination and naming of the actual log file.
      In the example above "container-name" is the name of the blob container/S3 bucket, "${deviceId}/${yyyy-MM-dd}" are the inner folders where your log file will be uploaded (you can add as many folders as you wish, with all kind of patterns) and "${options.key}" is the actual name of the file. When requesting a pre-signed URL, the key must be provided by the device, otherwise the URL cannot be generated without knowing the whole path where the content will be uploaded.

    • As mentioned in the conceptual page, Bosch IoT Manager supports two types of credential configurations. In this example we are using a pre-signed URL (AzurePresignedURLConfig). If you want to request temporary credentials from Azure, then you should use AzureTemporaryCredentialsConfig.

    • The first argument of AzurePresignedURLConfig represents the endpoint e.g. "https://blobuploadpoc.blob.core.windows.net".

    • As tenantId, clientId and clientSecret arguments type in your specific Ids.

    • azureBlobUpload is the Azure-specific binding within the mass management scripting API. Use awsS3Upload for AWS uploads.

    Requesting temporary credentials from AWS

    If you want to upload to an AWS S3 bucket with temporary credentials then the Groovy script should be:

    String jsonConfig = '''{
    "region": "eu-central-1",
    "bucket": "blob-upload-test",
    "startOptions" : {"aws.s3.bucket":"blob-upload-test"},
    "defaultValiditySec": 43200,
    "policyTemplate": {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Sid": "AllObjectActions",
    "Effect": "Allow",
    "Action": "s3:*Object",
    "Resource": ["arn:aws:s3:::${bucket}/${options.key}"]
    }
    ]
    }
    }''';
    temporaryCredentialsConfig = new AWSTemporaryCredentialsConfig(
    "aws access key",
    "aws secret access key",
    jsonConfig
    );
    awsS3Upload.handleRequest(temporaryCredentialsConfig);

    What is different from the upper example script:

    • When working with temporary credentials the jsonConfig contains more configuration information needed for AWS. e.g. the optimal region.

    • defaultValiditySec is the validity in seconds of the credentials.

    • policyTemplate is an AWS-specific policy, which adds some additional permissions.

    • Here we request temporary credentials from AWS with AWSTemporaryCredentialsConfig. If you want to request a pre-signed URL from AWS, then you should use AWSPresignedURLConfig.

    • the Statement includes these permission settings. These values allow all actions to be executed on the objects in the bucket.

    Now, let's get back to our main example.

  3. Click Next.

  4. On the next dialogue select the virtual device of your choosing. Remember it must have the uploadable or autoUploadable feature.

    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_uploadableFeature.png
  5. On the Rule Triggers step add an Event Based trigger and more specifically an UploadRequestEvent, as the rule will be listening for it.

    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_addTrigger.png

  6. Click OK and then Next.

  7. On the Execution Options step we do not need to make any other changes. So leave them as they are.

    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_executionOptions.png
  8. Click Finish and Enable the rule.

    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_enableRule.png

Monitor the rule execution and see the results

The upload process is initiated when the device sends an UploadRequest event and the event based trigger of your rule catches it. The rule will be fired and the log upload procedure will commence. See the flow of the procedure in our File upload conceptual page.

You can monitor the rule execution status through the Execution Status window.

images/confluence/download/attachments/1783509391/dm_mme_fileUpload_executionStatus.png

You can also examine its execution info from the lastUpload property of the uploadable feature of the device. The lastUpload property contains information about the current or the last executed upload.

  1. Go back to the Device Management perspective.

  2. Select the specific device and its uploadable feature.

  3. Within the Uploadable Properties panel that opens up (as shown in the screenshot below) see its lastUpload property.
    It contains the correlationId, start and end time, state and status code.

images/confluence/download/attachments/1783509391/dm_mme_fileUpload_downloadUpload.png

A successful upload will allow you to download the actual uploaded object from the Bosch IoT Manager UI.

Download the file by clicking on the link here , as seen at the end of the screenshot above.

Initiate the upload from the backend

For diagnosing or monitoring purposes you may also trigger the device to send the UploadRequestEvent from the backend.

  1. Go to the Device Management perspective and select the device of interest.

  2. Select its uploadable feature.

    images/confluence/download/attachments/1783509391/dm_mme_fileUpload_uploadableFeature.png
  3. Click trigger from the Action Info panel. This will manually trigger the device to send an uploadRequest event to the backend.

    images/confluence/download/thumbnails/1783509391/dm_mme_fileUpload_actionsInfo.png
  4. This will trigger the rule that we created in the steps above and the necessary credentials will be requested from Azure or AWS.

  5. To initiate the actual file upload execute the start action from the Actions Info.