Sophos Mobile Control Web service guide

Sophos Mobile Control Web service guide Product version: 3.5 Document date: July 2013

Contents 1 About Sophos Mobile Control... 3 2 Prerequisites... 4 3 Server-side implementation... 5 4 Client-side implementation... 6 5 Available entities... 7 6 Available filters... 22 7 Available operations... 28 8 Appendix... 65 9 Technical support... 71 10 Legal notices... 72.utimaco.com

Web service guide 1 About Sophos Mobile Control Sophos Mobile Control is a device management solution for mobile devices like smartphones and tablets. It allows configuration and software distribution as well as security settings and many other device management operations on mobile devices. With Sophos Mobile Control you can keep corporate data safe by managing apps and security settings. The Sophos Mobile Control client is easily installed and managed with over-the air setup and configuration through the Sophos Mobile Control web console. With the Sophos Mobile Control Self Service Portal for your users, you can reduce IT efforts by allowing them to register their own devices and carry out other tasks without having to contact the helpdesk. 3 3

Sophos Mobile Control 2 Prerequisites To use the web service, you need a Sophos Mobile Control user account. These accounts consist of the following information: Customer User Password 4

Web service guide 3 Server-side implementation The server-side portion of the web service runs inside the Java EE application Server JBoss 4.2.3 GA. The web service stack in use is JBoss-WS-CXF (version 3.1.1 GA) and is based on JAX-WS. The web service is defined to use the following options: Style Document Use Literal ParameterStyle Wrapped 5 5

Sophos Mobile Control 4 Client-side implementation The web service definition is provided as a standard WSDL file. This file lists the available operations and entities and serves as the basis for the generation of the necessary web service client stubs. All major programming languages offer tools for the automated generation of the client stubs. The web service client needs to be set to maintain the session across different calls. This may or not be the default behavior depending on the web service client framework in use. The webservice is available at https://[hostname]/mdmwebservice. The WSDL file can be obtained at https://[hostname]/mdmwebservice?wsdl. 6

Web service guide 5 Available entities Notes: Access types for the entities: r: read only w: write only : read and write Links to entities: If the value is a link to an entity, you can edit the link to an existing entity, but not the nested entity itself 5.1 WsAdminUser Represents admin users for customers including the following attributes: Type Value Mandatory Access Integer id r user name Required, length 1 to 100 last name Required, length 1 to 100 first name Required, length 1 to 100 email Required, length 1 to 100 password w WsAdminUserProperty[] properties 7 7

Sophos Mobile Control 5.2 WsAdminUserProperty To set new WsAdminUserProperties, you have to get the existing WsAdminUserProperties from the selected WsAdminUser and add the new Properties to this array. Afteards you have to save the WsAdminUser. Represents admin user properties including the following attributes: Type Value Mandatory Access key Required, length 1 to 100 value required, length 1 to 65535 5.3 WsAndroidProfile Represents profiles for android devices including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 100 description Required, length 1 to 255 version Required, length 1 to 100 WsOperatingSystem[] link to operating system Required, min. elements 1 byte[] profile content Required 8

Web service guide 5.4 WsComplianceCriterion Represents compliance criteria for compliance sets including the following attributes: Type Value Mandatory Access WsComplianceCriterionType link to criterion type Required value of criterion type Required, length 1 to 65535 WsOperatingSystemPlatform link to platform Required Map<WsComplianceCriterionAction Type, WsComplianceCriterion Action> link of type to actions 5.5 WsComplianceCriterionAction Represents compliance criterion actions for compliance sets including the following attributes: Type Value Mandatory Access WsComplianceCriterion ActionType link to type Required value Required, length 1 to 65535 5.6 WsComplianceCriterionActionType Represents compliance criterion action types for compliance criterion actions including the following static attributes: Type Value Access WsComplianceCriterionActionType disallow_eas_traffic, email_admin, transfer_taskbundle r 9 9

Sophos Mobile Control 5.7 WsComplianceCriterionType Represents compliance criterion types for compliance criterion actions including the following static attributes: Type Value Access WsComplianceCriterionType general_managed, general_min_osversion, general_min_clientversion, general_max_client_sync_gap, general_blacklisted_apps, general_whitelisted_apps, general_mandatory_apps, general_passcode_present, general_data_roaming_enabled, general_voice_roaming_enabled, general_smsec_max_scan_gap, general_smsec_malware_allowed, general_smsec_suspicious_allowed, general_smsec_unwanted_allowed, android_root_allowed, android_nonmarket_allowed, android_encryption_active, android_adb_allowed, ios_jailbreak_allowed, ios_max_app_sync_gap, ios_mandatory_profiles, ios_encryption_active, ios_app_locate_active wp_max_app_sync_gap wp_encryption_active r 5.8 WsComplianceSet Represents compliance sets for devices including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 255 description Required, length 1 to 255 boolean boolean android enabled blackberry enabled 10

Web service guide Type Value Mandatory Access boolean ios enabled boolean boolean boolean WsComplianceCriterion[] symbian enabled windows mobile enabled windows phone enabled compliance criteria 5.9 WsComplianceViolation Represents compliance violations for devices including the following attributes: Type Value Mandatory Access type r info r Boolean disallow active sync r Date insert Date r 5.10 WsCustomer Represents customers including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 100 external id Required, length 1 to 100 technical contact forename Max. length 100 technical contact Max. length 100 11 11

Sophos Mobile Control Type Value Mandatory Access surname technical contact email Max. length 100 technical contact phone number Max. length 100 technical contact mobile number Max. length 100 technical contact addit. info Max. length 100 WsCustomerProperty[] customer properties Required 5.11 WsCustomerProperty To add new WsCustomerProperties, you have to get the existing WsCustomerProperties from the selected WsCustomer and add the new Properties to this array. Afteards you have to save the WsCustomer. Represents customer properties including the following attributes: Type Value Mandatory Access key Required, length 1 to 100 value Max. length 65535 12

Web service guide 5.12 WsDeletedDevice Represents deleted devices including the following attributes: Type Value Mandatory Access Integer device id r name r description r operating system name r phone number r serial number r Date date of deletion r 5.13 WsDevice Represents devices including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 100 description Required, length 1 to 65535 email address Length 1 to 100 WsDeviceGroup link to device group Required WsOperatingSystem link to operating system Required Date last sync date Boolean managed status Boolean compliance status WsDeviceProperty[] device properties Required 13 13

Sophos Mobile Control Type Value Mandatory Access phone number Required, length 1 to 100 5.14 WsDeviceGroup Represents device groups including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 100 description Required, length 1 to 100 WsComplianceSet link to compliance set for corporate devices Required WsComplianceSet link to compliance set for employee devices Required 5.15 WsDeviceProperty To add new WsDeviceProperties, you have to get the existing WsDeviceProperties from the selected WsDevice and add the new Properties to this array. Afteards you have to save the WsDevice. Represents device properties including the following attributes: Type Value Mandatory Access key Required, length 1 to 100 value Required, length 1 to 65535 type Length 1 to 50 14

Web service guide 5.16 WsDeviceTemplate Represents device templates including the following attributes: Type Value Mandatory Access id r name r WsOperationSystem link to operating system r 5.17 WsInstalledIOSProfile Represents ios configuration profiles installed on devices including the following attributes: Type Value Mandatory Access payload identifier payload description payload display name payload organization r r r r payload UUID r payload version r Boolean is encrypted r Boolean is managed r Boolean Boolean has removal passcode payload removal disallowed r r 15 15

Sophos Mobile Control 5.18 WsInstalledIOSProvisioningProfile Represents ios provisioning profiles installed on devices including the following attributes: Type Value Mandatory Access payload name r payload UUID r expiry date r 5.19 WsInstalledSoftware Represents software packages installed on devices including the following attributes: Type Value Mandatory Access name r identifier r version r Integer app size r Integer data size r 5.20 WsInternalSSPUser Represents internal SSP users including the following attributes: Type Value Mandatory Access last name Required, length 1 to 100 first name Required, length 1 to 100 user name Required, length 1 to 100 phone number Required, length 1 to 100 email Required, length 1 to 100 16

Web service guide Type Value Mandatory Access GUID r common name r distinguished name r 5.21 WsIOSProfile Represents profiles for IOS devices including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 100 description Required, length 1 to 100 version Required, length 1 to 100 WsOperatingSystem[] link to operating system Required, min. elements 1 byte[] profile content Required, length 1 to 65535 5.22 WsOperatingSystem Represents operating systems including the following attributes: Type Value Mandatory Access Integer id r name r version r WsOperatingSystemPlatform platform r 17 17

Sophos Mobile Control 5.23 WsOperatingSystemPlatform Represents operating system platforms including the following static attributes: Type Value Access WsOperatingSystemPlatform android, symbian, windowsmobile, windowsphone, iphone, blackberry, other r 5.24 WsSoftware Represents software packages for WsDevice including the following attributes. Either file content and file name or just the file link must be set. Type Value Mandatory Access Integer id r name Required, length 1 to 100 description Required, length 1 to 255 version Required, length 1 to 100 WsOperatingSystem[] link to operating systems Required, min. elements 1 byte[] file content Max. size 10 MB file name Max. length 255 file link Max. length 255 18

Web service guide 5.25 WsTaskBundle Represents task bundles including the following attributes: Type Value Mandatory Access Integer id r name Required, length 1 to 100 version Required, length 1 to 100 WsOperatingSystem[] link to operating systems Required, min. elements 1 WsTaskBundleTask[] tasks Required, min. elements 1 5.26 WsTaskBundleTask Represents task bundle tasks for task bundles defined on the server including the following attributes: Type Value Mandatory Access WsTaskbundleTaskType type Required name required, length 1 to 255 Integer rcs object id identifier Max. length 255 message text Max. length 255 Boolean enforce 19 19

Sophos Mobile Control 5.27 WsTaskbundleTaskType Represents the task bundle task types for task bundle tasks on the server including the following static attributes: Type Value Access TaskbundleTaskType MDMAgentInstall, SoftwareInstall, CommandBundleTransfer, WinMobileProfileTransfer, TextSms, Wipe, ResolveActiveSyncId, TriggerSmsecScan, AndroidProfileTransfer, IOSMDMBootstrap, IOSMDMProfileTransfer, IOSMDMProfileRemoval, IOSMDMProvisioningProfileTransfer, IOSMDMProvisioningProfileRemoval r 5.28 WsTransition Represents transitions ( task ) for devices including the following attributes: Type Value Mandatory Access Integer id r package name r WsDevice device r Date scheduled date r Date execution date r Integer status r 20

Web service guide 5.29 WsVersionInfo Information about the server version: Type Value Mandatory Access core version r gui version r web service version r 21 21

Sophos Mobile Control 6 Available filters 6.1 WsAdminUserFilter Allows filtering the admin user list with the following options: Type Integer Integer Integer Value id login name last name from index page size 6.2 WsAndroidProfileFilter Allows filtering the android profile list with the following options: Type Integer WsOperatingSystem[] Integer Integer Value id name version link to operating system from index page size 22

Web service guide 6.3 WsComplianceSetFilter Allows filtering the compliance set list with the following options: Type Integer Integer Integer Value id name from index page size 6.4 WsCustomerFilter Allows filtering the customer list with the following options: Type Integer Integer Integer Value id external id name from index page size 6.5 WsDeletedDeviceFilter Allows filtering the deleted devices list with the following options: Type Date Value name deletion date, returns results with deletion dates not older than given date 23 23

Sophos Mobile Control 6.6 WsDeviceFilter Allows filtering the device list with the following options: Type Integer WsOperatingSystem[] boolean boolean Date Integer Integer Value id name phone number email link to operating systems managed compliant updated date, returns results with update dates not older than given date from index page size 6.7 WsDeviceGroupFilter Allows filtering the device group list with the following options: Type Integer Integer Integer Value id name from index page size 24

Web service guide 6.8 WsDeviceTemplateFilter Allows filtering the device template list with the following options: Type Integer WsOperatingSystem[] Integer Integer Talue id name link to operating systems from index page size 6.9 WsInternalSSPUserFilter Allows filtering the internal SSP user list with the following options: Type Value common name email phone number user name 6.10 WsIOSProfileFilter Allows filtering the ios profile list with the following options: Type Integer WsOperatingSystem[] Integer Integer Value id name version link to operating systems from index page size 25 25

Sophos Mobile Control 6.11 WsOperatingSystemFilter Allows filtering the operating system list with the following options: Type Integer WsOperatingSystemPlatform Integer Integer Value id name link to platform from index page size 6.12 WsSoftwareFilter Allows filtering the software list with the following options: Type Integer WsOperatingSystem[] Integer Integer Value id name version link to operating systems from index page size 6.13 WsTaskBundleFilter Allows filtering the task bundle list with the following options: Type Integer WsOperatingSystem[] Integer Integer Value id name version link to operating systems from index page size 26

Web service guide 6.14 WsTransitionFilter Allows filtering the transition list with the following options: Type Integer WsDevice Integer Integer Value id link to device from index page size 27 27

Sophos Mobile Control 7 Available operations All operations except for getversioninfo() require the web service client to be logged in. Note: In the following operations, the acronym MTA may occur. MTA stands for Multi Tenant Admin and can be used as a synonym for super administrator. 7.1 clonemtasettingsandassignrcsmos(wscustomer) This operation clones settings from the super administrator customer to the given target customer. This is useful when setting up new customers. All settings are copied to the target customer. Device groups are also copied. All packages the super administrator has are assigned (as opposed to being copied) to the target customer. WsCustomer: The customer to receive the cloned settings WsCustomer: The modified customer (not yet saved) LoginRequiredException: If the web service client has no valid session InsufficientRightsException: If the web service client has no rights to access this operation (especially in case the logged in user is not a super administrator user) 7.2 createadminuser(,,, ) This operation creates an admin user for the logged in customer. If a password is needed, it has to be set after creation and before saving of the admin user. : user name : last name : first name : email address WsAdminUser: The created admin user for the logged in customer (not yet saved) 28

Web service guide LoginRequiredException: If the web service client has no valid session InsufficientRightsException: If the web service client has no rights to access this operation 7.3 createandroidprofile() The operation creates a template forandroid profiles. This template needs to be edited and filled with information afteards. None WsAndroidProfile: The created android profile (not yet saved) LoginRequiredException: If the web service client has no valid session InsufficientRightsException: If the web service client has no rights to access this operation 7.4 createandroidprofiletransition(wsdevice, WsAndroidProfile, Date) This operation creates a transition to send an Android profile to an Android device. WsDevice: Device for transition WsAndroidProfile: Android profile for selected device Date: Scheduled start date Integer: The ID of the created transition 29 29

Sophos Mobile Control 7.5 createandsavecustomer(,,,,,,,,,, boolean) The operation creates and saves (!) a customer and an admin user for this customer. : customer name : external id : technical contact last name : technical contact first name : technical contact email address : admin user login name : admin user last name : admin user first name : admin user email address : admin user password boolean: Users have to change their predefined passwords. return Integer: the id of the saved customer throws (especially in case the logged in user is not a super administrator user) MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 30

Web service guide 7.6 createcomplianceset() This operation creates an empty template for a compliance set which needs to be edited afteards. None WsComplianceSet: The created compliance set (not yet saved) 7.7 createdevicedecommissiontransition(wsdevice) This operation creates a decommission transition for a device. The command for decommissioning will be sent to the selected device. WsDevice: Device to decommission Integer: The ID of the created transition 31 31

Sophos Mobile Control 7.8 createdevicefromtemplate(wsdevicetemplate) This operation creates a device from a device template which needs to be edited afteards. WsDeviceTemplate: The device template to use WsDevice: The created device (not yet saved). 7.9 createdevicegroup() This operation creates a device group for the logged in customer. Needs to be edited afteards. None WsDeviceGroup: The created device group (not saved yet) 32

Web service guide 7.10 createdevicelocatetransition(wsdevice) This operation creates a locate transition for a device. The command for locating the device will be sent to the selected device. WsDevice: device to locate Integer: The ID of the created transition 7.11 createdevicelockcodetransition(wsdevice, ) This operation creates a device lock with a new password transition for a device. The command to lock the device with a new password will be sent to the selected device. WsDevice: Device to lock with code : Lock code to use Integer: The ID of the created transition 33 33

Sophos Mobile Control 7.12 createdevicelocktransition(wsdevice) This operation creates a lock transition for a device. The command to lock the device will be sent to the selected device. WsDevice: The device to lock Integer: The ID of the created transition 7.13 createdevicesynctransition(wsdevice) This operation creates a sync transition for a device. The command to sync the device with the server will be sent to the selected device. WsDevice: device to sync Integer: The ID of the created transition 34

Web service guide 7.14 createdeviceunlocktransition(wsdevice) This operation creates an unlock transition for a device. The command for a device unlock will be sent to the selected device. WsDevice: Device to unlock Integer: The ID of the created transition 7.15 createdevicewipetransition(wsdevice) This operation creates a wipe transition for a device. The command for a device wipe will be sent to the selected device. WsDevice: The device to wipe Integer: The ID of the created transition 35 35

Sophos Mobile Control 7.16 createinternalsspuser(,,,, ) The operation creates an internal SSP user for the logged in customer. The SSP user will get a generated password by email. : user name : last name : first name : email address : phone number The created internal SSP user (not yet saved) 7.17 createiosprofile() The operation creates a template for ios profiles. This template needs to be edited and filled with information afteards. None The created ios profile (not yet saved) 36

Web service guide 7.18 createiosprofiletransition(wsdevice, WsIOSProfile, Date) This operation creates a transition to send an ios profile to an ios device. WsDevice: Device for ios profile transition Date: Scheduled start date The ID from the created transition 7.19 createsoftware() This operation creates an empty template for a software package which needs to be edited afteards. The entities for a software package differ by the type you choose. If you want a package with a link to an application, you only need to set the link in the entity. If you want to create a software package with an application file, you have to set the file content and file name in the entity (see chapter 5.24). None The created software package (not yet saved) 37 37

Sophos Mobile Control 7.20 createsoftwaretransition(wsdevice, WsSoftware, Date) This operation creates a software install transition for a device. The command to install a software package will be sent to the selected device. WsDevice: Device for software transition WsSoftware: Software package for selected device Date: Scheduled start date The ID of the created transition 7.21 createtaskbundle() This operation creates an empty template for a task bundle which needs to be edited afteards. None The created task bundle (not yet saved) 38

Web service guide 7.22 createtaskbundletransition(wsdevice, WsTaskBundle, Date) This operation creates a task bundle transition for a device. The command to execute the task bundle will be sent to the selected device. WsDevice: The target device WsTaskBundle: The task bundle to transfer Date: Scheduled start date Integer: the ID of the created transition InsufficientRightsException: If the web service client has no rights to access this operation 7.23 getversioninfo() This operation returns the server information (core, GUI and web service version). None WsVersionInfo: Information of the server InsufficientRightsException: Does not apply in this case 39 39

Sophos Mobile Control 7.24 istransitionfinal(wstransition) This operation returns true if the state of the selected transition is final. WsTransition: the transition to check True, if the transition is in a final state, false otheise. 7.25 linkdevicetouser(wsdevice, WsInternalSSPUser) This operation links the selected device to the selected internal SSP user. The SSP user can operate this device from his SSP afteards. WsDevice: Device to link with user WsInternalSSPUser: User for linking True, if the link was successful, false otheise. MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 40

Web service guide 7.26 listadminusers(wsadminuserfilter) This operation returns an array of admin users matching the given filter. If no users are found, the operation returns null. WsAdminUserFilter: The admin user filter to use WsAdminUser[]: Array of WsAdminUser matching the given filter 7.27 listandroidprofiles(wsandroidprofilefilter) This operation returns an array of Android profiles matching the given filter. If no profiles are found, the operation returns null. WsAndroidProfileFilter: The Android profile filter to use WsAndroidProfile[]: Array of WsAndroidPriles matching the given filter 41 41

Sophos Mobile Control 7.28 listcompliancesets(wscompliancesetfilter) This operation returns an array of compliance sets matching the given filter. If no compliance sets are found, the operation returns null. WsComplianceSetFilter: The compliance set filter to use WsComplianceSet[]: Array of WsComplianceSets matching the given filter 7.29 listcomplianceviolations(wsdevice) This operation returns an array of compliance violations matching the given filter. If no compliance violations are found, the operation returns null. WsDevice: The device for which to look up compliance violations WsComplianceViolations[]: Array of WsComplianceViolations of the given device 42

Web service guide 7.30 listcustomerproperties() This operation returns a list of WsCustomerProperties for the logged in customer. none WsCustomerProperty[]: Array of WsCustomerProperties for the logged in WsCustomer 7.31 listcustomers(wscustomerfilter) This operation returns an array of customers matching the given filter. If no customers are found, the operation returns null. WsCustomerFilter: The customer filter to use WsCustomer: Array of WsCustomers matching the given filter InsufficientRightsException: If the web service client has no rights to access this operation (especially in case the logged in user is not a super administrator user) 43 43

Sophos Mobile Control 7.32 listdeleteddevices(wsdeleteddevicefilter) This operation returns an array of deleted devices matching the given filter. If no deleted devices are found, the operation returns null. WsDeletedDeviceFilter: The deleted device filter to use WsDeletedDevice[]: Array of WsDeletedDevices matching the given filter 7.33 listdevicegroups(wsdevicegroupfilter) This operation returns an array of device groups matching the given filter. If no groups are found, the operation returns null. WsDeviceGroupFilter: The device group filter to use WsDeviceGroup[]: Array of WsDeviceGroups matching the given filter 44

Web service guide 7.34 listdevices(wsdevicefilter) This operation returns an array of devices matching the given filter. If no devices are found, the operation returns null. WsDeviceFilter: The device filter to use WsDevic[]: Array of WsDevices matching the given filter 7.35 listdevicetemplates(wsdevicetemplatefilter) WsDeviceTemplateFilter: The device template filter to use WsDeviceTemplates[]: Array of WsDeviceTemplates matching the given filter 45 45

Sophos Mobile Control 7.36 listinstallediosprofiles(wsdevice) This operation returns an array of installed ios profiles matching the given filter. If no installed ios profiles are found, the operation returns null. WsDevice: The device whose profiles shall be queried WsInstalledIOSProfile[]: Array of WsInstalledIOSProfiles of the given device 7.37 listinstallediosprovisioningprofiles(wsdevice) This operation returns an array of installed ios provisioning profiles matching the given filter. If no installed ios provisioning profiles are found, the operation returns null. WsDevice: The device whose provisioning profiles shall be queried WsInstalledIOSProvisioningProfile[]: Array of WsInstalledIOSProvisioningProfiles of the given device 46

Web service guide 7.38 listinstalledsoftware(wsdevice) This operation returns an array of installed software matching the given filter. If no software is found, the operation returns null. WsDevice: The device whose installed software shall be queried WsInstalledSoftware[]: Array of WsInstalledSoftware[] of the given device 7.39 listinternalsspusers(wsinternalsspuserfilter) This operation returns an array of internal SSP users matching the given filter. If no users are found, the operation returns null. WsInternalSSPUserFilter: The internal SSP user filter to use WsInternalSSPUser[]: Array of WsInternalSSPUsers mathing the given filter 47 47

Sophos Mobile Control 7.40 listiosprofiles(wsiosprofilefilter) This operation returns an array of ios profiles matching the given filter. If no ios profiles are found, the operation returns null. WsIOSProfileFilter: the ios profile filter to use WsIOSProfile[]: Array of WsIOSProfiles matching the given filter 7.41 listoperatingsystems(wsoperatingsystemfilter) This operation returns an array of operating systems matching the given filter. If no operating systems are found, the operation returns null. WsOperatingSystemFilter: The operating system filter to use WsOperatingSystem[]: Array of WsOperatingSystems matching the given filter 48

Web service guide 7.42 listsoftware(wssoftwarefilter, boolean) This operation returns an array of software packages matching the given filter. If no software packages are found, the operation returns null. WsSoftwareFilter: The software filter to use Boolean: Include content of uploaded packages WsSoftware[]: Array of WsSoftware matching the given filter 7.43 listtaskbundles(wstaskbundlefilter) This operation returns an array of task bundles matching the given filter. If no task bundles are found, the operation returns null. WsTaskBundleFilter: The task bundle filter to use WsTaskbundle[]: Array of WsTaskBundles matching the given filter 49 49

Sophos Mobile Control 7.44 listtransitions(wstransitionfilter) This operation returns an array of transition matching the given filter. If no transitions are found, the operation returns null. WsTransitionFilter: The transition filter to use WsTransition[]: Array of WsTransitions matching the given filter 7.45 login(,, ) This operation fulfills the login for the user with the given credentials. : The customer name : The user name : The password Boolean: True, if the credentials are correct, false otheise. 50

Web service guide 7.46 logout() This operation logs out the logged in user. None Boolean: True WebserviceException: Any errors 7.47 removeadminuser(wsadminuser) This operation removes the selected admin user. s true if successful. WsAdminUser: Admin user to remove Boolean: True if removing was successful, false otheise. 7.48 removeandroidprofile(wsandroidprofile) This operation removes the selected android profile. s true if successful. WsAndroidProfile: Android profile to remove Boolean: True, if removing was successful, false otheise. 51 51

Sophos Mobile Control 7.49 removecomplianceset(wscomplianceset) This operation removes the selected compliance set. s true if successful. WsComplianceSet: Compliance set to remove Boolean: True, if removing was successful, false otheise. 7.50 removecustomer(wscustomer) This operation removes the selected customer. This operation is only possible, if all devices of the customer are deleted before. s true if successful. WsCustomer: The customer to remove Boolean: True, if removing was successful, false otheise. InsufficientRightsException: If the web service client has no rights to access this operation (especially in case the logged in user is not a super administrator user). 52

Web service guide 7.51 removedevice(wsdevice) This operation removes the selected device. s true if successful. WsDevice: The device to remove Boolean: True, if removing was successful, false otheise. 7.52 removedevicegroup(wsdevicegroup) This operation removes the selected device group. s true if successful. WsDeviceGroup: The device group to remove Boolean: True, if removing was successful, false otheise. 53 53

Sophos Mobile Control 7.53 removeinternalsspuser(wsinternalsspuser) This operation removes the selected internal SSP user. s true if successful. WsInternalSSPUser: The internal SSP user to remove Boolean: True, if removing was successful, false otheise. 7.54 removeiosprofile(wsiosprofile) This operation removes the selected ios profile. s true if successful. WsIOSProfile: ios profile to remove Boolean: True, if removing was successful, false otheise. 54

Web service guide 7.55 removesoftware(wssoftware) This operation removes the selected software package. s true if successful. WsSoftware: Software to remove Boolean: True, if removing was successful, false otheise. 7.56 removetaskbundle(wstaskbundle) This operation removes the selected task bundle. s true if successful. WsTaskBundle: Task bundle to remove Boolean: True, if removing was successful, false otheise 55 55

Sophos Mobile Control 7.57 removetransition(wstransition) This operation removes the selected transition. s true if successful. WsTransition: The transition to remove Boolean: True, if removing was successful, false otheise. 7.58 resetdevicelogindata(wsdevice) This operation resets the login data of the selected device. s true if successful. WsDevice: The device whose login data shall be reset. Boolean: True, if reset login data was successful, false otheise. 56

Web service guide 7.59 saveadminuser(wsadminuser) This operation saves a previously created admin user and returns the ID of the saved admin user, if the operation was successful. WsAdminUser: Admin user to save Integer: The admin user ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 7.60 saveandroidprofile(wsandroidprofile) This operation saves a previously created Android profile and returns the ID of the saved profile, if the operation was successful. WsAndroidProfile: Android profile to save Integer: The Android profile ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 57 57

Sophos Mobile Control 7.61 savecomplianceset(wscomplianceset) This operation saves a previously created compliance set and returns the ID of the saved compliance set, if the operation was successful. WsComplianceSet: Compliance set to save Integer: The compliance set ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 7.62 savecustomer(wscustomer) This operation saves a previously created customer and returns the ID of the saved customer, if the operation was successful. WsCustomer: The customer to save Integer: The customer ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 58

Web service guide 7.63 savedevice(wsdevice) This operation saves a previously created device and returns the ID of the saved device if the operation was successful. WsDevice: the device to save Integer: The device ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 7.64 savecustomerproperty(wscustomerproperty) This operation saves a WsCustomerProperty for the logged in customer. Not all WsCustomerProperties are supported to be modified by this method. The parameters that can be modified are listed. WsCustomerProperty: The customer property to save Boolean: true, if successful, false if not. MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 59 59

Sophos Mobile Control Supported properties email_href.subject email_href.content.anroid email_href.content.ios pwd.new.email.subject pwd.new.email.content pwd.reset.email.subject pwd.reset.email.content APPLE_PUSHSERVER_PKCS12_KEYSTORE APPLE_PUSHSERVER_PKCS12_KEYSTORE_PASSWORD compliance.adminmail.recipients compliance.adminmail.timetable ssp.agreementtext ssp.maxalloweddevices ssp.postinstallmessage 7.65 savedevicegroup(wsdevicegroup) This operation saves a previously created device group and returns the ID of the saved group, if the operation was successful. WsDeviceGroup: The device group to save Integer: The device group ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 60

Web service guide 7.66 saveinternalsspuser(wsinternalsspuser) This operation saves a previously created internal SSP user and returns the distinguished name (DN) of the saved internal SSP user, if the operation was successful. WsInternalSSPUser: Internal SSP user to save : The internal SSP user distinguished name (DN) MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 7.67 saveiosprofile(wsiosprofile) This operation saves a previously created ios profile and returns the ID of the saved profile if the operation was successful. WsIOSProfile: ios profile to save Integer: The ios profile ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 61 61

Sophos Mobile Control 7.68 savesoftware(wssoftware) This operation saves a previously created software package and returns the ID of the saved software package, if the operation was successful. WsSoftware: The software to save Integer: The software ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 7.69 savetaskbundle(wstaskbundle) This operation saves a previously created task bundle and returns the ID of the saved task bundle, if the operation was successful. WsTastBundle: The task bundle to save Integer: the task bundle ID MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 62

Web service guide 7.70 setcustomertointernalldapconfig(wscustomer) This operation allows the creation of an internal LDAP entry for the customer on the server. The customer s properties are modified to use the internal LDAP configuration. This operation should only be used when the customer currently has no LDAP configuration (internal or external). After configuring it, the customer may use the LDAP directory for managing internal SSP users. WsCustomer: The customer to configure internal LDAP WsCustomer: The modified customer with internal LDAP (not yet saved) InsufficientRightsException: If the web service client has no rights to access this operation (especially in case the logged in user is not a super administrator user). 7.71 unlinkdevicefromuser(wsdevice) This operation removes the link of the selected device to an internal SSP user. s true, if successful. WsDevice: Device to unlink from user Boolean: True if unlink was successful, false otheise MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 63 63

Sophos Mobile Control 7.72 updateinternalsspuserpassword(wsinternalsspuser,, boolean) This operation adds/updates the password of the internal SSP user. Has the possibility to require password change after login. WsInternalSSPUSer: internal SSP user to update : New password for internal SSP user Boolean: True = user have to change password after login. Boolean: True, if update password was successful, false otheise. throws MandatoryValueMissingException: One of the required fields is not set. ValueOutOfRangeException: Value of required field is out of range. 64

Web service guide 8 Appendix Note: In the following examples, the acronym MTA may occur. MTA stands for Multi Tenant Admin and can be used as a synonym for super administrator. 8.1 Example: how to create, save and remove a device The following snippet shows a simplified Java example on how to create, save and remove a device. Exception and error handling is not included for brevity. /** * Shows how to create a new device using a device template and * how to save and remove it. */ public void createandremovedevice() { try { //try to login if (!proxy.login(logincustomer, loginusername, loginpassword)) { //wrong credentials, your error handling here return; } //create new device: get all Android device templates WsOperatingSystemFilter osfilter = new WsOperatingSystemFilter(); osfilter.setplatform(wsoperatingsystemplatform.android); WsOperatingSystem[] oss = proxy.listoperatingsystems(osfilter); WsDeviceTemplateFilter templatefilter = new WsDeviceTemplateFilter(); templatefilter.setoperatingsystems(oss); WsDeviceTemplate[] templates = proxy.listdevicetemplates(templatefilter); //create new device: get all device groups WsDeviceGroup[] groups = proxy.listdevicegroups(new WsDeviceGroupFilter()); //create new device: create new device object from any template WsDevice device = proxy.createdevicefromtemplate(templates[0]); //create new device: set mandatory device properties device.setname("webservice test"); device.setdescription("description"); device.setphonenumber("+441701234567"); device.setemailaddress("test@domain.com"); device.setgroup(groups[0]); //create new device: save device and keep device's id Integer createddeviceid = proxy.savedevice(device); //important: request device using the id WsDeviceFilter devicefilter = new WsDeviceFilter(); devicefilter.setid(createddeviceid); //should be exactly one WsDevice[] devices = proxy.listdevices(devicefilter); device = devices[0]; 65 65

Sophos Mobile Control } //clean up: remove device proxy.removedevice(device); //logout proxy.logout(); } catch (Exception e) { //your exception handling here e.printstacktrace(); } 66

Web service guide 8.2 Example: how to create and remove a transition The following snippet shows a simplified Java example on how to create and remove a lock transition. Exception and error handling is not included for brevity. /** * Shows how to create a device lock task for a device and how to watch * the created task's status. */ public void createandremovetask() { try { //try to login if (!proxy.login(logincustomer, loginusername, loginpassword)) { //wrong credentials, your error handling here return; } //get all ios operating systems WsOperatingSystemFilter osfilter = new WsOperatingSystemFilter(); osfilter.setplatform(wsoperatingsystemplatform.iphone); WsOperatingSystem[] oss = proxy.listoperatingsystems(osfilter); //get some ios device, this example assumes the device is already //managed/bootstrapped WsDeviceFilter devicefilter = new WsDeviceFilter(); devicefilter.setoperatingsystems(oss); WsDevice[] devices = proxy.listdevices(devicefilter); //create device lock task with lock code "1234" Integer createdid = proxy.createdevicelocktransition(devices[0], "1234"); //get transition (=task) for further use WsTransitionFilter transitionfilter = new WsTransitionFilter(); transitionfilter.setid(createdid); //should be exactly one WsTransition[] transitions = proxy.listtransitions(transitionfilter); //you would usually wait for the transition (=task) to be finished or //list it's status somewhere //check if task is in a final state (successful or failed) boolean isfinal = proxy.istransitionfinal(transitions[0]); if (isfinal) { transitions = proxy.listtransitions(transitionfilter); //check the status of the transition Integer status = transitions[0].getstatus(); } //clean up: remove transition proxy.removetransition(transitions[0]); } //logout proxy.logout(); 67 67

Sophos Mobile Control catch (Exception e) { //your exception handling here e.printstacktrace(); } } 8.3 Example: how to create and save customers The following snippet shows a simplified Java example on how to create a new customer using the most common options. Extensive exception and error handling is not included for brevity. /** * Shows how to create a customer. */ public void testsetupcustomer() throws Exception { boolean loginresult = proxy.login(customermta, usernamemta, passwordmta); WsCustomer customer = proxy.createcustomer( "customer name", //login name "extid", //external Id (for SMSDC) "tech contact last name", //technical contact data "tech contact first", "tech@customer.com"); WsCustomerProperty[] props = new WsCustomerProperty[]{ //maximum number of devices new WsCustomerProperty("general.maxDevices", "50"), //account expiry date (in milliseconds since 1970-01-01) new WsCustomerProperty("general.validUntil", "1339106399000"), //localization of devices (1=allowed, 0=not allowed) new WsCustomerProperty("general.locate", "1"), new WsCustomerProperty("general.allowAdminLocate", "1"), //available platforms (1=available, 0=unavailable) new WsCustomerProperty("PLATFORM_ANDROID_ENABLED", "1"), new WsCustomerProperty("PLATFORM_BLACKBERRY_ENABLED", "0"), new WsCustomerProperty("PLATFORM_IOS_ENABLED", "1"), new WsCustomerProperty("PLATFORM_SYMBIAN_ENABLED", "0"), new WsCustomerProperty("PLATFORM_WINDOWSMOBILE_ENABLED", "1"), //available modules (1=available, 0=unavailable) new WsCustomerProperty("SMARTCONTROL", "0"), new WsCustomerProperty("PHONEBOOK", "0"), new WsCustomerProperty("FILE_EXPORT_DEVICES", "0"), new WsCustomerProperty("PUBLICATIONS", "0"), new WsCustomerProperty("EAS_PROXY", "0"), new WsCustomerProperty("BACKUP_AND_RESTORE", "0") }; customer.setproperties(props); //Save the customer Integer createdid = proxy.savecustomer(customer); asserttrue(createdid!= null); //Query the customer by ID WsCustomerFilter filter = new WsCustomerFilter(); filter.setid(createdid); WsCustomer[] createdcust = proxy.listcustomers(filter); //Clone settings and device groups, assign all MTA packages 68

Web service guide proxy.clonemtasettingsandassignrcsmos(createdcust[0]); //Query the customer by ID WsCustomer[] updatedcust = proxy.listcustomers(filter); //Configure customer to use internal ldap for SSP users customer = proxy.setcustomertointernalldapconfig(updatedcust[0]); //Save the customer proxy.savecustomer(customer); } //Logout proxy.logout(); 69 69

Sophos Mobile Control 8.4 Example: how to disable customers The following snippet shows a simplified Java example on how to disable (or lock ) an existing customer. Extensive exception and error handling is not included for brevity. Disabled customers do not allow any users to login. Devices, however, may still synchronize with the server. Disabling a customer should be seen as a temporary action. Customers which are no longer used should be deleted instead. /** * Shows how to disable or enable customers by modifying their properties. */ public void testdisablecustomer() throws Exception { boolean loginresult = proxy.login(customermta, usernamemta, passwordmta); //Query the customer by ID WsCustomerFilter filter = new WsCustomerFilter(); filter.setid(customerid); WsCustomer[] customers = proxy.listcustomers(filter); //Disable customer, check if property already exists, otheise create it WsCustomerProperty disabledprop = null; WsCustomerProperty[] oldprops = createdcust[0].getproperties(); for (WsCustomerProperty prop : oldprops) { if (prop.getpropertykey().equals("general.disabled")) { disabledprop = prop; disabledprop.setvalue("1"); } } if (disabledprop == null) { WsCustomerProperty[] newprops = new WsCustomerProperty[oldProps.length+1]; System.arraycopy(oldProps, 0, newprops, 0, oldprops.length); newprops[newprops.length-1] = new WsCustomerProperty("general.disabled", "1"); createdcust[0].setproperties(newprops); } //Save customer proxy.savecustomer(createdcust[0]); } //Logout proxy.logout(); 70

Web service guide 9 Technical support You can find technical support for Sophos products in any of these ways: Visit the SophosTalk forum at http://community.sophos.com/ and search for other users who are experiencing the same problem. Visit the Sophos support knowledgebase at http://www.sophos.com/en-us/support.aspx. Download the product documentation at http://www.sophos.com/en-us/support/documentation.aspx. Send an email to support@sophos.com, including your Sophos software version number(s), operating system(s) and patch level(s), and the text of any error messages. 71 71

Sophos Mobile Control 10 Legal notices Copyright 2011-2013 Sophos Ltd. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otheise unless you are either a valid licensee where the documentation can be reproduced in accordance with the license terms or you otheise have the prior permission in writing of the copyright owner. Sophos is a registered trademark of Sophos Ltd. All other product and company names mentioned are trademarks or registered trademarks of their respective owners. 72