Execute a campaign update

This tutorial describes how to start a new campaign to provide OS updates to registered devices.

Once a new campaign is active, the device-side client app intermittently polls the Knox E-FOTA server to check for the latest available update. With each campaign, multiple operations can be included for each device.

When multiple campaigns are run on the same device, operations are queued in order of priority. If operations have the same order of priority, the operations will be executed according to the campaign start time.

NOTE—To prevent an active policy from using an untested binary file, each new binary file that you upload has the Inactive status by default. While inactive, a binary file cannot be used to create a campaign. It can only be used to perform test operations. Once you have tested the new binary, you can manually set its status to Active. It can then be used to create a campaign. For more information, see Manage firmware: Update firmware status.

Create a new campaign

Execute a new update campaign through the Campaign Management page.

While the campaign is active, target devices poll the server to check for the latest available updates to download and install. Campaigns specify which target software version will be available.

To create a new campaign:

1. Log into the Knox E-FOTA Advanced portal.
2. Go to Campaign Management > Campaigns.

   

3. Click New E-FOTA Campaign.
4. Enter the following Campaign Details:
• Campaign Name—Enter a name of up to 80 characters.
• Description—(Optional) Enter a description of up to 5000 characters, for example, "Security update".
• Update Failure Message—(Optional) This message is displayed to the device user if the update fails to download. Enter a message of up to 256 characters.
• Update Success Message—(Optional) This message is displayed to the device user once the update successfully downloads. Enter a message of up to a maximum of 256 characters.
• Campaign Period—Enter a date range for the campaign to remain active. The value must be set to at least 1 hour.
• Campaign Retry—(Optional) Set an automatic action if an update fails to upload to a device or if updates remain pending at the end of the campaign period.

  Select one of the following options:

  • Unlimited—Set the operation to retry and remain active until all devices successfully download the update.
  • Up to—Set a limit for the number of times an operation can retry pushing updates (maximum of 99 retries).

  

5. Scroll to Selected Devices—Specify a target device for the update campaign.
   • Allow devices to be added while campaign is running—(Optional) If you select this, the campaign will remain active even when all enrolled devices have been updated. The campaign will only expire at the specified end date of the campaign period. During the period when the campaign is active, you can add more devices to it.
   • To push to a single device—Select Device ID or Friendly Name.
   • To push to a group of devices—Select Device Group or Domain.
6. Under Select Action, choose Deploy Selected Software Versions.

   

7. Select the name of the software to push.
8. Select the software version to push.
9. Click Execute.

   

Set a schedule for the update

Setting a schedule for campaigns minimizes disruptions during critical business hours.

To customize the schedule, expand Download & Update when creating a new campaign.

Download & Update—(Optional) Allows the admin to customize download settings.

Enter values for the following options:

• Download Time Slot—Specify a time range for the device to download updates.
• Update Start Time—Enter the time and date for the campaign to start.

Customize network options

Customize download options using the Download & Update menu.

Specify the network connection required to download updates by setting custom network options. Set devices to download updates through mobile data or restrict updates to occur through Wi-Fi only to avoid incurring data charges. Knox E-FOTA Advanced also enables the ability to balance network load for optimal bandwidth control.

To customize the network options, create a new campaign, and expand Download & Update before executing.

Download & Update—(Optional) Allows the admin to customize download settings.

Select the following network customization options:

• Enable data download over mobile network—Enables updates to download while connected to mobile data. If you don't select this option, devices will only update when connected to a Wi-Fi network.
• Maximum data downloaded over mobile—Set a value for the maximum size that can be downloaded over a cellular network.
• Network Load—Allows you to define a maximum load value per time period when downloading an update over Wi-Fi or cellular network. If you set this option, a device downloading an update can't download more than the set quota over the set timeframe. This option has the following fields:
  • Quota—Download size that cannot be exceeded over a set time period. Possible values: Integer between 0 to 600 MB (inclusive).
  • Timeframe—Time period in which a download operation cannot exceed a set value. Possible values: Integer greater than 0.

  NOTE—To enable the Network Load option and set default values, go to Admin > Domain Settings > Network load. When you set default values, those values are automatically displayed each time you create a new campaign, but you can always adjust them as needed.

• Wi-Fi Only Expiration Date & Time—Set devices to update only when connected to a Wi-Fi network until a particular date and time. When the expiration date and time are reached, devices will be able to use cellular data to download updates. The date and time are based on local server time.
• Update Start Time—Set the time to start the update. The time is based on local device time.
• E-FOTA is enabled during roaming—Allow update downloads over the air while the device is roaming.
• Update while plugged in only—Only allow updates if the device is connected to a power supply.

Create a silent or critical update campaign

Create a silent or critical campaign update using the Update Type options when creating a new Knox E-FOTA campaign.

To push a silent or critical update, create a new campaign, and select the following options before executing:

Update Type—Specify if the update is a Critical Update or Silent Update:

• Critical Update—The device user has the option to delay the update while a critical task is in progress, but the user can't decline the update.
• Silent Update—The device will be updated; the user won't be notified.

Check campaign status

After a campaign is executed, you can check the operation status by doing the following:

1. Go to Campaign Management > Campaigns.

   

2. Scroll to Campaigns.
3. View the operation status of the campaign under Status:
   Completed status—Statuses that reflect operations that are complete or closed.

   Completed statuses:

   Operation Status	Description
   Success	The operation ended successfully and a success report has been sent.
   Failed	The operation may have failed due to the following issues: Device problems Installation failed Network connectivity or configuration issues E-FOTA Advanced server problems Update file problems Locked device
   Not Reported	The device downloaded the download package successfully. However, the report wasn't sent to the server. This may be due to a campaign time-out.
   Partially updated	Part of the update failed to install or download. For additional details, review the error message or error code page.
   Rejected	The update was declined by the device user. To set a mandatory update, create a silent or critical update campaign.
   Timed out	A time out occurred before the operation can be performed. The following are possible reasons: The campaign period ended. The device isn't able to communicate with the server. The device is connected but hasn't yet sent a report.
   Up-to-date	The device has been updated to the latest version available. No operations to perform on the device.

   Ongoing status—Statuses for ongoing operations. If multiple statuses are reported by the device, the server saves the latest status in the group.

   Ongoing statuses:

   Operation Status	Description
   DD Sent	After sending the deployment descriptor (DD) to the device, the server waits for the next status and will report the next status.
   DL Cancelled	The update was not downloaded to the device.
   DL Session Completed	The device completed the download (DL) of the update file and notified the server that the file was downloaded successfully. It will then install the file.
   DL Session Deferred	The download package download was postponed.
   DL Session Interrupted	The download was interrupted. The following are possible reasons: The connection was lost. The device user paused the download. Client app logic interrupted the download.
   DL Session Resumed	The download has resumed after an interruption.
   DL Session Started	The download has started.
   DL in Progress	Download is in progress. Progress will be indicated by percentage if information is provided by the device's E-FOTA client app.
   DM Session Started	The (device management) DM session has started on the device.
   DM Session in Progress	The DM session is in progress on the device.
   Failed - Waiting for Retry	Campaign operation failed and is waiting to retry. The campaign will remain active until the maximum amount of retries has been reached.
   In Progress	Operation in progress.
   Installation Cancelled	File installation has been cancelled. Update cancelled.
   Installation Completed (DP)	Installation of the download package (DP) is complete.
   Installation Completed (Update File)	Installation of the update file(s) is complete.
   Installation Deferred	Installation of the update file(s) or download package was deferred.
   Installation Started (DP)	Installation of the download package on the device has started.
   Installation Started (Update File)	Installation of the update file(s) has started.
   Partially Updated – Waiting for Retry	The device was partially updated. The device will keep retrying as long as the campaign is active and the maximum number of retries has not been reached.
   Pending	The following are possible reasons for a pending status: Did not reach the campaign start date and time Server initiated campaign: Server-initiated messages were not yet triggered Non-server initiated campaigns: The device has not yet started the DM session.
   Push Notification Received	The device received the push notification.
   Rejected – Waiting for Retry	The campaign operation was rejected and is waiting to retry. The campaign will remain active until the maximum amount of retries has been reached.
   Running	Filters all the operations in running status.
   Server Initiated Message in Progress	The server-initiated campaign was triggered and the DM session hasn't started yet.
   Waiting for User DL Confirm	Waiting for the user to confirm the download.
   Waiting for User Install Confirm	Waiting for the device user to confirm the installation. The possible installation phases are: Pre-install Install Post-install

4. (Optional) To view campaign details, click on the name of the campaign.

   

Get a client log

When troubleshooting issues, it is helpful to check the client log from a device registered with Knox E-FOTA.

To get a client log:

1. Create a new campaign.
2. Under Select Action, choose Get Client Logs.

   

3. Click Execute.
4. Go to Campaign Management> Operations.
5. Find the device ID associated with the campaign and click Get Data Package.