The XenMobile console is a great way of managing your environment, but sometimes you need to be able to do things in bulk. XenMobile provides an extensive API that allows you to do many things in a scripted way. The API is great if you are an experienced developer and you have the time and resources to build extensive scripts and debug them. I’ve been asked on multiple occasions on how to do bulk actions by customers who don’t want to spend months writing the scripts to do this.
Having worked with Microsoft Exchange and Lync in the past, I figured you should be able to do this with PowerShell as well. So, I wrote a PowerShell module that allows you to do several of the tasks you can do through the API. If you know your way around PowerShell, you’ll be able to use this in no time.
You can get the module here: https://github.com/wvanbesien/XenMobileShell
Click on the “Clone or Download” link and download the file. Copy the module (the psm1 file) into the following folder (which you’ll have to create): C:\windows\system32\windowspowershell\v1.0\Module\XenMobileShell
| Important: The PowerShell module can be freely downloaded from github and is NOT SUPPORTED by Citrix in any way. |
Using the PowerShell module
Requirements:
- As the module uses the API, you need an account with API access.
- The module uses PowerShell 5.0 which included with Windows 10. For other platforms, it’s a free download.
- You’ll need to be able to access port 4443 (the admin port) on the server in order to access the API. Also, you’ll have to connect using a valid FQDN. That means: a valid certificate on the server, the name matches, and the certificate is trusted.
get help information
The module includes help information. Normally, the module should load automatically when you open PowerShell. You can confirm it did and show all the available commands:
get-command *xm* |
To get the help file for any of the commands (here new-xmenrollment), do the following (you can get information about parameters, get examples etc):
get-help new-xmenrollment |
Before you can run any of the commands, you’ll actually have to setup a session to the server.
Here is how you’d setup a session with user xmapi, password “Password” and server “mdm.ccslabs.biz” (the second example uses the PowerShell PScredential object which is useful if you want to use this in a script and don’t want to store clear text passwords in the script):
new-xmsession -user "xmapi" -password "Password" -server mdm.someserver.com # uses a username and password
|
If everything is successful, you should receive a token and be informed when the session will time out. Just to repeat this again: you cannot use an IP address to connect, you will need to use a FQDN.
| Note: By default XenMobile server uses a 1 hour static timeout. It may be preferable to use an inactivity timeout. You can change this in the server options. |
Let’s do some stuff
After you have set up a session, you can start running some commands. ( # denotes a comment you do not need to type yourself. )
|
However, you can chain this with other PowerShell commands as well. The following will create a CSV file with all devices.
get-xmdevice | export-csv c:\devices.csv |
Want to run some of the commands in sequence with the output of one being the input of the next?
|
Change device ownership
This is a common task: changing the ownership of a bunch of devices. The device ownership is a device property (called CORPORATE_OWNED). Each device in the database has a device ID and all device commands use this ID:
get-xmdeviceproperty -id 28 #show the properties of a device. You can see if ownership is set. |
If you don’t know the id, use the get-xmdevice command. For example, the following will show the device properties of a device with a given serial number:
get-xmdevice -criteria <serialnumber> | get-xmdeviceproperty |
In case you wonder, the criteria can be the serial number, or user name. Basically, it’s the same field as the ‘search’ box in our GUI.
Now for ownership, there are 3 possible states:
- the ownership is unknown. In that case, the CORPORATE_OWNED property simply doesn’t exist.
- the ownership is corporate. In that case, the CORPORATE_OWNED property is set to 1
- the ownership is byod. In that case, the CORPORATE_OWNED property is set to 0
To set this for a device with id 28:
set-xmdeviceproperty -id 28 -name "CORPORATE_OWNED" -value "1" |
So, let use a more complex example. Say you have a CSV file with serial numbers for all the corporate devices. All other devices should be recorded as BYOD. First in the CSV file, name the column with serialnumbers ‘criteria’ (it allows for easy PowerShell piping) and run the following:
import-csv serialnumber.csv | get-xmdevice | set-xmdeviceproperty -name "CORPORATE_OWNED" -value "1" |
Now, if you csv file didn’t have the serialnumbers in a column called criteria, you can accomplish the same with this slightly longer command (assuming the command is called ‘serialnumber’:
import-csv serialnumber.csv | %{get-xmdevice -criteria $_.serialnumber } | set-xmdeviceproperty -name "CORPORATE_OWNED" -value "1" |
Now to set the remaining devices to BYOD, we just change those device that don’t have ownership set:
get-xmdevice -filter "[device.ownership.unknown]" | set-xmdeviceproperty -name "CORPORATE_OWNED" -value "0" |
Bulk enrolling
Obviously, we can also use the module to do bulk enrollments. The commands we use here have a lot of options, and you don’t have to specify all of them. It is also possible to send notifications to users when creating an enrollment invitation. In that case, notification servers must be configured on the server and you have to specify the notification templates to use for notification. Note: the template names are case-sensitive and the command will fail if you have even the smallest typo in the template name.
Obviously, if you want to deploy devices in bulk it’s best to create a CSV file with the required info. (It is possible to to an active directory search and pipe that into the enrollment commands, but that’s a topic for another time). To make you life easier, name the columns in the CSV file the same as the parameter name in the enrollment command: user, OS, ownership, phoneNumber etc. The only mandatory values are the user, OS and ownership. Once you have created your CSV file, you can create the enrollment invitations as follows:
import-csv enrollments.csv | new-xmenrollment |
If the column names don’t match, you will need to specify them. Also, because the enrollment commands requires a confirmation, you want to override the prompt (which in otherwise would be requested for each invitation):
import-csv enrollment.csv | %{new-xmenrollment -user $_.username -OS $_.os -ownership $_.ownership -force } |
Now, say you want to use the invitation url + PIN method. Below command will create the enrollment invitations and store the details (url and pin code) to a csv file:
import-csv enrollment.csv | new-xmenrollment -mode "invitation+pin" | export-csv enrollmentdetails.csv |
The new-xmenrollment command has a lot options. You can specify all of these in a csv file and if the column names match the name of the parameter you don’t need to specify it.
Closing
These are just some of the things you can do using the PowerShell module. There’s a lot more and this module can easily be incorporated into larger PowerShell scripts. Similarly, you can use this module to automate actions using Microsoft System Center Orchestrator.
