MDM Server Web Services Reference Guide (Internal)

Transcription

1 D Server Web Services Reference Guide (Internal) Version 2.1

2 obile Device anager 2.1 obile Device Sync anager 1.2 obile Consumer Device anagement Template 1.2 obile Device Backup & Restore Template 1.1 obile Device Remote Control Template 1.2 Dual ode Phone anagement Template 1.1 February 2010 Copyright Alcatel-Lucent [ All rights reserved. Important Notice to Users No part of this document may be reproduced or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the express permission of otive, Inc. ( otive ) and/or Alcatel-Lucent. This document and the related software may only be used pursuant to a Software License Agreement or other similar written agreement in place between you and either otive or Alcatel-Lucent. Furthermore, otive and Alcatel-Lucent expressly disclaim any and all warranties regarding the information contained in, and the products and systems described in, this document, whether express, implied, or statutory, including without limitation implied warranties of merchantability or fitness for a particular purpose. Furthermore, this document is subject to change without notice. There may exist in this document references to using this product and the systems described herein in connection with products and/or systems owned by third parties. Please note that this information is provided as a courtesy to assist you. Such references are not intended to imply the granting of a license to use such products and/or systems. Such licenses shall result only from separately executed agreements between you and the owner of such products and/or systems. Neither otive nor Alcatel-Lucent assume any responsibility or liability for incorrect or incomplete information provided about such third-party products. otive, the otive logo, and any otive product names contained herein are trademarks or registered trademarks of otive, Inc. Alcatel-Lucent and the Alcatel-Lucent logo are registered trademarks of Alcatel-Lucent. All other company and product names mentioned herein are the trademarks or service marks of their respective owners. The products and systems described herein may be covered by the various patents that have been issued to otive and/or Alcatel-Lucent. Disclaimers This product is intended for commercial uses. Without the prior written consent of either otive or Alcatel-Lucent it must not be used, sold, licensed or otherwise distributed for use in any hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life-support machines, or weapons systems, in which the failure of products could lead directly to death, personal injury, or severe physical or environmental damage. You hereby agree that the use, sale, license or other distribution of the products for any such application without the prior written consent of either otive or Alcatel-Lucent, shall be entirely at your sole risk. You hereby agree to defend and hold otive and Alcatel-Lucent harmless from any claims for loss, cost, damage, expense or liability that may arise out of or in connection with the use, sale, license or other distribution of the products in such applications. This document was originally written in English. If there is any conflict or inconsistency between the English version and any other version of a document, the English version shall prevail. OB100-Dwebservices

3 Contents Preface... xi Audience... xi Conventions... xi Support and contact information... xii 1 Overview of obile Device anager Web Services... 1 Overview of the OAP Web Service as an Example... 2 Namespaces... 2 What is WSDL?... 3 Anatomy of the WSDL Document... 4 Definitions... 4 Types... 4 essages... 5 Operations... 6 Binding... 7 Service Using obile Device anager Web Services... 9 Using the OAP Web Service anaging Subscribers and Devices Getting Device Information Using the Device anagement Web Service Assigning Profiles Comparing and Changing Profile Assignments Updating Device Firmware Creating a Discovery Job Creating a Command Script Job Creating a Workflow Job Grouping & Criteria Template anagement Import Criteria Template iii

4 Update criteria template Delete criteria template Export criteria template Fetch existing criteria templates Create criteria group Update criteria group Delete criteria group Fetch existing criteria group Evaluate Using the Device Synchronization Web Service Synchronization Services Administration Service Activity Log Service Using the yphone Portal Web Service Getting Device Information Assigning Profiles Changing Profile Assignments Updating Device Firmware Using the Enterprise Portal Web Service Getting Device Information Assigning Profiles Changing Profile Assignments Updating Device Firmware Using the OE Portal Web Service Operations Reference OAP Web Service Operations activatedevice deactivatesubscriber deletesubscriber detectsubscriber finddevice getdeviceloginfo reactivatesubscriber rebootstrapsubscriber Device anagement Web Service Operations assignimagetodevice assignprofilestodevice iv

5 compareprofileassignments createcommandscriptjobfordevice creatediscoveryjobfordevice createworkflowjob editprofileassignments getavailableprofilesfordevice getavailableworkflowjobnames getcompatibleimagesfordevice getdevicetree getjobstatusfordeviceresponse getprofileassignments getupdatepathsfordeviceandimage resendprofileassignments Bulk Device anagement Assign Profile to Devices from a Group Assign Cron Profile to Devices from a Group Assign Profile to Devices from Devices Assign Cron Profile to Devices from Devices Invoke ProfileGet For Devices From Group Invoke Cron ProfileGet For Devices From Group Invoke Cron ProfileGet For Devices From Devices Invoke Firmware Update on Devices from Group Invoke Firmware Update on Devices from Devices Invoke Cron Firmware Update on Devices from Devices Get DeviceJob Summary by BDJobId Grouping & Criteria Template anagement Import Criteria Template Update criteria template Delete criteria template Export criteria template Fetch existing criteria templates Create criteria group Update criteria group Delete criteria group Fetch existing criteria group Evaluate Evaluate Evaluate v

6 Evaluate y Phone Portal Web Service Operations assignprofiles getavailabledevicefirmwareupdatepaths getavailabledevicefirmwareupdates getavailableprofiles getprofileassignments myphonequery updatedevicefirmware updateprofileassignments Enterprise Portal Web Service Operations assignprofiles getavailabledevicefirmwareupdatepaths getavailablefirmwareupdates getavailableprofiles getenterpriseportalphonesquery getprofileassignments updatefirmware updateprofileassignments OE Portal Web Service Operations extractwarrantyinformation getanufacturers getpublishedupdatepackages publishupdatepackages Complex Type Reference Complex Types AccessibleImageSummaryResponse ActivateDeviceRequest ActivateDeviceResponse AssignImageToDeviceRequest AssignProfileDetail AssignProfilesRequest AssignProfilesResponse AssignProfilesToDeviceRequest AttributeDetail AvailableDeviceFirmwareUpdate AvailableDeviceFirmwareUpdatePathRequest vi

7 AvailableDeviceFirmwareUpdatePathResponse AvailableDeviceFirmwareUpdateResponse AvailableProfileDevice AvailableProfilesResponse BaseSubscriberResponse CompareProfileAssignmentsResponse CPSignature CreateCommandScriptJobRequest CreateOADeviceRequest CreateSubscriberRequest CreateSubscriberResponse CreateWorkflowJobRequest DeviceJobStatusResponse DeviceLogEntryRequest DeviceLogEntryResponse DeviceLogEntryResult DeviceLogSearchCriteriaRequest DeviceTreeNodeDetails DiscoveryJobRequest EditProfileAssignmentsResponse EnterprisePortalAssignProfilesRequest EnterprisePortalAssignProfilesResponse EnterprisePortalAvailableDeviceFirmwareUpdatePathResponse EnterprisePortalAvailableDeviceFirmwareUpdateResponse EnterprisePortalAvailableProfilesResponse EnterprisePortalPhoneQueryResponse EnterprisePortalProfileAssignmentsResponse EnterprisePortalResponse EnterprisePortalUpdateFirmwareResponse EnterprisePortalUpdateProfileAssignmentsResponse ExtractWarrantyInformationResponse FindDeviceRequest FindDeviceResponse Firmware GetAvailableProfilesForDeviceResponse GetAvailableWorkflowJobNamesResponse GetCompatibleImagesForDeviceResponse GetDeviceTreeResponse vii

8 viii GetanufacturersResponse GetPublishedUpdatePackagesResponse GetUpdatePathsForDeviceAndImageResponse ImageSummaryResponse JobCreationResponse anufacturerwsimpl odelwsimpl OAConfiguration PhoneQueryDevice PhoneQueryResponse ProfileAssignment ProfileAssignmentsDevice ProfileAssignmentsResponse ProfileAssignmentChangeRequest ProfileAssignmentComparison ProfileAttribute ProfileAttributeDifference ProfileDetail ProvisioningRequest ProvisioningRequestOptionsRequest PublishedUpdatePackage PublishUpdatePackagesRequest PublishUpdatePackagesResponse RebootstrapSubscriberRequest RebootstrapSubscriberResponse ResendProfileAssignmentsRequest SortByCriteria UpdateFirmwareRequest UpdateFirmwareResponse UpdatePackage UpdatePackageDetails UpdatePath UpdatePathSummaryResponse UpdateProfileAssignmentsRequest UpdateProfileAssignmentsResponse UpdateSummaryResponse WarrantyInformation

9 5 Status Code Reference Status Codes WSDL Reference OAP WSDL Device anagement WSDL y Phone Portal WSDL Enterprise Portal WSDL OE Portal WSDL BD WSDL Glossary Index ix

10 x

11 Preface otive obile Device anager allows service providers to remotely provision, update, and manage mobile devices and services throughout the device life cycle. The product provides for single and bulk device provisioning, configuration and management, problem resolution, firmware upgrades, event management, and reporting. D Server uses the standards-based OA D protocol to communicate with the native D client installed on mobile devices. Audience The D Server Web Services Reference Guide (Internal), an internal resource, is intended for developers who develop or customize existing data sources for a D Server. In obile Service anagement Solution deployments, customer-specific models depend on the D data sources to query the D Server. The data sources contain the methods required to remotely invoke the D Server web services using SOAP over HTTP. In return, the web services return client responses in XL format. Conventions This document uses the following typographic conventions: Bold Identifies the names of graphical user interface buttons, options, commands, fields, and labels. Italic Identifies variable placeholders such as function or method parameters representing information that must be provided by the implementation or user. Also identifies documentation titles and certain terms to emphasize meaning. onospace Identifies information that you are required to type exactly as shown. This convention also identifies code and command samples, screen prompts, messages, and filenames. onospace italic Identifies parameters whose actual names or values you must provide at a screen prompt or in a text field. UPPERCASE Identifies the names of keys on the keyboard. In multi-line code listings, the symbol indicates that the text was wrapped for typographical reasons. Audience xi

12 Support and contact information If you encounter issues with this product, visit the Online Customer Support (OLCS) [ website. After registering and logging on, you can access troubleshooting information. In addition, you can contact Alcatel-Lucent otive Support by phone, fax, or , as follows: Toll-free phone (within U.S.) Outside U.S. Fax , option (United States) <support@motive.com> The otive Product Group and its parent company, Alcatel-Lucent, are interested in feedback about your experience with this product and its documentation. If you have comments or suggestions, send to <pubs@motive.com>. xii Preface

13 This chapter covers: 1 Overview of obile Device anager Web Services Overview of the OAP Web Service as an Example Namespaces What is WSDL? Anatomy of the WSDL Document 1

14 Web Services are web-based applications that dynamically interact with other Web applications. The obile Device anager web services are invoked remotely using SOAP or HTTP-GET/POST protocols and return an "answer" to the client in XL format. The web services can be consumed on any operating system just as long as that operating system supports the SOAP protocol and XL. As an example, this overview chapter examines the structure of the otive OAP WSDL document and describes the WSDL that defines the OAP web service. The obile Device anager license includes the basic OAP web service to manage subscribers and get some device information. The use of all other obile Device anager web services requires the Web Service Premium license. The remainder of the guide provides a summary of how to use the obile Device anager s web services and reference sections on web service operations, complex types, status codes, and the complete WDSLs. Chapter 2, Using obile Device anager Web Services on page 9 Chapter 3, Operations Reference on page 25 Chapter 4, Complex Type Reference on page 87 Chapter 5, Status Code Reference on page 117 Chapter 6, WSDL Reference on page 127 Overview of the OAP Web Service as an Example The otive OAP Adapter Web Service is an Extensible arkup Language (XL) Web service with a SOAP API. This allows you to programmatically find devices and their compatible updates, as well as create, deactivate, activate, and delete subscribers. The OAP Service is a licensed Web Service that allows a licensed site to populate and communicate with an otive D Server. The OAP Service has been created to meet real-world requirements for integrating with carrier provider s billing and/or CR systems used to manage subscriber and device operations. This service can be accessed using standard Simple Object Access Protocol (SOAP) requests over HTTP. Namespaces The root element of every WSDL file is <definitions>, which includes a complete description of services and the namespaces used by the service. Namespaces provide contexts for identifiers; two items can share the same identifier so long as they have different namespaces. For the OAP Web Service, the following namespaces are declared. 2 Overview of obile Device anager Web Services

15 OAP Namespaces Namespace targetnamespace tns1 tns2 tns3 tns4 tns5 apachesoap impl intf wsdl wsdlsoap xsd Address Refer to for more details on namespaces in WDSL. What is WSDL? To invoke an otive web service, the client must know several things such as the public interfaces of the web service applications and the data type of the objects required as parameters. WSDL (Web Services Language) is an XL grammar for describing network services as collections of communication endpoints capable of exchanging messages. The WSDL document describes how to invoke a service and provides information on the data being exchanged, the sequence of messages for an operation, protocol bindings, and the location of the service. A WSDL document defines services as a collection of endpoints, but separates the abstract definition from the concrete implementation. essages and port types provide abstract definitions for the data being exchanged and the operations being performed by a service. A binding is provided to map to a concrete set of ports, usually consisting of a URL location and a SOAP binding. In the next section, we will examine the various components that make up a WSDL, using the OAP WSDL as an example. What is WSDL? 3

16 Anatomy of the WSDL Document For understanding the WSDL document, we will use the OAP WDSL as our sample. Excerpts of the OAP WSDL are shown throughout the following discussions. See the Chapter 6, WSDL Reference on page 127 section to see complete copies of the WSDLs for the otive Web Services. The elements of the WDSL document are as follows: Definitions on page 4 Types on page 4 essages on page 5 Operations on page 6 Binding on page 7 Service on page 7 The following sections describe these elements of the WSDL document in greater detail. Definitions The document starts with the <definitions> element. This root element contains the name of the service and namespace definitions. It contains the default WDSL namespace as: xmlns=" Apart from the various namespaces, the <definitions> element also contains an optional attribute called targetnamespace, which defines the namespace for all WSDL items defined in this document such as messages, operations, and porttypes. targetnamespace=" Types The <types> element describes all the data types used between the client and server. WSDL uses the W3C XL Schema specification (XSD) as its typing system. If the service uses only XL Schema built-in simple types, such as strings and integers, the <types> element is not required. However, in the OAP WDSL, there are complex types (complextype) defined that have two different kinds of definitions: 4 Overview of obile Device anager Web Services

17 types, with associated parameters (elements), and, <complexcontent> types, that are extendable or restrictive. This type is often used for array type definitions. In the following example snippet, defined types are highlighted in bold letters. <types> <wsdl:types> <schema targetnamespace=" xmlns=" <import namespace=" <import namespace=" <import namespace=" <import namespace=" <import namespace=" <import namespace=" <complextype name="createsubscriberrequest"> <element name="externaltenantid" nillable="true" type="xsd:string"/> <element name="imsi" nillable="true" type="xsd:string"/> <element name="phonenumber" nillable="true" type="xsd:string"/> <element name="pin" nillable="true" type="xsd:string"/> <complextype name="oaconfiguration"> <element name="clientpassword" nillable="true" type="xsd:string"/> <element name="clientusername" nillable="true" type="xsd:string"/> <element name="deviceexternalid" nillable="true" type="xsd:string"/> <element name="dmenabled" type="xsd:boolean"/> <element name="manufacturername" nillable="true" type="xsd:string"/> <element name="modelname" nillable="true" type="xsd:string"/> <element name="serverid" nillable="true" type="xsd:string"/> <element name="serverpassword" nillable="true" type="xsd:string"/> [snip...] essages The <message> element describes a one-way message, whether it is a single message request or a single message response. It defines the name of the message and contains zero or more message part elements, which can refer to message parameters or message return values. In the following example snippet, all defined messages are highlighted in bold letters. <wsdl:message name="rebootstrapsubscriberresponse"> <wsdl:part name="rebootstrapsubscriberreturn" type="tns3:rebootstrapsubscriberresponse"/> <wsdl:message name="detectsubscriberrequest"> <wsdl:part name="subscriberrequest" type="tns1:createsubscriberrequest"/> <wsdl:part name="createoadevicerequest" type="tns2:createoadevicerequest"/> <wsdl:message name="activatedeviceresponse"> <wsdl:part name="activatedevicereturn" type="tns3:activatedeviceresponse"/> essages 5

18 [snip...] In our example, the SOAP toolkit has generated names of these message elements that are similar to the associated complextype or operation, but this is not a standard way of naming these methods. You can name them anyway you desire. Each of these messages contains a <part> element(s). The <part> element names must be the same as the method's parameter names. A defined namespace is also defined: usually either the WSDL standard namespace of the otive OAP adapter values namespace. The value of the type attribute must be specified as an XL Schema QName--this means that the value of the attribute must be namespace-qualified. For example, the string type attribute references the namespace for XL Schema, defined earlier within the definitions element: xmlns:partns=" Another example: the finddeviceresponse message specifies a type of FindDeviceResponse, which references the otive OAP adapter values namespace, also defined within the definitions element: xmlns:partns="java:com.insignia.oampadapter.values" Note From icrosoft Documentation, A qualified name (QName) is composed of a prefix and a local part. The prefix provides the namespace prefix part of the qualified name, and must be associated with a namespace Uniform Resource Identifier (URI). Operations In the OAP example, the operation element contains two messages: an input message and an output message, as well as a resulting fault value. Again, the message attribute must be specified as an XL Schema QName. This means that the value of the attribute must be namespace-qualified. For example, in the first operation shown, getdeviceloginfo, the input element specifies a message attribute of tns:getdeviceloginfo; the tns prefix references the targetnamespace defined earlier within the definitions element. There can be zero, one or more than one <porttype> elements in a WSDL document; the OAP WSDL has one: oampport. <porttype> elements can also be placed in a separate file which can then be imported in the WSDL document. In the following example, all defined operations are highlighted in bold letters. <wsdl:porttype name="oampport"> <wsdl:operation name="detectsubscriber" parameterorder="subscriberrequest createoadevicerequest"> <wsdl:input message="impl:detectsubscriberrequest" name="detectsubscriberrequest"/> <wsdl:output message="impl:detectsubscriberresponse" name="detectsubscriberresponse"/> <wsdl:operation name="activatedevice" parameterorder="activatedevicerequest"> <wsdl:input message="impl:activatedevicerequest" name="activatedevicerequest"/> <wsdl:output message="impl:activatedeviceresponse" name="activatedeviceresponse"/> [snip...] 6 Overview of obile Device anager Web Services

19 Binding The <binding> element actually associates the operations defined in the <porttype> element to a particular protocol. The bindings can be made available using HTTP GET, HTTP POST or SOAP. A nested <soap:binding> element indicates that the binding will be made available via SOAP. The style attribute indicates the overall style of the SOAP message format. A value of rpc specifies an RPC format. The transport attribute indicates the transport of the SOAP messages. For example, for SOAP HTTP transport, the value is: For each operation that the Web service exposes, there is a soapaction HTTP header. As per SOAP 1.1, soapaction is used to identify the intent of the message. It suggests that the server can use this attribute to route the message without having to parse the whole message. The <operation> element can contain <input>, <output> and <fault> elements which all correspond to the same elements in the <porttypes> element. Inside these elements is the <soap:body> element which specifies what gets into the <body> of the resulting SOAP message. The body element has three attributes: use - this attribute determines whether the data is encoded or literal. encodingstyle - this attribute determines the type of encoding if the data is encoded, as in our case. For SOAP encoding, the encodingstyle has the URI value of: (If the value of use was set to literal, then that means the resulting SOAP message contains the data formatted as specified in the definitions (Types, essages, and porttypes sections). namespace - this attribute is defined to prevent name clashing. Service The last element within the WSDL document is the <service> element. The WSDL generator asks the name of the service element when creating WSDL. A service element contains the <port> element. The <port> element associates a location with a <binding> in a one to one fashion. In the OAP example, the port refers to the binding called oampportsoapbinding and contains a <soap:address> element that tells the client where the SOAP end point is located. For example: <soap:address location= where machine name defines where the OAP Web service is deployed. There can be more than one <service> elements in a WSDL element. The advantages of having multiple <service> elements are that, you can group the elements according to the underlying protocol (e.g. HTTP, STP etc.) or you can group ports according to the URL destination. Each <service> element can contain more than one <port> elements. Binding 7

20 Following is the defined <service> element within for the OAP example: <service name="oampportservice"> <wsdl:port binding="impl:oampport" name="oampws"> <wsdlsoap:address location=" </wsdl:port> </wsdl:service> 8 Overview of obile Device anager Web Services

21 This chapter covers: 2 Using obile Device anager Web Services Using the OAP Web Service Using the Device anagement Web Service Grouping & Criteria Template anagement Using the Device Synchronization Web Service Using the yphone Portal Web Service Using the Enterprise Portal Web Service Using the OE Portal Web Service 9

22 This chapter provides an overview of the use of various obile Device anager web service operations to carry out common device management tasks. Using the OAP Web Service on page 10 Using the Device anagement Web Service on page 11 Using the yphone Portal Web Service on page 20 Using the Enterprise Portal Web Service on page 22 Using the OE Portal Web Service on page 23 Using the Device Synchronization Web Service on page 16 Using the OAP Web Service The OAP Web Service provides operations to manage the activation and deactivation of subscribers and devices, and also to get device information. anaging Subscribers and Devices Use the following OAP web service operations to manage subscribers and their devices. Note Three conditions must exist to allow management of a device. 1. The subscriber must be activated (in the obile Device anager system). 2. The device must be activated. 3. The device must be the current active device for the subscriber (when the subscriber has multiple devices.) If a device is inactive for a subscriber, use rebootstrapsubscriber to make it the active device for the subscriber. detectsubscriber on page 29 - Creates and activates a subscriber and device depending on whether the subscriber and device previously exist in the D database. Case 1 - Both Subscriber and Device are new (do not yet exist in D database.) Both the subscriber and device will be created and activated. The device will be bootstrapped and will become the active device for the subscriber. (Note: A subscriber may have more than one device, but only one is regarded as active. Only the active device can be managed, e.g. have device management jobs assigned to it.) Case 2 - The Subscriber already exists and the Device is new 10 Using obile Device anager Web Services

23 The device will be created and activated. The device will be bootstrapped and will become the active device for the subscriber. Any other devices belonging to the subscriber will become inactive. Case 3 - The Subscriber is new and Device already exists. The subscriber will be created and activated. The device will be associated with the new subscriber and will become the active device for the subscriber. The device will be bootstrapped if it was not previously bootstrapped. Case 4 - Both Subscriber and Device already exist. The device will be associated with the subscriber and will become the active device for the subscriber. The device will be bootstrapped if it was not previously bootstrapped. activatedevice on page 26 - Activates a device. deactivatesubscriber on page 27 - Deactivates a subscriber. deletesubscriber on page 28 - Deletes a subscriber. The subscriber must be deactivated before being deleted. reactivatesubscriber on page 32 - Reactivates a subscriber that has been deactivated. rebootstrapsubscriber on page 33 - Rebootstraps the subscriber s active device that has previously been bootstrapped. This also makes the device the currently active device for a subscriber with multiple devices. Getting Device Information Use the following operations to obtain information about devices. Several other operations that get information from the system are also available, and will be discussed with their appropriate use in the sections to follow. finddevice on page 31 - Finds a device and provides information such as manufacturer, model, activation state, firmware image ID, etc. getdeviceloginfo on page 31 - Gets activity log information for one or more devices based on specified search criteria. Using the Device anagement Web Service The device management web service provides operations to configure, update, and otherwise manage mobile devices over their entire life cycle. Use of the Device anagement web service requires the Web Service Premium license. The configuration of a device involves assigning profiles to the device. A profile is a collection of settings that are specific to a tenant (or operator). Subscriber specific settings are specified when the profile is assigned to a device. Updating the device s firmware involves finding the available update images and paths given the device s current firmware version, and assigning the new image (or images) to the device. Getting Device Information 11

24 In addition to the Assign Profiles and Firmware Update jobs, the obile Device anager supports discovery, command script, and workflow jobs to provide additional flexibility and automation of device management tasks. Device management jobs are created and queued for execution when assigning profiles, updating firmware, etc., so the job status may be polled to check the progress/status of the job. Assigning Profiles The available profiles for the device (depending on its capabilities) are retrieved from the database (step 1), and specified profiles are then assigned to the device creating a Assign Profile job (step 2). The job is queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress. The job status may be polled until a DONE status is returned (step 3). Use the following sequence of operations to assign profiles to a device. 1. getavailableprofilesfordevice on page 42 - Gets information about the set of profiles that may be assigned to a device, and provides details on each profile and its attribute settings. 2. assignprofilestodevice on page 35 - Provisions service or application attributes (settings) by assigning profiles to a device. An Assign Profile job (for D profiles) or a CP Assign Profile job (for CP profiles) is created for each profile assigned. 3. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Comparing and Changing Profile Assignments The profiles assigned to the device are retrieved from the database (step 1), and specified profiles compared and/or edited (steps 2, 3), and finally resent to update the settings in the device (step4). The job status may be polled until a DONE status is returned (step 5). Use the following operations to compare or edit profile assignments. 1. getprofileassignments on page 70 - Gets information about the set of profiles that are assigned to the devices of a subscriber, and provides details on each profile and its attribute settings. 2. compareprofileassignments on page 37 - Compares expected attribute values (settings) with the last known attribute values stored in the database for each profile specified. 3. editprofileassignments on page 41 - Changes attribute values (settings) for specified profiles that have been assigned to a device. The changes are made in the database only. To change the attribute values on the device, a subsequent resendprofileassignments operation should be invoked. 4. resendprofileassignments on page 48 - Resends specified profile assignments to a device. 5. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. 12 Using obile Device anager Web Services

25 Updating Device Firmware The available target images for the device are retrieved from the database (step 1). Update paths (for multiple step updates) are retrieved using the specified target image (step 2). The image (or multiple images for multistep update paths) are then assigned to the device creating a Firmware Update job (step 3). The job is queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress.the job status may be polled until a DONE status is returned (step 4). Use the following sequence of operations to update the firmware of a device. 1. getcompatibleimagesfordevice on page 43 - Gets information about all available firmware images to which a device may be updated. 2. getupdatepathsfordeviceandimage on page 47 - Gets information about the updates and images that comprise each path available to update a device to the specified firmware image. It also gets the number of devices that currently have the specified firmware image installed. 3. assignimagetodevice on page 34 - Updates a device s firmware. 4. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Creating a Discovery Job The discovery job returns a list of all branch and leaf nodes for a specified management node on a device. Like other device management jobs, the job is created and queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress. The server notifies the device, and when the device connects, the results are collected from the device and stored in the database. The results may be used to submit firmware updates or other jobs to the targeted device. Use the following operations when creating a discovery job. 1. creatediscoveryjobfordevice on page 39 - Creates a Discovery Job to obtain information from a device s device tree. 2. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Creating a Command Script Job The command script job allows a command script (containing multiple device management commands) to be applied to a device. Use the following operations when creating a command script job. 1. createcommandscriptjobfordevice on page 38 - Creates a Command Script Job for a device. Updating Device Firmware 13

26 2. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Creating a Workflow Job The workflow job allows an ICE workflow (containing multiple device management operations and rules that allow branching based on internal and external information) to be applied to a device. Use the following operations when creating a workflow job. 1. getavailableworkflowjobnames on page 42 - Gets the names of all available workflows. Workflows are uploaded to the obile Device anager system using the D Console. 2. createworkflowjob on page 40 - Creates a Workflow Job for a device. 3. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Grouping & Criteria Template anagement Criteria template web service will be provided for the end user to manage criteria templates. Following services are provided by this web service. Import Criteria Template on page 15 Update criteria template on page 15 Delete criteria template on page 15 Export criteria template on page 15 Fetch existing criteria templates on page 15 Create criteria group on page 15 Update criteria group on page 15 Delete criteria group on page 16 Fetch existing criteria group on page 16 Evaluate on page Using obile Device anager Web Services

27 Import Criteria Template Import the criteria template to the database. This template will be used for grouping module to group device. Refer - Import Criteria Template on page 59. Update criteria template Update existing criteria template with the provided updated template. Refer Assign Cron Profile to Devices from a Group on page 50. Delete criteria template Delete existing criteria template from the database. Refer Delete criteria template on page 60 Export criteria template Export the criteria template data from database to xml file. Refer Export criteria template on page 61. Fetch existing criteria templates Retrieve all existing criteria templates from the database. Refer Fetch existing criteria templates on page 61. Create criteria group Define a criteria group that is combination of criteria template and actual parameter values to group devices. This is used by end users to group devices. Refer Create criteria group on page 62. Update criteria group Update existing criteria group. Refer Update criteria group on page 62. Import Criteria Template 15

28 Delete criteria group Delete the criteria group. Refer Delete criteria group on page 63. Fetch existing criteria group Retrieve all existing criteria groups. Refer Fetch existing criteria group on page 63. Evaluate Evaluates the group provided, process it and returns response. This operation has four flavors depending on the input parameters as follows: Evaluate on page 64 Evaluate on page 64 Evaluate on page 65 Evaluate on page 66 Using the Device Synchronization Web Service There are 2 exposed web services : Synchronization Services on page 16 Administration Service on page 18 Activity Log Service on page 19 Synchronization Services The following the APIs exposed within this web service: Initiating Backup on page 17 Initiating Restore on page 17 Create Subscriber on page Using obile Device anager Web Services

29 Getting Available Backups on page 17 Reactivating Device on page 17 Get Backup Contents on page 18 Is Device Activated on page 18 getjobstatus on page 18 gettenants on page 18 Initiating Backup Backup operation sends a message to a device instructing it to synchronize its data with the server. The device data will be backed-up onto the server. Initiating Restore Restore operation restores back the data which was previously backed up. The backup session ID identifies the data set that needs to be restored or synched back to the device. It sends a message to the device to synchronize its data from the backed-up data on the server. Create Subscriber Sends a configuration message to the mobile device about the Sync Server. This API ensures the subscriber data is stored on successful transmission of the bootstrap message. The operation is aborted if the PIN number is not a numeral. Getting Available Backups Available backups are device data that has already been pushed to the Server from the device. A maximum of 5 latest back-ups are available. Reactivating Device Sends a configuration message to the mobile device about the Sync server. Aborts the operation if the PIN number is not a numeral. Synchronization Services 17

30 Get Backup Contents Retrieves the backed up data for the required content type and for the particular session ID. Is Device Activated Just checks if the device details are present in the database, it does not provide information on the Bootstrap and Activation status of the device. getjobstatus Retrieves information of a Job, given its Job ID, from a database. The following are the different Job states SUCCESS, FAILED, INITIATED, IN_PROGRESS, DELETED. gettenants Retrieves a list of tenant details stored in the database. Administration Service The following are the exposed Administration services: Set Server Configuration Settings on page 18 Set Device DBConfig Settings on page 19 Set Tenant on page 19 Get Tenants on page 19 Get Devices on page 19 Delete Device on page 19 Set Server Configuration Settings Sets the configuration data related to Kannel, Number of backups, and Web server. 18 Using obile Device anager Web Services

31 Set Device DBConfig Settings Stores the configuration data related to Device data storage types. Set Tenant Stores the tenant-related data in the database. Get Tenants Retrieves the list of tenants stored in the database Get Devices Returns the list of devices stored in the database Delete Device Removes the details of a device given by the device ID from the Database if the device ID exists. Activity Log Service The following are the exposed Administration Services: Get Activity Log By Range on page 19 Log Activity on page 20 Get Activity Log By Range Returns a list of ActivityLogOutputData from the database based on the start index and the offset. If ostrecentloggedactivityfirst data is true then the list will be sorted so that the start index will contain the most recent activity log within the lot. The offset can be a maximum of 100, even if the number of entries are more than 100, only 100 will be returned. In the event the number of entries are less than the offset number only the actual remaining number of entries will be returned. It throws an if the boundary conditions do not satisfy the start index. Activity Log Service 19

32 Log Activity Logs information on activities in the web UI layer. Note Other activities are logged within the web service component. Using the yphone Portal Web Service y Phone Portal operations provide device management information and functions for a single device, given a subscriber phone number or device ID. Use of the yphone Portal web service requires the Web Service Premium license. The yphone Portal web services may be used in the design of a self-care portal or other customer-facing web site. Getting Device Information Use the following operation to obtain detailed information for all devices belonging to a subscriber. myphonequery on page 71 - Gets information about the devices of a subscriber. Information for each device includes the device ID, device tree, manufacturer, model, current firmware version, and currently assigned profiles. Assigning Profiles The available profiles for the device (depending on its capabilities) are retrieved from the database (step 1), and specified profiles are then assigned to the device creating a Assign Profile job (step 2). The job is queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress. If desired, the job status may be polled using the getjobstatusfordeviceresponse operation of the Device anagement web services until a DONE status is returned (step 3). Use the following sequence of operations to assign profiles to a device. 1. getavailableprofiles on page 70 - Gets information about the set of profiles that may be assigned to the devices for a subscriber, and provides details on each profile and its attribute settings. 2. assignprofiles on page 67 - Provisions service or application attributes (settings) by assigning profiles to a device. An Assign Profile job (for D profiles) or a CP Assign Profile job (for CP profiles) is created for each profile assigned. 3. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. 20 Using obile Device anager Web Services

33 Changing Profile Assignments The profiles assigned to the device are retrieved from the database (step 1), and specified profiles compared and/or edited (steps 2, 3), and finally resent (using the resendprofileassignments operation of the Device anagement web services) to update the settings in the device (step4). If desired, the job status may be polled using the getjobstatusfordeviceresponse operation of the Device anagement web services until a DONE status is returned (step 5). Use the following operations to edit profile assignments. 1. getprofileassignments on page 70 - Gets information about the set of profiles that are assigned to the devices of a subscriber, and provides details on each profile and its attribute settings. 2. updateprofileassignments on page 73 - Updates profile assignments in the database for a device. This operation should be used with the resendprofileassignments operation that sends the profile assignment changes to the device. 3. resendprofileassignments on page 48 - Resends specified profile assignments to a device. 4. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Updating Device Firmware The available target images for the device are retrieved from the database (step 1). Update paths (for multiple step updates) are retrieved using the specified target image (step 2). The image (or multiple images for multistep update paths) are then assigned to the device creating a Firmware Update job (step 3). The job is queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress. If desired, the job status may be polled using the getjobstatusfordeviceresponse operation of the Device anagement web services until a DONE status is returned (step 4). Use the following sequence of operations to update the firmware of a device. 1. getavailabledevicefirmwareupdates on page 69 - Gets information about the available firmware images for the devices of a subscriber. Information for each image includes the image ID, description, version, and upgrade priority. 2. getavailabledevicefirmwareupdatepaths on page 68 - Gets the available update paths (each is a list of Image IDs) that may be used to update the firmware to the specified target image for a device. 3. updatedevicefirmware on page 72 - Updates a device s firmware. 4. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Changing Profile Assignments 21

34 Using the Enterprise Portal Web Service Enterprise Portal operations provide device management information and functions for a set of subscribers or devices. Use of the Enterprise Portal web service requires the Web Service Premium license. The operations may be used in the design of an enterprise self-care portal or simply used to execute bulk configurations or updates on a specified population of devices. Getting Device Information Use the following operation to obtain detailed information for all devices for a set of subscribers. getenterpriseportalphonesquery on page 79 - Gets information about each device of a subscriber for a set of subscribers. Information includes the device ID, device tree, manufacturer, model, current firmware version, and currently assigned profiles. Assigning Profiles The available profiles for the devices (depending on its capabilities) are retrieved from the database (step 1), and specified profiles are then assigned to each device creating a Assign Profile job (step 2). The job is queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress. If desired, the job status may be polled using the getjobstatusfordeviceresponse operation of the Device anagement web services until a DONE status is returned (step 3). Use the following sequence of operations to assign profiles to the devices of a set of subscribers. 1. getavailableprofiles on page 78 - Gets information about the set of profiles that may be assigned to each device of a subscriber for a set of subscribers. Provides details on each profile and its attribute settings. 2. assignprofiles on page 74 - Provisions service or application attributes (settings) by assigning profiles to a set of devices given their device IDs. An Assign Profile job (for D profiles) and/or a CP Assign Profile job (for CP profiles) is created for each device, depending on the set of profiles assigned. 3. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Changing Profile Assignments The profiles assigned to the device are retrieved from the database (step 1), and specified profiles compared and/or edited (steps 2, 3), and finally resent (using the resendprofileassignments operation of the Device anagement web services) to update the settings in the device (step4). If desired, the job status may be polled using the 22 Using obile Device anager Web Services

35 getjobstatusfordeviceresponse operation of the Device anagement web services until a DONE status is returned (step 5). Use the following operations to edit profile assignments for a set of devices. 1. getprofileassignments on page 80 - Gets information about the set of profiles assigned to each device of a subscriber for a set of subscribers. Provides details on each profile and its attribute settings. 2. updateprofileassignments on page 82 - Updates profile assignments in the database for a set of devices. This operation should be used with the resendprofileassignments operation, that sends the profile assignment changes to a device. 3. resendprofileassignments on page 48 - Resends specified profile assignments to a device. 4. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Updating Device Firmware The available target images for the set of devices are retrieved from the database (step 1). Update paths (for multiple step updates) are retrieved using the specified target image (step 2). The image (or multiple images for multistep update paths) are then assigned to the device creating a Firmware Update job (step 3). The job is queued (or scheduled) for execution, and a job ID is returned to allow the tracking of job progress. If desired, the job status may be polled using the getjobstatusfordeviceresponse operation of the Device anagement web services until a DONE status is returned (step 4). Use the following sequence of operations to update the firmware of a set of devices. 1. getavailablefirmwareupdates on page 77 - Gets information about the available firmware images for each device of a subscriber for a set of subscribers. Information for each image includes the image ID, description, version, and upgrade priority. 2. getavailabledevicefirmwareupdatepaths on page 76 - Gets the available update paths (each is a list if Image IDs) that may be used to update the firmware for each of a set of specified devices and target firmware images. 3. updatefirmware on page 81 - Updates a set of devices firmware. 4. getjobstatusfordeviceresponse on page 45 - Gets the job status of a specified job for a device. Using the OE Portal Web Service Update packages are managed using the OE Portal web services. Use of the OE Portal web service requires the Web Service Premium license. Use the following operations to publish update packages and to get other information. Updating Device Firmware 23