# Creating & Managing Integration Rules for 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. To utilize integration rules, you must: 1. [Set up _Integration Rule_ records][1] within your Vault, which will contain the set of rules for your integration. 2. [Create _Field Rules_][2] and/or [_Query Object Rules_][3] to define the set of rules which apply to your integration rule. If you require a reference lookup, [set up _Reference Lookup_ object records](/en/lr/58198/), then associate them with a relevant _Field Rule_. 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 {#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-map} 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][6] to map the data in the source Vault to equivalent values in the target Vault. ### Reference Lookup {#ref-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](/en/lr/58198/). If you need to create dynamic reference lookups rather than predefined values, you should instead use a [Target Field Lookup][4] 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-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](/en/lr/42778/#order-of-operations).
## About Query Object Rules {#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][3]. ## About Primary Query Objects {#about-primary-query}
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 {#create-int-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][8] 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 {#create-field-rule} 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][9], 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][6], 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 AS, TONAME(), TOLABEL(), TODISPLAYFORMAT(), LONGTEXT(), and RICHTEXT() in the Developer Portal. 13. Click **Save**. ## How to Create Query Object Rules {#create-query-rule} 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](/en/lr/1037069/). 9. Click **Save**. [1]: #create-int-rule [2]: #create-field-rule [3]: #create-query-rule [4]: #target-field-lookup [6]: #ref-lookup [8]: #about-primary-query [9]: #static-default