# Creating & Managing Reference Lookups for Connections

When creating a Vault-to-Vault integration, it may be necessary to transform data from the source Vault's data model to fit within the target Vault's data model. For example, you may need to indicate that the `country__v` value "U.S." in the source Vault is equivalent to "United States" in the target Vault.

Reference lookups further define an Integration Rule via its Field Rules, where the reference lookup sets the value of a field on a target object or document indirectly from a value in the source Vault.

Creating reference lookups has three steps:

  1. Set up _Reference Lookup_ object records. This article walks you through this step.
  2. Set up _Integration Rules_ containing <a href="/en/gr/62154/#create-field-rule">_Field Rules_</a>
.
  3. Develop a Spark message processor to utilize your reference lookups. Learn more about <a class="external-link " href="https://developer.veevavault.com/sdk/#Message_Processor" target="_blank" rel="noopener">Spark message processors in the Developer Portal<i class="fa fa-external-link" aria-hidden="true"></i></a>.

## Accessing Reference Lookup Administration

You can view and manage integrations from **Admin** > **Connections**. Once there, select a record with a _Vault to Vault Connection Type_. On the _Connection_ details page, you will find a **Reference Lookups** section.

You must have a security profile that grants the _Application: Manage Connections_ permission to access _Connections_ in the **Connections** tab.

## How to Create Reference Lookup Records {#create-reference-lookup}

To create _Reference Lookup_ records:

1. From the _Connection_ details page, expand the **Reference Lookups** section.
2. Click **Add**.
3. In the **Create Reference Lookups** dialog, select a **Reference Lookup Type**, for example, _Object_. The [Generic][1] type can be used when:
     * You are mapping a single-value picklist.
     * There are mismatched data types where the type in the source Vault is different from that in the target Vault.
4. Select the **Target Object**, for example, _Country (`country__v`)_. If you've selected _Generic_ as the type, enter a _Name_ that ends in `__c`. Only lowercase, alphanumeric characters and underscores (`_`) are allowed.
5. Click **Continue**.
6. If you're creating a lookup of type _Object_, select a **Target Key Field**. This is the field on the object used to map values between Vaults. We do not recommend selecting `name__v` as the key field, as object record names can change. Instead, we recommend using a static field such as ID.
7. Next, you need to add your first value to the lookup. Click **Add**.
8. Enter a **Source Key**. This key identifies the object record in the source Vault. We recommend using the record ID. For example, the ID for the "US" _Country_ record in the source Vault. You can use the same **Source Key** with multiple target keys if **Dynamic** is selected on the **Target Key** field.
9. Select a **Target Key**. This key identifies the object record in the target Vault. For example, select _United States_ from the list of available object records in the target Vault. If your lookup type is _Generic_, you must enter this value manually. Select **Dynamic** to use a conditional formula to apply the **Target Key** value.
10. Optional: Select a **Query Object**. You can only use the fields on the _Query Object_ to populate the _Target Key_ field via a conditional formula. This field is required if _Dynamic_ is selected on the _Target Key_ field. Be aware that the _Query Object_ is not selectable if the connection is not active.
11. Optional: Enter a <a href="/en/gr/42857/">formula</a>
 that applies the _Target Key_ value if evaluated to true. For example, the classification of documents crosslinked from the source Vault to target Vault must be determined by the _Region_ value. In this example, you could use a formula such as, `region__c = 'us__c'` to apply the document's _Target Key_ value. The formula must evaluate to a single value. You can only use fields from the _Query Object_ to build the formula. If condition formulas on multiple reference lookups for the same _Source Key_ evaluate to true, Vault selects the value that matches the lowest record ID of the reference lookups. The formula is required if _Dynamic_ is selected on the _Target Key_ field.
12. Set the **Status**. We recommend setting lookups as _Inactive_ until you are ready to code them into your Spark message processor.
13. Click **Save**. If you have more _Reference Lookup_ records to add, you can click **Save + Create**.
14. Optional: If you want to add values for everything associated with the object, we recommend using a [CSV template][2].

Once you've created the desired lookups, create applicable <a href="/en/gr/62154/#create-int-rule">_Integration Rules_</a>
 with <a href="/en/gr/62154/#create-field-rule">_Field Rules_</a>
 referencing the new lookup.

### About Generic Lookups {#Generic}

*Generic* supports any-to-any mapping for all single-value fields. As a best practice, only use *Generic* when your required data type is not available.

Admins can manually map data types using the *Generic* option when:

* The data type in the source Vault does not match the data type in the target Vault.
* You need to match a data type not listed here.
* You need to match a single-value picklist. Multi-value fields (including picklists) are not supported.

For single-value picklists, you must additionally populate the picklist's label (as opposed to its `name__v`) as both the source and target keys.

## Exporting and Loading Reference Lookup Templates {#Template}

To easily update many reference lookup values at once, you can export a fillable template to update all records in bulk. To do so, click **Export Template** from the _Reference Lookup_ details page.

Vault downloads the template as a CSV file with the following columns:

  * **Target Name (for display / reference use only)**: This pre-populated column lists the name of every record in the target Vault associated with this target object, up to a maximum of 2,000 records.
  * **Target Key**: This fillable column lists the _Target Key Field_ value used to identify this record in the target Vault. For example, if your _Target Key Field_ is ID, enter the IDs associated with these records in the target Vault.
  * **Source Name (for display / reference use only)**: This fillable column is available to list the name of every record in the source Vault associated with this target object.
  * **Source Key**: This fillable column lists the keys to identify the object record in the source Vault, and must be unique. We recommend using the record ID. For example, the ID for the "U.S" _Country_ record in the source Vault.

After filling in your exported template, you can quickly load your values into Vault. To do so, click **Load Reference Lookup** and select your completed CSV. When the load process is complete, you will receive a notification. If there are any errors in your load, the notification will contain a link to download the error log.

 [1]: #Generic
 [2]: #Template