XenMobile Rest API

XenMobile Rest API

book

Article ID: CTX223162

calendar_today

Updated On:

Description

XenMobile provides an extensive REST API that can be leveraged to extract data and provide it for business needs. This feature provides customers with the facility of calling XenMobile services using REST API. Instead of using XenMobile console, customers can call exposed services by using any REST client.

One of the major benefits of this feature is that customers can carry out different bulk operations in an automated way using scripts. Using these APIs, customers can setup external systems that can authenticate and connect to XenMobile server, retrieve specific information required for business needs such as number of devices enrolled, deploy any device, perform full or selective wipes, information about users, groups, applications, delivery groups and much more. These functions when called can perform the same tasks that an admin can execute from console; however it can also be used to perform certain other tasks that take longer and manual approach such as generating bulk invitations and/or OTP’s.
 

Instructions

How to use XenMobile REST API

The REST APIs are designed to connect over HTTP(S) and require an administrator account for authentication. Both XenMobile on-premises software and cloud deployments have full support for the REST APIs. Customers can decide the data parameters and values they would like to access via the API. 
This article provides a step by step guide to use XenMobile REST APIs. In this article we will cover the steps to “Search a device by serial number and then lock that device” using REST API. Customers can use similar approach to perform other tasks e.g. Find all Devices in a Delivery group then Deploy resources on them.

Search a device by serial number and then lock that device

Pre-requisites

The sample code presented in this article is written for NodeJS. Similar code can be written in any other language/environment. This code is OS independent and should work with all the popular operating systems (i.e. Windows, Mac, Linux etc.)

Node modules

Sample code in this article uses following NodeJS modules. These modules can be installed using Node Package Manager (NPM).  

Helper method

A helper method “sendRequest” is used in sample code to make request to XenMobile REST APIs.
Here is the implementation of this method:
  
var request     = require('request');
var SERVER_URL  = 'https://<SERVER_FQDN>:<PORT>/xenmobile/api/v1/';
 
function sendRequest(url, method, headers, requestData, cb) {
    request({
        url      : SERVER_URL + url,
        method   : method,
        headers  : headers, 
        json     : requestData
    }, function (error, response, responseJSON) {
        if(error || response.statusCode !== 200 || (responseJSON.status !== undefined && responseJSON.status !== 0)) {
            var errorMessage = error ? error : (responseJSON.message || responseJSON); 
            cb(errorMessage);
        } else {
            cb(null, responseJSON);
        }
    });
}
 

Steps to search and lock a device

Here are the steps to search any device in XenMobile by its serial number and then perform the lock action on that device.

Step-1: Login User

Before sending any API call we need to login and retrieve authentication token. This authentication token will then be used in subsequent API calls. To make the login request, send username and password as request data in “sendRequest” method. In response, server returns authentication token as “auth_token” in JSON object. We will keep this authToken in a global variable so that we can use it in next calls.
Here is the sample code to make the login call. 
var authToken   = null;
 
function loginUser(cb) {
    var url         = 'authentication/login';
    var requestData = {
        'login'     : 'username',
        'password'  : 'password'
    }
    sendRequest(url, 'POST', {}, requestData, function(err, response) {
        if(err) {
            cb(err);
        } else {
            authToken =  response.auth_token;  
            cb(null, {});            
        } 
    });
}
 
After defining these methods, let’s add entry point for our sample from where we can call all these methods that we created earlier.
Here is the sample code for the entry point of our sample. It uses async.waterfall to manage nested callbacks. 
var async = require('async');
 
function main() {
    async.waterfall([                       
        function(callback) {
            loginUser(callback);
        }        
    ], 
    function(err, result){
        if(err) {
            console.log("Error Occured" + err);
        } else {
            console.log("operation completed successfully");
        }
    });
} 
 
main();
 
 
As we have successfully retrieved auth_token, we can now call XenMobile REST APIs.

Step-2: Search Device

XenMobile provides device filter API for searching a device. This API requires a search string. It is similar to searching a device in console’s search text field (in Devices tab).
Here is the sample code to make a device search call: 
function searchDevice(searchText , cb) {
    var url         = 'device/filter';
    var requestData = {
        'search'    : searchText
    };
    sendRequest(url, 'POST', {'auth_token': authToken}, requestData, cb);
}
 
Now we will make following changes in our entry point code to call searchDevice method. The additions are highlighted in red. 
var async        = require('async');
 
function main() {
    async.waterfall([
        function(callback) {
            loginUser(callback);
        },
        function(data, callback) {
            searchDevice("ABC123456789", callback);
        }
    ], 
    function(err, result){
        if(err) {
            console.log("Error Occured" + err);
        } else {
            console.log("operation completed successfully");
        }
    });
} 
 
main();
 

In response, we will get all devices based on the search text we provided. We can now perform any action on this set of devices.

Step-3: Perform Lock Action

XenMobile provides option to perform any action on a list of devices through its REST APIs. Now let’s make a call to lock the devices we retrieved in previous step.
Here is the code to make device lock call: 
function lockDevices(deviceIds , cb) {
    var url         = 'device/lock';
    var requestData = deviceIds;
    sendRequest(url, 'POST', {'auth_token': authToken}, requestData, cb);
}

Now we will make following changes in our entry point code to call lockDevices method. The additions are highlighted in red 
var async = require('async');
 
function main() {
    async.waterfall([
        function(callback) {
            loginUser(callback);
        },
        function(data, callback) {
            searchDevice("ABC123456789", callback);
        },
        function(devices, callback) {
            var deviceIds = [];
            for(var index in devices.filteredDevicesDataList) {
                deviceIds.push(devices.filteredDevicesDataList[index].id);
            }
            lockDevices(deviceIds, callback);
        }
    ], 
    function(err, result){
        if(err) {
            console.log("Error Occured" + err);
        } else {
            console.log("operation completed successfully");
        }
    });
} 
main();
This will lock the device with the given serial number.

Similarly, we can search devices by IMEI or user name and perform any other action (wipe, selective wipe etc.) on the retrieved devices. These are just some of the things that we can do using the XenMobile REST API. There is a lot more that can be done using these powerful XenMobile REST APIs.
 

Additional Information

Citrix Documentation - REST APIs ​​​​​​​
Powered by Wolken Software