Developer Guide

File Bucket & Reports

1. Overview

The File Bucket module in IoTRoutes acts as a centralized file repository used by workflows, APIs, and users.
It provides secure storage for templates, generated reports, and uploaded media such as device images, firmware packages, or CSV exports.

Each file in the bucket is indexed with metadata such as:

• File Name and Extension

• MIME Type

• Owner / Creator

• Category (Template, Report, Media, Firmware, etc.)

• Tags and Descriptions

• Creation and Expiration Dates

• Access Mode (Public, Restricted, System)

Workflows and APIs can both read and write files in the bucket, making it an essential part of the automation ecosystem.

2. File Storage and Access

Files are stored physically in the platform’s storage backend (filesystem or cloud bucket), while metadata is indexed in the database.
Developers can use the File Bucket API to perform:

Access control is role-based — ensuring only authorized users and workflows can manipulate or retrieve files.

3. Report Generation via Workflow

One of the most powerful uses of the File Bucket is automated report generation through workflow actions.
The platform integrates with the NPOI library to produce Word (.docx) or Excel (.xlsx) reports using template files stored in the bucket.

Typical Use Case:

A workflow step takes measurement data (for example, daily temperature logs), merges it with a Word template containing placeholders, and produces a formatted report automatically stored in the bucket and optionally emailed to users.

4. Template Structure

A template is a preformatted document (.docx or .xlsx) containing placeholder fields that the workflow replaces dynamically with live data.
For example, a Word template might include:

When the workflow executes, it replaces these placeholders with actual values from context variables or calculated expressions.

Supported Placeholder Types:

• Simple variable: {{DeviceName}}

• Expression result: {{@{avg(sensor.temperature)}}}

• Date/Time formatting: {{ReportDate | format('yyyy-MM-dd')}}

• Nested object access: {{Device.Status.Description}}

5. Workflow Action – Generate Report

Action Name: GenerateWordReport (or GenerateExcelReport)
Purpose: Creates a document from a stored template using context data and saves it to the File Bucket.

Parameters:

Example:

6. Formula Integration

Report actions fully support Formula Expressions in both the file name and content substitution.
You can dynamically generate paths or conditional content:

Example:

Or use formulas in placeholders:

7. Sending or Using Generated Reports

After generation, workflows can:

• Send the report by email (using the SendEmail action).

• Attach it to a device record as documentation.

• Include it in a command message (for example, to send maintenance checklists).

• Trigger external API uploads (for example, to a customer portal or ERP system).

8. Best Practices

• Keep templates generic and use formula placeholders for flexibility.

• Organize bucket folders by purpose: /templates/, /reports/, /media/.

• Use metadata and tags for versioning and easy retrieval.

• Avoid embedding large media in templates — link to media files in the bucket instead.

• Test templates locally before deploying them to production workflows.

9. Example: Device Health Report Workflow

Scenario: Generate a daily report summarizing all device statuses.

Steps:

1. Retrieve all active devices and their last reported health status.

2. Aggregate into a dataset.

3. Use the “DeviceHealth.docx” template from /templates/.

4. Generate and store the report in /reports/daily/.

5. Email the report to the system administrator.