Blueprint app version mismatch causes downgrade and data loss during Converge

Android

When a Blueprint specifies an older app version than what is running on your devices, triggering Converge forces Esper Agent to reinstall that older version. If your app stores device-specific data—such as access tokens—in local storage, the reinstallation wipes that data and requires manual reconfiguration on every affected device.

Why this happens

Blueprints are declarative: Esper treats them as the exact target state for every device in the group. When Converge runs, it compares the live device state against the Blueprint and corrects any divergence, including app version. If the Blueprint's app version field was not updated before Converge was triggered, Esper interprets the newer on-device version as non-compliant and downgrades it. Reinstalling an app clears its local storage, which destroys any data the app wrote there—including per-device tokens.

Step 1: Align the Blueprint app version with your production fleet

1. Open the Esper Console and navigate to Blueprints → [Your Blueprint Name] → Apps.
2. Check the APK version pinned in the Blueprint and compare it to the version currently running on your production devices. You can confirm the on-device version at Devices & Groups → [Device Name] → Apps.
3. If the Blueprint version is lower than the production version, update the Blueprint's app version field to match production exactly. This ensures Converge sees no version divergence and does not trigger a reinstall.
4. Save the Blueprint.
5. Only after the Blueprint version matches production, run Converge: navigate to Devices & Groups → [Your Group] → Blueprint → Converge.

Step 2: Target Converge only at devices that need the change

1. Identify the specific devices or groups that require the update rather than running Converge fleet-wide. Limiting scope reduces the risk of unintended reinstalls on devices that are already in a known-good state.
2. If you need to push a single setting change—for example, granting a permission—without touching app install state, update only that setting in the Blueprint, then run Converge against the targeted group only.
3. For changes that should apply to one device and not propagate fleet-wide, make the change directly on the individual device at Devices & Groups → [Device Name] → [Setting]. Esper records this as Drift. It will not be overwritten unless you explicitly run Converge against that device.

Step 3: Use Managed Configuration to protect per-device tokens

1. Work with your app developers to implement Android Managed Configuration support. Managed Configuration allows your app to read its configuration—including device-specific tokens or identifiers—from a managed bundle delivered by Esper Agent rather than from local storage. This means tokens survive any reinstall or upgrade because they are re-delivered by Esper automatically.
2. Once your app supports Managed Configuration, open the Esper Console and navigate to Blueprints → [Your Blueprint Name] → Apps → [Your App] → Managed Configuration.
3. Define a key-value pair for each token your app requires. For tokens that must be unique per device, use Esper's template variables (for example, {{device.serial}}) so each device receives its own value without manual entry.
4. Save the Blueprint and run Converge. Esper Agent pushes the managed configuration bundle to each device, and the app reads the token on next launch—no manual reconfiguration required.

Verify: After Converge completes, navigate to Devices & Groups → [Your Group] and confirm all devices show In Sync status. Then open Devices & Groups → [Device Name] → Apps on a sample device and confirm the app version matches your Blueprint. If you implemented Managed Configuration, launch the app on that device and confirm it authenticates successfully using the delivered token—without any manual input. Devices should reach In Sync within 10 minutes of Converge completing.

If this doesn't resolve it

If devices are still being downgraded after you have aligned the Blueprint version, or if app data loss continues after implementing Managed Configuration, collect the following before contacting support:

• The Blueprint name and the exact app version pinned in it
• The app version confirmed on-device before and after Converge (visible in the Activity Feed for that device)
• A screenshot or export of the Managed Configuration key-value pairs if Step 3 was completed
• The device serial numbers or group name affected

Contact Esper Support with the above information so the team can review your Blueprint state and Converge history directly.

Still need help?

If you encounter Blueprint app version mismatches or data loss during Converge, submit a support ticket and include your Blueprint app version, device model, and a description of the data affected.