# Common operations This page provides examples of some common operations you might perform with the Common Android Reseller Library, including: - [Create `ResellerService` objects](https://developers.google.com/zero-touch/guides/reseller-library/common-operations#create_resellerservice_objects) - [Create `Customer` objects](https://developers.google.com/zero-touch/guides/reseller-library/common-operations#create_customer_objects) - [Claiming a batch of devices](https://developers.google.com/zero-touch/guides/reseller-library/common-operations#claim_a_batch_of_devices) - [Unclaiming a batch of devices](https://developers.google.com/zero-touch/guides/reseller-library/common-operations#unclaim_a_batch_of_devices) - [Exchanging a Samsung device](https://developers.google.com/zero-touch/guides/reseller-library/common-operations#exchange_a_samsung_device) - [Exchanging an Android (non-Samsung) device](https://developers.google.com/zero-touch/guides/reseller-library/common-operations#exchange_an_android_non-samsung_device) *** ** * ** *** ## 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](https://developers.google.com/zero-touch/guides/reseller-library/get-started#knox_deployment_program) with the [Knox Deployment Program](https://www.samsungknox.com/en/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](https://developers.google.com/zero-touch/guides/reseller-library/get-started#zero-touch_enrollment) to obtain your `resellerId` and service account key. > [!WARNING] > **Warning:** Service account keys can become a security risk if not managed carefully. For advice see [best practices for managing API keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys). 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.