10.12.18.�Configure Import and Export

The Import and Export configuration allows you to set options for importing data from XML files as an alternative to the CSV Import tool. These data might be generated manually or by other database or e-commerce systems. For example xTuple supports importing orders from Yahoo! stores.

Importing data from XML files is a multi-step process:

The files have to be received from the originator and placed on a computer file system where the xTuple application can find them.
Any wrapper information has to be stripped off, such as mail headers for files received by electronic mail.
The XML has to be converted from its original format to one understood by the xTuple application.
The converted file has to be read by the xTuple application and its contents inserted into the database.

xTuple currently does not automate the first two steps in this process.

xTuple uses XSLT to convert XML files from one format to another. XML file formats are described in DTDs. The xtupleimport DTD defines an XML file format which can be directly imported by the xTuple application. This DTD defines XML tags with names that correspond exactly with the names of views and columns in the xTuple import API.

An XSLT file for transforming Yahoo! OrderList files for import into an xTuple database is available from xTuple. If you need to import data files in other XML formats you must write your own XSLT to convert the data to conform to xTuple's DTD.

To configure which transformations to use for XML files in various formats, click the XSLT Mapping tab on the Configure Import and Export window.

Configure XSLT Mapping

When configuring XSLT Mapping, you are presented with the following options:

Default XSLT File Directories: The XSLT files used to perform the translation between XML data formats must be present on the file system of the computer which is running the xTuple application. This set of options lets you define one directory for each operating system platform where the application should look for XSLT files.
Map of XSLT import and export filters: This is a list of document transformations recognized by the xTuple application. These transformations are called filters.

To the far right of the list of import and export filters, the following buttons are available:

NEW: Opens the screen for entering new XSLT import and export filters.
EDIT: Opens the screen for editing existing XSLT import and export filters.
DELETE: Delete existing XSLT import and export filters.

To create a new XSLT Map, select the NEW button. The following screen will appear:

XSLT Map

When creating a new XSLT Map, you are presented with the following options:

Map Name

This is a name you choose to describe this map.

Document Type

This is the XML document type that the application will use to find the correct filter to use when importing an XML document. When the application starts to import an XML document, it looks for the DOCTYPE processing directive at the top of the file. If the DOCTYPE is xtupleimport then no transformation is required. Otherwise it searches for a match in the Document Type and System Identifier columns to find the correct filter to use when importing the file.

The Document Type of an XML file is the name of its root element.

System Identifier

This is the System Identifier that the application will use to find the correct filter to use when importing an XML document.

The System Identifier is a URI that describes how to get the DTD for the XML document.

Import XSLT File Name

This is the name of the XSLT file that will be used to transform XML files with this Document Type and System Identiifer to xTuple's format for XML files. If the name of the file is a full path, starting with a drive letter on Windows or a / on Macintosh or Linux, then the application will look for this file using this full path specification. If the name is a simple filename (like myTransform.xsl) or a relative pathname (like oasis/from_ubl.xsl) then the application will look for it in the default XSLT directory defined on the Configure Import and Export window.

Export XSLT File Name

This is the name of the XSLT file that will be used to transform XML files generated by xTuple to a file of the given Document Type and System Identifier.

Note

Exporting XML is not currently supported by xTuple. At this time the Export XSLT File Name on the XSLT Map window and the XML Export tab on the Configure Import and Export window are placeholders for future development.

To the far right of the screen, the following buttons are available:

CANCEL: Cancels any changes to the XSLT Map and returns to the Configure Import and Export window.
SAVE: Saves the changes to the XSLT Map and returns to the Configure Import and Export window.

The XML Import tab on the Configure Import and Export window lets you define how the transformations are to be performed.

XML Import

When configuring XML Import processing you are presented with the following options:

XSLT Processor

XSLT is a language for transforming XML documents. To apply an XSLT stylesheet to a given XML document you need an XSLT processor. This is a program that interprets or compiles the XSLT and then performs the transformation on the XML file.

Note

Each XSLT processor has its own command-line syntax.

Use External XSLT Processor. Commands

Lets you define the command line that the xTuple application should execute to perform the transformation. Two arguments that will always be required are the name of the XSLT file which describes the transformation and the XML file to be transformed. When typing the command line that should be run to call the XSLT processor, put %f where the XSLT processor expects to find the name of the XML file and %x where the XSLT processor expects to find the name of the XSLT file.

In the figure you see three different XSLT processors defined. Each has its own syntax, which is reflected by the differences in the sequence of options and the way run-time parameters are passed to the stylesheets. Note that msxsl.exe takes the XML and XSLT files in a different order than the other two processors.

XSLT run-time parameters let you write a stylesheet with default values that can be changed when you run a transformation without editing the stylesheet itself. In this example, written to use xTuple's stylesheet for importing Yahoo! orders, the customer_default_tax_authority parameter is set to INET; when Customer records are created they will all be assigned the tax authority INET.

Default Import File Directories

This names the directory on each platform that the xTuple application will search when the user wants to import XML files. It is used to populate the Import XML window.

XML File Handling Options

This set of options lets you choose what the application should do with XML files after they have been imported successfully. Files which lead to errors during import will be left in place.

Do nothing after successful import: If you choose this option then the application will leave imported files unchanged in the import directory.
Rename after successful import. Append: If you choose this option then the application will leave the files in the import directory but will add a suffix to the file. You must give a suffix in the adjacent text field if you select this option.
Move after successful import to: If you choose this option then the application will move the files to the directory you name after the import is complete. If the directory name is a simple or relative path then the application assumes this is a subdirectory of or is relative to the Default Import Directory.
Delete after successful import: This will remove the files from the import directory after they have been imported.

Note

The XML Export tab is currently empty. It is a placeholder for future development.