Creating & Managing Reference Lookups for Vault 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 “US.” in the source Vault is equivalent to “United States” in the target Vault.

Reference lookups are a type of integration rule which allow you to configure a lookup to set 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 Integration Rules. Learn more.
  2. Set up Reference Lookup object records. This article will walk you through this step.
  3. Develop a Spark message processor to utilize your reference lookups. Learn more about Spark message processors in the Developer Portal.

Accessing Reference Lookup Administration

You can view and manage integrations from Admin > Connections. Once here, 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

To create Reference Lookup records:

  1. From the Connection details page, expand the Reference Lookups section.
  2. Click Add.
  3. From the Create Reference Lookups dialog, select a type for this reference. For example, Object. If you have mismatched data types where the type in the source Vault is different from that in the target Vault, select Generic.
  4. Next, 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, and must be unique. We recommend using the record ID. For example, the ID for the “US” Country record in the source Vault.
  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.
  10. Set the Status. We recommend setting lookups as Inactive until you are ready to code them into your Spark message processor.
  11. Click Save. If you have more Reference Lookup records to add, you can click Save + Create.
  12. Optional: If you want to add values for everything associated with the object, we recommend using a CSV template.

Generic

If the data type in the source Vault does not match the data type in the target Vault, or if you need to match a data type not listed here, Admins can manually map data types using the Generic option.

Generic supports any-to-any mapping for all single-value fields. Multi-value fields are not supported. For example, Yes/No fields are supported, and multi-value picklists are not supported. As a best practice, only use Generic if your required data type is not available.

Exporting and Loading Reference Lookup Templates

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.