Collapse AllExpand All

3.1.1. Overview

The preferred format for data imports into xTuple is character-separated or comma-separated values (CSV) files. Examples of CSV files are fixed width or tab-delimited text files (.txt) and comma-delimited files (.csv). To facilitate these imports, xTuple provides a free CSV application called CSVimp. To learn more about working with CSVimp, xTuple's free tool for managing data imports, please see the online documentation here: http://www.xtuple.org/DataImportTool.

Tip

When you need to open a CSV file as an import file (or an XML file as a map), you may at first not see the file if the file extensions are absent or if they are different. In the File Type field, be sure to select All Files to make sure all the files located in your target directory are visible.

CSVimp is included as a selectable component when xTuple ERP is installed. You can access the data import tool within xTuple by navigating to System > Utilities > Maintain CSV Atlases. CSVimp is also available in a standalone version, which has a login screen similar to that of xTuple ERP. This allows you to connect the standalone CSVimp tool to whichever database you want.

There are three primary steps involved when CSVimp is used to import data (steps one and two are interchangeable):

  1. Define the Atlas

    An atlas is a collection of maps defining relationships between: A) the columns of the data that will be imported (CSV files) and B) the corresponding fields in the xTuple database. An atlas is saved as an XML file. The Atlas window will be open and ready for maintenance after you have navigated to System > Utilities > Maintain CSV Atlases in xTuple, or after you have logged into the standalone CSVimp tool.

    Note

    In many cases, an Atlas consists of only one map because the data for only one table will be imported.

    The atlas is one of the two screens you will see when opening the CSVimp tool. If an atlas has been predefined (as in the case of xWD), open the xml file that has been made available by navigating from within the atlas to File > Open.

    Tip

    For more advanced data manipulation when importing data, the Pre SQL and Post SQL tabs on the CSV Atlas screen can be used to provide extra SQL statements before and after the data is placed in the xTuple database.

  2. Load the import file

    As mentioned earlier, the import file needs to be a plain text CSV file. You must first load the file into CSVimp before you can start the import. To load the import file, on the CSV Tool screen navigate to File > Open CSV.

  3. Import the data

    This step places the data in the CSV file into the xTuple table as defined by the map that has been loaded in the Atlas screen. To perform the import, on the CSV Tool screen navigate to Import > Start. After the import, you can select the next map from the atlas to continue importing data for more tables. To do this, simply navigate to Map > Edit on the CSV Tool screen.

In the next section we will look at how these three data import steps described above apply to an xWD example.