Documentation

Mistake on this page? Email us

Creating an update campaign

This tutorial describes how to create and run an update campaign. It shows you how to:

  • Create a device filter to target specific devices.
  • Create and start an update campaign.
  • Monitor your update campaign by checking campaign phases.
  • Stop your campaign, if necessary.
  • Archive your campaign once it is finished.

There are three ways to create and run an update campaign:

  • Using Device Management Portal. This tutorial focuses on this method.
  • Using the APIs.

Consult our troubleshooting information if you encounter any issues with the update process.

Prerequisites

Before you start this tutorial, you should have:

Create a device filter

To distribute a firmware update to remote devices as part of an update campaign, you need to specify which devices this update targets. A device filter lets you select which devices to target based upon their attributes or identity.

In Device Management Portal:

  1. Click Device directory on the menu bar on the left.
  2. In the grey bar above the list of devices, click the arrow next to Filters. The default is Simple view.
  3. From left to right, choose an attribute and operator, and give a value, such as Device ID.
    • Click Add another if you want to combine multiple attributes in one filter.
    • You can also choose an attribute that applies to multiple devices.
    • If you want to use a raw string instead, click Advanced view.
  4. Click the small Save disk icon, and give your filter a name.
  5. Click Save filter.

Your filter is automatically applied, and lists the devices matching your selected attributes.

Create an update campaign

Once you have created a device filter, you can create an update campaign.

In Device Management Portal:

  1. Click the Firmware update option from the menu bar on the left.
  2. Click Update campaigns.
  3. Click New campaign.
    1. Enter a Name and a Description.
    2. Select your manifest file from the dropdown list.
    3. Select your device filter from the filter dropdown list.
    4. Click Save.

Note: Device Management Portal refers to the estimated number of devices included in a campaign. This is because the filter only includes registered devices when the campaign starts. If a device deregisters in the meantime, it is not included in the campaign.

Editing an update campaign

The above steps create the update campaign as a Draft.

In Device Management Portal:

  1. Click Firmware update.
  2. Select a campaign that you created in the previous step.
  3. A pane opens to the right.
  4. Click Edit.
  5. You can now edit your campaign.

Starting an update campaign

Once you are happy with the update campaign parameters like which manifest to use, targeted devices, and so on, you can start the campaign.

Note: Once your campaign enters this phase, it locks. You cannot change information like the selected manifest or targeted devices.

In Device Management Portal:

  1. Go to Firmware update > Update campaigns and select your active campaign.
  2. A pane opens to the right.
  3. Click Start.

Active

During this phase, Update sends manifests and waits for responses. If no errors occur, Update stops once it completes active tasks.

You cannot edit the campaign during this phase. You can stop it forcibly if necessary.

The time this phase takes varies from a few seconds to a few weeks, and depends on:

  • The campaign configuration.
  • The number of devices.
  • Device connectivity.
  • Manifest install rules.
  • And other factors.

Stopping

In this phase, Update cleans up the campaign and releases unused credits. Update does this automatically once it finishes its active tasks. You can also stop the campaign manually if you need to.

Note: Manually stopping the campaign is not a required step, unless you have reason to stop it before it would normally finish.

In Device Management Portal:

  1. Go to Firmware update > Update campaigns and select your active campaign.
  2. A pane opens to the right.
  3. Click Stop.

Stopped

This phase means that Update has finished everything from the Stopping phase. You can't restart a campaign once you stop it.

If you want to restart a campaign at this point, you need to create a new one.

Archived

Archiving lets you remove old campaigns from search filters. It doesn't matter if all devices updated successfully, the campaign stopped automatically because of an error, or you stopped the campaign manually.

Once you archive a campaign, you cannot un-archive it. You can then delete archived campaigns if you want.

In Device Management Portal:

  1. Go to Firmware update > Update campaigns and select your active campaign.
  2. A pane opens to the right.
  3. Click Archive.