Importing data

If you have a large dataset, chances are you'll want to automate the process. To do this, you need to provide data in a format which Nymbol can understand. Currently the best way to provide this is in XML, and you can represent practically the entire structure of a collection, including its assets, taxonomies and custom data in a single XML file.

Example

Here's an example of a single object:

<?xml version='1.0'?>
<assets>
    <asset>
        <name>Assembly Rooms</name>
        <description>The Assembly Rooms comprises of a modernist reinforced concrete structure...</description>
        <subcollection>Derbyshire</subcollection>
        <latitude>52.923551</latitude>
        <longitude>-1.475792</longitude>
        <completed>1977</completed>
        <architect>Casson, Conder &amp; Partners </architect>
        <resource>
            <url>http://walkingarchitecture.co.uk/birmingham/upload/web11.png</url>
            <kind>image</kind>
            <name></name>
        </resource>
        <resource>
            <url>http://walkingarchitecture.co.uk/birmingham/upload/web13.png</url>
            <kind>image</kind>
            <name></name>
        </resource>
        <taxonomy>
            <name>Categories</name>
            <term>
                <name>Featured</name>
            </term>
        </taxonomy>
    </asset>
</assets>

Preparing the data for export

The XML file needs to be well-formed and contain a single <assets> element, inside which is each <asset> you want to export.

You don't need to specify the collection, as the user importing the data will first navigate to their empty collection then select the Import option. You can however specify the subcollection an asset should belong to using the <subcollection> tag, as per the example above. The important tags to remember are:

  • <name> - the name of the asset.
  • <description> - the description of the asset. See the section on this tag further down the page.
  • <latitude> and <longitude> - optional mapping coordinates for the object
  • <resource> - one tag for each resource. See the section on this tag further down the page.
  • <taxonomy> - a tag for each taxonomy the asset belongs to, with a set of matching <term> tags inside it that define the terms within the taxonomy to which this asset applies.

The <description> tag

You can specify the description for an asset in two ways: either by just placing the text of the decryption inside the tag (using Markdown syntax) or by specifying the languages in which the description is available. To make your descriptions multilingual, you'll specify your <description> tag like this:

<description>
    <language>en</languate>
    <body>[English language text]</body>
</description>
<description>
    <language>fr</language>
    <title>[Optional French name for the asset]</title>
    <body>[French language text]</body>
</description>

So quite simply, you'd just specify a different <description> tag for each language. Bear in mind, these aren't nested in a parent <description> tag, but are siblings of the <name> and optional <subcollection> tags.

The <resource> tag

You can specify the resources tied to your existing objects by using the <resource> tag, with one tag for each resource. Specifying resources as you see in the above example is pretty easy. The three tags you need are:

  • <kind> - the type of resource (text, image, audio, video, link). For embedded resources like YouTube videos and Flickr images, use the link type
  • <url> - the URL to the resource's media (not applicable to text resources)
  • <name> - an optional name for the resource

You can also specify a <description> for each resource, exactly as you would for an asset (see the above section on the <description> tag for details).

The <taxonomy> tag

Use the <taxonomy> tag to specify which taxonomies and terms apply to this object. See the Taxonomies guide for full details.

You start by defining the name of each taxonomy, then specify the terms underneath that apply to this particular object. The Nymbol importer will match up existing taxonomies in your collection with those that have the same name in your XML file (if you've ever looked at the XML file the WordPress export tool generates, you'll see how this behaviour is similar).

Specify a new <taxonomy> tag for each taxonomy that has terms relating to this object, like so:

<taxonomy>
    <name>Categories</name>
    <term>
        <name>Featured</name>
        <name>1970s buildings</name>
    </term>
</taxonomy>

<taxonomy>
    <name>Tours</name>
    <term>
        <name>Sightseeing</name>
    </term>
</taxonomy>

Within your <term> tags you can specify the following:

  • <name> - the name of the term (required)
  • <uid> - the UID of the term as found in the Nymbol database (used if you want to change an existing term's name)
  • <description> - an optional description for the term. The specs for this field are the same as in the <asset> tag, so see the section above on the <description> tag for more
  • <order> - an optional number used to order the application of terms to an asset, or more specifically, when viewing a taxonomy term, what order should the assets within it appear?

You can also specify custom fields for the term, as long as they relate to fields setup inside the Nymbol collection the user is importing the data into. See the section below on custom data.

Custom data

You can specify custom fields to be exported in your XML file. But please note, Nymbol will assume any unrecognised tag in your <asset> represents a custom field, so it will report errors if it can't find an existing field within the database. So you must make sure that you or your content curator sets up the custom fields within their Nymbol collection before performing the import. Also note that the import won't fail, but that if you have to redo the import, you'll need to delete the existing assets, as Nymbol doesn't check for existing assets and overwrite them.

For custom data, simply specify the field name as an XML tag, with the value inside it. Currently, only basic field types like short text, long text and whole number are supported.

Next guide: Syncing data → ← Previous guide