Importer 2.x

Legacy documentation for Importer 2.x.

Importer lets you import multiple kinds of data into various types of ExpressionEngine content:

  • CSV (imports into Channel Entries or Members)
  • JSON (imports into Channel Entries or Members)
  • XML (imports into Channel Entries or Members)
  • EE Relationship Fields (imports into a Playa field)
  • Playa Fields (imports into a Playa field)

CSV

Data Source: File

Valid Content Types: Channel Entries and Members

You can import data from a CSV (comma-seperated values) file with Importer. CSV files can be manually generated and edited with a text editor, and is also a popular option available for export from many applications. In the import profile, you can specify whether the values are separated by comma, tab, or semicolon. Be sure that each value is wrapped in an encloser character (such as quotes) so Importer doesn't misread some data. You can also specify whether or not the first row of values is column names and should be omitted from the import. It is highly suggested that the first row of data be column names to better faciliate importing.

click to enlarge

Below is sample formatting of what a CSV file should look like for importing into Channel Entries:

"title","author","body","extended","categories","tags","status"
"CSV Test Entry - Alpha","support@solspace.com","A regular ol body field","Duplicate Test - Extended","One,Two","cheese,rainbows","open"
"CSV Test Entry - Beta","support@solspace.com","What do you mean I have a body?","Go go gadget field","Two,New Category","pies,cheese,peanuts","closed"

And for a Members import:

"username","screen_name","first_name","email"
"brettb","Brett Bretterson","Brett","brett@example.com"
"robr","Robert Robertson","Robert","robert@example.com"

JSON

Data Source: File

Valid Content Types: Channel Entries and Members

You can import data from a JSON file with Importer. You can optionally specify the name of a primary JSON element to allow for importing of more complicated data. For example, your JSON file might contain a set of arrays, one of which is named data and contains the items you wish to import. You can otherwise leave this blank. To allow manual uploading of JSON files, JSON needs to be added to config/mimes.php file:

'json'    =>    array('application/json', 'text/javascript'),

click to enlarge

Below is sample formatting of what a JSON file should look like for importing into Channel Entries:

[
    {
        "title":"JSON Test Entry - Alpha",
        "author":"support@solspace.com",
        "body":"A regular ol body field",
        "extended":"Duplicate Test - Extended",
        "categories":
            {
                "category":["One","Two"]
            },
        "tags":"cheese,rainbows",
        "status":"open"
    },

    {
        "title":"JSON Test Entry - Beta",
        "author":"support@solspace.com",
        "body":"What do you mean I have a body?",
        "extended":"Go go gadget arms!",
        "categories":
            {
                "category":["Two","New Category"]
            },
        "tags":"pies,cheese,peanuts",
        "status":"closed"
    }
]

And for a Members import:

[
    {
        "username":"brettb",
        "screen_name":"Brett Bretterson",
        "first_name":"Brett",
        "email":"brett@example.com"
    },

    {
        "username":"robr",
        "screen_name":"Robert Robertson",
        "first_name":"Robert",
        "email":"robert@example.com"
    },
]

XML

Data Source: File

Valid Content Types: Channel Entries and Members

You can import data from a XML file with Importer. You'll need to specify the primary XML element that contains the records you intend to parse. For example, in Atom feeds, entry would be used. Some XML documents may not validate as Strict XML. By choosing Loose XML, we may be able to still parse these documents. However, it will take longer to import. Characters like < and & are illegal in XML elements. In the event your data contains these characters (or any HTML), you will need to make sure the characters are HTML entities (ex: &lt; and &amp;). An alternative option is wrapping your applicable values with CDATA tags. Importer will not attempt to parse any data within the CDATA section and leave it untouched.

click to enlarge

Below is sample formatting of what an XML file should look like for importing in Channel Entries:

<?xml version="1.0" encoding="utf-8"?>
    <entries>
        <entry>
            <title>XML Test Entry - Alpha</title>
            <author>support@solspace.com</author>
            <body>A regular ol body field</body>
            <extended>Duplicate Test - Extended</extended>
            <categories>
                <category>One</category>
                <category>Two</category>
            </categories>
            <tags>cheese,rainbows</tags>
            <status>open</status>
        </entry>
        <entry>
            <title>XML Test Entry - Beta</title>
            <author>support@solspace.com</author>
            <body>What do you mean I have a body?</body>
            <extended>Go go gadget arms!</extended>
            <categories>
                <category>Two</category>
                <category>New Category</category>
            </categories>
            <tags>pies,cheese,peanuts</tags>
            <status>closed</status>
        </entry>
    </entries>

And for a Members import:

<?xml version="1.0" encoding="utf-8"?>
    <members>
        <member>
            <username>brettb</username>
            <screen_name>Brett Bretterson</screen_name>
            <first_name>Brett</first_name>
            <email>brett@example.com</email>
            <birthday month="12" year="1941" day="7">1941-12-07</birthday>
        </member>
        <member>
            <username>robr</username>
            <screen_name>Robert Robertson</screen_name>
            <first_name>Robert</first_name>
            <email>robert@example.com</email>
            <birthday month="02" year="1980" day="29">1980-02-29</birthday>
        </member>
    </members>

EE Relationship Fields

Data Source: EE Relationship custom fields

Valid Content Types: P&T Playa custom field

ExpressionEngine Relationship fields allow you to relate a single channel entry per custom field and it will cache the data in ExpressionEngine's tables. The P&T Playa field type allows you to relate multiple entries per custom field AND it does not cache it but instead looks up the entries during template processing. This allows better performance and expanded caching abilities.

This essentially allows you to migrate/clone the data of 1 or more EE Relationship fields into a single Playa field. The exporting and importing of data happens all within existing EE channel entry data (you are not importing new data from an external file, etc).

The set up for this is straightforward. You simply choose your Channel and all the Relationship fields you wish to import.

click to enlarge

And then, you choose the Playa field to import into and in which order you wish the Relationship fields to be imported. Important Note: If the Playa field already has data, any imported data will be appended onto existing. If a Related Entry being imported already exists in the Playa Field, it will be ignored and not imported.

click to enlarge

P&T Playa Fields

Data Source: P&T Playa custom fields

Valid Content Types: P&T Playa custom field

Importer has the ability to combine multiple P&T Playa fields into a single Playa field. Works just like the ExpressionEngine Relationships field import (above), where you choose your Channel, your Playa fields, and then which Playa field you wish to import into and in what order.

This essentially allows you to clone the data of 1 or more Playa fields into a single Playa field. The exporting and importing of data happens all within existing EE channel entry data (you are not importing new data from an external file, etc).