February 2009
Volume 24 Number 02
Going Places - Mobile Device Provisioning With SyncML
By Ramon Arjona | February 2009
Contents
What Is OMA?
SyncML: XML for Synchronization
SyncML Elements
The SyncBody Element
But, Wait! There's More!
Putting SyncML to Work
In the April 2008 issue of MSDN Magazine, Mike Calligaro wrote a Going Places column about provisioning a Windows Mobile device using XML files and the DMProcessConfigXML API. The XML files Mike used were based on the Open Mobile Alliance (OMA) Client Provisioning (OMA-CP) standard for device management, formerly known as Wireless Application Protocol (WAP).
OMA-CP works fine for managing a few devices, and in his column Mike has suggestions for ways to push provisioning information to multiple devices at once. But what if you need to provision thousands of devices in a systematic way over a long period of time? And what if you need to know what software and registry settings are already set on the devices you're trying to manage?
This sort of large, coordinated provisioning effort is the domain of OMA Device Management (OMA-DM). The OMA-DM protocol is based on a dialect of XML called SyncML, and it can be used to provision and manage devices in an enterprise scenario. This column will discuss the structure of a SyncML document used in the OMA-DM protocol. I will cover specific usage scenarios for the Windows Mobile platform, including remotely wiping the device. I will also demonstrate how you can set a browser favorite on the device using the XML from Mike's column in conjunction with OMA-DM.
What Is OMA?
OMA is an industry group comprising more than 200 mobile operators, mobile device manufacturers, and software vendors (including Microsoft). OMA was formed in 2002 to create a single group to manage the burgeoning number of mobile device standards that were appearing in the marketplace, including WAP, Device Management, and SyncML. This multiplicity of groups was creating duplication of work, so the concerned industry partners got together and brought all of these important initiatives together under a single umbrella group.
OMA standards help make it easier to work with mobile devices and networks by creating a nonproprietary way to communicate between technologies. SyncML and OMA-DM are two aspects of this open protocol family. Like all protocols, they are subject to a certain amount of interpretation, and every vendor is free to supply its own value-added extensions. But working with them is easier and more straightforward than trying to negotiate a proprietary, vendor-specific format.
SyncML: XML for Synchronization
SyncML is an XML-based markup that is used as the basis for most protocols defined by OMA. A SyncML document is called a message. The message must be well-formed XML but not necessarily valid XML. That is, it must have matching open and close tags for all elements, must have quotes around all attributes, and otherwise conform to the basic definition of well-formedness that is essential to any document calling itself XML.
While there is a SyncML document type definition (DTD), there is no requirement that the sender or receiver validate against it. One of the reasons for this is that validation requires extra memory and processor time, and mobile devices tend to be short on both of these resources. The message, in turn, contains command elements that do the heavy lifting of specific OMA protocols.
SyncML and OMA-DM are transport independent. There are transport bindings defined for HTTP and Object Exchange (OBEX), and it would be possible for other bindings to be defined. This makes SyncML and OMA-DM useful for provisioning devices over the air. Using SyncML and OMA-DM with a compliant device-management server, you can push configurations to a device without using a memory card, without tethering the device, and without asking the end user for interaction, such as visiting a Web site.
One or more messages is contained, conceptually, in a SyncML package. The SyncML package encompasses all of the messages sent between a sender and a receiver.
SyncML Elements
A SyncML document consists of a root SyncML element, a header defined by the SyncHdr element, and a body defined by the SyncBody element. The root of a SyncML document is always a SyncML element, which looks like this:
<SyncML xmlns='SYNCML:SYNCML1.1'> ... </SyncML>
The SyncML element contains the SyncHdr and SyncBody child elements. A SyncHdr element looks like the markup in Figure 1. This short header tells you everything that a receiver would need to know to process the message.
Figure 1 SyncHdr
<SyncHdr> <VerDTD>1.2</VerDTD> <VerProto>DM/1.2</VerProto> <SessionID>1</SessionID> <MsgID>1</MsgID> <Target> <LocURI>https://mgmt.contoso.com/ </LocURI> </Target> <Source> <LocURI>urn:uuid:6D67E196-D082-4c91-A0DD-DEB3D1D58EB5</LocURI> <LocName>MyDeviceName</LocName> </Source> <Cred> <Meta> <Format xmlns="syncml:metinf">b64</Format> <Type xmlns="syncml:metinf">syncml:auth-md5</Type> </Meta> <Data>ODZlMDNiYmM1MjA1YTI3MDc5MDk2MDcwYTA4OGM2Zjg=</Data> </Cred> </SyncHdr>
The VerDTD element indicates that this message conforms to version 1.2 of the SyncML Representation Protocol, as defined by OMA. The VerProto element indicates something similar: that you're looking at a message that deals with version 1.2 of the OMA-DM protocol. The version numbers are the same, but the two things are different. SyncML is used for different OMA protocols, including a device management protocol (which I am discussing in this column) and a data synchronization protocol (for which SyncML was originally designed).
The SessionID element indicates at which SyncML session you're looking. The value of this ID can be, at most, 4 bytes long.
The MsgID is an ID that is unique within the session. It's used to keep track of the conversation between sender and receiver. When the receiver replies with results, the results refer to the message being responded to by including the MsgID in a MsgRef element.
The Target element says who the receiver of the message is meant to be. The Source element says who the sender of the message is meant to be. These elements both contain a LocURI element that contains the string uniquely identifying the sender or receiver. The LocURI of the Target and Source must be a URL, a URI, or a URN. Since a management server will usually already have a unique DNS name, it is common to see the fully qualified domain name of the management server in the LocURI when the sender or receiver is a management server.
Note that neither the Target nor the Source element is directly related to addressing or routing the message. These tasks are left to the device-management application and the supporting transport protocols.
Mobile devices are frequently referred to by a URN that refers to a GUID—as defined by RFC 4122—that refers uniquely to the specific device being addressed. It is up to the application to map this GUID back to an address that can be reached over the network. Since the GUID is not an immediately intuitive way to tell to which specific device you are talking, the application has added a LocName element to the Source element, which holds the name of the device that originated the SyncML message.
Finally, the Cred element contains information that identifies the originator. It contains a pair of Meta elements that inform the recipient this message uses the MD5 authentication scheme that is defined in the SyncML standard, and that the security token is base-64 encoded. The Data element that is the sibling of the Meta elements contains the authentication token that can be used by the recipient to confirm the sender's identity.
The SyncBody Element
A SyncBody element is shown in Figure 2. Notice that the Target elements here, just like in the SyncHdr, are identified by LocURI. Nearly everything in SyncML is identified by LocURI. The LocURI is built according to a nested tree structure, similar to the nested tree structure of an XML document, but is somewhat less expensive to process than a series of nested XML nodes. The root of the conceptual tree is identified by the " . " character, which must always be specified.
Figure 2 SyncBody Element
<SyncBody> <Add> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Vendor/MSFT/SwMgmt/Download/SetBrowserFavorite/PkgID </LocURI> </Target> <Data>pkg id setbrowserfavorite</Data> </Item> <Item> <Target> <LocURI>./Vendor/MSFT/SwMgmt/Download/SetBrowserFavorite/PkgURL </LocURI> </Target> <Data>https://content.contoso.com/download/SetBrowserFavorite.cab </Data> </Item> </Add> <Exec> <CmdID>3</CmdID> <Item> <Target> <LocURI>./Vendor/MSFT/SwMgmt/Download/SetBrowserFavorite/Operations/DownloadInstall </LocURI> </Target> </Item> </Exec> <Final/> </SyncBody>
The tree contains information about the mobile device, including details such as the amount of memory it has or what executables are available to be invoked over OMA-DM. When a LocURI is used to refer to this tree of device information, it must always be a full URI. That is, it must always be specified from the device root down to the specific leaf to be addressed. Partial or relative URIs are not allowed in this part of the OMA-DM specification.
Note that I refer to this as a "conceptual" tree. That is because the SyncML and OMA-DM specifications do not impose any implementation details on the mobile device or on the device management server for how this information is actually persisted to a backing store. SyncML wants to address the data as though it were a tree, but you could store it in a relational database, in the device or server registry, in volatile memory, in a series of flat files, or in some other way. The specification is completely agnostic to the mechanism used to physically persist this data.
Beneath the root node are three important child nodes: DevInfo, DevDetail, and Vendor. The DevInfo node contains information about the device manufacturer, the language set on the device's UI, and the device ID. The DevDetail node contains other vendor-independent information about the device, including its hardware version and the maximum length of URI supported by the device. Most other interesting details about the device are stored under the Vendor node. By specification, implementers must park their extensions to the OMA-DM protocol under the Vendor node, and this is where you will spend much of your time when provisioning or managing Windows Mobile devices.
Remote Wipe
The Exec command always tells the device to do something, but there is a limited set of things the device can be commanded to do by OMA-DM. One other thing that can be triggered on a Windows Mobile device by OMA-DM is a remote wipe. This is similar to the wipe feature offered for Windows Mobile clients by Exchange and is really useful if a device under your control has been lost or stolen. The command to wipe a device with OMA-DM looks like this:
<Exec> <CmdID>3</CmdID> <Item> <Target><LocURI>./Vendor/MSFT/RemoteWipe/doWipe</LocURI></Target> </Item> </Exec>
It's possible to wipe a device with OMA-CP, too. So you could, if you really wanted to, create a CAB file with provisioning XML in it and distribute it to the device via OMA-DM download. The CAB file's contents would then get routed to the same RemoteWipe CSP that would be invoked by OMA-DM, and the results would be the same.
The SyncBody element shown earlier contains one Add element. The Add element tells the receiver to add a node or series of nodes to the device-information tree. The Microsoft implementation of OMA-DM supports something called implicit add, which means that if an Add command refers to a LocURI with nodes that are not present on the device, all of the nodes from the root to the leaf are inserted into the device-information tree. Without this extension, nodes would have to be added to the device tree one at a time, which would rapidly consume bandwidth, processor time, and—eventually—the user's patience.
This Add command is adding something to the Download node for software management on the device having the URL content.contoso.com/download/SetBrowserFavorite.cab. Ultimately, this URL will be routed to a configuration service provider (CSP) on the device—coincidentally called the Download CSP—that will try to fetch the content specified by this URL.
The Add command is followed by an Exec command. The Exec command tells the device to go do something. In this case, it's telling the device to go download and install the package with the ID SetBrowserFavorite.cab.
The Exec command is followed by a Final element, which tells the receiver that this is the last SyncML message that should be expected for this session. Without the Final element, the receiver would expect that there would be more SyncML messages to follow.
If you can install a CAB file onto the device by copying it onto the device via ActiveSync, you can usually install that CAB file onto the device using OMA-DM. The CAB file must be signed with a certificate that the device trusts. If the file is not signed with a valid certificate, the installation of the CAB file will fail. This differs from the behavior you'll see when installing an unsigned CAB file over ActiveSync. When you install an unsigned file over ActiveSync the device might prompt you for confirmation of your intention to install the unsigned CAB, assuming policy on the device is set to allow this.
The OMA-DM protocol on a Windows Mobile device does not prompt you. It just fails, notifies you of the failure with a message containing an error code in the Managed Programs applet, and sends a related error code back to the device management server. This design makes sense because ActiveSync is being initiated by you, or hopefully someone you trust, while the device is physically in your hands. OMA-DM is initiated by a remote agent, at a time that is completely out of your control.
First, the Download CSP fetches the content from the specified URL. Then it looks at the CAB file and fails if it is unsigned. If the CAB file is signed, the Download CSP unpacks the CAB file and routes the contents of the file appropriately. If the CAB contains software, the software is installed onto the device. If the CAB contains OMA-CP provisioning XML—such as the CAB file Mike created in his column—then the provisioning XML is applied to the device. If the CAB file contained plain content, such as a movie or a home screen, then this content is stored on the device file system.
The Managed Programs applet records every attempt, successful or failed, to install a CAB file onto the device via OMA-DM. After the installation has completed, the device sends a code defined by the OMA-DM standard back to the management server in a new OMA-DM session.
But, Wait! There's More!
Windows Mobile devices respond to a subset of the command elements specified in SyncML. Following are a few command elements I haven't discussed yet.
The Alert command allows the sender to notify the recipient. For instance, an alert from a management server to a device might tell the device to wake up and start a session. Or an alert could contain information that should be displayed to the end user through the UI.
The Atomic element is used to group other commands that must all succeed or fail as a unit. This is important when a group of commands is related and partial success would leave the device in an undesirable or unknown state. Unless grouped in an Atomic element, three separate Add commands would succeed or fail independent of each other and generate three separate response messages for the management server.
Delete is the opposite of Add. The Delete command removes a node from the device tree. If the node has child nodes, those are removed, too. Some nodes, such as the built-in DevInfo node and its children, can't be removed, and the attempt to remove them generates an error code. The Replace command replaces a given node in the device tree.
The Get command is used to query the device tree for information and returns that information in a SyncML message to the sender. For instance, to get the amount of storage available currently on the device, the following Get command would be sent:
<Get> <CmdID>3</CmdID> <Item> <Target> <LocURI>./Vendor/MSFT/DeviceInformation/TotalStorage</LocURI> </Target> </Item> </Get>
The Result command is sent in response to a Get, containing the value of the node the Get requested.
The Sequence element is used to group nodes in a specific order. If you expect to have commands processed one after another, you must group them in a Sequence element. Otherwise the order of execution is not guaranteed.
And finally, the Status element contains the success or failure code returned by a given operation. A Status of 200 generally indicates success.
Putting SyncML to Work
SyncML began as a protocol not for device management but for device synchronization. Implementations of the OMA sync protocol based on SyncML are used frequently to allow devices to synchronize calendar and contact information. The base protocol specification for SyncML addresses the requirements for synchronization as well as the requirements for management. This means the base SyncML representation protocol contains elements that are never used in OMA-DM and other elements that are never used in synchronization.
First-time readers of the SyncML specification may find themselves a bit confused, because the specification is trying to address two divergent problem domains. While there is some overlap between synchronization and management, the two things are definitely not the same. It's helpful to segregate the elements of SyncML that are used in management conceptually from those that are used in synchronization when reviewing the protocol representation specification.
You need to have a management server to provision your devices via OMA-DM. There are several commercial offerings available, including Microsoft System Center Mobile Device Manager 2008. And there are noncommercial SyncML libraries and implementations available as well. The amount of flexibility allowed to vendors and implementers means that making devices and servers talk using OMA-DM is not always as straightforward as one would want. But the difficulties presented by integration of different devices that use OMA standards is immensely preferable to the difficulty of making devices interoperate using the hodgepodge of unrelated, proprietary communication methods that dominated the mobile marketplace before the advent of OMA.
Send your questions and comments to goplaces@microsoft.com.
Ramon Arjona is a Senior Test Lead working on the Windows Mobile team at Microsoft.