dotCMS' content Import Tool: Or how to save time on bulk content imports and edits.

$URLMapContent.title

dotCMS' content Import Tool: Or how to save time on bulk content imports and edits. Posted: 08.20.2009

When should you use it?

The short answer: anytime you have to upload or update a large amount of content. Depending on the complexity of your structures, it could start at 10 pieces of content where you would actually save more time putting your information in a CSV, and importing it all at once.
Nevertheless, here are the two most common reasons for using the dotCMS import tool.

  1. You need to migrate content from another system: If you had information such as "Events" handled via a third party vendor and wanted to use the dotCMS calendar to manage your events, you'd use the import tool to get all of that content into the dotCMS. As long as you can export the content from your third party system to a CSV file, you're in good shape. The CSV will then need to be formatted to match the "Event" structure (by default the only required fields are; Title, Start Date, End Date) before the import can be run. How do I know how to format my CSV file correctly?
  2. You need to add or update a large amount of content at once: Let's say that you're in higher education and that once a year you need to add the new rosters for all of the teams for the upcoming season. Instead of adding new players and updating existing players one at a time, you can create a CSV file with all of that information and import it at once. FTW: Since the CSV import supports the import of category values, your CSV file would know which players to associate with which teams.

Where do I get started?

Remember how adding content in the dotCMS manually is a similar process than importing it via CSV? One reason is that in both cases the process begins from the same location, the "Content" page on the dotCMS. However, the only difference is that whereas you would usually select your content type and select "Add New Content", to import content you'd click on the "Import Content" link at the top of your page. Bonus: You can also select the Import shortcut by hovering over the "Content" tab.

Once you're in you'll be asked to select what type of content you'd like to import, select your key fields if you're updating content that already exists, and browse for your CSV. You'll then proceed to the import preview screen which will notify you of any errors or changes that will be made should you confirm the import. (Note: A key field is a field used as a reference when checking for existing content on the dotCMS. When a key field is selected, the import will update all non-key fields of the existing piece of content with those in the CSV file)

For more information on exactly how to go about importing content and the overall process, please refer to our documentation on Importing Content.

Easy as 1-2-3...3.5:

Importing content in the dotCMS via CSV is not a difficult process at all. As long as your CSV file is formatted correctly, you'll be pretty much set with just these few steps:

  • Create your CSV file (er rcommend using the dotCMS CSV Sample tool) for your structure
  • Populate your file with the content you'd like to import
  • Run your file through the dotCMS import tool
  • Give yourself a pat over the shoulder

Not feeling too adventurous? You can always split your CSV file into smaller bits if you prefer. This may help reduce the time it takes for the content to be imported, but will also make it easier for your to read the Preview page and locate any potential errors in your CSV file.

Hints, Best Practices, and other Uses:

Now that you know all about the import tool, here are a couple of things that'll ensure you make the most out of it.

  • Use the dotCMS CSV Template generator to get you started. Before you create any type of CSV file template for content import, I highly recommend that you use the import tools' CSV example file/template. It generates a custom CSV template for any structure on your dotCMS instance. You'll find a link for it on the "Import Content" page above the CSV upload field.
  • Import content's basic information, handle the rest via dotCMS Content Page.
    When you have complex structures with a large percentage of optional fields, limit your CSV import to the most important fields. There's no need to run through 2000 rows of data to find two events that have a location. Just upload the event information and add the location to these two pieces of content by search for them on the "Content" search page.
  • Use the CSV Import tool to make bulk edits to content existing in the dotCMS.
    Let's say you want that one of you create a new category for your news content, and you'd like to categorize existing content with this category. Instead of going one by one and re-categorizing your content, you can export all of your news items using the dotCMS Export tool, then bulk-edit your CSV file, and re-upload it into the dotCMS.
    Make sure that you choose key fields when updating content via the import tool, otherwise you're going to end up with a lot of duplicates (one step forward....).
  • The dotCMS also has a bulk import tool for adding users to the dotCMS.
    If you can't have enough of the content import tool, and you need to import something else, you can try our user import tool. It works much in the same way, offering you a CSV Template export for your user information, so that you can add a batch of users if you were for example creating a new mailing list in the dotCMS with users that were not yet in your system. (Note, you'll need access to creating dotCMS users to access this feature. This is a link called "Load Users" that can be found next to the "Create User" link at the top of the User Manager page.
  • When migrating content from another system, don't limit yourself to the existing fields.
    Collect your basic information like Event Start Date, Title, and Event End Date, and then use the dotCMS to dress things up. This is like the import tools' 1-2 punch combo, use it. Run your import and get your basic data in the dotCMS, and then go back to your content and add your custom field values like Videos, Tags, Images and so on.
  • Remember, the import tool can be used in combination with the "manual" content editing method in any order. You can first add your content manually, then edit via import. You can import a bunch of pieces of content and edit one or more of them manually afterward, and the wheel goes round and round.
  • The dotCMS also has a bulk import tool for adding users to the dotCMS.
  • If you can't have enough of the import tool, and you need to import something else, you can try our user-import tool. It works much in the same way, offering you a CSV Template export for your user information, so that you can add a batch of users if you were for example creating a new mailing list in the dotCMS with users that were not yet in your system.


New report from Digital Clarity Group notes that a majority of digital marketing teams don’t or can’t use all the software capabilities they have, creating “shelfware” or “underused” software. Gain fresh perspective on the challenges facing digital marketers. Download Now.