Data imports using XML files use a visual data mapper. Learn more in Import data with an XML file.

In the Data Mappings subtable, create a row for each source field you want included in the data import. 

  • The Source Type field tells the data import how to match the source field to the destination field. For example, a source type of Header tells the data import that the source fields are header values in columns, while a source type of Constant provides a single, a user-specified value that is input into the destination field. 
  • The Source Field is the location in the external data where you want to map a value from. 
  • The Destination Field is the location in the platform table where you want to map the value to. 
  • The Data Item Type dictates what type of data item the destination field is. Certain data item types require additional steps in their mapping, as seen in the subheadings below.

Name, Address, and Currency fields

Name, Address, and Currency fields require additional mappings. These field types are comprised of multiple values which must be split up and mapped individually. Then, you must create a data mapping which specifies the Format Definition you want used to combine the values when they are imported into the destination field. 

For example, if the destination field is ContactName, you must have First Name and Last Name as separate columns within your CSV or SFTP server, then create the following data mappings: 

Source TypeSource FieldDestination FieldData Item TypeMapping TypeMapping Subtype
HeaderFirstNameContactNameNameNameFirst or Given Name
HeaderLastNameContactNameNameNameKey Name / Surname / Name
ConstantExampleFormatDefinitionNameContactNameNameNameFormat

Once imported, the first and last name would be formatted and placed in the ContactName field as one stored value. 

Currency fields always require a currency value be mapped. Currency code and currency decimal are only required if the environment is multi-currency. Otherwise, the default is derived from the Currency Manager application. 

Date, Date Time, and Time

Date, Datetime, and Time fields require a Mapping Sub Type to ensure the field values are correctly imported. The Mapping Sub Type indicates the format for the value being stored. 

For example, a Mapping Type of Date has many options for Mapping Sub Type, such as Day, Month, Year or Year, Month, Day. If a non-standard time format is needed, select the Custom Option mapping sub type and enter the format in the mapping options field.

For DateTimes, Dates, and Times, use Java DateTimeFormatter for parsing. Make sure such formats are encapsulated in "".  For example, a DateTime input of 2026-02-25T15:21:44.092688Z is parsed when the Mapping Option is set to "yyyy-MM-dd'T'HH:mm:ss.SSSSSSX" including the starting and ending ".

Table Lookups

Table lookups pass in one, or many, values that are used to identify a record within the data import data. Once found, the table lookup stores the nwID or unique text value used to identify that record. You must pass as many values as are required to only find a single record. If the table lookup values match multiple records, the system won't be able to match your query and an error is thrown. 

Learn more in Table lookups and Table lookups and foreign keys.

Table lookup fields require a Mapping Sub Type that tells them where to find the unique ID for that record. Options include:

  • Lookup via Nextworld ID—Use when the imported data has an nwId. This populates the destination field with the nwId from the source record. 
  • Lookup via external ID—Use when the imported data has a unique external ID that must be imported into the platform. This allows other objects to still reference the external ID, even once the data has been imported. This is similar to Table Lookup By Value, except the field is always nwExternalId. 
  • Table Lookup By Value—Uses a single field's value to uniquely identify records. The system automatically builds a query to find a record base on the primary lookup of the table lookup data item. If the data item doesn't have a primary lookup, the system looks for the table. If you use the Mapping Options field, that value overrides the primary lookup of the data item and table. 
  • Table Lookup by Multiple Values—Uses multiple field's values to uniquely identify records. This functions the same as Table Lookup By Value, except you create a row for each field you want included in the query used to identify the record. This sub type  must have a mapping option to prevent the system from looking at the same lookup twice. Example seen below.

If the imported data has two Header fields of Company and City, you would create the following mappings:

Source TypeSource FieldDestination FieldData Item Type
Mapping Sub TypeMapping Options
HeaderCompanyDataImportTestsTableLookupTable LookupTable lookup by multiple valuesDataImportCompanyField
HeaderCityDataImportTestsTableLookupTable LookupTable lookup by multiple values
DataImportOrgUnitField

If the values in Company and City are Acme and Chicago, the query would look for a record in the imported data that has a value for Acme in the DataImportCompanyField and Chicago in the DataImportCityField field. If a single record is found with these conditions, the nwId of the record is imported into the Destination Table.

Multi-Select List Lookup

Multi-select list lookup data mappings enable you to pull in a list of values and map them into a different data structure than normal text values. 

The Multi-Select List Lookup Mapping Type requires a Mapping Sub Type that specifies how the values are formatted in the imported data. For example, comma delimiting would indicate that the list of values was separated by commas. If you have a comma delimited list in a CSV, the list needs to be wrapped in quotes, like "ExampleValue1, ExampleValue2, ExampleValue3."

Run Number and Row Number

Run number uniquely identifies each import which is run, while the row number identifies which row of the CSV file was processed. If your destination table has the nwImportRowNumber, nwImportRunNumber, and DataImportRunNumber fields, a value is automatically mapped into them when an import is run and you don't need to create a mapping in the Data Mappings subtable. Only create a Run Number or Row Number mapping if you want to use your own field. 

These fields are useful for integrations, logic blocks, and error tracking. For example, if you have multiple imports into an integration table, each run would have its own unique value. This would allow you to group the data based on when it was imported, process it in those groups, then move it into the live table within the platform. Or, you could use the run number to find and review errors from your import. Learn more in Integration logic blocks.

File Status and File Name

File status and file name are useful if your data import has multiple files included. These fields allow you to look at each file name and their status in order to determine if there are errors. 

If you want to track the file status, create a data item and make it a list lookup with the DataImportFileStatus lookup record, then map that value into your import. This allows you to initiate logic based on the status of your imported files. 

Additional Options

Additional configuration can be applied to any mapping type including: 

  • Work Field—Allows a value to be included in the data import which is not validated against the destination table. Values imported as work fields are included in the payload and passed to processing logic blocks. 
  • Null Profile—Sets the default value for a destination field by specifying one or more values that constitute null or empty.
  • Cross Reference—Modifies specific values from the source file before being imported into the destination field. This field is used if you are mapping values into a list lookup. 

For more information, see:

  • Dependent table lookup configuration for data imports
  • Table lookup configuration for batch data imports

Table lookup configuration for batch data imports

Table lookups are used in data import batch integrations to assign an imported data item with a nwId.  For example, in a Nextworld application you copy the value in a lookup field, you are copying the nwId of the record to which it is mapped. 

Table lookups are mainly driven by the Destination Field of the mapping. The Destination Field must belong to the Destination Table, and must be a Table Lookup type data item. Set the Mapping Type field to Table Lookup.

The sections below describe the process flow of importing table lookups.

Preprocessing

Before an import is run all table lookups are processed to find the related table, found in the Destination Table, decomposing composite fields, and validating related fields. Mappings are sorted into for value, nwId, and supporting lookups. Mappings that share a Destination Table are grouped so they can be processed together.

Processing

Table lookups are processed for each row in the CSV file. The first step is to process all supporting table lookups. Supporting table lookups are processed by value, meaning they can have multiple values. These are stored to be referenced later.

The next step is to build the main query for the table lookup. All table lookups that share a Destination Table are added to the query. Lookup via Nextworld ID, Lookup via external ID, and Lookup via Nextworld ID Mapping Sub Types pull values from the CSV file based on the mapping Source Field. Dependent lookups pull values from processed supporting lookups.

Query Execution

If the query is successful, the nwId of the returned record is entered as value for Destination Table. If the query returned nothing or the query returned more than one value an exception is thrown.