Common operations

This page provides examples of some common operations you might perform with the Common Android Reseller Library, including:

Create ResellerService objects

Use the Samsung and Google factory classes to create ResellerService objects. With ResellerService objects, a common set of methods is available to enroll Samsung and other Android devices.

Samsung devices

The example below shows how to create a ResellerService object using the SamsungResellerServiceFactory class to manage Samsung devices.

Before you can do this, you need to onboard with the Knox Deployment Program (KDP).

ResellerService samsungResellerService = SamsungResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath, clientIdentifier);

Other Android devices

The example below shows how to create a ResellerService object using the GoogleResellerServiceFactory class to manage other (non-Samsung) Android devices. Before you can do this, you need to follow the steps in Get started for zero-touch enrollment to obtain your resellerId and service account key.

ResellerService googleResellerService = GoogleResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath);

Create Customer objects

A customer purchasing Samsung and non-Samsung devices requires two customer IDs.

Samsung devices

To manage Samsung devices, you use the customer's Knox Customer ID. To get the Knox Customer ID, you need to first create a Customer object. To do so, call createCustomer using a SamsungResellerService created from the SamsungResellerServiceFactory. Here's an example:

CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
    .setCustomerName("TestCustomer") .addPrimaryEmails("superAdmin@gmail.com")
    .putVendorParams("country", "US") .putVendorParams("firstName", "Avery")
    .putVendorParams("lastName", "Yamada") .putVendorParams("service", "KME")
    .build();
CreateCustomerResponse response = samsungResellerService.createCustomer(request);
String companyId = response.getCustomer().getCompanyReference().getCompanyId();

If successful, the request returns a CreateCustomerResponse object from which you can extract the Knox Customer ID.

Other Android devices

For other Android devices, the customer requires a zero-touch enrollment customer ID. If a customer already uses zero-touch enrollment with another reseller, you use their existing customer ID. Otherwise, you need to create a Customer object. To do so, call createCustomer using a ResellerService created from the GoogleResellerServiceFactory. Here’s an example:

CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
    .setCustomerName("TestCustomer")
    .addPrimaryEmails("owner@gmail.com")
    .addSecondaryEmails("admin@gmail.com")
    .build();
CreateCustomerResponse response = googleResellerService.createCustomer(request);
String companyId = response.getCustomer().getCompanyReference().getCompanyId();

If successful, the request returns a CreateCustomerResponse object. You can retrieve the customer ID from the response.

Claim a batch of devices

Claiming a device creates an association between the device and a customer. For example, if you sell a batch of devices to a customer you would claim the devices for that customer.

This example shows one way to process a batch of devices that includes orders of devices from multiple manufacturers (Samsung and other Android devices) from multiple customers.

Step 1: Organize devices and customers

Given a table of device IMEIs, manufacturers, and IDs of the customers the devices were sold to, one way to manage orders is to organize them into two lists: Samsung device orders and other Android (non-Samsung) device orders. Then, for each list, group devices by customer. For example:

Samsung devices

Customer name Samsung Knox customer ID Manufacturer IMEI
ABC corp 11 Samsung

1234567801

1234567802

Other Android devices

Customer name Customer ID Manufacturer IMEI
ABC corp 21 Google 1234567803
XYZ corp 22 Sony

1234567804

1234567805

Step 2: Create ClaimDevicesRequest object

Samsung devices

// Note: You can only claim devices for a single customer in each request.
ClaimDevicesRequest claimSamsungDevicesRequest = ClaimDevicesRequest.newBuilder()
   .addClaims(
       DeviceClaim.newBuilder()
           .setCustomer(
               CompanyReference.newBuilder()
                   .setVendor(Vendor.SAMSUNG)
                   .setCompanyId("11")
                   .build())
           .setDeviceIdentifier(
               DeviceIdentifier.newBuilder()
                   .setImei("1234567801")
                   .setManufacturer("Samsung")
                   .build())
       .build())
   .addClaims(
       DeviceClaim.newBuilder()
           .setCustomer(
               CompanyReference.newBuilder()
                   .setVendor(Vendor.SAMSUNG)
                   .setCompanyId("11")
                   .build())
           .setDeviceIdentifier(
               DeviceIdentifier.newBuilder()
                   .setImei("1234567802")
                   .setManufacturer("Samsung")
                   .build())
           .build())
   .build();

Other Android devices

ClaimDevicesRequest claimGoogleDevicesRequest = ClaimDevicesRequest.newBuilder()
    .addClaims(
        DeviceClaim.newBuilder()
            .setCustomer(
                CompanyReference.newBuilder()
                    .setVendor(Vendor.GOOGLE)
                    .setCompanyId("21")
                    .build())
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .setManufacturer("Google")
                    .build())
            .build())
    .addClaims(
        DeviceClaim.newBuilder()
            .setCustomer(
                CompanyReference.newBuilder()
                    .setVendor(Vendor.GOOGLE)
                    .setCompanyId("22")
                    .build())
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567804")
                    .setManufacturer("Sony")
                    .build())
            .build())
    .addClaims(
         DeviceClaim.newBuilder()
             .setCustomer(
                 CompanyReference.newBuilder()
                     .setVendor(Vendor.GOOGLE)
                     .setCompanyId("22")
                     .build())
             .setDeviceIdentifier(
                 DeviceIdentifier.newBuilder()
                     .setImei("1234567805")
                     .setManufacturer("Sony")
                     .build())
             .build())
    .build();

Step 3: Claim devices for customers

To claim devices for customers, call ClaimDevicesAsync. This examples requires two separate requests: one from the Samsung ResellerService object and one from the Google ResellerService object.

// Samsung devices
ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

// Other Android devices
ClaimDevicesResponse googleResponse = googleResellerService.claimDevicesAsync(claimGoogleDevicesRequest);

A ClaimDevicesAsync request returns a list of Operation objects, which contain the status of the request (in progress, complete, complete with errors, or failed). To check the status of an operation (for example, if the response returned IN_PROGRESS), call getOperation.

// Samsung devices
GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

// Other Android devices
GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);

Unclaim a batch of devices

Unclaiming a device disassociates it from a customer. You might need to unclaim a device if a device order is canceled or a shipment of devices can't be successfully completed. To unclaim a batch of devices, follow these steps:

Step 1: Create UnclaimDevicesRequest object

Samsung devices

// Each request can only unclaim devices belonging to a single customer. The request must also
// include the customer's Samsung Knox customer ID.
UnclaimDevicesRequest unclaimSamsungDevicesRequest = UnclaimDevicesRequest.newBuilder()
    .putVendorParams("customerId", "11")
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567801")
                    .build())
        .build())
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567802")
                    .build())
            .build())
    .build();

Other Android devices

UnclaimDevicesRequest unclaimGoogleDevicesRequest = UnclaimDevicesRequest.newBuilder()
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .build())
            .build())
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567804")
                    .build())
            .build())
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567805")
                    .build())
            .build())
    .build();

Step 2: Unclaim devices

To unclaim devices, call UnclaimDevicesAsync. This example requires two separate requests: one from the Samsung ResellerService object and one from the Google ResellerService object.

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);
UnclaimDevicesResponse googleResponse = googleResellerService.unclaimDevicesAsync(unclaimGoogleDevicesRequest);

An UnclaimDevicesAsync request returns a list of Operation objects, which contain the status of the request (in progress, complete, complete with errors, or failed) To check the status of an operation (for example, if the response returned IN_PROGRESS), call getOperation.

Samsung devices

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

Other Android devices

GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);

Exchange a Samsung device

If a device needs to be replaced for any reason, you can exchange it. This example assumes that you're exchanging a Samsung device for another Samsung device.

Step 1: Create an UnclaimDeviceRequest object

// Note: The request must include the customer's Samsung Knox customer ID.
UnclaimDevicesRequest unclaimSamsungDevicesRequest = UnclaimDevicesRequest.newBuilder()
    .putVendorParams("customerId", "11")
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567801")
                    .build())
        .build())
    .build();

Step 2: Call UnclaimDeviceAsync

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);

An UnclaimDevicesAsync request returns a list of Operation objects, which contains the status of the request (in progress, complete, complete with errors, or failed). To check the status of an operation (for example, if the response returned IN_PROGRESS), call getOperation:

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

Step 3: Create a ClaimDeviceRequest object

ClaimDevicesRequest claimSamsungDevicesRequest = ClaimDevicesRequest.newBuilder()
   .addClaims(
       DeviceClaim.newBuilder()
           .setCustomer(
               CompanyReference.newBuilder()
                   .setVendor(Vendor.SAMSUNG)
                   .setCompanyId("11")
                   .build())
           .setDeviceIdentifier(
               DeviceIdentifier.newBuilder()
                   .setImei("1234567806")
                   .setManufacturer("Samsung")
                   .build())
       .build())
   .build();

Step 4: Call ClaimDeviceAsync

ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

A ClaimDevicesAsync request returns a list of Operation objects, which contains the status of the request (in progress, complete, complete with errors, or failed). To check the status of an operation (for example, if the response returned IN_PROGRESS), call getOperation:

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

Exchange an Android (non-Samsung) device

If a device needs to be replaced for any reason, you can exchange it. This example assumes that you're exchanging an Android (non-Samsung) device for another Android (non-Samsung) device.

Step 1: Create an UnclaimDeviceRequest object

UnclaimDeviceRequest unclaimGoogleDeviceRequest = UnclaimDeviceRequest.newBuilder()
    .setUnclaim(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .build())
            .build())
    .build();

Step 2: Call UnclaimDevice

googleResponse = googleResellerService.unclaimDevice(unclaimGoogleDeviceRequest);

Step 3: Create a ClaimDeviceRequest object

ClaimDeviceRequest claimGoogleDeviceRequest = ClaimDeviceRequest.newBuilder()
    .setClaim(
        DeviceClaim.newBuilder()
            .setCustomer(
                CompanyReference.newBuilder()
                    .setVendor(Vendor.GOOGLE)
                    .setCompanyId("21")
                    .build())
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567807")
                    .setManufacturer("Google")
                    .build())
            .build())
       .build();

Step 4: Call ClaimDevice

ClaimDeviceResponse response = googleResellerService.claimDevice(claimGoogleDeviceRequest);

If successful, the call returns a ClaimDeviceResponse object containing the deviceId. Otherwise, it throws a common exception containing an error code.