**Source URL:** https://general.veevavault.dev/medical/vault-sdk/sdk-integrations/spark-messaging/integration-rules.md # Integration Rules When using Spark messaging for Vault to Vault integrations, it may be necessary to transform data from the source Vault's data model to fit within the target Vault's data model. Integration Rules allow developers to incorporate configurable rules for mapping object and document fields between two Vaults into a `MessageProcessor`. Vault only supports integration rules for Vault to Vault integrations. Available transformation rules include: * **Field Mapping**: Map a source Vault field to a target Vault field. * **Reference Lookup**: Perform a lookup to map a source key value to target key value. * **Static Default**: Set a field to a static value. Integration rules are fully configured and evaluated on the target Vault. This preserves the loosely coupled characteristic of Spark messaging integrations. It is the target Vault's responsibility to process the received message. To set up integration rules: 1. Set up Integration rules through the Vault UI. [Learn more about this process in Vault Help](https://platform.veevavault.help/en/gr/62154). 2. Optional: To use reference lookups, you must set up reference lookup records to map data key values between Vaults. Learn how to set these up in the Vault UI in [Vault Help](https://platform.veevavault.help/en/gr/58198). 3. Develop a `MessageProcessor` with the following logic: 4. Retrieve data from the source Vault through VQL and HTTP Callout. 5. Set the VQL Describe Query header `X-VaultAPI-DescribeQuery` to `true`, which returns the source Vault data model. 6. Use `IntegrationRuleService` to evaluate your integration rules. ### Field Mapping {#field-mapping} Field mapping rules allow you to set the value of a field on a target object or document directly from a value returned from a VQL query to the source Vault. This is useful when you need to derive field values for a record in the target Vault from data coming from the source Vault. For example, you may want to provide the *Name* of a record from the source Vault as a cross-reference within an object field on the target Vault. When you create an HTTP Callout for a field rule, you may need to add functions such as [`RICHTEXT()`](/vql/references/system-limits-performance/queryable-field-types#Rich_Text_Field_Type) or `TONAME()` based on the query field type. You can retrieve the field type using `getQueryFieldType`. The example below retrieves the type of an object field, then appends the appropriate VQL function to the query field before adding it to a list, which can be included in an HTTP Callout. ``` @MessageProcessorInfo() public class ExampleProcessor implements MessageProcessor { public void execute(MessageContext context) { IntegrationRuleService service = ServiceLocator.locate(IntegrationRuleService.class); GetIntegrationRulesRequest request = service.newGetIntegrationRulesRequestBuilder().build(); GetIntegrationRulesResponse response = service.getIntegrationRules(request); for (IntegrationRule integrationRule : response.getIntegrationRules()) { List selectFields = VaultCollections.newList(); for (FieldRule fieldRule : integrationRule.getFieldRules()) { ObjectFieldType objectFieldType = fieldRule.getQueryFieldType(ObjectFieldType.class); switch (objectFieldType) { case LONGTEXT: selectFields.add("LONGTEXT(" + fieldRule.getQueryField() + ")"); break; case RICHTEXT: selectFields.add("RICHTEXT(" + fieldRule.getQueryField() + ")"); break; default: selectFields.add(fieldRule.getQueryField()); } } } } } ``` ### Reference Lookups {#Ref_Lookup_Rules} Reference lookup rules allow you to set the value of a field on a target object or document indirectly from a value returned from a VQL query to the source Vault, using a lookup. This is useful in cases where a reference value differs between the source and target Vault. For example, you can indicate that the *Country* value “US” in the source Vault is equivalent to "United States" in the target Vault. Reference Lookups support the following data types, listed in the [ReferenceLookupType](https://repo.veevavault.com/javadoc/vault-sdk-api/26.1.0/docs/api/com/veeva/vault/sdk/api/integration/ReferenceLookupType.html) Enum: * Document types * Document lifecycle states * Object lifecycle states * Picklist values * Vault objects * [Generic](/vault-sdk/sdk-integrations/spark-messaging/integration-rules/#Generic) As a best practice, you should use global identifiers such as `external_id__v` to map data. You should only use reference lookups in cases where this is not possible. #### Target Field Lookups {#target-field-lookups} Rather than using predefined values for reference lookups, you can also create dynamic reference lookups with the `target_field_lookup` field. 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. This eliminates the need to maintain reference lookup values, and instead developers can code their integrations to dynamically resolve object references. The `target_field_lookup` field is only available if: * Your `query_field_type` is a Vault object. Target field lookups are not yet supported for documents. * Your `target_object_field` is an object reference field corresponding to an object with an outbound relationship to this field rule's `target_object`. #### Generic {#Generic} If the data type in the source Vault does not match the data type in the target Vault, or if you need to map a data type not listed in the [ReferenceLookupType](https://repo.veevavault.com/javadoc/vault-sdk-api/26.1.0/docs/api/com/veeva/vault/sdk/api/integration/ReferenceLookupType.html) Enum, Admins can manually map data types using the `GENERIC` option. `GENERIC` supports any-to-any data type mapping except for multi-value fields. For example, Boolean (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. ### Static Field Defaults {#static-field-defaults} Field default rules allow you to set the value of a field on the target object or document to a default value. This is useful in cases where you want all records created via the integration to have a default value for a field. For example, you may want the *Description* field to say "created by a Vault Integration." You can also use field default rules in combination with field mapping or reference lookup rules. For example, you can specify a fallback value in cases where the query to the source Vault does not return a value. When creating field defaults with the MDL `Fieldrule` subcomponent, note the following requirements for the `field_default` attribute based on field type: * Text fields accept alphanumeric values up to the length of the field * Number fields accept any integer or decimal value * Yes/No (Boolean) fields can have values of either `true` or `false` * Date fields must be in GMT and formatted as `{yyyy}-{mm}-{dd}` * DateTime fields must be in GMT and formatted as `{yyyy}-{mm}-{dd}T{hh}:{mm}:{ss}.{mmm}Z` * Single-value picklist fields must be the `name__v` for the picklist value. For example, `requires_triage__c`. * Multi-value picklist fields must be the `name__v` for the picklist values, separated by a comma. For example, `saturday__c,sunday__c`. --- **Previous:** [Message Delivery Event Handler](/medical/vault-sdk/sdk-integrations/spark-messaging/message-delivery-event-handler) **Next:** [User Exception Messages](/medical/vault-sdk/sdk-integrations/spark-messaging/user-exception-messages)