This document describes extending the RM mobile device management with custom types of OMA DM client devices.

Defining a Custom Device Type

Each device in RM is uniquely identified by its type and ID, which are available as type and ID of the device root control unit of the corresponding device. The ID of OMA DM devices is obtained from the DevInfo OMA DM standard object ./DevInfo/DevId.

The type of the device is determined by a set of rules defined in OMD DM device definition files in XML format. Each device definition file corresponds to one class of devices and contains the conditions, which a device has to satisfy in order to be classified as belonging to this device class. Such a condition is expressed as a pattern, which is matched against the DMT structure of the OMA DM device. A single device might match the pattern of more than one device definition file. In this case, the device type is determined by the device definition, which declares the highest "ranking" attribute. The ranking attribute allows defining hierarchies of device classes – more generic device types (which define weaker DMT pattern conditions and having lower ranking) and more concrete device types (defining additional DMT conditions over the genetic type conditions and having higher ranking).

Device definition files are placed in the syncml/dev directory of RM and should be named after the device type they are describing (i.e. <device_type>.xml).

Device Definition File DTD

Following are the elements of the device definition file format and their semantics, described in a DTD-like manner.

Control Unit to DMT Mapping

An arbitrary class of devices, including any OMA DM enabled device, can be represented in RM by using the control unit model and therefore can be managed in a unified way. To represent a device as a set of control units, there should be one or more Control Unit Providers, which will represent the specific devices as hierarchies of control unit objects.

The RM offers enhanced mapping between the data models of OMA DM and RM, i.e. between DMT and control unit models respectively. In this case, you do not have to implement any Control Unit Providers, but only write:

• Control Unit to DMT Mapping (CU-DMTM) files, which specify the exact mapping between concrete DMT nodes and control units representing devices of the specific type in RM.

  CU-DMTM files are located in the syncml/dmtm directory of RM and their names should start with the device type they are related to. In particular, the naming convention of mapping files is <device_type>_<dmt_node_keyword>.xml, e.g. mprm.generic.oma-dm.device_Acc-1.2.xml.

• Control Unit Metadata XML files, which define the control unit interface of the CUs representing the specific type of devices in the RM.

  For every such CU-DMTM definition, there MUST be a corresponding control unit metatype (defined in a metadata XML), which defines the interface of the control unit type - number and type of the state variables and actions, parent relations, etc. Therefore, a CU-DMTM definition does not have to describe the control units completely – it only provides complementary information to that included in the CU metatype, which is related to the "implementation" of the control units of that type on top of DMT operations. See the Generic Device Management documentation for more information on control unit metadata.

  The CU metadata XML files for the control units defined in the CU-DMTM files are located in syncml/cu directory and should be named after the control unit type.

The RM will automatically register Control Unit Providers for the control units involved in DMT-to-CU mapping.

CU-DMTM DTD

Variables to Node Settings Mapping

Beside to the structure of a device's DMT, RM also tries to map the variables from CU-DMTM files to node settings (also termed as inheritable properties) which are named according to the convention device.property.<variable>. That is, a variable, for example called "myvar", is substituted with the value of a node setting if the setting is called device.property.myvar.

Such node properties with default values can be described along to RM in Metatype Provider services or can be directly defined and set by calling the Generic Device Manager (e.g. by using the New button on a node's settings in the Management Console). For mobile devices, you can skip implementing and registering Metatype Provider services, and just write a metadata XML in the appropriate format and save it in the syncml/nodemtp RM's directory.

CU-to-DMT Mapping Example

Design the CU Mapping according to an Existing DMT

The most common approach for developing support for a certain management object (MO) in the device management tree (DMT) is to start from the definition and semantics of the MO.

For the purposes of better understanding the example, we will use a MO that is common to the OMA DM enable devices compliant with OMA DM version 1.2 - the DM Account management object (./DMAcc), whose refined representation is available in the RM distribution.

The full description of this management object is available at the Web site of the Open Mobile Alliance - the standard objects for OMA DM v1.2 devices are specified in the "OMA Device Management Standardized Objects" specification. This section concentrates on the DM Account Management Object from this specification.

The tree that exists within our example device is represented with the following real DMT sub-tree (the view is extracted from the Managing an OMA DM Device generic DMT browser for an OMA DM v.1.2 enabled device):

Having this MO definition for a starting point, we will proceed with designing the control units representing the DM Accounts object.

For each DM account <X>, we'll have a control unit which will unite the account's address properties available in the ./DMAcc/AppAddr/<X> DMT interior node and the account's authentication properties available in ./DMAcc/AppAuth/<X> sub-interior node. All DM account control units for a specific device will share a common parent control unit holding the values of the nodes ./DMAcc/AppID and ./DMAcc/ServerID. Finally, the control units for the DM Account MO along with the other standard MO DevInfo and DevDetail will be united in a folder called Standard Objects. We'll focus on the mapping of DM account CUs to account-specific DMT nodes.

The state variables of the DM account control units are formed taken into account the most important interior nodes and the nodes with important values and the actions – setters of the variables' values. We will also define a constructor action, called "Create DM Account", for creating a DM server account on the device, and a destructor action.

Creating a new DM account in the device's DMT by using a constructor.

Create CU Metatype Providers

To describe the structure and format of the control units, designed at the previous step, to RM, we have to provide a metatype for each CU type. CU metatypes describes the CU interface associated with the relevant type including all state variables, actions, parent-child relations, etc. The most convenient way to provide a metatype is by means of XML files, named as <cu_type>.xml within the syncml/cu RM directory. See the user documentation of Generic Device Management RM package for more information about control unit metatypes.

CU metadata XMLs involved in CU-to-DMT mapping should be placed in the syncml/cu directory of RM. The CU metadata XML files for the root "DM Accounts" singleton control unit is syncml/cu/mprm.oma-dm-1.2.std.acc.root.xml and for the DM server account CU type is syncml/cu/mprm.oma-dm-1.2.std.acc.xml.

Creating the metadata XML file of a CU type mapped to a DMT sub-tree involves the following steps:

1. Create the basic structure of the XML file (we'll look at mprm.oma-dm-1.2.std.acc.xml as it contains more useful and illustrative information):

   <metatype-provider>

     <objectclass load="true">

       <locale>en</locale>

       <name>DM Account</name>

       <id>mprm.oma-dm-1.2.std.acc</id>

       <description>DM Account</description>

     

       <!—attribute definition -->

       <!—attribute definition -->

       . . .

       <!—action definition -->

       <!—action definition -->

       . . .

     </objectclass>

   </metatype-provider>

   The value of the <id> tag must match with the control unit type which will be specified in the corresponding CU-DMTM file within the <cu-type> tag. In our case, the type of the DM account control units is mprm.oma-dm-1.2.std.acc.

2. pecify parent relation of the control units if any:

   The next extract from mprm.oma-dm-1.2.std.acc.xml specifies that all DM account units of an OMA DM device have parent control units of type mprm.oma-dm-1.2.std.acc.root.

      <attribute modifier="req">

         <name>ParentType</name>

         <id>mbs.control.parent.type</id>

         <description>Parent Control Unit types definition</description>

         <type>&string;</type>

         <cardinality>1</cardinality>

         <value>

           <array>

             <scalar>mprm.oma-dm-1.2.std.acc.root</scalar>

           </array>

         </value>

       </attribute>     

               
   

   Use the attribute with name "ParentType" and ID "mbs.control.parent.type" to specify a relation with a parent CU type. The actual value of parent control unit must be set within the <value> tag. A control unit type can have more than one parent type, so we must define all parents by using the <array> tag and set the value of <cardinality> tag accordingly.

   
   

3.  Specify a super type of the CU type if any (not defined in the mprm.oma-dm-1.2.std.acc.xml).

   For the needs of this tutorial, following is an extract taken from another CU metadata XML file, mprm.osgi-meg.device.xml, which shows how to declare super CU types (mprm.generic.osgi.device and mprm.generic.oma-dm.device).

     <attribute modifier="req">

         <name>Super Type</name>

         <id>super</id>

         <description>Super Type</description>

         <type>&string;</type>

         <cardinality>2</cardinality>

         <value>

           <array>

             <scalar>mprm.generic.osgi.device</scalar>

             <scalar>mprm.generic.oma-dm.device</scalar>

           </array>

         </value>

       </attribute>

   Use the attribute with name "Super Type" and ID "super" to specify a super type relation. Declaring a super type means that a control unit of this type will inherit all state variables and actions from all its super type control units. The super types must be set by using the <value> tag. As a control unit can have more than one super type, we must enclose all super types in an <array> tag and set the value of the <cardinality> tag accordingly.

4. Describe all state variables of the control units.

   The next snippet contains a definition of a state variable with ID Addr and name Address. It will represent the Addr node of the account-specific interior node ./DMAcc/AppAddr/<X>.

   <attribute modifier="req">

         <name>Address</name>

         <id>Addr</id>

         <description>Host address of the SyncML server, IP or URL.</description>

         <type>&string;</type>

         <cardinality>0</cardinality>

       </attribute>  

    

5. Specify all actions of the control units.

   The next example contains a definition of an action with ID $set.Addr for setting the value of Addr state variable and thence of the ./DMAcc/AppAddr/<X>/Addr DMT node.

        <!-- Set Addr -->

       <objectclass load="true">

         <locale>en</locale>

         <name>Set host address</name>

         <id>$set.Addr</id>

         <description>Sets host address of the SyncML server, IP or URL.</description>      

         <attribute modifier="in">

           <name>Address</name>

           <id>val</id>

           <description>The new server's address</description>

           <type>&string;</type>

           <cardinality>0</cardinality>

         </attribute>

       </objectclass>

   Define an action by using the <objectclass> tag. If the content of the <id> tag starts with "$set.". It means that the action is a setter of new values to a certain state variable. The <attribute> tag is used here to define that this action has one input argument (modifier must be set to "in"). The ID of the attribute should match with the data of the relevant <action-definition> within the corresponding CU-DMTM file so that the input argument can be mapped.

6. Declare constructors

   A control unit constructor must have action ID starting with "$create.". In the DM account control unit interface, the constructor is called $create.acc and will be used for adding new DM accounts to the DMT.

      <objectclass load="true">

         <locale>en</locale>

         <name>Create DM Account</name>

         <id>$create.acc</id>

         <description>Creates a new Device Management account.</description>

         <attribute modifier="in">

           <name>Account alias</name>

           <id>Name</id>

           <description>The name of the new account</description>

           <type>&string;</type>

           <cardinality>0</cardinality>

         </attribute>

         <attribute modifier="in">

           <name>Address</name>

           <id>Addr</id>

           <description>Host address of the SyncML server, IP or URL.</description>

           <type>&string;</type>

           <cardinality>0</cardinality>

         </attribute>

           . . .

       </objectclass>

7. Declare the destructor

   The control unit destructor must have action ID equal to "$destroy".

   <objectclass load="true">

         <locale>en</locale>

         <name>Delete DM Account</name>

         <id>$destroy</id>

         <description>Deletes the DM account.</description>

       </objectclass>

     

Create Control Unit to DMT Mapping (CU-DMTM)

As previously discussed, CU-DMTM files map specific DMT sub-trees to control units of certain types by using XML syntax.

CU-DMTM files should be placed in the syncml/dmtm directory of RM. The CU-DMTM file for the ./DMAcc MO, discussed in this example, is syncml/dmtm/mprm.generic.oma-dm.device_Acc-1.2.xml.

To create a CU-DMTM XML mapping file, follow the next steps:

1. Start describing the basic skeleton of the mapping with <control-unit-dmtm> as root tag and specify the type of OMA DM devices this file is applicable for. Use <device-filter> tag described in Control Unit to DMT Mapping to define additional constraints over OMA DM devices.

   Here, the mapping is for devices of type mprm.generic.oma-dm.device and the filter narrows the scope of the mapping to devices implementing version 1.2 of the OMA DM specifications.

   <control-unit-dmtm>

     <device-type>mprm.generic.oma-dm.device</device-type>

     <device-filter>(DmV=1.2)</device-filter>

     <!-- control unit definition -->

     <!-- control unit definition -->

     . . .

   </control-unit-dmtm>

2. Start defining a control unit type related to a DMT node of interest by opening a <control-unit> tag.

   <control-unit>

       

       <!— DMT node scope definition -->

       <!— CU type mapping -->

       <!— CU ID mapping -->

       <!— CU parent mapping -->

       <!— CU parent mapping -->

       . . .

       <!— CU state variable mapping -->

       <!— CU state variable mapping -->

       . . .

       <!— CU action mapping -->

       <!— CU action mapping -->

       . . .

     </control-unit>

3. Specify the scope of the control units of the relevant type in the DMT, i.e. one or more DMT nodes which are considered as roots of the DMT sub-trees. Use the <dmt-node> tag as described in Control Unit to DMT Mapping.

   The snippet shows that the currently defined control unit type is scoped to the ./DMAcc/AppAddr/<X> nodes.

   <dmt-node>

   <path-pattern try-struct="true">./DMAcc/AppAddr/{X}</path-pattern>

   </dmt-node>

   
   

   Every other node URIs used in the definition of this control unit type might be relative to the node(s) specified by this element. The {X} variable is resolved at runtime against a particular device. The resolving procedure will determine all DMT nodes that match the pattern, which in turn will determine the number of control unit instances that will be available of this type. ./DMAcc/AppAddr/{X} must be a valid node of target device's DMT.

4. Declare the type of the control units associated with the DMT node within a <cu-type> tag as described above. The type must match with the type ID specified in the corresponding CU metadata XML file.

   The extract from the DM account CU-DMTM file specifies that the control unit type being mapped is mprm.oma-dm-1.2.std.acc whose structure has been discussed in the previous section.

   <cu-type>mprm.oma-dm-1.2.std.acc</cu-type>

5. Declare the ID of current control unit within a <cu-id> tag.

      <cu-id>

         <id-format>{X}</id-format>

       </cu-id>

   In case the ID format contains a variable, the IDs are determined at runtime by substituting the variables (e.g. {X}) with their values according to the URI pattern within the relevant <dmt-node> tag.

6. Declare the parent type(s) if the control units have parents within one or more <cu-parent> tag.

     <cu-parent>

         <cu-type>mprm.oma-dm-1.2.std.acc.root</cu-type>

         <cu-id>

           <id-format>DMAccounts</id-format>

         </cu-id>

       </cu-parent>   

                
   

   The parent type and ID should be available in a CU metadata XML file. In the example, the DM account control units will have a common parent of type mprm.oma-dm-1.2.std.acc.root, previously discussed, and with ID equal to "DMAccounts". The CU metadata XML file for mprm.oma-dm-1.2.std.acc.root is syncml/cu/mprm.oma-dm-1.2.std.acc.root.xml.

7. Map all control unit state variables to specific DMT nodes. Use <state-var> tags.

   <!-- AppAddr subtree -->

      <state-var>

        <state-var-id>Addr</state-var-id>

        <node-attr attr-name="value">Addr</node-attr>

      </state-var>

         

   The Addr node specified in the extract is relative to the DMT URI specified in the <dmt-node> tag of the current control unit definition, i.e. its URI is ./DMAcc/AppAddr/{X}/Addr. The Addr node must be a valid node of DMT of the target device. There must be a corresponding CU metadata file (in our case syncml/cu/mprm.oma-dm-1.2.std.acc.xml), which contains a state variable definition with ID equal to the content of the <state-var-id> tag.

   <!-- Address part -->

       <attribute modifier="req">

         <name>Address</name>

         <id>Addr</id>

         <description>Host address of the SyncML server, IP or URL.</description>

         <type>&string;</type>

         <cardinality>0</cardinality>

       </attribute>

8. Map all control unit actions to DM commands over a specific DMT node. Use <action> tags.

   • Setter action definition - Setter actions are expected to have ID $set.<state_var_id>.

       <!-- Set Address -->

         <action>

           <action-id>$set.Addr</action-id>

           <action-definition>

             <Replace>

               <Item>

                 <Target><LocURI>Addr</LocURI></Target>

                 <Meta><Format xmlns='syncml:metinf'>chr</Format></Meta>

                 <Data>{val}</Data>

               </Item>

             </Replace>

           </action-definition>

           <refresh>

             <cu-state><this/></cu-state>

           </refresh>

         </action>

     
     

     The action's input argument defined as {val} will be used to replace the Addr node of device's DMT. The URI of the node is ./DMAcc/AppAddr/{X}/Addr where {X} is resolved at runtime and will be mapped to a concrete DM server account.

     There must be a corresponding CU metadata file where an action with the same ID and input argument ID are defined.

       <!-- Set Addr -->

         <objectclass load="true">

           <locale>en</locale>

           <name>Set host address</name>

           <id>$set.Addr</id>

           <description>Sets host address of the SyncML server, IP or URL.</description>

           <attribute modifier="in">

             <name>Address</name>

             <id>val</id>

             <description>The new server's address</description>

             <type>&string;</type>

             <cardinality>0</cardinality>

           </attribute>

         </objectclass>

   • Execute action definition

         <action>

           <action-id>start</action-id>

           <action-definition>

             <Exec>

               <Item>

                 <Target><LocURI>{$multi:$}/RM/Bundles/{bundle_id}/Operations/Start</LocURI></Target>

                 </Item>

             </Exec>

           </action-definition>

           <refresh>

             <cu-instance><cu-type>meg.deployment.package</cu-type></cu-instance>

             <cu-instance><cu-type>meg.deployment.package.bundle</cu-type></cu-instance>

           </refresh>

         </action>        

     The action definition taken from the syncml/dmtm/mprm.osgi-meg.device_Deployment.xml specifies that invoking the start control unit action will result in executing the OMA DM "Exec" operation over a specific node of the DMT of the target device. {bundle_id} is resolved at runtime according to the concrete CU definition. The <refresh> tag is used to indicate that RM has to refresh the state of all control unit instances of the defined type on the backend after the start action is complete.

   • External action definition

         <action>

           <action-id>update</action-id>

           <external/>

             <refresh>

             <cu-instance><cu-type>meg.deployment.package</cu-type></cu-instance>

               <cu-instance><cu-type>meg.deployment.package.bundle</cu-type></cu-instance>

           </refresh>

         </action>

     Such an external action must be implemented and registered in the MS OSGi framework as a com.prosyst.syncml.dm.manager.map.Action service for the defined control unit type and action ID. By specifying some action as "external", a programmer gains more flexibility while implementing the specific action.

9. Define control unit constructors as CU actions starting with $create..

   The next example maps the constructor $create.acc to an "Add" OMA DM operation which has target DMT node ./DMAcc/AppAddr/<Name>.

       <action>

         <action-id>$create.acc</action-id>

         <action-definition>

             <!-- Add Root node and the display name -->

            <Add>

              <Item>

                <Target><LocURI>./DMAcc/AppAddr/{Name}</LocURI></Target>

                <Meta><Format xmlns='syncml:metinf'>node</Format></Meta>

              </Item>

            </Add>

              . . .

         </action-definition>

         <refresh>

           <cu-instance><cu-type>mprm.oma-dm-1.2.std.acc</cu-type></cu-instance>

         </refresh>

       </action>

10. Define the control destructor as a CU action whose ID is equal to $destroy.

    <!-- Destructor -->

        <action>

          <action-id>$destroy</action-id>

          <action-definition>

            <Delete>

              <Item>

                <Target><LocURI>./DMAcc/AppAddr/{X}</LocURI></Target>

              </Item>

              <Item>

                <Target><LocURI>./DMAcc/AppAuth/{X}</LocURI></Target>

              </Item>

            </Delete>

          </action-definition>

          <refresh>

            <cu-instance><cu-type>mprm.oma-dm-1.2.std.acc</cu-type></cu-instance>

          </refresh>

        </action>