Organizations using both a PromoMats Vault and a Medical Vault can utilize the Spark messaging framework to create a standard Vault to Vault connection. This connection transfers documents across Vaults, such as medical literature references or labeling documents, and automates the creation and updating of CrossLink documents and anchors. See About the PromoMats - Medical Vault Connection for detailed information about how the connection works.

PromoMats - Medical Vault Connection Components

The following components support the standard Vault to Vault PromoMats - Medical connection.


The PromoMats Medical Connection (promomats_medical__v) record is available from Admin > Connections in your PromoMats and Medical Vault. You must establish the Vault to Vault connection before using it.

Integration & Integration Points

The Integration and Integration Point objects enable Vault to manage the message queues and define what documents and data the connection maps from one Vault to another. These records are used by Vault to manage the connection and track any connection errors.

The PromoMats Medical Connection record includes the following default Integration records with standard Integration Point records in your PromoMats and Medical Vaults:

  • Inbound Documents
    • Documents Inbound Integration Point
  • Outbound Documents
    • Documents Outbound Integration Point
  • Anchors
    • Anchors Inbound Integration Point

Integration Rules

To support the PromoMats - Medical connection, it may be necessary to transform data from the source Vault’s data model to fit within the target Vault’s data model. You can use the Document Inbound Integration Rule to incorporate configurable rules for mapping document fields between two Vaults. Learn more about creating and managing Integration Rules.

Query Object Rules

The connection supports Query Object Rules for the Inbound Documents integration point. You can configure query object rules to filter documents assigned to the PromoMats Medical Connection document type group. For example, you could create a query object rule to only create CrossLinks for documents where the Country field is set to Canada.


This feature includes four (4) standard message processing queues: two (2) in your PromoMats Vault and two (2) in your Medical Vault. You can access and manage these queues from Admin > Connections > Spark Queues.

In each Vault, you have:

  • PromoMats Medical Document Outbound Queue (promomats_medical_doc_outbound_queue__v)
  • PromoMats Medical Document Inbound Queue (promomats_medical_doc_inbound_queue__v)

User Exception Objects

Vault includes the User Exception Message object and its child object, User Exception Item, to help you track and resolve any errors that occur with your PromoMats - Medical Vault Connection. If either end of your integration can’t process an incoming message, Vault creates a User Exception Message record to capture the failure.

Vault also creates individual User Exception Item records for each item that failed on the related Integration Point record in one of your Vaults. Vault typically creates User Exception Messages in the source Vault when there are issues with the configuration or connection itself. User Exception Messages in the target Vault often contain User Exception Items, as the target Vault can encounter document-specific errors as well as configuration errors.

You can view and manage these messages from Admin > Connections > User Exception Messages. If you want specific users or groups to receive notifications when Vault creates User Exception Message records, you must create a custom lifecycle for the User Exception Message object and configure a notification entry action.

A User Exception Message means that you need to update your configuration. After you update the configuration, Vault attempts to resolve any errors the next time the connection runs. You can also select the Rerun Integration action to run the connection and resolve errors.

Standard Document Type Group

The PromoMats Medical Connection Document Type Group record is available to support this connection.

We recommend adding the PromoMats Medical Connection document type group to the following document subtypes:

  • Medical Vault
    • Clinical Study Report (clinical_study_report__c)
    • Data on File (data_on_file__c)
    • Important Safety Information (ISI) (important_safety_information_isi__c)
    • Scientific Journal Article (journal_article__c)
  • PromoMats Vault
    • FPI - Full Prescribing Information (fpi_full_prescribing_information__c)
    • IFU - Instructions for Use (ifu_instructions_for_use__c)

Vault uses this document type group to determine which document types to transfer from one Vault to another. When a document belonging to this group enters its steady state, Vault sends a Spark message to create a CrossLink document in the connected Vault and updates the document fields to reflect changes made to the document in the source Vault. If you add the PromoMats Medical Connection document type group to any document types other than those recommended above, you must update the Document Type reference lookup to map the document type in the source Vault to the document type in the target Vault in order for Vault to transfer documents.

Configuring the PromoMats - Medical Connection

You must complete the following steps in both your PromoMats Vault and your Medical Vault to configure the standard connection:

  1. Establish the Vault to Vault connection between your PromoMats Vault and your Medical Vault. See Creating & Managing Connections for detailed instructions.
  2. Define reference lookups for controlled fields within the connection scope and load these to each Vault.
  3. Ensure the Country Code (code__sys) field on the Country (country__v) object is populated.
  4. Update any required fields that are not defined in the connection to either have a default value or to make values not required.
  5. Ensure the connection’s standard Document Type Group is set to Active and add the group to each document type.
  6. Enable CrossLinks.
  7. Optional: Configure any query object rules, custom field rules, and reference look-ups. We recommend setting up custom field rules for the following fields: expiration_date__c, document_author__c/authors__c, publication_date__c/source_date__c, and source__c/reference_source__c.
  8. Optional: Disable anchors on crosslinked documents.
  9. Optional: Update the connection to create CrossLinks for pre-existing documents.
  10. Optional: We recommend that you create a flash report to run when there are active User Exception Message records in either Vault.

If you don’t complete these steps in both Vaults, the connection will not work.

Configuring Reference Lookups

Reference lookups are a configuration component referenced by integration rules that allow you to map the value of a field on a target document indirectly from a value in the source Vault.

The PromoMats - Medical Vault connection creates a Document Type reference lookup in your PromoMats and Medical Vaults. Vault uses this reference lookup to map source document types to their corresponding target document types when creating new CrossLink documents. You can view and edit this lookup by navigating to Admin > Connections > PromoMats Medical Connection > Reference Lookups.

While configuring the Vault connection, you can create additional Document Type reference lookups. We recommend creating CSV mapping files and loading these to your Vault to create reference lookups. See Creating & Managing SDK Reference Lookups for detailed instructions.

If you do not define or activate a Document Type reference lookup before Vault attempts to create a CrossLink for that document type, Vault will generate a User Exception Message. Vault also creates User Exception Messages if there are multiple reference lookups for the same target and source keys.

Loading Mappings

After you create CSV mapping files for documents and object records, you can use Vault Loader to load reference lookups to your target Vault:

  1. Navigate to the Loader tab.
  2. Select your CSV file.
  3. In the Object Type drop-down, select Reference Lookups.
  4. In the Action Type field, select Create.
  5. Click Start Load.

After you load reference lookups, confirm they loaded successfully. Then, navigate to Admin > Connections in each Vault and review the reference lookups to ensure they appear as expected.

Updating Fields

In order for the connection to run successfully, you need to update any required document or object fields that are not defined in the connection to either have a default value or to make values not required. For example, ensure documents transferred from a PromoMats Vault to a Medical Vault have Product and Country values, and whether they are required, populated, and mapped correctly.

CrossLink documents enable content from one Vault to be used in another Vault within the same domain. In order for the connection to create documents across both your PromoMats and your Medical Vaults, you’ll need to enable CrossLinks in both Vaults.

When you enable CrossLinks, you can also choose to exclude document overlays and signature pages from the document in the source Vault when Vault creates the CrossLink document in the target Vault. If your documents include signature pages at the beginning, Vault may offset any anchors placed on the crosslinked documents. To avoid this, we recommend excluding signature pages or placing them at the end of the documents.

Transferring Anchors

By default, Vault includes version-specific anchors from the source Vault document on the crosslinked document in the target Vault. The PromoMats - Medical Connection only creates anchors once per Crosslink version.

To prevent Vault from transferring anchors on CrossLink documents:

  1. Navigate to Admin > Connections > PromoMats Medical Connection.
  2. Expand the Integrations section.
  3. Click Anchors.
  4. Click .
  5. Set the Status to Inactive.
  6. Click Save.

By default, the PromoMats - Medical Vault connection only creates CrossLinks for documents created after enablement. You can update the Last Successful Run Time field on the Inbound Documents integration in your target Vault. For example, you can select a specific date from several years ago, which prompts Vault to create CrossLinks for documents from that date going forward. If you want the connection to create CrossLinks for every document since Vault creation, you can leave the Last Successful Run Time field blank.

Connection Limitations

See Standard Vault to Vault Connection Limitations for limitations.

You need a System Admin security profile as well as the following permissions to set up the standard PromoMats - Medical connection:

Type Permission Label Controls
Security Profile Admin: Application: Manage Connections Ability to set up the PromoMats - Medical connection
Security Profile Object: User Exception Item, User Exception Message: Read Ability to see User Exception Item and User Exception Message records if a connection failure occurs