Product Documentation

Managing Devices

Jan 31, 2011

You can manage devices in the following ways:

  • Tagging devices to identify ownership of the device. You can tag devices with a script or by using the Device Manager web console.
  • Adding devices to Device Manager either manually or by using the Device Provisioning tool.
  • Locking and unlocking devices by using the Device Manager web console.
  • Revoking device certificates to prevent devices from accessing Device Manager.
  • Wiping information from devices that includes removing some or all of the data on the device.

To add devices to Device Manager

The Device Manager server repository database stores a list of mobile devices. Each mobile device is defined by a unique serial number and/or IMEI. To populate Device Manager with your devices, you can add the devices manually. To do so, in the Device Manager web console, click New device and then select the device type. You can also import a list of devices from a file by using Device Provisioning tool (Windows Mobile and Symbian devices only), or by using Device Auto Discovery (only available with the Secure Device option).

To import a list of devices by using a file

Develop a text file according to the following format by using a utility application, such as a text editor, spreadsheet application, or note taker.

Element Notes

Serial Number

Device serial number (required if IMEI is not given)

IMEI

Device IMEI identifier (required if serial number is not given)

Operating System Family

Required to be WINDOWS, ANDROID, or iOS.

Property name 1

Optional

Property value 1

Optional

Property name (n)

Optional

Property value (n)

Optional

Many mobile operators or device manufacturers provide lists of authorized mobile devices, and you can use these lists to avoid having to enter a long list of mobile devices manually. Device Manager supports an import file format that is common to all three of the supported device types.

Note the following:

  • File charset must be UTF-8/
  • Semi-colon (;) is used as the field delimiter so it must be escaped if it is present in the data.
  • For iOS device import, Serial Number is mandatory. Serial Number is the identifier for iOS devices.

For example:

1050BF3F517301081610065510590391;15244201625379901;WINDOWS;propertyN;propertyV\;test\;1\;2;prop 2;prop2 value 
2050BF3F517301081610065510590392;25244201625379902;ANDROID;propertyN;propertyV$*&&ééétest 
3050BF3F517301081610065510590393;35244201625379903;iOS;test; 
4050BF3F517301081610065510590393;;iOS;test; 
;55244201625379903;ANDROID;test.testé;value;

To import a task file

  1. Click the Import tab.
  2. Browse to the corresponding provisioning file.
  3. Click Import.

Viewing the Device Properties

When you click a device name in Device Manager and then click Edit, you can view device overview information for a device type. The tabs that appear may differ slightly depending on the device.

The main tabs that appear and the information they contain are as follows:

  • General. On this tab, you can view device properties, such as the software inventory, the device serial number, IMEI, as well as the Strong ID if the Secure Device option is available in the license installed on the server. You can also display the status of the Device Lock and Device Wipe commands:
    • The statement No device lock/wipe, if no command was sent.
    • A description and the date and time at which the command was sent or carried out.
  • Properties. The hardware inventory appears on this tab. The list is updated automatically each time the device connects to Device Manager. For devices that use the Secure Device Option, additional tabs appear, such as Certificates and Master Keys.
  • Software. The software inventory appears on this tab. The list includes all applications and software packages installed on a device, such as package name, author, size, installation date, and version of the software. You must request an inventory if you want to display the applications deployed through Device Manager as well as user-installed apps. To request an inventory, you need to configure a deployment from the Deployment tab. Under Resources to be deployed, select Software Inventory.
    Note: For Windows Mobile devices exclusively, only software programs available in the Add/Delete program menu on the device appear on the Software tab.
  • iOS Profiles. You can view the profiles for an iOS device on the iOS Profiles tab. Profiles may include web clips, mobile device management (MDM) configurations, access permissions, and more.
    Note: When working with iOS configuration profiles generated with Apple’s iOS Configuration Utility (IPCU), such as profiles for Exchange ActiveSync, WiFi, and VPN access with a certificate, Device Manager cannot prompt the device unless you include the certificate password in the profile when you create the certificate. You must include the certificate password in the IPCU steps, and then use Device Manager to import the profiles with the certificates.
  • Certificates.
  • Deployment. You can view a complete real-time view of package deployment, on a per-device basis, on the Deployment tab. You can view of all packages assigned to a device, and the status of the deployment.
    Note: The status of pending is the same as remaining. The status means that the package has not yet been deployed.
  • Connection. The Connections tab displays the users who have authenticated against a device. It lists the user name, and last two authentication times.
  • MDM Status. On this tab, you can review the MDM status for iOS devices. The information that appears is as follows:

    MDM status:

    • INACTIVE. The server does not expect the device to connect to it any time soon, nor does it consider it necessary.
    • ENQUEUED. The server is attempting to communicate with the device, but a push notification has yet to be sent to the Apple Push Notification service (APNs).
    • ACTIVE. The server is either currently handling a device request, or it expects the device to reply to a previously sent command.
    • PENDING. The server is waiting for a connection from the device.

    Last push initiation. The time of the most recent push notification initiated by Device Manager.

    Last notification completion. The time of the most recent completed push notification to the device.
    Note: The message "Completion of a Push notification attempt" means the notification payload was successfully sent to the server running APNs and the server did not reply with an error (which would indicate syntax errors and so on).

    Last reply device time. The time that a device connected to Device Manager following a push notification.

Viewing Device Management Status

For each device you manage, Device Manager provides information on device management status, whether or not the device has been jailbroken, device operating system and hardware information, serial number and IMEI/MEID number, user of the device, device phone number, and so on.

Three of the most commonly used and important statuses for your device indicate whether or not a device is managed or not: Jailbroken/Rooted, SMG Status, and Managed.

The following table describes the status information and colored icons that you see on the Devices tab in Device Manager:

Status Explanation

Jailbroken/Rooted

A green light means that the device is NOT jailbroken (iOS) or rooted (Android).

A red light means that the device has been jailbroken or rooted.

Secure Mobile Gateway Status

A green light means that Secure Mobile Gateway recognizes the device as legitimate and allows the device to access your Exchange email infrastructure.

A red light means that Secure Mobile Gateway recognizes the device as a potential threat to your email Exchange email infrastructure and is blocking the device.

A gray light means that your instance of Device Manager does not have Secure Mobile Gateway installed and configured.

Device Managed

A green light means that the device is managed by Device Manager, which means that the device has the XenMobile agent installed on it and that it is enrolled (and can communicate) with the server running Device Manager.
Note: In some cases, a device will appear as "managed" even though it does not have the XenMobile agent installed. This means that the device has likely been recognized by Device Manager through an ActiveSync connection. For example, if you import users into Device Manager who own a BlackBerry or Palm device, or if they connect to their email server through Active Sync, their devices will appear in Device Manager as "managed." Even though these devices cannot have a Device Manager agent installed, their communication with Device Manager Is limited, and they cannot have policies deployed to them, it is possible to issue an ActiveSync or Blackberry wipe to them.

A red light means that the device is not currently being managed by Device Manager for the following possible reasons:

  • If you perform a revoke, wipe, or selective wipe on a device.
  • If the device has an agent installed on it, but it was never enrolled.
  • If the device has an agent installed on it, but the user profile or corporate certificate has been removed.

Anonymous

Under the User column, a status of Anonymous can occur if a user authentication fails (wrong credentials).

When this happens, Windows Mobile and Symbian devices switch to anonymous mode. It can also happen if the user can no longer be used to authenticate from a device.

iOS and Android devices authenticate by using a client certificate, so those devices will only become Anonymous if the user is deleted or disabled in Active Directory.

To search for and edit device properties

From the Devices tab in the Device Manager web console, you can search for a device in the list. You can also edit the device properties to add additional properties.

To search for a device

The Search option under the Devices tab is a free-form search field, in which you can search for a device by typing in information you know about a device. You can also narrow your search within certain criteria.

  1. Click the search icon and then specify one or more of the following criteria:
    • The name of one of the device’s users
    • The device serial number
    • The device IMEI
    • The model of the device
    • Device platform
    • Operating system version
    Note: For each search criteria, you can enter the first letters or numbers of the item you are looking for.
  2. To narrow the search to specific criteria, in the Search list, select one or more of the following check boxes:
    • IMEI/MEID
    • User
    • Model
    • Platform
    • OS version
    • Serial number

To restore the complete list of devices, click x next to the Search field.

To edit the device properties

After you have added one or more devices into the repository database, you can populate additional comprehensive device data into the repository database. This ability allows administrators to maintain a detailed hardware inventory of their field devices within Device Manager.

  1. Click the Devices tab.
  2. Highlight the device to which you want to add additional hardware information and then click Edit.
  3. Click the Properties tab and then click New Property.
  4. Select either one of the included fields or select Other to create a custom data field. This field is free form, and can contain up to a maximum of 256 characters.

To show or hide device status

Under System Configuration in the Device Manager web console, you can change the parameters of how the device status appears. In the Devices column, you can also choose which columns to show or hide.

The following procedure describes how to show or hide the device status for jailbroken or rooted, Secure Mobile Gateway, and Device Manager management.

  1. In Device Manager, click Options.
  2. In the Options dialog box, click General.
  3. Under General Parameters, you can click to enable or disable the following status:
    • Highlight "Jailbroken/Rooted" column
    • Highlight "SMG Status" column
    • Highlight "Managed" column
    • Enable device triangulation
    • Enable WebEAS for iOS

To add or remove device status columns

  1. Click the Devices tab.
  2. Click the arrow in a status column to show a list of the possible columns that you can display. Each selected item appears in the Devices table.
  3. Clear a check box to hide a status column.

Locking a Device Remotely

If the device is lost, but you are not sure it was stolen, you can remotely lock the device. To do so, select the device in Device Manager and then on the Security menu, click Lock.

For Android and Windows Mobile devices, the system will then generate a PIN code that will be set in the device if the user had not set a PIN code already. To access the device, the user will have to type that PIN code.

When the device is found again, you can remove the lock by using the Cancel the lock option.

Selectively Wiping a Device

A selective wipe clears corporate data from a device while retaining personal information and selected settings. All mobile device management profiles, along with all packages pushed to the device from Device Manager, are removed. A device can be reenrolled at any time following a selective wipe.

Selectively wiping an Android device does not disconnect the device from Device Manager and the corporate network. To prevent the device from accessing Device Manager, you must also revoke the device certificates.

In the case of devices with the Samsung KNOX API enabled, selectively wiping the device also removes the Samsung KNOX container.

When you perform a selective wipe on a Windows 8 or Windows 8.1 device, the wipe also removes the contents of profile folder for any user who is signed on to the device at the time. Any web clips that you deliver to users through a configuration are not removed. Web clips are only removed when users manually unenroll their devices.

Selectively wiping a Windows Phone device removes the enterprise token that allows applications to be installed on the device by Device Manager. Additionally, the wipe removes all Device Manager certificates and configurations that have been deployed to the device.

To selectively wipe a device

  1. Using a web browser, navigate to http[s]://serveraddress[:port]/zdm, where serveraddress is the fully qualified domain name (FQDN) or IP address of the Device Manager server and port is the optional port number if you changed the default setting.
  2. Log on to the Device Manager web console using an account with administrative permissions.
  3. Click the Devices tab and then, in the results pane, select the device that you want to wipe.
  4. Click Security > Selective wipe.
  5. For Android devices only, after the device has been wiped, click Security > Revoke to disconnect the device from the corporate network.
  6. To withdraw a selective wipe request before it has been carried out, click Security > Cancel selective wipe.

Requesting a Full Wipe for a Device

If a device is stolen or lost, you can send a request to erase all of the data on a device. For Android devices, this also includes the option to include any memory cards.

To fully wipe a device, from the Devices tab on the XenMobile Device Manager web console, select Secuirty > Full Wipe.
Note: Erasing a device may not complete entirely if the current holder of the device has time to turn the device off before the content of the memory card is completely deleted. As such, they may still have access to data on the device.

If the wipe of the device is not done and the device is retrieved, you can cancel the wipe command by selecting the Cancel wipe menu item.

For Android devices, you can choose to wipe only the device, which removes any internally stored data, or choose to wipe the device, plus any externally connected storage data (memory cards).

For Windows Phone 8 devices, a full wipe removes all MDM information, plus all user data, including all personal content, such as apps, emails, contacts, and media files.

For Windows Mobile devices that are running Windows Mobile 6 or earlier, after wiping, you may need to send the device back to the manufacturer to reload the original operating system and/or software.

Tagging User Devices Automatically

You can tag user devices as either corporate-owned or employee-owned to keep track of your company's Bring Your Own Device (BYOD) program. You can tag the devices either automatically with a script or manually by using the Device Manager web console. To enable employee and corporate device tagging, you need to download a Microsoft PHP, add device IDs to a .csv file, and execute the given XenMobile scripts that will automate the device tagging process. After setting up the device tagging, you schedule the script as a repeating Windows Task to run every minute.
Note: For on-premise deployments, the tagDevices.php script is located at C:\Program Files (x86)\Citrix\XenMobile Device Manager\samples\WebServices.

To set up device tagging

  1. In a browser, go to the Windows PHP download site at http://windows.php.net/download/.
  2. Download the installer package named php 5.3 (VC9 x86 Thread Safe (2012-Feb-02 21:56:19).
  3. Install the package on your local system at c:\php5.
  4. Copy the two files named tagDevice.php and devices.csv to c:\temp. (This PHP script is host, location, and platform agnostic).
  5. Open the tagDevice.php file in a text editor and replace the default information (highlighted) with the following parameters:
    • For an on-site Device Manager implementation:
      $soap_url = "<servername>/zdm/services/EveryWanDevice?wsdl"  
      $client = new SoapClient(null, array( 
      'location' => $soap_url, 
      'url' => "<servername>", 
      'login' => "demo", 
      'password'=> "XXXXX")); 
      For example:
      $soap_url = "mdm.zenprise.com/zdm/services/EveryWanDevice?wsdl" 
      $client = new SoapClient(null, array( 
      'location' => $soap_url, 
      'url' => "mdm.zenprise.com", 
      'login' => "demo", 
      'password'=> "XXXXX")); 

      where mdm.zenprise.com is the name of the Device Manager server and zdm is the Device Manager instance name.

    • For a cloud deployment ​implementation:
      $soap_url = "<instance>.zc.zenprise.com/<instance>/services/EveryWanDevice?wsdl"; 
      $client = new SoapClient(null, array( 
      'location' => $soap_url, 
      'url' => "<instance>.zc.zenprise.com", 
      'login' => "demo", 
      'password'=> "XXXXX")); 
      For example:
       
      $soap_url = "abc.zc.zenprise.com/abc/services/EveryWanDevice?wsdl"; 
      $client = new SoapClient(null, array( 
      'location' => $soap_url, 
      'url' => "abc.zc.zenprise.com", 
      'login' => "demo", 
      'password'=> "XXXXX")); 
      
  6. Edit the devices.csv file and add the serial numbers of all corporate devices, on separate lines.
  7. Open a DOS command prompt, cd to c:\temp and then run the command tagDevice.php as follows:
    c:\temp>c:\php5\php.exe tagDevice.php 
    device:7R043870A4S is a personal asset 
    device:82835PLWY7K is a personal asset 
    device:88025X9PA4T is a personal asset 
    device:880277VSA4S is a personal asset 
    device:99000052027603 is a personal asset 
    device:A1000013555FD9 is a personal asset 
    device:A10000138B2613 is a personal asset 
    device:A1000017B0A311 is a personal asset 
    device:C329030326CC33E is a corporate asset 
    device:GB0262YCETV is a personal asset 
    device:GB0289L3ETV is a personal asset 
    c:\temp>

To configure a device tagging script to run as a repeating task

  1. Create a file named tagDevice.cmd under c:\temp (where you previously had copied tagDevice.php and devices.csv) and add the following line: cd c:\temp && c:\php5\php.exe tagDevice.php
  2. Create an MS Scheduled task to execute this command once every minute (/MO 1). For example: c:\> schtasks /create /TN tagDevice c:\temp\tagDevice.cmd /MO 1
  3. Query the tasks to verify that it exists by executing the following command: c:\ schtasks /query /TN tagDevice
  4. To delete the task, execute this command: c:\ schtasks /delete /TN tagDevice

Tagging User Devices Manually

You can manually tag a device in one of the following ways:
  • Tag the device during the invitation-based enrollment process (iOS only). When you enroll an iOS device, you have the option of tagging the device as either corporate-owned or employee-owned.
  • Tag the device during the Self Help Portal enrollment process. When using the Self Help Portal to self-enroll a device, you can also tag the device as either corporate-owned or employee-owned.
  • Tag the device by adding a device property (any device). You add a property to the device from the Devices tab in Device Manager. You create the property named Device Ownership and choose either Corporate or Employee.