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:

Set up Integration rules through the Vault UI. Learn more about this process in Vault Help.
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.
Develop a MessageProcessor with the following logic:
Retrieve data from the source Vault through VQL and HTTP Callout.
Set the VQL Describe Query header X-VaultAPI-DescribeQuery to true, which returns the source Vault data model.
Use IntegrationRuleService to evaluate your integration rules.

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() 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<String> 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

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 Enum:

Document types
Document lifecycle states
Object lifecycle states
Picklist values
Vault objects
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

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

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 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

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.