Importing data

The data file, which is used by the importer is basically a self-explanatory collection of assets.

<model xmlns="http://namespaces.csutils.sf.net/importer/model/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://namespaces.csutils.sf.net/importer/model/1.0.0 importer.xsd ">
  <assets>
    <asset type="{myns}OrgExample">
      <names>
        <name locale="de_DE">Org1</name>
        <name locale="en_US">Org1_en</name>
        <name locale="en_GB">Org1_en</name>
      </names>
      <attributes>
        <slot name="OrgExampleAttr1"><value>Value 5</value></slot>
        <slot name="OrgExampleAttr2">
          <value>Value 2</value>
          <value>Value 1</value>
        </slot>
      </attributes>
    </asset>
  </assets>
</model>

The example would import an instance of a custom asset type named mynsOrgExample. As you can see, the assets names and slots are specified.

Identifications

This is sufficient for trivial data. In general, however, there is the problem of identifying assets:

  • To create a relationship, you need to identify the target object. It doesn't matter, whether the target object is already existing or is imported as part of the same data file.
  • To update or delete objects, you need to identify the object, which is being updated, or deleted.

    The importer supports two different possibilities to identify objects:

  • Identifications by name; this assumes that object names (or, more precisely, the combination of name and locale) are unique.
  • Identifications by unique slot values; this assumes that there is a slot attribute with a unique value for every instance.

    Identifications are specified as part of the data file. Here's an extended version of the above data file, which would establish a relationship between two assets:

    <model xmlns="http://namespaces.csutils.sf.net/importer/model/1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://namespaces.csutils.sf.net/importer/model/1.0.0 importer.xsd ">
      <identifications>
        <uniqueName assetType="{myns}OrgExample"/>
        <uniqueName assetType="{myns}UserExample"/>
      </identifications>
    
      <assets>
        <asset type="{myns}OrgExample">
          <names>
            <name locale="de_DE">Org1</name>
            <name locale="en_US">Org1_en</name>
            <name locale="en_GB">Org1_en</name>
          </names>
          <attributes>
            <slot name="OrgExampleAttr1"><value>Value 5</value></slot>
            <slot name="OrgExampleAttr2"><value>Value 2</value></slot>
          </attributes>
        </asset>
    
        <asset type="{myns}UserExample">
          <names>
            <name locale="de_DE">User1</name>
          </names>
          <attributes>
            <slot name="UserExampleAttr1"><value>Val 1</value></slot>
            <relation name="EmployeeOf"><target name="Org1"/></relation>
          </attributes>
        </asset>
      </assets>
    </model>
    

Relationshiphs

The data file in the previous section specifies that organizations and users are identified by name. In particular, it establishes a relationship between the user named User1 and the organization named Org1:

        <relation name="EmployeeOf"><target name="Org1"/></relation>

Multiple targets may be specified:

        <relation name="EmployeeOf">
          <target name="Org1"/>
          <target name="Org2"/>
        </relation>

Updates

To update data, you use the same data file than for inserts. The main difference is, that an identification is required. For example, in the case of identification by name, the importer assumes that an object is being updated, if an object with the same name is already existing.

Identification by slot values

As an alternative to identification by name, you might use identification by unique slot values. Assuming that organizations and users have a unique slot called "uniqueKey", we might rewrite our sample file from above like this:

<model xmlns="http://namespaces.csutils.sf.net/importer/model/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://namespaces.csutils.sf.net/importer/model/1.0.0 importer.xsd ">
  <identifications>
    <uniqueSlot attributeName="uniqueKey" assetType="{myns}OrgExample2"/>
    <uniqueSlot attributeName="uniqueKey" assetType="{myns}UserExample2"/>
  </identifications>

  <assets>
    <asset type="{myns}OrgExample">
      <names>
        <name locale="de_DE">Org1</name>
        <name locale="en_US">Org1_en</name>
        <name locale="en_GB">Org1_en</name>
      </names>
      <attributes>
        <slot name="uniqueKey"><value>Org1Key</value></slot>
        <slot name="OrgExampleAttr1"><value>Value 5</value></slot>
        <slot name="OrgExampleAttr2"><value>Value 2</value></slot>
      </attributes>
    </asset>

    <asset type="{myns}UserExample">
      <names>
        <name locale="de_DE">User1</name>
      </names>
      <attributes>
        <slot name="uniqueKey"><value>User1Key</value></slot>
        <slot name="UserExampleAttr1"><value>Val 1</value></slot>
        <relation name="EmployeeOf"><target slotValue="Org1Key"/></relation>
      </attributes>
    </asset>
  </assets>
</model>