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 Device Management, 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. 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 when using pre-signed URL and temporary credentials with both Azure and AWS, what are the needed arguments and how to initiate the upload from the backend.

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:

Enter the Rules UI feature of the Bosch IoT Suite UI and click + icon on the right.
The Create a rule dialog will open. On its first step:
1. Type in a user friendly name for the rule.
2. Set the scope of the rule.
  1. Select Device as Type.
  2. On Device selection by, click ID and select the virtual device of your choosing from the view that opens on the right. Remember it must have the Uploadable or AutoUploadable feature.
  3. On the Execution Options step we do not need to make any other changes. So leave them as they are.
  4. Click Next.
On the Triggers step:
1. Click the + in the middle view to add a new trigger.
2. As Type select Event Based.
3. Click the Select from event browser icon on the right of the blue input field that was automatically selected.
4. In the dialog that opens, select UploadRequestEvent, as the rule will be listening for it.
5. Click Save.
At the Action step enter the Groovy script, which will be executed by the rule. In the screenshot below we are requesting a pre-signed URL from Azure thus we use AzurePresignedURLConfig.

As mentioned in the conceptual page, Bosch IoT Device Management supports two types of credential configurations. Expand a Groovy script guide depending on your preferred credentials and cloud storage infrastructure:
1. Pre-signed URL request
  Pre-signed URL from Azure
  If you want to upload to Azure via a pre-signed URL then the Groovy script should be:
  
  String jsonConfig = '{
  
  "targetTemplate" : "container-name/${deviceId}/${yyyy-MM-dd}/${options.key}"
  
  azurePresignedUrlConfig = new AzurePresignedURLConfig(
  
  "AZURE_ENDPOINT",
  
  "AZURE_TENANT_ID",
  
  "AZURE_CLIENT_ID",
  
  "AZURE_CLIENT_SECRET", jsonConfig)
  
  azureBlobUpload.handleRequest(azurePresignedUrlConfig );
  - 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 obviously the name of the blob container, "${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.
  - azureBlobUpload is the Azure-specific binding within the mass management scripting API.
  Pre-signed URL from AWS
  Here is an example groovy script, which requests a pre-signed URL from AWS:
  
  String jsonConfig = '{
  
  "region" : "eu-central-1",
  
  "bucket" : "bucket-name",
  
  "targetTemplate" : "bucket-name/${deviceId}/${yyyy-MM-dd","startOptions" : {"aws.s3.bucket" : "bucket-name"}}';
  
  awsPresignedURLConfig = new AWSPresignedURLConfig(
  
  "AWS_ACCESS_KEY",
  
  "AWS_SECRET_ACCESS_KEY", jsonConfig);
  
  awsS3Upload.handleRequest(awsPresignedURLConfig);
  
  Some notes about requesting a pre-signed URL from AWS:
  - When working with AWS the jsonConfig contains more configuration information needed for AWS. e.g. the optimal region.
  - targetTemplate is the template that the device follows for the destination and naming of the actual log file.
    In the example above "bucket-name" is the name of the 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.
  - awsS3Upload is the AWS-specific binding within the mass management scripting API.
2. Temporary credentials request
  Temporary credentials from Azure
  Here is an example groovy script, which requests temporary credentials from Azure:
  
  String jsonConfig = '''{
  
  "defaultValiditySec": 43200,
  
  "permissions": "acrw"
  
  }''';
  
  temporaryCredentialsConfig= new AzureTemporaryCredentialsConfig((
  
  "AZURE_ENDPOINT",
  
  "AZURE_TENANT_ID",
  
  "AZURE_CLIENT_ID",
  
  "AZURE_CLIENT_SECRET", jsonConfig);
  
  azureBlobUpload.handleRequest(temporaryCredentialsConfig);
  
  Some notes about requesting a pre-signed URL from Azure:
  - The values of the defaultValiditySec and permissions properties set here are the default ones.
  - The value of the permissions property defines the Azure-specific permissions for these specific temporary credentials. In this example the credentials allow A(adding), C(creating), R(reading) and W(writing). See Specify permissions for all available permission options and their acronyms.
  - With temporary credentials metadata and tags can be added to the BLOB upload if the permissions, defined for these credentials, allows such operations.
  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": "bucket-name",
  
  "startOptions" : {"aws.s3.bucket":"bucket-name"},
  
  "defaultValiditySec": 43200,
  
  "policyTemplate": {
  
  "Version": "2012-10-17",
  
  "Statement": [
  
  {
  
  "Sid": "AllObjectActions",
  
  "Effect": "Allow",
  
  "Action": "s3:*Object",
  
  "Resource": ["arn:aws:s3:::${bucket}"]
  
  }
  
  ]
  
  }
  
  }''';
  
  temporaryCredentialsConfig = new AWSTemporaryCredentialsConfig(
  
  "AWS_ACCESS_KEY",
  
  "AWS_SECRET_ACCESS_KEY", jsonConfig
  
  );
  
  awsS3Upload.handleRequest(temporaryCredentialsConfig);
  
  Some notes about requesting temporary credentials from AWS:
  - When working with AWS the jsonConfig contains more configuration information needed for AWS. e.g. the optimal region.
  - policyTemplate is an AWS-specific policy, which sets permissions for these specific temporary credentials.
  - The Statement property includes these permission settings. This example allows all actions on the objects in the bucket. Learn more on Bucket policies and user policies.
  - With temporary credentials metadata and tags can be added if the permissions, defined for these credentials, allows such operations.
3. Combination of both type of credentials
  Combination of pre-signed URL and temporary credentials from AWS
  Bosch IoT Manager allows you to include both type of credentials into your Groovy script and use whichever is set in the event. Here is an example with pre-signed and temporary credentials requests from AWS:
  
  String presignedURLTemplate = '''{
  
  "region": "eu-central-1",
  
  "bucket": "bucket-name",
  
  "startOptions" : {"aws.s3.bucket":"bucket-name"},
  
  "targetTemplate" : "bucket-name/${deviceId}/${yyyy-MM-dd}/${options.key}"
  
  }''';
  
  awsPresignedURLConfig = new AWSPresignedURLConfig(
  
  "AWS_ACCESS_KEY",
  
  "AWS_SECRET_ACCESS_KEY", presignedURLTemplate);
  
  String temporaryCredentialsTemplate = '''{
  
  "region": "eu-central-1",
  
  "bucket": "bucket-name",
  
  "startOptions" : {"aws.s3.bucket":"bucket-name"},
  
  "defaultValiditySec": 43200,
  
  "policyTemplate": {
  
  "Version": "2012-10-17",
  
  "Statement": [
  
  {
  
  "Sid": "AllObjectActions",
  
  "Effect": "Allow",
  
  "Action": "s3:*Object",
  
  "Resource": ["arn:aws:s3:::${bucket}"]
  
  }
  
  ]
  
  }
  
  }''';
  
  temporaryCredentialsConfig = new AWSTemporaryCredentialsConfig(
  
  "AWS_ACCESS_KEY",
  
  "AWS_SECRET_ACCESS_KEY",
  
  temporaryCredentialsTemplate
  
  );
  
  awsS3Upload.handleRequest(awsPresignedURLConfig, temporaryCredentialsConfig);
  
  Some notes about including both credentials in your Groovy script:
  - When implementing two handlers you must set the storage.providers option as part of your event. Its value, e.g. generic or aws / azure, etc., determines which handler is going to be used, i.e. the backend understands what type of credentials to request based on the event type.
  - This allows some events to be processed with one credentials config in the Groovy script and other events to be processed with another credentials config.
Click Finish and Enable the rule.

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 Executions UI feature.

Initiate the upload from the backend

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

Follow the same process for creating a rule like above but this time:

On the Trigger step, select a Manual Fire trigger.
On the Action step type in the following Groovy script:

target.feature("com.bosch.iot.suite.manager.upload:Uploadable:1.0.0").trigger("correlationId", "options: {key: <key>}")

where you should add the correlationId as a string and the desired request options as a map.

Find more information on request options in our File upload conceptual page.
Once the rule is created and enabled you have to manually fire it from the Fire rule icon on the right:
This will trigger the rule that we created in the steps above and the necessary credentials will be requested from Azure or AWS.