MDM Server Web Services
Reference Guide (Internal)
Mobile Device Manager 2.1
Mobile Device Sync Manager 1.2
Mobile Consumer Device Management Template 1.2
Mobile Device Backup & Restore Template 1.1
Mobile Device Remote Control Template 1.2
Dual Mode Phone Management Template 1.1
February 2010
Copyright
©
2007-2010
Alcatel-Lucent
[
http://www.alcatel-lucent.com
]. 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 Motive, Inc. (“Motive”) 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 Motive or Alcatel-Lucent.
Furthermore, Motive 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 Motive nor Alcatel-Lucent assume any responsibility or liability for incorrect or incomplete
information provided about such third-party products.
Motive, the Motive logo, and any Motive product names contained herein are trademarks or registered trademarks of Motive, 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 Motive and/or Alcatel-Lucent.
Disclaimers
This product is intended for commercial uses. Without the prior written consent of either Motive 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 Motive or Alcatel-Lucent, shall be entirely at your sole risk. You
hereby agree to defend and hold Motive 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.
MOB100-MDMwebservices
Preface ... xi
Audience ... xi
Conventions ... xi
Support and contact information ... xii
1
Overview of Mobile Device Manager Web Services ... 1
Overview of the OAMP Web Service as an Example ... 2
Namespaces ... 2
What is WSDL? ... 3
Anatomy of the WSDL Document ... 4
Definitions ... 4
Types ... 4
Messages ... 5
Operations ... 6
Binding ... 7
Service ... 7
2
Using Mobile Device Manager Web Services ... 9
Using the OAMP Web Service ... 10
Managing Subscribers and Devices ... 10
Getting Device Information ... 11
Using the Device Management Web Service ... 11
Assigning Profiles ... 12
Comparing and Changing Profile Assignments ... 12
Updating Device Firmware ... 13
Creating a Discovery Job ... 13
Creating a Command Script Job ... 13
Creating a Workflow Job ... 14
Grouping & Criteria Template Management ... 14
Import Criteria Template ... 15
iii
Contents
Update criteria template ... 15
Delete criteria template ... 15
Export criteria template ... 15
Fetch existing criteria templates ... 15
Create criteria group ... 15
Update criteria group ... 15
Delete criteria group ... 16
Fetch existing criteria group ... 16
Evaluate ... 16
Using the Device Synchronization Web Service ... 16
Synchronization Services ... 16
Administration Service ... 18
Activity Log Service ... 19
Using the MyPhone Portal Web Service ... 20
Getting Device Information ... 20
Assigning Profiles ... 20
Changing Profile Assignments ... 21
Updating Device Firmware ... 21
Using the Enterprise Portal Web Service ... 22
Getting Device Information ... 22
Assigning Profiles ... 22
Changing Profile Assignments ... 22
Updating Device Firmware ... 23
Using the OEM Portal Web Service ... 23
3
Operations Reference ... 25
OAMP Web Service Operations ... 26
activateDevice ... 26
deactivateSubscriber ... 27
deleteSubscriber ... 28
detectSubscriber ... 29
findDevice ... 31
getDeviceLogInfo ... 31
reactivateSubscriber ... 32
rebootstrapSubscriber ... 33
Device Management Web Service Operations ... 34
assignImageToDevice ... 34
assignProfilesToDevice ... 35
iv
compareProfileAssignments ... 37
createCommandScriptJobForDevice ... 38
createDiscoveryJobForDevice ... 39
createWorkflowJob ... 40
editProfileAssignments ... 41
getAvailableProfilesForDevice ... 42
getAvailableWorkflowJobNames ... 42
getCompatibleImagesForDevice ... 43
getDeviceTree ... 44
getJobStatusForDeviceResponse ... 45
getProfileAssignments ... 46
getUpdatePathsForDeviceAndImage ... 47
resendProfileAssignments ... 48
Bulk Device Management ... 49
Assign Profile to Devices from a Group ... 50
Assign Cron Profile to Devices from a Group ... 50
Assign Profile to Devices from Devices ... 51
Assign Cron Profile to Devices from Devices ... 52
Invoke ProfileGet For Devices From Group ... 53
Invoke Cron ProfileGet For Devices From Group ... 54
Invoke Cron ProfileGet For Devices From Devices ... 55
Invoke Firmware Update on Devices from Group ... 56
Invoke Firmware Update on Devices from Devices ... 56
Invoke Cron Firmware Update on Devices from Devices ... 57
Get DeviceJob Summary by BDMJobId ... 58
Grouping & Criteria Template Management ... 58
Import Criteria Template ... 59
Update criteria template ... 60
Delete criteria template ... 60
Export criteria template ... 61
Fetch existing criteria templates ... 61
Create criteria group ... 62
Update criteria group ... 62
Delete criteria group ... 63
Fetch existing criteria group ... 63
Evaluate ... 64
Evaluate ... 64
Evaluate ... 65
v
Evaluate ... 66
My Phone Portal Web Service Operations ... 66
assignProfiles ... 67
getAvailableDeviceFirmwareUpdatePaths ... 68
getAvailableDeviceFirmwareUpdates ... 69
getAvailableProfiles ... 70
getProfileAssignments ... 70
myPhoneQuery ... 71
updateDeviceFirmware ... 72
updateProfileAssignments ... 73
Enterprise Portal Web Service Operations ... 74
assignProfiles ... 74
getAvailableDeviceFirmwareUpdatePaths ... 76
getAvailableFirmwareUpdates ... 77
getAvailableProfiles ... 78
getEnterprisePortalPhonesQuery ... 79
getProfileAssignments ... 80
updateFirmware ... 81
updateProfileAssignments ... 82
OEM Portal Web Service Operations ... 83
extractWarrantyInformation ... 83
getManufacturers ... 84
getPublishedUpdatePackages ... 85
publishUpdatePackages ... 85
4
Complex Type Reference ... 87
Complex Types ... 88
AccessibleImageSummaryResponse ... 88
ActivateDeviceRequest ... 88
ActivateDeviceResponse ... 88
AssignImageToDeviceRequest ... 89
AssignProfileDetail ... 89
AssignProfilesRequest ... 90
AssignProfilesResponse ... 90
AssignProfilesToDeviceRequest ... 90
AttributeDetail ... 90
AvailableDeviceFirmwareUpdate ... 91
AvailableDeviceFirmwareUpdatePathRequest ... 91
vi
AvailableDeviceFirmwareUpdatePathResponse ... 92
AvailableDeviceFirmwareUpdateResponse ... 92
AvailableProfileDevice ... 92
AvailableProfilesResponse ... 93
BaseSubscriberResponse ... 93
CompareProfileAssignmentsResponse ... 94
CPSignature ... 94
CreateCommandScriptJobRequest ... 94
CreateOMADeviceRequest ... 94
CreateSubscriberRequest ... 95
CreateSubscriberResponse ... 95
CreateWorkflowJobRequest ... 96
DeviceJobStatusResponse ... 96
DeviceLogEntryRequest ... 96
DeviceLogEntryResponse ... 97
DeviceLogEntryResult ... 97
DeviceLogSearchCriteriaRequest ... 99
DeviceTreeNodeDetails ... 100
DiscoveryJobRequest ... 101
EditProfileAssignmentsResponse ... 101
EnterprisePortalAssignProfilesRequest ... 101
EnterprisePortalAssignProfilesResponse ... 101
EnterprisePortalAvailableDeviceFirmwareUpdatePathResponse ... 102
EnterprisePortalAvailableDeviceFirmwareUpdateResponse ... 102
EnterprisePortalAvailableProfilesResponse ... 102
EnterprisePortalPhoneQueryResponse ... 102
EnterprisePortalProfileAssignmentsResponse ... 102
EnterprisePortalResponse ... 102
EnterprisePortalUpdateFirmwareResponse ... 103
EnterprisePortalUpdateProfileAssignmentsResponse ... 103
ExtractWarrantyInformationResponse ... 103
FindDeviceRequest ... 103
FindDeviceResponse ... 103
Firmware ... 104
GetAvailableProfilesForDeviceResponse ... 104
GetAvailableWorkflowJobNamesResponse ... 104
GetCompatibleImagesForDeviceResponse ... 104
GetDeviceTreeResponse ... 105
vii
GetManufacturersResponse ... 105
GetPublishedUpdatePackagesResponse ... 105
GetUpdatePathsForDeviceAndImageResponse ... 106
ImageSummaryResponse ... 106
JobCreationResponse ... 106
ManufacturerWSImpl ... 106
ModelWSImpl ... 107
OMAConfiguration ... 107
PhoneQueryDevice ... 107
PhoneQueryResponse ... 108
ProfileAssignment ... 108
ProfileAssignmentsDevice ... 108
ProfileAssignmentsResponse ... 109
ProfileAssignmentChangeRequest ... 109
ProfileAssignmentComparison ... 109
ProfileAttribute ... 109
ProfileAttributeDifference ... 110
ProfileDetail ... 110
ProvisioningRequest ... 110
ProvisioningRequestOptionsRequest ... 111
PublishedUpdatePackage ... 111
PublishUpdatePackagesRequest ... 111
PublishUpdatePackagesResponse ... 112
RebootstrapSubscriberRequest ... 112
RebootstrapSubscriberResponse ... 112
ResendProfileAssignmentsRequest ... 113
SortByCriteria ... 113
UpdateFirmwareRequest ... 113
UpdateFirmwareResponse ... 113
UpdatePackage ... 114
UpdatePackageDetails ... 114
UpdatePath ... 114
UpdatePathSummaryResponse ... 114
UpdateProfileAssignmentsRequest ... 115
UpdateProfileAssignmentsResponse ... 115
UpdateSummaryResponse ... 115
WarrantyInformation ... 116
viii
5
Status Code Reference ... 117
Status Codes ... 118
6
WSDL Reference ... 127
OAMP WSDL ... 128
Device Management WSDL ... 135
My Phone Portal WSDL ... 148
Enterprise Portal WSDL ... 158
OEM Portal WSDL ... 171
BDM WSDL ... 175
Glossary ... 197
Index ... 199
ix
x
Motive Mobile Device Manager
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.
MDM Server
uses the
standards-based
OMA
DM protocol to communicate with the native DM client installed on mobile devices.
Audience
The
MDM Server Web Services Reference Guide (Internal)
, an
internal
resource, is intended for developers who develop
or customize existing data sources for a
MDM Server
. In Mobile Service Management Solution deployments, customer-specific
models
depend on the MDM data sources to query the
MDM Server
. The data sources contain the methods required to
remotely invoke the MDM Server web services using SOAP over HTTP. In return, the web services return client responses
in XML 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.
■
Monospace
—Identifies information that you are required to type exactly as shown. This convention also identifies
code and command samples, screen prompts, messages, and filenames.
■
Monospace 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.
xi
Audience
Preface
Support and contact information
If you encounter issues with this product, visit the
Online Customer Support (OLCS)
[
https://support.alcatel-lucent.com
]
website. After registering and logging on, you can access troubleshooting information.
In addition, you can contact Alcatel-Lucent Motive Support by phone, fax, or email, as follows:
1-866-582-3688, option 1
Toll-free phone (within U.S.)
+1 613 784 6100 (United States)
Outside U.S.
1-512-339-9040
Fax
<[email protected]>
The Motive 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 email to
<[email protected]>
.
Preface
xii
1
This chapter covers:
■
Overview of the OAMP Web Service as an Example
■
Namespaces
■
What is WSDL?
■
Anatomy of the WSDL Document
1
Overview of Mobile Device Manager Web
Services
Web Services are web-based applications that dynamically interact with other Web applications. The Mobile Device Manager
web services are invoked remotely using SOAP or HTTP-GET/POST protocols and return an "answer" to the client in XML
format. The web services can be consumed on any operating system just as long as that operating system supports the
SOAP protocol and XML. As an example, this overview chapter examines the structure of the Motive OAMP WSDL
document and describes the WSDL that defines the OAMP web service.
The Mobile Device Manager license includes the basic OAMP web service to manage subscribers and get some device
information. The use of all other Mobile Device Manager web services requires the Web Service Premium license.
The remainder of the guide provides a summary of how to use the Mobile Device Manager’s web services and reference
sections on web service operations, complex types, status codes, and the complete WDSLs.
■
Chapter 2, “Using Mobile Device Manager 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 OAMP Web Service as an Example
The Motive OAMP Adapter Web Service is an Extensible Markup Language (XML) 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 OAMP Service is a licensed Web Service that allows a licensed site to populate and communicate with an Motive
MDM Server. The OAMP Service has been created to meet real-world requirements for integrating with carrier provider’s
billing and/or CRM 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 OAMP Web Service, the following namespaces are declared.
Overview of Mobile Device Manager Web Services
2
OAMP Namespaces
Address
Namespace
http://www.insignia.com/ssp/oampWS
targetNamespace
http://domain.insignia.com
tns1
http://values.subscriberManagement.insignia.com
tns2
http://values.oampAdapter.insignia.com
tns3
http://values.deviceLog.oampAdapter.insignia.com
tns4
http://util.insignia.com
tns5
http://xml.apache.org/xml-soap
apachesoap
http://www.insignia.com/ssp/oampWS
impl
http://www.insignia.com/ssp/oampWS
intf
http://schemas.xmlsoap.org/wsdl
wsdl
http://schemas.xmlsoap.org/wsdl/soap/
wsdlsoap
http://www.w3.org/2001/XMLSchema
xsd
Refer to
http://www.w3.org/
for more details on namespaces in WDSL.
What is WSDL?
To invoke an Motive 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 Description Language) is an XML 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. Messages 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 OAMP WSDL as an example.
3
What is WSDL?
Anatomy of the WSDL Document
For understanding the WSDL document, we will use the OAMP WDSL as our sample. Excerpts of the OAMP 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 Motive Web Services.
The elements of the WDSL document are as follows:
■
“Definitions” on page 4
■“Types” on page 4
■“Messages” 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="http://schemas.xmlsoap.org/wsdl/"
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="http://www.insignia.com/ssp/oamp"
Types
The
<types>
element describes all the data types used between the client and server. WSDL uses the W3C XML Schema
specification (XSD) as its typing system. If the service uses only XML Schema built-in simple types, such as strings and
integers, the
<types>
element is not required. However, in the OAMP WDSL, there are complex types (complexType)
defined that have two different kinds of definitions:
Overview of Mobile Device Manager Web Services
4
■
<sequence>
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="http://domain.insignia.com" xmlns="http://www.w3.org/2001/XMLSchema"> <import namespace="http://www.insignia.com/ssp/oampWS"/> <import namespace="http://values.subscriberManagement.insignia.com"/> <import namespace="http://values.oampAdapter.insignia.com"/> <import namespace="http://values.deviceLog.oampAdapter.insignia.com"/> <import namespace="http://util.insignia.com"/> <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/> <complexType name="CreateSubscriberRequest"> <sequence>
<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"/>
</sequence> </complexType>
<complexType name="OMAConfiguration"> <sequence>
<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"/> </sequence>
</complexType>
[snip...]
Messages
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>
<wsdl:message name="detectSubscriberRequest">
<wsdl:part name="subscriberRequest" type="tns1:CreateSubscriberRequest"/> <wsdl:part name="createOMADeviceRequest" type="tns2:CreateOMADeviceRequest"/> </wsdl:message>
<wsdl:message name="activateDeviceResponse">
<wsdl:part name="activateDeviceReturn" type="tns3:ActivateDeviceResponse"/>
5
Messages
</wsdl:message>
[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 Motive OAMP
adapter values namespace. The value of the type attribute must be specified as an XML Schema QName--this means that
the value of the attribute must be namespace-qualified. For example, the string type attribute references the namespace
for XML Schema, defined earlier within the definitions element:
xmlns:partns="http://www.w3.org/2001/XMLSchema"
Another example: the findDeviceResponse message specifies a type of FindDeviceResponse, which references the Motive
OAMP adapter values namespace, also defined within the definitions element:
xmlns:partns="java:com.insignia.oampAdapter.values"
Note
From Microsoft 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 OAMP 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 XML 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 OAMP 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 createOMADeviceRequest"> <wsdl:input message="impl:detectSubscriberRequest" name="detectSubscriberRequest"/>
<wsdl:output message="impl:detectSubscriberResponse" name="detectSubscriberResponse"/> </wsdl:operation>
<wsdl:operation name="activateDevice" parameterOrder="activateDeviceRequest"> <wsdl:input message="impl:activateDeviceRequest" name="activateDeviceRequest"/> <wsdl:output message="impl:activateDeviceResponse" name="activateDeviceResponse"/> </wsdl:operation>
[snip...]
Overview of Mobile Device Manager Web Services
6
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:
http://schemas.xmlsoap.org/soap/http
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:
http://schemas.xmlsoap.org/soap/encoding
(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, Messages, 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 OAMP 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=”http://[machinename]:[port]/soap/oampWS>
where machine name defines where the OAMP 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, SMTP etc.) or you can
group ports according to the URL destination. Each
<service>
element can contain more than one
<port>
elements.
7
Binding
Following is the defined
<service>
element within for the OAMP example:
<service name="oampPortService">
<wsdl:port binding="impl:oampPort" name="oampWS">
<wsdlsoap:address location="http://localhost:7001/soap/oampWS"/>
</wsdl:port>
</wsdl:service>
Overview of Mobile Device Manager Web Services
8
2
This chapter covers:
■
Using the OAMP Web Service
■
Using the Device Management Web Service
■
Grouping & Criteria Template Management
■
Using the Device Synchronization Web Service
■
Using the MyPhone Portal Web Service
■
Using the Enterprise Portal Web Service
■
Using the OEM Portal Web Service
9
Using Mobile Device Manager Web
Services
This chapter provides an overview of the use of various Mobile Device Manager web service operations to carry out
common device management tasks.
■
“Using the OAMP Web Service” on page 10
■
“Using the Device Management Web Service” on page 11
■
“Using the MyPhone Portal Web Service” on page 20
■
“Using the Enterprise Portal Web Service” on page 22
■
“Using the OEM Portal Web Service” on page 23
■
“Using the Device Synchronization Web Service” on page 16
Using the OAMP Web Service
The OAMP Web Service provides operations to manage the activation and deactivation of subscribers and devices, and
also to get device information.
Managing Subscribers and Devices
Use the following OAMP 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 Mobile Device Manager 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 MDM database.
❐
Case 1 - Both Subscriber and Device are new (do not yet exist in MDM 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
Using Mobile Device Manager Web Services
10
❐
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 Management 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 Management 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.
11
Getting Device Information
In addition to the Assign Profiles and Firmware Update jobs, the Mobile Device Manager 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 DM 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.
Using Mobile Device Manager Web Services
12
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.
13
Updating Device Firmware
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 Mobile Device Manager system using the MDM 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 Management
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 16
Using Mobile Device Manager Web Services
14
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
.
15
Import Criteria Template
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 17
Using Mobile Device Manager Web Services
16
■
“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.
17
Synchronization Services
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.
Using Mobile Device Manager Web Services
18
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
MostRecentLoggedActivityFirst 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.
19
Activity Log Service
Log Activity
Logs information on activities in the web UI layer.
Note
Other activities are logged within the web service component.
Using the MyPhone Portal Web Service
My Phone Portal operations provide device management information and functions for a single device, given a subscriber
phone number or device ID. Use of the MyPhone Portal web service requires the Web Service Premium license.
The MyPhone 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 Management 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 DM 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.
Using Mobile Device Manager Web Services
20
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 Management 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 Management 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 Management 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.
21
Changing Profile Assignments
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 Management 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 DM 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 Management web services)
to update the settings in the device (step4). If desired, the job status may be polled using the
Using Mobile Device Manager Web Services
22
getJobStatusForDeviceResponse operation of the Device Management 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 Management 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 OEM Portal Web Service
Update packages are managed using the OEM Portal web services. Use of the OEM Portal web service requires the Web
Service Premium license.
Use the following operations to publish update packages and to get other information.
23
Updating Device Firmware
■
“publishUpdatePackages” on page 85
- Publishes an update package by uploading the update zip file to the MDM
database.
■
“getPublishedUpdatePackages” on page 85
- Gets data about published update packages for a specified manufacturer
and model.
■
“getManufacturers” on page 84
- Gets information about all manufacturers and their associated models.
■“extractWarrantyInformation” on page 83
- Gets warranty information (device ID, whether or not it is activated,
firmware version, and subscriber to which the device is associated) for all devices of a specified manufacturer and
model.
Using Mobile Device Manager Web Services
24
3
This chapter covers:
■
OAMP Web Service Operations
■
Device Management Web Service Operations
■
Bulk Device Management
■
Grouping & Criteria Template Management
■
My Phone Portal Web Service Operations
■
Enterprise Portal Web Service Operations
■
OEM Portal Web Service Operations
25
Operations Reference
This chapter provides descriptions of the Mobile Device Manager Web Service operations. Each operation includes
information on input, output (and exceptions, if applicable) associated with usage of the operation.
Operations for the following Web Services are described.
■
“OAMP Web Service Operations” on page 26
- Operations for managing subscribers/devices, finding devices, and
getting device activity.
■
“Device Management Web Service Operations” on page 34
- Operations for managing devices including device discovery,
getting available profiles for a device, assigning profiles and comparing profile assignments. It also includes operations
for getting available update images, updating devices, and creating workflow and command script jobs.
■
“My Phone Portal Web Service Operations” on page 66
- Operations to support the query of device information and
to configure and update a device based on the input of a subscribers phone number.
■
“Enterprise Portal Web Service Operations” on page 74
- Operations to support the management of a population of
devices by a 3rd party such as an enterprise. Operations include the query of device information and the configuration
and update of devices.
■
