Migrate existing devices to AMAPI

Devices already managed by your custom DPC can be migrated to Android Device Policy (ADP) and take advantage of the Android Management API.

Prerequisites

  • The device is already managed by your EMM with a custom DPC.
  • Your custom DPC is integrated with the AMAPI SDK.
  • The device is enrolled with Google Play EMM API.
  • The device belongs to a Managed Google Play Accounts enterprise.
  • The device runs Android 9 or later.
  • In case of work profiles on company-owned devices, the device must run Android 11 or later.

Integrate with the AMAPI SDK in your custom DPC

The migration process requires the custom DPC application to integrate the AMAPI SDK. You can find more information about this library and how to add it to your application in the AMAPI SDK integration guide.

Steps to migrate a device

  1. Set up a policy intended to be used by the device after it is migrated to AMAPI. For the best user experience, this should be equivalent to the policy already enforced on the device by your DPC.
  2. Create a migration token for the device by calling enterprises.migrationTokens.create.
  3. Send the value of this migration token to your custom DPC.
  4. Make sure Android Device Policy is installed on the device by using Play EMM API.
  5. Use DpcMigrationClientFactory to create a DpcMigrationClient
  6. On the DpcMigrationClient, call the migrateDeviceManagementToAndroidManagementApi method. This completes the migration.
  7. The deviceState changes to ACTIVE, and you will receive a STATUS_REPORT message through the Pub/Sub channel.

Once the migration completes the calling app loses its Device Owner or Profile Owner privileges, as these are transferred to Android Device Policy. This process can be represented by the following sequence diagram:

DPC Migration sequence diagram

Note: The device must be connected to the internet to begin migration. The process is designed to be resilient to network disconnections during the process of migration, so that the key operations requiring network connectivity are done before the actual transfer of device owner or profile owner rights from your DPC to Android Device Policy happens.

Migration token

A migration token is requested by the EMM server to signal the intention to migrate a particular device that is managed by a custom DPC. A migration token can be used till the migration is completed successfully or till it expires.

Custom DPC integration

First you need to create a DpcMigrationRequest, passing the token, and if necessary, the list of configured Wi-Fi networks to its builder:

// Create a DpcMigrationRequest
DpcMigrationRequest request =
        DpcMigrationRequest.builder()
            .setMigrationToken(token)
            .build();

You can then use get a DpcMigrationClient and start the migration process with migrateDeviceManagementToAndroidManagementApi:

// Create a DpcMigrationClient
DpcMigrationClient dpcMigrationClient = DpcMigrationClientFactory.create(context);
try {
  // Use helper function to retrieve Admin component name
  var adminComponentName = getAdminComponent(context);

  ListenableFuture<DpcMigrationAttempt> futureAttempt =
          dpcMigrationClient.migrateDeviceManagementToAndroidManagementApi(
              new ComponentName(context, DpcMigrationNotificationReceiver.class),
              adminComponentName,
              request);
  // handle futureAttempt
} catch (RuntimeException e) {
  // send failure feedback: "Error: " + e
}

Track the progress of the migration

The migration process is tracked on the device through a DpcMigrationAttempt.

You can directly use the one returned by migrateDeviceManagementToAndroidManagementApi or use getMigrationAttempt and listMigrationAttempts methods to get and list migration attempts.

// Passing an empty name, we retrieve the last attempt 
var request = GetDpcMigrationAttemptRequest.builder().build();

var attempt = client.getMigrationAttempt(request);

You can optionally set up a DpcMigrationListener using your NotificationReceiverService, to listen for status updates for the DpcMigrationAttempt.

// DpcMigrationNotificationReceiver for callback handling
public class DpcMigrationNotificationReceiver extends NotificationReceiverService
    implements DpcMigrationListener {

  @Override
  protected DpcMigrationListener getDpcMigrationListener() {
    // getDpcMigrationListener"
    return this;
  }

  @Override
  public void onMigrationStateChanged(DpcMigrationAttempt migrationAttempt) {
    // send success feedback
  }
}

Handle Wi-Fi networks

If there are Wi-Fi networks managed by the custom DPC, AMAPI ONC policy should match configurations of these networks for AMAPI to start managing them smoothly. The interaction of DPC migration with Wi-Fi management varies depending on the management mode.

Fully managed devices and work profiles on company-owned devices

During migration, Android Device Policy assumes that any Wi-Fi network configured in policy having the same SSID and security type of a configured Wi-Fi network on the device is identical to the matching configured Wi-Fi network. Hence, Wi-Fi networks configured by custom DPC are untouched after migration until there is a change in the ONC policy corresponding to the network. However, if the custom DPC is uninstalled after migration, then the Wi-Fi networks configured by custom DPC are removed automatically. Android Device Policy continues to enforce policy, and if any of these networks are configured in policy, the networks as configured in policy are added as usual.

Work profile on a personal device

For technical reasons, Wi-Fi networks configured by the custom DPC need to be removed by the custom DPC for Android Device Policy to start managing these Wi-Fi networks. The AMAPI SDK takes care of this and removes such Wi-Fi networks before transferring the ownership from the custom DPC to Android Device Policy but it requires the custom DPC to pass information about these networks in DpcMigrationRequest. After migration, networks configured in policy will be added normally, so it is recommended that the networks added by the custom DPC should be configured in policy as well.

There are some points to be aware of:

  • If the active network is a Wi-Fi network configured by custom DPC, the device can briefly be offline during migration.
  • Only the Wi-Fi networks configured by custom DPC should be passed in DpcMigrationRequest, otherwise migration fails if a network cannot be removed by AMAPI SDK (e.g. user added Wi-Fi network).
  • Wi-Fi networks should be passed in DpcMigrationRequest only when the custom DPC is a profile owner on a personally-owned device, otherwise migration fails.
  • For technical reasons, Android 12 is an exceptional case where the networks passed in DpcMigrationRequest are ignored and all Wi-Fi networks configured by the custom DPC are removed automatically. Further, it is a requirement for the custom DPC to have ACCESS_WIFI_STATE permission on Android 12 for work profiles on personally-owned devices, otherwise migration fails.

Caveats

Here are some caveats related to this feature.

Enterprise-specific ID

For work profiles on Android 12 and later, the enterprise-specific id, which can be accessed from DevicePolicyManager.getEnrollmentSpecificId does not change at the time of the migration. However, if a work profile managed by Android Device Policy is created again on the device (for example after deleting the previous one or after factory-resetting the device), the enterprise-specific ID will change at that point.

Work profiles on fully managed devices

This feature is not supported on fully managed devices which have a work profile running Android 9 or 10. Migrating these devices must not be attempted, and regardless of whether an error is raised, such devices are not supported for DPC migration.