# Configuring the Quality-LIMS Connection Organizations using both a Quality Vault and a LIMS Vault can utilize the Spark messaging framework to create a standard Vault to Vault connection. This connection transfers _Batch_, _Related Batch_, _Material_, _Related Material_, _Product_, _Product Family_, _Product Variant_, _Product Marketed_, _Organization_, _Asset Family_, and _Asset_ records across Vaults and automates the creation and updating of [CrossLink documents](/en/lr/23143/). See [About the Quality-LIMS Connection](/en/lr/713971/) for detailed information about how the connection works.
## Quality-LIMS Connection Components The following components support the standard Quality-LIMS Connection. ### Connections The following _Connection_ records are available from **Admin > Connections**: * _Quality to LIMS_ (`quality_to_lims__v`) is available in your Quality Vault * _Quality - LIMS Connection_ (`quality_lims_connection__v`) is available in your LIMS Vault You will still need to [establish the Vault to Vault connection](/en/lr/53358/#Establish_Vault_to_Vault) before you can use 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 read-only and are used by Vault to manage the connection and track any connection errors. The _Quality to LIMS_ connection record includes the following default Integration records with standard _Integration Point_ records in your Quality Vault: | Integration Name | Integration Point Name(s) | Sent From | Sent To | | --- | --- | --- | --- | | Quality-LIMS Reference Object Integration | Quality - LIMS Asset | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Asset Family | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Batch | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Material | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Organization | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Product | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Product Family | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Product Marketed | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Product Variant | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Related Batch | Quality | LIMS | | Quality-LIMS Reference Object Integration | Quality - LIMS Related Material | Quality | LIMS | | Quality/LIMS Document Integration | LIMS Documents Outbound | Quality | LIMS | | Quality/LIMS Document Integration | LIMS Documents Inbound | LIMS | Quality | The _Quality - LIMS Connection_ record includes the following default Integration records with standard Integration Point records in your LIMS Vault: | Integration Name | Integration Point Name(s) | Sent From | Sent To | | --- | --- | --- | --- | | LIMS/Quality Object Integration | LIMS - Quality Asset | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Asset Family | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Batch | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Material | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Organization | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Product | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Product Family | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Product Marketed | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Product Variant | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Related Batch | Quality | LIMS | | LIMS/Quality Object Integration | LIMS - Quality Related Material | Quality | LIMS | | LIMS/Quality Document Integration | Quality Documents Outbound | LIMS | Quality | | LIMS/Quality Document Integration | Quality Documents Inbound | Quality | LIMS | ### Integration Rules {#integration-rules} To support the Quality-LIMS 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 Integration Rules to incorporate configurable rules for mapping object and document fields between two Vaults. Learn more about [creating and managing Integration Rules](/en/lr/62154/). [Field rules](/en/lr/62154/#about-field-rules) define the specific set of rules that apply to an integration rule. Ensure the following field rules for the Inbound Document integration rule are active in both your Quality and LIMS Vault: * `document_classification__v` * `document_link_field__v` * `document_major_version_number_field__v` * `document_minor_version_number_field__v` * `document_subtype__v` * `document_type__v` * `document_version_link_field__v` These field rules are active by default. If any of these field rules are inactivated, the connection creates a [_User Exception Message_][1] while attempting to transfer a document. ### Queues This feature includes four (6) standard [message processing queues](/en/lr/53147/): three (3) in your Quality Vault and three (3) in your LIMS Vault. You can access and manage these queues from **Admin > Connections > Spark Queues**. In your Quality Vault, you have: * _Quality - LIMS Reference Object Outbound Queue_ (`qual_lims_ref_object_outbound_queue__v`) * _LIMS Documents Outbound Queue_ (`lims_documents_outbound_queue__v`) * _LIMS Documents Inbound Queue_ (`lims_documents_inbound_queue__v`) In your LIMS Vault, you have: * _LIMS - Quality Reference Object Inbound Queue_ (`lims_quality_object_inbound_queue__v`) * _Quality Documents Outbound Queue_ (`qual_documents_outbound_queue__v`) * _Quality Documents Inbound Queue_ (`qual_documents_inbound_queue__v`) ### User Exception Objects {#user-exception-object} 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 Quality-LIMS 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 the outbound Vault. 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 Groups {#doc-type-groups} The following _Document Type Group_ records are available to support this connection: * _Quality to LIMS Connection_ is available in your Quality Vault * _LIMS to Quality Connection_ is available in your LIMS Vault Vault uses these document type groups to determine which [document types](/en/lr/618/) to transfer from one Vault to another. When a document belonging to one of these groups 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 configured, Vault also sends Superseded versions of documents created since the connection last ran. You must configure a [_Document Type_ reference lookup][2] to map the document type in the source Vault to the document type in the target Vault in order for Vault to transfer documents. ### Standard Document State Types {#doc-state-types} The following _Document State Types_ are available to support this connection: * _Steady_, _Obsolete_, and _Superseded_ are available on document lifecycles in your Quality Vault * _Steady_, _Obsolete_, and _Superseded_ are available on document lifecycles in your LIMS Vault Vault creates documents that are transferred through the connection in the states that you assign to these state types. Learn more about defining [defining document state types](/en/lr/14560/#).
### Last Successful Run Field On every inbound _Integration_ record, the _Last Successful Run_ field captures the date and time that the integration last ran with no errors. Vault uses this date to query changes since the integration's last successful run. You can use the _Last Successful Run_ field in the following ways: * If you don't want Vault to transfer existing object records or existing _Steady_ state documents as CrossLink documents, set this field to the date and time when you will activate the connection. * If you need to rerun every _Integration Point_ within the _Integration_ record, you can clear the _Last Successful Run_ field. The next time an action in either Vault triggers the connection, Vault will re-process all documents or object records within the scope of that integration point. When activating a Quality-LIMS Connection, set the _Last Successful Run_ field on each active _Integration_ to the date and time that you want transfers to start. If you do not set a value on the _Last Successful Run_ field, Vault will transfer all relevant records and documents. ## Configuring the Quality-LIMS Connection You must complete the following steps in both your Quality Vault and your LIMS Vault to configure the standard connection: 1. Ensure the connection's integrations and child integration points are set to _Active_. By default, integration and integration points are inactive. 2. Define reference lookups for controlled fields within the integration scope and load these to each Vault. See details about [configuring reference lookups][2] below. 3. Update any required fields that are not defined in the connection to either have a default value or to make values not required. See details about [updating fields][3] below. 4. Update existing records and CrossLink documents to prevent Vault from creating duplicates when the connection runs. See [instructions and information about object record creation][4] below. 5. Ensure the connection's [standard _Document Type Groups_][5] are set to _Active_ and add all necessary document types to each group. 6. Update document lifecycles to assign document states to the connection's [standard document state types][6]. In both Vaults, we recommend setting the connection's document state types to the _Approved_ state. 7. Enable CrossLinks. See [details about this step][7] below. 8. Optional: Enable the transfer of _Steady_ state and _Superseded_ document versions. See [details about this step][8] below. 9. We recommend that you create a [flash report](/en/lr/51842/) to run when there are active _User Exception Message_ records in either Vault. 10. Establish the Vault to Vault connection between your Quality Vault and your LIMS Vault. See [Creating & Managing Connections](/en/lr/53358/#Establish_Vault_to_Vault) for detailed instructions. 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][9] that allow you to map the value of a field on a target object or document indirectly from a value in the source Vault. When you configure the Quality-LIMS Vault Connection, you need to add reference lookups for controlled fields within the integration scope. We recommend creating CSV mapping files and loading these to your Vault to create reference lookups. For example, in order for Vault to transfer documents from one Vault to the other, you need to create _Document Type_ reference lookups to map the source document types to the target document types. See [Creating & Managing SDK Reference Lookups](/en/lr/58198/) for detailed instructions. ### Loading Mappings After you create CSV mapping files for documents and object records, you can use [Vault Loader](/en/lr/26607/) to load reference lookups to your Vault: 1. Navigate to the **Loader** tab. 2. Select your **CSV File**. See the sample _Object_ mapping file and the sample _Document Type_ mapping file. 3. In the **Object Type** drop-down, select _Reference Lookups_. 4. In the **Action Type** field, select _Create_. 5. Click **Start Load**. Load _Document Type_ reference lookups in your Quality Vault. Load both _Object_ reference lookups and _Document Type_ reference lookups in your LIMS Vault. 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 {#update-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, in the Quality Vault, update the _Unit of Measure_ field on the _Batch_ object. Keeping _Unit of Measure_ as a required field will cause errors when the connection runs if you don't extend the _Integration Rules_. ### Object Fields Update fields to be optional or to have a default value on the _Batch_, _Related Batch_, _Material_, _Related Material_, _Product_, _Product Family_, _Product Variant_, _Product Marketed_, _Organization_, _Asset Family_, and _Asset_ objects in your Quality Vault, and on the same objects in your LIMS Vault. ### Document Fields In addition to updating document fields to be optional or to have a default value, you need to [configure field-level security](/en/lr/2942/) on the _Major Version Number_ document field on the _Base Document_ type. In both Vaults, add an _Editable_ security override for the _Application Owner_ account. ## Updating Existing Object Records & CrossLink Documents {#update-objects} ### Object Records When creating an object record as part of the connection, Vault populates the _Link_ (`link__sys`) field on the target record or CrossLink with the _Global ID_ (`global_id__sys`) of the source record. These fields let Vault know which records to update in the target Vault when data is updated in the source Vault. If your Vault contains existing records that you want the Quality-LIMS Connection to update, you can manually enter the _Global ID_ value from the source record in the _Link_ field on the target record. Once the connection is active, Vault will update these existing records rather than creating new ones. ### CrossLink Documents If your Vault contains existing CrossLink documents bound to a specific _Steady_ state version and you don't want Vault to create duplicates when the connection runs, you can: * Enter the _Global ID_ value from the source document in the _Link_ field on the CrossLink document * Enter the _Global Version ID_ value from the source document in the _Document Version Link_ field on the CrossLink document ## Enabling CrossLinks {#enable-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 Quality and your LIMS Vaults, you'll need to [enable CrossLinks](/en/lr/23139/#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. ## Transferring Steady State & Superseded Document Versions {#transfer-versions} When enabled, Vault can transfer all _Steady_ state and _Superseded_ document versions between Vaults when the connection runs. When users create multiple versions of the same document within a five-minute window, Vault recognizes all versions (_Steady_ state and _Superseded_) and creates them as CrossLinks. When disabled, Vault only transfers the most recent _Steady_ state version created within a 5-minute window. ## Connection Limitations The Quality-LIMS Connection does not support the transfer of minor document versions. See [Standard Connection Limitations](/en/lr/53358/#limitations) for additional limitations. ## Related Permissions You need a System Admin security profile as well as the following permissions to set up the standard Quality-LIMS Connection: |Type|Permission Label|Controls| |--- |--- |--- | |Security Profile|Admin: Application: Manage Connections|Ability to set up the Quality-LIMS 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]: #user-exception-object [2]: #reference-lookups [3]: #update-fields [4]: #update-objects [5]: #doc-type-groups [6]: #doc-state-types [7]: #enable-crosslinks [8]: #transfer-versions [9]: #integration-rules