Creating & Managing Integration Rules for Vault Connections

Integration Rules allow developers to incorporate configurable rules for mapping object and document fields between two Vaults for use in a Spark Message Processor. When the target Vault receives a Spark message from the source Vault, the target Vault may need to transform the received data from a call-back query into a format it can understand. For example, when a Regulatory Vault sends the Study Protocol Title field to a Clinical Vault, the Clinical Vault can use an integration rule to map this field to their equivalent Study Description field.

Integration rules are fully configured and evaluated on the target Vault, which means it’s the target Vault’s responsibility to process received Spark messages.

Utilizing integration rules have several steps:

  1. Set up Integration Rule records within your Vault, which will contain the set of rules for your integration.
  2. Create Field Rules and Query Object Rules to define the set of rules which apply to your integration rule. If you’re creating a reference lookup, set up Reference Lookup object records.
  3. Develop a Spark message processor to utilize your integration rules. Learn more about Spark message processors in the Developer Portal.

Accessing Integration Rule Administration

You can view and manage integration rules from Admin > Connections > Integration Rules. You must have a security profile that grants the Application: Manage Integrations permission to access integration rules in the Connections tab.

About Standard Integration Rules

Standard Integration Rules are editable in the UI by default, including activating and inactivating existing rules using in-line editing. However, some Veeva provided integrations may restrict the ability to activate or inactivate Integration Rules as well as restrict the ability to edit Field Rule defaults.

About Field Rules

Field rules define the specific set of rules which apply to an Integration Rule. By selecting a target object and object field (or target document and document field), Vault sets the value of a field in the target Vault. Query Fields are like the SELECT portion of your call-back query, and if you need more specificity, you can add filters such as WHERE with query object rules.

Field Mapping

Field mapping sets the value of a field in the target Vault based on a field in the source Vault.

For example, the target Vault receives a message saying Product records have changed from the source Vault via a Spark message. Once received, the target Vault’s Spark message processor sets the country__v field on these records. To do this, the target Vault calls back the source Vault with an integration rule, setting the value of the source Vault’s country__v field to the country__v field in the target Vault.

If the data you’re mapping has exactly the same external keys, field mapping is all you need. However, most cases require the use of reference lookups to map the data in the source Vault to equivalent values in the target Vault.

Reference Lookup

Reference lookups provide additional transformations for field mappings through a predefined list of equivalent values between the source and target Vault. For example, when retrieving the value of country__v fields from the source Vault, reference lookups execute an additional transformation to map the source Vault’s value of “U.S.” to the target Vault’s equivalent value of “United States.”

Reference lookups support any-to-any mapping for all single-value field types. Multi-value fields are not supported. For example, Yes/No fields are supported, and multi-value picklists are not supported.

To create reference lookups, you must first define the list of reference lookup values for the Connection record.

If you need to create dynamic reference lookups rather than predefined values, you should instead use a Target Field Lookup when creating your field rules. For example, Admins can configure a field rule for a child object that uses parent__cr.name__v for an object reference instead of using predefined values in a reference lookup CSV. This eliminates the need to maintain reference lookup values, and instead developers can code their integrations to dynamically resolve object references.

Static Field Default

Static field defaults set the value of a field in the target Vault to a literal default value. For example, after receiving records from the source Vault, a field rule in the target Vault can set the description__c text field to “Received from integration,” or set a custom Priority picklist to “Requires Triage.”

You can also use field default rules in combination with field mapping or reference lookup rules. For example, you can specify a “fallback” or “default” value in cases where the query to the source Vault does not return a value. To do this, set a field default value as well as your field mapping or reference lookup values on your field rule.

If you’re setting an object field to a default value, there may be other field defaults configured. To avoid unexpected results, Admins should familiarize themselves with the order of operations for object field defaults.

About Query Object Rules

Query object rules provide an additional layer of specificity to your field rules. While field rules provide the SELECT portion of a query, query object rules provide filtering capabilities in a WHERE. For example, a field rule can select the Country field on Product object records. With query object rules, you can additionally specify that you’re only interested in object records where the Status is Active.

While query object rules work in conjunction with field rules, a query object rule is not tied to one particular field rule. For example, if you define your query object rule Filter Clause as status__v = 'active__v', your Spark message processor developer can apply this query object rule to all of the field rules in this integration rule.

Learn how to create query object rules.

About Primary Query Objects

Integration rules allow setting a Primary Query Object. By setting a primary query object on an integration rule, you constrain its field rules to a particular object or document while also getting access to the relationships on that object or document.

For example, there is a integration which needs to retrieve a Product Manufacturer’s Incident Phone Number, where Manufacturer is represented as an object relationship field on the Product object. By setting the primary query object to Product, integration rules have access to the relationship between Product and Manufacturer.

For example, the Vaccine product has a Manufacturer field with the value VeePharm, where VeePharm is a Manufacturer object record which has a text field labeled Incident Phone Number. Given the Vaccine product, this integration can quickly grab the Incident Phone Number on the related VeePharm manufacturer record.

Setting a primary query object constrains all field rule queries to this object. For example, once the primary query object is set to Product, field rules on this integration rule could not query for User object records that have the Incident Phone Number set as their Office Phone Number, assuming no relationship between Users and Product exists.

If no primary query object is set on an integration rule, the field rules are not constrained and you cannot access relationships.

How to Create an Integration Rule

To create an integration rule:

  1. From Admin > Connections > Integration Rules, click Create.
  2. Enter a Label for the integration rule. This is what Vault Admins see when configuring the rule.
  3. Enter a Name for the integration rule. If you’ve already filled in the Label field, Vault suggests a default Name. This is what developers use to reference the rule in a Spark message processor.
  4. Select an existing Connection where this integration rule should apply.
  5. Optional: Select an existing Integration Point where this integration rule should apply.
  6. Optional, but recommended: Select a Primary Query Object. If set, the primary query object constrains this integration rule’s field rules to the selected object or document while also giving you access to the relationships on that object or document. If omitted, this integration rule’s field rules are not constrained and you cannot access relationships.
  7. Click Save.

After creating an integration rule, create Field Rules which define the set of rules for this integration rule.

How to Create Field Rules

To create field rules for an integration rule:

  1. From Admin > Connections > Integration Rules, select the integration rule where you wish to create field rules.
  2. From the integration rule detail page, select + Create in the Field Rules section.
  3. Select the Target Object for this field rule.
  4. In the Target Object Field picklist, select a field on the target object.
  5. Optional: Change the Label or Name. Based on the object and field names, Vault suggests a default value for these fields. The Label is how Vault Admins reference this rule, and the Name is how developers reference this rule.
  6. Optional: If your Target Field is an object reference field corresponding to an object with an outbound relationship to this field rule’s Target Object, you can select a Target Field Lookup. This field allows developers to code integrations which dynamically resolve object references, eliminating the need to maintain reference lookup values. Only link__sys or unique fields related to the object referenced in the field rule’s Target Object are available as the Target Field Lookup. This field is only supported for Target Objects of type Object.
  7. Optional: If you’re creating a static field default, enter the Field Default value. If specified, this field rule will default the selected Target Object Field to this value if no value is specified during the creation of a new Target Object record. You can also set this field as a “fallback” value by setting this field as well as field mapping or reference lookup fields.
  8. Optional: If you’re creating a reference lookup, select a Reference Lookup Type and Reference Lookup object.
  9. Optional: If you aren’t creating a static default, specify the Query Object. Similar to the Target Object in the current Vault, this is the object in the source Vault. If your integration rule has a Primary Query Object configured, this field is constrained to that object.
  10. Optional: If you’ve specified a Query Object, select the Query Field. Similar to the Target Object Field in the current Vault, this is the field on the query object in the source Vault.
  11. Optional: If you’ve specified a Query Field, select the Query Field Type. This is the data type of the field in the source Vault.
  12. Optional: If you’ve specified a Query Field, add a Query Field Select. This field overrides the SELECT clause, which is helpful in cases where you need to transform the data with a VQL function such as TONAME(). If you’re providing an alias (AS) in this field, that alias must also exist in the Query Field for this rule. Learn more about TONAME(), TODISPLAYFORMAT(), LONGTEXT(), and RICHTEXT() in the Developer Portal.
  13. Click Save.

How to Create Query Object Rules

To create query object rules for an integration rule:

  1. From Admin > Connections > Integration Rules, select the integration rule where you wish to create object query rules.
  2. From the integration rule detail page, select + Create in the Query Object Rules section.
  3. Select the Query Object for this field rule. For example, product__v.
  4. Optional: Change the Label or Name. Vault suggests a default value for these fields. The Label is how Vault Admins reference this rule, and the Name is how developers reference this rule.
  5. Optional: Change the Status of this query object rule. This has no functionality up front, but Spark message processor developers can create custom logic using the rule Status.
  6. Under Filter Criteria, enter the Filter Clause. This is the logic for this query object rule, written with Criteria VQL. If the source Vault is available, use the token button to enter fields on the query object. For example, status__v = 'active__v'.
  7. Optional: Enter any custom tokens manually in the format {{token}}. Your Spark message processor developer must resolve these tokens.
  8. Use the Validate link to check if the VQL syntax is valid. However, this link only checks the VQL syntax for the current target Vault, and correct syntax may differ between the source and target Vault if the Vaults are on different versions. Learn more about VQL syntax in the Developer Portal.
  9. Click Save.