Creating a Lookup Field Mapping

Important Note: Before you can create a new Lookup Mapping you must first create a Lookup Query using the Lookup Queries tab on the Form Mapping.  For more information review the articles in this section:  Defining Lookup Queries

Lookup Field Mappings should be used whenever the field value that you want to migrate is not on the Source Form.  The Lookup Query is used to select a value from a different form either on the Source or Target server.

To create a new Lookup Mapping, first select the Target Field from the list of fields in the Field Mapping List, then select Lookup from the New Mapping field below.  A new screen is then presented to allow the Lookup Mapping to be completed:

First select the Lookup Query Identifier using the drop-down menu, then select the Lookup Field from the corresponding drop-down menu (based on the Lookup Query Form).   After selecting the Lookup Query Identifier, the details of the Query are displayed underneath in read-only format.

If no matching records are returned by the Lookup Query then you can define what action to take using the No Match Action field:

On No Match Action	Description
Set Null	Sets the target field value to Null;
Ignore	No value should be pushed to the target record. This will mean that if the target record exists already, any existing value will not be updated.
Skip Record	No target values are set for this record, skips to the next record;
Log Warning	For no match, the value should be set to NULL and a warning recorded.
Log Error	No target value is set but an error is recorded in the log.
Set Default	The Default value is used to set the target field instead.

In some cases, more than record is returned by the Lookup Query.  In this case, you can use the Multiple Match Action field to control the behaviour of the migration as follows:

Multiple Match Action	Description
Set Null	Sets the target field value to Null;
Ignore	No value should be pushed to the target record. This will mean that if the target record exists already, any existing value will not be updated.
Use First	Sets the target value to the field value returned by the first record in the Query.
Skip Record	No target values are set for this record, skips to the next record.
Log Warning	For multi match, the value should be set to NULL and a warning recorded.
Log Error	No target value is set but an error is recorded in the log.
Set Default	The Default value is used to set the target field instead.
Concatenate CSV	Sets the target field to a list of comma separated values based on the matched records retrieved from the lookup.

If you choose Set Default, then enter the Default value in the Default field next to the above options.

Note that Concatenate CSV delimits all values in the list with double quotes, even if only one value is returned.

Now use the Validate button to validate the Lookup mapping details.  Then use the Apply button to save your changes, or use the Revert button to revert back to the last saved version.

Related Articles

Introduction to Lookup Queries

Defining Lookup Queries

Creating a Source Lookup Query

Creating a Target Lookup Query