# Configuring the PromoMats - Medical Connection

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 <a href="/en/gr/23143/">CrossLink documents</a> and anchors. See <a href="/en/gr/680370/">About the PromoMats - Medical Connection</a> for detailed information about how the connection works.

## PromoMats - Medical Connection Components

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

### Connections

The _PromoMats Medical Connection_ (`promomats_medical__v`) record is available from **Admin > Connections** in your PromoMats and Medical Vault. You must <a href="/en/gr/53358/#Establish_Vault_to_Vault">establish the Vault to Vault connection</a> 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 {#int-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 <a href="/en/gr/62154/">creating and managing Integration Rules</a>.

### Query Object Rules

The connection supports <a href="/en/gr/62154/#about-query-object-rules">Query Object Rules</a> 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_. 

### Queues

This feature includes four (4) standard <a href="/en/gr/53147/">message processing queues</a>: 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 {#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 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 <a href="/en/gr/59885/">notification entry action</a>.

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 <a href="/en/gr/618/">adding the _PromoMats Medical Connection_ document type group</a> 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][1] 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 <a href="/en/gr/53358/">Creating & Managing Connections</a> 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][4]. 
  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 <a href="/en/gr/51842/">flash report</a> 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}

Reference lookups are a configuration component referenced by [integration rules][2] 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 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 <a href="/en/gr/58198/">Creating & Managing SDK Reference Lookups</a> 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_][3]. 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. 

### Enabling CrossLinks {#enabling-crosslinks}

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 <a href="/en/gr/23139/#enable-crosslinks">enable CrossLinks</a> 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 <i class="far fa-pencil-alt"></i>.
  5. Set the _Status_ to **Inactive**.
  6. Click **Save**.

### Configuring Pre-Existing Document CrossLinks

By default, the PromoMats - Medical 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 <a href="/en/gr/53358/#limitations">Standard Connection Limitations</a> for limitations.

## Related Permissions
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 |


[1]: #reference-lookups
[2]: #int-rules
[3]: #user-exception-objects
[4]: #enabling-crosslinks