Using Batch Jobs to Automate Notehub Workflows

At Blues, we’ve seen the challenges of managing large IoT fleets firsthand.

Device failures, inconsistent firmware, and fragmented data pipelines quickly overwhelm manual workflows as deployments scale. Without a unified automation strategy, administrators are left scrambling to diagnose outages and maintain device health across a scattered mix of dashboards and scripts.

To help address these challenges, Notehub’s new batch jobs feature lets you automate bulk operations across your fleets using simple, repeatable workflows. Whether you’re onboarding new devices, updating configurations, or generating system-wide reports, batch jobs provide the control and efficiency you need to operate at scale.

In this article, you’ll learn how batch jobs work in Notehub, see practical scenarios where they add value, and get guidance on using them to streamline your own device management tasks.

How Batch Jobs Work

Notehub’s batch jobs let you define and execute large-scale operations through a job submission workflow. Each job is described by a JSON file that specifies which devices to target and what actions to perform—such as provisioning, setting environment variables, assigning fleets, or generating detailed reports.

The workflow is straightforward:

1. Create a Job: Upload a JSON file that outlines your desired operation. The JSON must:

   1. Select devices (by their fleet, serial number, or DeviceUID).
   2. Specify the actions to take or reports to generate for the selected devices.

2. Optionally perform a dry run: This allows you to preview the job’s effects without making any changes. This step is strongly recommended for any job that will modify device state, as it helps catch errors before they impact your fleet.

3. Execute the Job: Once satisfied with the dry run, execute the job to apply changes or generate reports. Batch jobs run asynchronously, allowing you to continue working while Notehub processes your requests.

4. Review results: After execution, detailed reports are available for download, showing the outcome for each device. Every job is tracked in Notehub with a full audit history, making it easy to verify actions and troubleshoot issues.

note

These steps give you a high-level overview of how batch jobs work. Refer to our documentation on batch jobs for specific steps on how to run batch jobs in your Notehub projects.

Batch jobs are designed to make large-scale device management efficient, consistent, and reliable—whether you’re provisioning new hardware, migrating fleets, or performing periodic system assessments.

With this basic overview out of the way, let’s look at some specific examples of how you may wish to use batch jobs for your device fleets.

Making Batch Changes

Batch jobs excel at applying configuration updates or project-wide changes across large sets of devices. By defining your changes in a JSON file, you can automate tasks that would otherwise be tedious and error-prone.

Example 1: Environment Variable Management

Batch jobs offer a powerful way to manage environment variables across devices. For example, consider the following JSON:

{
  "comment": "Set multiple environment variables",
  "select": {
    "all_devices": true
  },
  "default_requests": {
    "vars_to_set": {
      "interval": "10",
      "legacy_interval": "-"
    }
  }
}

The job above will set an "interval": "10" environment variable on all devices, and delete a "legacy_interval" variable from all devices.

To override values for specific devices you can include them in a "device_requests" property. For example, the job below performs the same request as the one above, but provides an override "interval" value for a single device.

{
  "comment": "Set multiple environment variables with overrides",
  "select": {
    "all_devices": true
  },
  "default_requests": {
    "vars_to_set": {
      "interval": "10",
      "legacy_interval": "-"
    }
  },
  "device_requests": {
    "dev:860322068093969": {
      "vars_to_set": {
        "interval": "20"
      }
    }
  }
}

Example 2: Fleet Migrations

Batch jobs also excel at performing fleet migrations. For example, the following JSON defines a batch job that selects all devices currently in a fleet named “OldFleet”, and migrates them to a new fleet named “NewFleet”.

{
  "comment": "Migrate devices from OldFleet to NewFleet",
  "select": {
    "devices_in_fleets": ["OldFleet"]
  },
  "default_requests": {
    "fleets_to_join": ["NewFleet"],
    "fleets_to_leave": ["OldFleet"]
  }
}

All batch jobs perform tasks that can also be completed manually in the Notehub user interface, or programmatically using the Notehub API.

Batch jobs, however, introduce a syntax better suited for large-scale updates. Doing a fleet migration with the Notehub API, for example, would require a call to Get Fleet Devices, and then multiple calls to Add Device to Fleets and Remove Device from Fleets.

With batch jobs, the same result can be had with one short JSON file. You can also perform a dry run to verify your changes before applying them, and Notehub stores your batch job workflows for easy repetition, auditing, and team collaboration.

Let’s look at some more examples.

Generating Reports

Batch jobs aren’t just for making changes—they’re also a powerful tool for generating reports across your entire fleet.

With a single job, you can collect detailed information on device status, environment variables, fleet assignments, activity history, and more. This allows you to quickly assess the health and configuration of your deployment, identify issues, and maintain comprehensive records without manual data gathering.

Example 1: Generating Fleet Snapshots

A common need for fleet managers is to get a snapshot of all devices, including their configuration, environment variables, and fleet assignments. Having these snapshots on hand provides a historical reference, making it easier to debug issues that arise in the future by comparing current device states to previous configurations.

As an example, here’s a batch job JSON that generates a detailed inventory report for every device in your project:

{
  "comment": "Generate a comprehensive inventory report for all devices",
  "select": {
    "all_devices": true
  },
  "report_options": {
    "device_info": true,
    "device_vars": true,
    "app_fleets": true
  }
}

The generated report will include metadata on each device (device_info), a list of each device’s current environment variables (device_vars), and a list of fleets to which each device is currently assigned (app_fleets).

Example 2: Monitoring Device Activity and Health

Another frequent use case is monitoring device activity to catch issues before they escalate. For example, you might want to regularly check which devices have been inactive, or spot trends in device health. Here’s a batch job JSON that generates a report focused on recent activity and health metrics:

{
  "comment": "Report on device activity and health for all devices",
  "select": {
    "all_devices": true
  },
  "report_options": {
    "device_activity": true,
    "device_health": true
  }
}

This report will include metadata on device event and session activity, including a recent_event_count, recent_session_count, and recent_session_seconds—helping you identify anomalies and devices that may need attention.

Provisioning Devices

Provisioning is often the most tedious process as projects start to scale. Setting up new devices can involve many manual error-prone steps.

Batch jobs can simplify your provisioning process by allowing you to automate the initial configuration of devices. Instead of onboarding each device manually, you can define all provisioning parameters—such as ProductUIDs, serial numbers, fleets, and environment variables—in a single JSON file. Once set, a device's provisioned configuration will be applied upon its first connection to your Notehub project.

As an example, the JSON below defines a batch job that provisions two new devices. Each device is given a default environment variable "interval":"30", a default fleet ("New"), and a device-specific serial numbers ("WeatherNode-001" and "WeatherNode-002", respectively). When a device comes online in Notehub, these settings are applied automatically.

{
  "comment": "Provision new devices",
  "default_requests": {
    "provision_product": "com.my-company.my-name:weather",
    "vars_to_default": {
      "interval": "30"
    },
    "fleets_to_default": ["New"]
  },
  "device_requests": {
    "dev:860322068093969": {
      "sn_to_default": "WeatherNode-001"
    },
    "dev:860322068093970": {
      "sn_to_default": "WeatherNode-002"
    }
  }
}

By leveraging batch jobs for provisioning, you can automate and standardize your onboarding process for large device fleets. This approach not only accelerates deployment but also minimizes configuration errors and ensures each device is set up with the correct parameters from the start.

Wrapping Up

Batch jobs are a powerful new Notehub feature for automating device management at scale. By automating repetitive tasks, batch jobs can help you scale your operations with confidence.

And we’d love to know what you think! If you have feedback on how batch jobs work, or if you have suggestions for any features we should add, feel free to reach out in our community forum.