Ganymede Object Data Import/Export Definition in XML

While the Ganymede server is capable of expressing its schema definition information in the <ganyschema> section of its XML file, this aspect of Ganymede's XML support is bound to be much less used than the data dumping and loading support. This section discusses the <ganydata> element that may be present in the Ganymede XML file format.

<ganydata>
The <ganydata> element is a container for object data to be updated on the server. When exported, the <ganydata> element contains a complete dump of the server's data state. When imported, the <ganydata> element can contain an optional <comment> element describing the transaction to be committed, and a collection of <object> elements which specify the objects to be created, edited, inactivated, or deleted.
Parent(s) Children
ganymede <comment>, <object>
Attributes
None

The <ganydata> element can contain an optional <comment> element containing text describing the purpose of the transaction to be committed by the Ganymede server on successful processing of the <object> elements. The text in the <comment> element will be included in all email generated by the Ganymede server in response to the transaction, and will be included in all logging related to the transaction.

<comment>

The optional <comment> element contains a text string describing the transaction to be performed. Any text contained by this element will be included in all email and logging generated for the transaction committed in response to the processing of the <ganydata> element.

The <comment> element will never be generated when dumping data with xmlclient. It is only meaningful when submitting change requests to the Ganymede server.

If the <comment> element contains anything other than character data, the contents of the <comment> element will be disregarded. You may not include HTML or other XML-formatted text within the <comment> element.

Parent(s) Children
<ganydata> Character data.
Attributes
None
Example
<comment>This server was decommissioned three years back, but never removed from Ganymede.</comment>

The <ganydata> element contains a series of <object> elements, each one corresponding to an object in the Ganymede database. The <object> element itself may contain one element for each field in the object. The open tag for the object element as exported contains possibly four attributes, those being type (required), id, num, and action.

<object>
The <object> element contains data for a single object. When exported, the <object> element contains a complete dump of the object's state, minus the historical fields (last modification data, etc.).When imported, the <object> element contains a collection of field elements whose contents are to be transmitted to the server to update the object identified by the <object>'s attributes.
Parent(s) Children
<ganydata> Various field elements, each with a unique tag name based on the name of the corresponding server field
Attributes
type
The name of the type this object belongs to. This string is case sensitive and must match the name attribute for the type's <objectdef> element, which is the object's type name with underscores substituted for spaces.
id
An optional identifier string for this object, unique among objects of this type within the <ganydata> element in this XML file. If this string is not present, the num attribute becomes mandatory. The id attribute is used for two purposes; the first is to identify an object on the server to be edited, inactivated or deleted if the action attribute specifies these actions. The second is to act as a target for <invid> elements within the XML file to use to refer to <object> elements that are created during the XML file processing. Each use is contingent on the id attribute of <object> and <invid> elements matching the server's idea of what the label of the object is.
num
An optional object number for this object, unique among objects of this type on the server. If this number is not present, the id attribute becomes mandatory. If both the id and num attributes are present, the id attribute takes precedence. The number contained in this attribute corresponds to the Invid object number for the object designated by this <object> element. The num attribute is used to select pre-existing objects on the server for editing, inactivation, or deletion. If this <object> has an action attribute value that would cause a new object to be created on the Ganymede server, the num attribute is simply ignored. It is an error to specify a num attribute for an object that does not already exist on the server at the time the xml file is processed.
oid

This attribute is provided when an object is dumped out by a Sync Channel. It is a globally unique identifier which encodes both the type of the object and its unique id number.

This attribute is disregarded when loading data.

action
The action attribute is optional, and plays a role only in XML data importing. If the action attribute is present, it may contain one of four strings:
  • create
  • edit
  • inactivate
  • delete

If there is no action attribute specified at import time, the <object> element will be created if the object has a id attribute and no num attribute and if there is no object already on the server that matches the id attribute. Otherwise, the pre-existing object on the Ganymede server matching the identifying attribute will be checked out for editing.

If the action attribute is present and contains "create", the <object> element will cause the Ganymede xmlclient to create a new object. In addition, in such cases all <invid> elements in the XML file with matching type and id attributes will be interpreted to be referring to the newly created <object> element.

If the action attribute is present and contains "edit", the <object> element will cause the Ganymede xmlclient to seek to check the object out for editing from the server. If no object exists on the server matching the id attribute, an error will be displayed and xmlclient will abort the transaction.

In the unspecified, "create", and "edit" cases, the object element will typically contain a set of field elements. In the "inactivate" and "delete" cases, the <object> element must be empty, and the xmlclient will simply attempt to inactivate or delete the object identified by the id or num attributes.

Aside from the special case of object inactivation or deletion, all <object> elements in a <ganydata> section will contain a set of elements that correspond to fields in the object to be created or edited on the server. The elements for these fields have no fixed tag name. Instead, each field element will start with an open tag that is named according to the name of the field, with spaces transformed into underscores.

For instance, a record to change the values of the "Room", "Groups", "Home Group" and "Email Aliases" fields in a pre-existing object on the server would be represented in the XML file as:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <invid type="Group" id="omssys"/>
        <invid type="Group" id="omsnet"/>
    </Groups>
    <Home_Group><invid type="Group" id="omssys"/></Home_Group>
    <Email_Aliases>
        <string val="abbey"/>
        <string val="jonabbey"/>
    </Email_Aliases>
  </object>

An <object> element contains nothing but such field elements, all of which lack any sort of attributes. The field elements themselves, however, will contain a variety of kinds of elements, depending on the field type. In the above example, the "Room" field is a scalar String field, the "Groups" field is a vector Invid/object reference field, the "Home Group" field is a scalar Invid/object reference field, and the "Email Aliases" field is a vector String field.

In the above example, the Groups and Email_Aliases vector field elements both contain a couple of items. These items will be added to those fields if they are not already present, but the xmlclient will not remove any other items which may already be in those fields.

If you want to assure that after xmlclient finishes its work that there will only be a given list of items in a vector field, you need to do this:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <set>
            <invid type="Group" id="omssys"/>
            <invid type="Group" id="omsnet"/>
        </set>
    </Groups>
  </object>

In this example, the <set> container element will force the xmlclient to set the Groups field to contain only the two items listed, adding or removing items as necessary.

You can also manually add or remove individual items, using <add>, <addIfNotPresent>, and <delete>:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <add>
            <invid type="Group" id="omsovr"/>
        </add>
        <delete>
            <invid type="Group" id="omsnet"/>
        </delete>
    </Groups>
  </object>

This will cause the omsovr group to be added and the omsnet group to be removed. You can have as many <add>, <addIfNotPresent> and <delete> containers as you want within a vector field, but <add>, <addIfNotPresent> and <delete> are not compatible with <set>. If you use <set>, you may not use <add>, <addIfNotPresent> or <delete> as well.

If you don't specify <add>, <addIfNotPresent>, <delete>, or <set>, the xmlclient will treat the items as belonging to an <addIfNotPresent> container. For this reason, the following is not allowed:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <invid type="Group" id="omsovr"/>
        <set>
            <invid type="Group" id="omssys"/>
            <invid type="Group" id="omsnet"/>
        </set>
    </Groups>
  </object>

because the omsovr element is considered to be in an <addIfNotPresent>, which may not co-exist with a <set> in a single field element.

There are presently ten different types of data fields supported by the Ganymede server, and each of these types has its own rules as to what kinds of elements are allowed within the field element and how they may be structured. For the most part, these rules are very similar for all field types, with just the value carrying element type differing. The following table shows the data carrying element types that correspond to the ten field types.

<string>
The <string> element contains data for Ganymede string fields, but is mandatory only for vector string fields. The <string> element is not necessary for scalar string fields, which support simply placing the content to be placed in the string field directly between the field element's open and close tags. If the <string> element is used for string field content, it must be empty.
Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
val
The contents of the mandatory val attribute actually holds the string value corresponding to this <string> element. As with all XML attributes, double quote characters must be replaced by '&quot;', naked ampersands must be replaced by '&amp;', and anything goes otherwise, including embedded newlines.
Example
<string val="broccol"/>
<boolean>

The <boolean> element is an optional data element for Ganymede boolean fields. Since Ganymede boolean fields are always scalar, you can simply place true, t, false or f (of whatever capitalization) between the field's start and end tags. If you do use the older <boolean> element as a data container, the <boolean> element must be empty.

Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
val
The contents of the mandatory val attribute holds a string corresponding to the value of this <boolean> element. "1", "true", "t", "yes", and "y", of whatever capitalization, all correspond to a true value. Any other value corresponds to a false value. Note that this is a looser standard than is allowed if you use a text string to represent the true or false value outside of the <boolean> element's val val attribute. In that case, you must use true, t, false, or f, of whatever capitalization.
Example
<boolean val="true"/>
<int>

The <int> element is an optional data element for Ganymede numeric fields. Since Ganymede numeric fields are always scalar, you can simply place a 32 bit signed integer value between the containing field's start and end tags. If you do use the older <int> element as a data container, the <int> element must be empty.

Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
val
The contents of the mandatory val attribute actually holds the integer value corresponding to this <int> element. This attribute can hold integer values in the range -4294967296 to 4294967295. The only characters allowed in this attribute value are the numeric digits and the minus sign. This same range holds if you skip the <int> element and just place the numeric value between the start and end tags of the containing field element.
Example
<int val="12042"/>
<float>
The <float> element contains a 64 bit floating point value, corresponding to the IEEE 754-1985 specification, for use with Ganymede float fields. As float fields are scalar in Ganymede, only one <float> element at a time may be contained in a float field element. The <float> element must be empty.
Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
val
The contents of the mandatory val attribute actually holds the 64 bit float value corresponding to this <float> element. This attribute can hold floating point values corresponding to the 64 bit floating point value specified by IEEE 754-1985 specification. The text of this attribute must conform to the rules specified in the java.lang.Double class, which generally corresponds to normal rules of ASCII floating point number representation, with support for numbers of the form 6.04E+25 in scientific notation for very large or very small numbers.
Example
<float val="3.141596254"/>
<ip>
The <ip> element contains an IPv4 or IPv6 address. IP fields may be scalar or vector in Ganymede. The <ip> element must be empty.
Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
val
The contents of the mandatory val attribute holds an IPv4 string in standard dotted decimal form, or an IPv6 string, in any RFC 1884 format. The Ganymede server will decide, based on its configuration, whether an IPv6 address will be accepted. Even if the Ganymede server is configured to allow IPv6, IPv4 strings will always be accepted, given that all IPv4 addresses have a canonical mapping into IPv6 addresses, according to the rules of IPv6.
Example
<ip val="127.0.0.1"/>, <ip val="::1"/>, <ip val="::FFFF:127.0.0.1"/>

All of these examples encode a loopback address, in either IPv4 or IPv6 form.

<date>
The <date> element contains a Java date value, which is effectively a 64 bit time stamp with millisecond resolution centered at Midnight, January 1, 1970, UTC. As date fields are scalar in Ganymede, only one <date> element at a time may be contained in a field element. The <date> element must be empty.
Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
val
The contents of the val attribute contains a human readable representation of the time stamp held in this <date> element. The val attribute takes data strings of the form "Sun, 03 Dec 1995 00:00:00", in which case the date is interpreted in the local timezone of the machine running the xmlclient or "Sun, 03 Dec 1995 00:00:00 CDT", in which the date will be interpreted by the specified timezone. The standard UNIX date format "Tue Jul 11 01:18:21 CDT 2000" is also supported. The precise form of date val string that may be parsed by the xmlclient, in particular the characters of the date and month, may differ according to the default Java locale of the JVM running the xmlclient. To avoid any possibility for imprecision, it may be necessary to instead use the timecode attribute.
timecode
The contents of the timecode attribute contains a 64 bit signed integer, corresponding to the number of milliseconds before or after Midnight, January 1, 1970, UTC. In order to use a UNIX-style 32 bit timecode to fill in the timecode attribute, you can simply multiply a 32 bit timecode by 1,000.
Example
<date val="Wed 28 Jun 2000 13:13:02" timecode="962215982000"/>
<password>

The <password> element contains a Java password value. As password fields are scalar in Ganymede, only one <password> element at a time may be contained in a field element. The <password> element must be empty. The <password> element may contain any or all of the eight optional attributes: plaintext, crypt, md5crypt, apachemd5crypt, lanman, ntmd4, ssha, shaUnixCrypt, and bCrypt.

If the plaintext attribute is present, all other hashes will be ignored when the client submits a <password> element, and the Ganymede server will generate new hashes as needed from the plaintext given. If none of the optional attributes are present, the password field will be cleared. All of these options are explained below.

If the plaintext attribute is not present but one or more of the hash attributes are, Ganymede will replace any previous information held in this field with information for the hashes you specified. If a Ganymede build process requires hash information that you did not provide when you submitted this <password> element, you may have problems.

In general, it is best to pass plaintext information to Ganymede when you want to tell Ganymede about a password change, but you can provide pre-hashed password data to Ganymede if you are comfortable about the limitations you might run into.

Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
plaintext

This attribute, if present, contains a password string in plain text. The client will transmit this password to the server, which will generate any needed hash formats according to the schema configuration for this field. If plaintext is specified, all other hash information in this element will be ignored.

crypt

This attribute, if present, contains a password string pre-hashed in UNIX crypt() format. The client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

md5crypt

This attribute, if present, contains a password string pre-hashed in FreeBSD-style md5Crypt() format. The client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

apachemd5crypt

This attribute, if present, contains a password string pre-hashed in Apache-style md5Crypt() format. The client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

lanman

This attribute, if present, contains a password string pre-hashed in the LANMAN encoding used by older versions of Windows networking. This hash format is one of the two password encryption formats used by the Samba password file. The client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

ntmd4

This attribute, if present, contains a password string pre-hashed in the Unicode-md4 encoding used by Windows NT and Windows 98 and later. This hash format is one of the two password encryption formats used by the Samba password file. The client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

ssha

This attribute, if present, contains a password string pre-hashed in the Salted SHA-1 format used by OpenLDAP. The client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

shaUnixCrypt

This attribute, if present, contains a password string pre-hashed in Ulrich Drepper's Sha Unix Crypt format. See http://people.redhat.com/drepper/sha-crypt.html for a discussion and a link to the specification for this format.

As with the other hash attributes, the client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

bCrypt

This attribute, if present, contains a password string pre-hashed in the OpenBSD BCrypt format

As with the other hash attributes, the client will transmit this hash text to the server, where it and any other hash text simultaneously provided will be retained. This attribute has no effect if the plaintext attribute is specified.

Example
<password md5crypt="$1$o8/.....$f398vnq51gnzf" shaUnixCrypt="$5$saltstring$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5"/>
<options>

The <options> element is similar to the <permmatrix> element, in that it provides a mapping for object and field types defined in the Ganymede server. While <permmatrix> provides a set of permission bits for each object or field for a Ganymede Role, the <options> element simply provides option strings for each object type and/or field. The main purpose of these option strings is to control what data triggers a Sync Channel, and what data is written out to an XML queue when a Sync Channel build is triggered.

Note that the <options> element was introduced in Ganymede 2.0, and is only acceptable in a Ganymede XML file with a version of at least major="1", minor="1".

Parent(s) Children
Various, based on the names of fields in an <object> Various, based on the names of object and field types defined
Attributes
None
Example
<options>
  <User option="1">
    <Username option="2"/>
    <UID option="2"/>
    <Home_Group option="1"/>
  </User>
  <Group option="1">
    <Group_Name option="2"/>
    <GID option="2"/>
    <Home_Users option="1"/>
    <Description option="0"/>
  </Group>
  <System option="0"/>
  <Admin_Persona option="0"/>
</options>

This simple example controls synchronization for User objects in a specific Sync Channel.

An options element can contain elements for each object type defined in the server's schema, which in turn can contain nested elements for each custom field defined in that object's schema definition. Both the elements corresponding to object types and the elements corresponding to individual field definitions will have a single attribute, option, containing 0, 1, or (in the case of a field element) 2.

These values correspond to the NEVER, WHENCHANGED, and ALWAYS elements in the SyncPrefEnum enum class.

0 stands for NEVER, and means that objects of the given type (or fields in an object type's definition) will never be synchronized to the enclosing Sync Channel.

1 stands for WHENCHANGED, and means that the object or field will be synchronized to the Sync Channel if the object or field was changed by a transaction.

2 stands for ALWAYS, which is only applicable for field elements. A field that is configured with a value of 2 will always be included when the containing object is modified by a transaction, whether or not that field was itself changed by the transaction.

See the Ganymede 2.0 Sync Guide for more details on the configuration and operation of a Ganymede Sync Channel.

Remember, as always with Ganymede object type and field names in XML, any spaces in an object type name or field name will be replaced by underscores when used as an element name in XML dumps and loads. In the above example, <Home_Group> refers to the "Home Group" field in the User object type.

<permmatrix>
The <permmatrix> element contains a mapping of permission values for object and field types defined in the Ganymede server. The <permmatrix> element is present in the Ganymede Role object, and defines what objects and fields a given Role allows access to. As Permission Matrix fields are scalar in Ganymede, only one <permmatrix> element at a time may be contained in a field element. The <permmatrix> element is designed to contain elements for each object type and field that permissions are set for.
Parent(s) Children
Various, based on the names of fields in an <object> Various, based on the names of object and field types defined
Attributes
None
Example
<permmatrix>
  <User perm="VCED">
    <Username perm="VCE"/>
    <UID perm="VC"/>
    <Home_Group perm="VCE"/>
  </User>
  <Group perm="VCED">
    <Group_Name perm="VCE"/>
    <GID perm="VC"/>
  </Group>
</permmatrix>

This simple example sets permission bits on the User object itself, along with the Username and UID fields defined as part of the User object type. Object and field names contained within a <permmatrix> element are required to have a perm attribute, which should contain a string with any combination of the following four characters:V, C, E, D. V stands for viewable, C stands for creatable, E for editable, and D for deletable. V, C, and E are allowed on elements corresponding to field names. Objects (like User in this example) may have V, C, E, and/or D.

The reason that the D flag is not enabled for fields is that there is no discrete notion of 'deletion' that applies to fields. Deleting an object is a distinct operation from editing it, but deleting a field and editing a field to set its contents to empty or null amounts to the same thing in Ganymede, so we don't bother tracking delete permissions for fields.

Remember, as always with Ganymede object type and field names in XML, any spaces in an object type name or field name will be replaced by underscores when used as an element name in XML dumps and loads. In the above example, <Home_Group> refers to the "Home Group" field in the User object type.

<invid>
The <invid> element contains a Ganymede object reference value, which is used to identify an object pointer in an invid field on the Ganymede server. The <invid> element must be empty.
Parent(s) Children
Various, based on the names of fields in an <object> None
Attributes
type
This attribute is mandatory, and contains an XML-encoded (underscores for spaces) object type string, with proper capitalization, to identify the kind of object this <invid> element is pointing to.
id
This attribute, if present, contains a string that is meant to uniquely identify a target object of type matching the value of the type attribute in this <invid> element on the Ganymede server. The targeted object may exist prior to XML file processing on the Ganymede server, or it may be created by processing of other <object> elements in the XML file by the xmlclient. If an <object> element of matching type with matching id is defined with an action attribute value of create, then all <invid> elements in the XML file with that type and id will point to the newly created object, and not any pre-existing object on the server that shared that type and id.

The id attribute will match against the label field specified for the specified object type.

num
This attribute, if present, holds an object number on the Ganymede server, and is used to address a pre-existing object on the server. This attribute should only be used when you explicitly want to address an object on the server, regardless of whatever other activity the <ganydata> element in the XML file defines.
oid
This attribute is present when an <invid> element is dumped out by a Sync Channel. It is a globally unique identifier for a pre-existing object, encoding both the type of the object target and its specific identity.
Example
<invid type="User" id="broccol"/>

Embedded Objects

In addition to the ten field types listed above, there is one unique case, and that is the case of embedded objects. I need to write about this in exhaustive detail.

Example

For example, a user object from the GASH schema kit might be represented in an XML file in the following fashion:

      <object type="User" id="broccol">
        <Username>broccol</Username>
        <UID>12003</UID>
        <Password><password crypt="j8hgwcyw232Jo"/></Password>
        <Account_Category><invid type="User_Category" id="normal"/></Account_Category>
        <Full_Name>Jonathan Abbey</Full_Name>
        <Division>CSD</Division>
        <Room>S321</Room>
        <Office_Phone>3199</Office_Phone>
        <Home_Phone>335-7681</Home_Phone>
        <Groups>
          <invid type="Group" id="omsprl"/>
          <invid type="Group" id="omsovr"/>
          <invid type="Group" id="omssys"/>
          <invid type="Group" id="genweb"/>
          <invid type="Group" id="gendof"/>
          <invid type="Group" id="omsnet"/>
          <invid type="Group" id="ganycvs"/>
          <invid type="Group" id="omjrst"/>
        </Groups>
        <Home_Group><invid type="Group" id="omssys"/></Home_Group>
        <Login_Shell>/bin/tcsh</Login_Shell>
        <Home_Directory>/home/broccol</Home_Directory>
        <Admin_Personae>
          <invid type="Admin_Persona" id="broccol:GASH Admin"/>
          <invid type="Admin_Persona" id="broccol:supergash"/>
        </Admin_Personae>
        <Netgroups>
          <invid type="User_Netgroup" id="omg-u"/>
          <invid type="User_Netgroup" id="omguse-u"/>
          <invid type="User_Netgroup" id="supad1-u"/>
        </Netgroups>
        <Directory_Volume>
          <object type="Embedded_Automounter_Map_Entry" id="103" num="103">
            <Automounter_Map><invid type="Automounter_Map" id="2"/></Automounter_Map>
            <NFS_Volume><invid type="NFS_Volume" id="23"/></NFS_Volume>
          </object>
        </Directory_Volume>
        <Email_Aliases>
          <string val="jonabbey"/>
          <string val="abbey"/>
          <string val="rust-admin"/>
        </Email_Aliases>
        <Signature_Alias>jonabbey</Signature_Alias>
        <Email_target>
          <string val="broccol@arlut.utexas.edu"/>
          <string val="broccol@csdsun7.arlut.utexas.edu"/>
        </Email_target>
        <Owner_list>
          <invid type="Owner_Group" id="OMG"/>
        </Owner_list>
      </object>