# Configuring Scientific Statement Management

Vault Medical provides the ability to create and manage reusable scientific statements through the _Scientific Statements_ (`annotation_keywords__sys`) object. 

You can navigate to **Business Admin > Objects > Scientific Statements** to create and edit statement records.

## About Statement Linking

Vault Medical allows you to manually or automatically generate reference links on _Scientific Statements_ in content. You can configure statements and associated references, allowing users to create four types of link annotations:

- **Suggested Links**: Vault generates pending links for non-exact text matches when the _Auto-Linking_ action is initiated manually, through an entry action, or based on the Auto-Linking settings. These links must be reviewed to be accepted or rejected. Non-exact matches may occur due to the following circumstances:
  - **Word Variance**: A single extra word within the document text compared to the _Scientific Statement_ record (applicable only to text of 25 words or less and is nonconfigurable).
  - **Punctuation**: Differences in punctuation between the document text and the _Scientific Statement_ record.
  - **Synonyms**: Vault's <a href="/en/gr/48194/">Thesaurus functionality</a> that expands searches to find results that include predefined synonyms.
  - **Stemming**: Vault's <a href="/en/gr/442/#stemming">search functionality</a> that returns inflections of search terms.
  - **Stop Words**: Vault's <a href="/en/gr/20161/">list of common words</a> that are removed from document content searches.
- **Approved Links**: When a user accepts a pending link, it becomes an Approved link.
- **Auto-Accepted Links**: Vault generates Auto-Accepted links for exact text matches when the _Auto-Linking_ action is initiated manually, through an entry action, or based on the Auto-Linking settings. These links do not require review or approval.
- **Manual Links**: While adding annotations, users can manually select approved _Scientific Statements_ based on matching fields. You must have at least one approved _Scientific Statement_ with the same _Primary Product_ and _Primary Country_ as the given document to manually link to a statement.

### Enabling Auto-Linking {#enable-suggested}

Auto-Linking must be enabled on the specific document type where you want it to be available, and link annotations must be <a href="/en/gr/63315/#enabling_link_annotations_document_links">enabled</a> in your Vault's _Application Settings_.

1. Navigate to **Admin > Configuration > Document Types**.
2. From the **Actions** menu next to the document type or subtype you want to enable, select **Edit Details**.
3. In the **Annotations** tab, under _Enable "Suggested Links" Action_, select **Enable Action** or **Do not Enable Action**. For document types, you can choose **Inherit from Base Document** to allow or disallow the Suggested Links action based on the setting of the base document type. Similarly, document subtypes and classifications can inherit enablement from their parent document type. Alternately, you can choose to enable or not enable the action individually for each specific document type, subtype, or classification.

The _Auto-Linking_ (<i class="far fa-lightbulb"></i>) action is now available for this document type. Optionally, you can add the _Auto-Linking_ <a href="/en/gr/12339/">user action</a> and <a href="/en/gr/12399/">entry action</a> to any document lifecycle state.

You can also add the [_Suggest Links with Rejected Links_][3] user action to any document lifecycle state. When users perform this action, Vault includes previously rejected suggestions with new links.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Users must have the <em>Annotate</em> and <em>Edit Relationship</em> permissions to perform the <em>Auto-Linking</em> user action.</p>
    </div>
  </div>
</div>



The following settings are enabled by default in new Vaults:

  * **Allow linking via selection of approved Annotation Keywords records**: Allows users to manually add _Scientific Statement_ links by selecting _Approved_ records when adding link annotations.
  * **Exclude specific characters when matching Annotation Keywords to content**: Allows Vault to ignore specific characters when evaluating a given string against a _Scientific Statement_'s _Statement_ or _Statement Variation_. By default, Vault ignores copyright (&copy;), registered (&reg;), trademark (&trade;), and servicemark (℠) characters. You can add or remove characters from this list, or disable this checkbox to include these characters in match criteria. 
  * **Exclude superscript and subscript characters when matching Annotation Keywords to content**: Allows Vault to ignore superscript and subscript characters when matching text. You can disable this checkbox to include these characters in match criteria.

### Configuring the Scientific Statement Auto-Linking Settings

In the _Scientific Statement Auto-Linking Settings_ page, you can configure Auto-Linking to run automatically when a document is uploaded based on selected document lifecycles and lifecycle states, improving efficiency and providing substantiation earlier in the document lifecycle. You can also configure Auto-Linking to restrict which _Scientific Statement_ object types are included to ensure that Auto-Linking runs only on object types that require substantiation. For object types, if none are selected, it means that all active and inactive object types are included for Auto-Linking.

To configure Auto-Linking:

1. Navigate to **Admin > Configuration > Application Configurations**.
2. Under _MedComms Configuration_, select **Scientific Statement Auto-Linking Settings**.
3. In the _Auto-Linking Lifecycle States_ section, you can select multiple active lifecycle states associated with the active document lifecycles for the document types that have Suggested Links enabled.
4. Optional: Click **Edit** to adjust the list of document lifecycles and lifecycle states displayed on the table in the _Auto-Linking Lifecycle States_ section.
5. Click **Save**.
6. In the _Auto-Linking Object Types_ section, you can select multiple active object types to include for auto-linking.
7. Optional: Click **Edit** to adjust the list of object types in the picklist in the  _Auto-Linking Object Types_ section.
8. Click **Save**.

### Auto-Approving Statements

When configured, Vault can automatically approve _Scientific Statements_ in the _Reviewed_ state when linked documents enter a steady state. To enable auto-approval, add the **Auto-Approve Statements** <a href="/en/gr/12399/">entry action</a> to the steady state document lifecycle state.

Vault notifies users when the entry action completes via email and the <a href="/en/gr/71440/">_Notifications_ page</a>.

The entry action validates any preconfigured entry criteria and required fields for each _Scientific Statement_. If any of these checks fail, the job completes and the document moves to the steady state, but the _Scientific Statement_ remains in its current state.

### Bringing Forward Annotations

You can configure the <a href="/en/gr/63315/#auto-bring-forward-annotations">_Bring Forward Annotations on Version Create_ setting</a> for document types to automatically bring forward Auto-Links. This setting does not affect manually brought forward annotations. 

To allow users to manually bring forward Auto-Links, navigate to **Admin > Settings > Application Settings** and verify that the <a href="/en/gr/63315/#enabling_bring_forward_annotations">**Allow users to bring forward annotations** setting</a> is enabled. You can then select the types of annotations that users can bring forward: lines, open notes, links, anchors, Auto-Links, and resolved notes.

### Updating the Scientific Statement Page Layout

To select a _Primary Country_ and _Primary Product_ when creating _Scientific Statements_, you must modify the _Scientific Statement_ object <a href="/en/gr/26387/">page layout</a>:

  1. Navigate to **Configuration > Objects > Scientific Statement**.
  2. Click the **Layouts** tab.
  3. Under _Layout Label_, click the **Actions** menu next to **Scientific Statement Action Layout** and select **Save As**.
  4. Enter a new **Layout Label**. 
  5. Select **Active** in the _Status_ drop-down.
  6. Under _Details_, click **Add** and select **Primary Country**.
  7. Click **Add** again and select **Primary Product**.
  8. Click **Done**.

### Adding a Scientific Statements Tab

To allow users to access _Scientific Statements_, you can add a <a href="/en/gr/23516/">custom tab</a>:

  1. Navigate to **Admin > Configuration > Tabs**.
  2. Click **Create**.
  3. Enter **Scientific Statements** as the **Label**.
  4. Click the **Tab Type** drop-down and select **Object**.
  5. Click the **Object** drop-down and select **Scientific Statements**.
  6. Under _Creation Options_, select **Create record in pop-up dialog**.
  7. Click **Save**.

## Managing the Statement Library

Before users can generate links, you'll need to complete the following steps, which are detailed below:

  * Confirm that the appropriate reference documents exist in your Vault. Upload additional documents if necessary and classify them with a document type that is enabled as a target for Suggested Links.
  * Create anchors on reference documents using the _Create Anchors_ tool.
  * Create _Scientific Statements_ records.
  * Review and approve statements via the _Scientific Statement_ lifecycle. Vault only uses statements in the _Approved_ state to suggest links.

### Creating New Scientific Statement Records

_Scientific Statements_ are managed as object records within Vault.

To create a new statement:

  1. From the **Scientific Statements** tab, click **Create**.
  2. Enter the **Statement**. This is the wording that will be used to suggest links to reference documents. By default, the statement must be between five (5) and 1500 characters. However, you can add statements with fewer than five (5) characters in Chinese, Japanese, and Korean.
  3. Optional: Enter a **Category**.
  4. Select a **Primary Country**.
  5. Select a **Primary Product**.
  6. Optional: Select a **Language**.
  7. Click **Save**, or to enter another statement, click **Save + Create**.

You can edit or add additional information to a statement by clicking **Edit** on the Scientific Statement Info page.

#### Managing Languages

To add a language:

  1. Navigate to **Admin > Settings > Language & Region Settings** and click **Edit**.
  2. Select the **Enable multilingual document handling checkbox** and click **Save**.
  3. Navigate to **Business Admin > Objects > Languages** and click **Create**.
  4. Enter the language **Name**.
  5. Select a corresponding **Language**.
  6. Optional: Enter a **Language Code**.
  7. Click Save.

After creating a _Language_ value, navigate to **Business Admin > Objects > Country Language** and click **Create**. Select a **Country** and a **Language** to create a join, indicating that the _Language_ selected is approved for use in the specified _Country_. This populates the _Language_ field available during _Scientific Statement_ creation.

Vault only uses _Language_ as a matching field on documents where the _Language_ field is available.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: You can only select a <em>Language</em> after selecting a <em>Primary Country</em>.</p>
    </div>
  </div>
</div>



### Relating Scientific Statement Records to Products & Countries

Using the join objects _Scientific Statement Country_ and _Scientific Statement Product_, you can relate _Scientific Statements_ to multiple products and countries.

You can also navigate to **Admin > Settings > Application Settings** and, under _Join Object Records_, select the **Enable Scientific Statement Country Join Object Record Creation SDK** and **Enable Scientific Statement Product Join Object Record Creation SDK** checkboxes to enable automatic join record creation.

Users can search for _Scientific Statement Country_ and _Scientific Statement Product_ object records. Vault considers these records when linking _Scientific Statements_ to documents.

### Relating Scientific Statement Records to Indications

Using the join object _Scientific Statement Indication_, you can relate _Scientific Statements_ to multiple indications. 

To do this, add the primary _Indication / Disease_ field to the _Details_ section along with the _Product Indications_ section to the various _Scientific Statement_ object page layouts. 

Additionally, with the existing _Indication / Disease_ document field, the <a href="/en/gr/831438/">Harvest Statements</a> feature automatically includes indication metadata when extracting _Statements_ from documents.

### Creating Statements from Link Annotations

You can use the _Get Link Annotation Data_ bulk document action and <a href="/en/gr/26607/">Vault Loader</a> to create _Scientific Statement_, _Link Target_, and _Scientific Statement Target_ records in bulk from existing link annotations on a defined set of documents. To extract annotation data from documents via a bulk action, see <a href="/en/gr/18822/">Using Bulk Document Actions</a>.

After completing the bulk document action, download and unzip the link annotation data file. The package contains three files, which must be loaded in numerical order and are named as follows:

  * `1_annotation_keywords__sys.csv`: This file contains data that Vault uses to create new _Scientific Statement_ object records.
  * `2_link_target__sys.csv`: This file contains data that Vault uses to create new _Link Target_ object records.
  * `3_annotation_keyword_targets__sys.csv`: This file contains data that Vault uses to create new _Scientific Statement Targets_ object records.

#### Creating Scientific Statements Records

Before you begin, you may wish to edit `1_annotation_keywords__sys.csv` in one or more of the following ways:

  * Add columns and values for any required _Scientific Statement_ fields not already present in the CSV. This is only necessary if you have added required fields to the _Scientific Statement_ object.
  * Edit other specific values as needed. For example, you may wish to revise values in the `match_text__sys` column for brevity.
  * When you extract link data from a _Steady_ state document, the corresponding `state__v` column defaults to `approved_state__sys`. If you do not wish to create statements in the _Approved_ state from approved documents, you must edit this column value before uploading.

To create new _Scientific Statement_ records:

  1. From the **Loader** tab, click the **Choose** button in the **CSV File** fields and select the `1_annotation_keywords__sys.csv` file.
  2. From the **Object Type** dropdown, select **Scientific Statements (`annotation_keywords__sys`)**.
  3. From the **Action Type** dropdown, select **Create**.
  4. Select the **Record Migration Mode** checkbox.
  5. Click the **Start Load** button.

When creating _Scientific Statement_ records in the _Approved_ state:

  * The _Approved_ state must be defined in the CSV.
  * The _Scientific Statement_ must pass validation for the _Approved_ state.

If these conditions are not met, Vault creates the records in _Draft_ state.

When creating _Scientific Statement_ records in the _Approved_ state, loading `1_annotation_keywords__sys.csv` without loading one or both of the additional files results in _Approved_ statements without references. Vault ignores these records when performing the _Suggest Links_ action.

#### Creating Link Target Records

_Link Target_ records establish the relationships to documents and anchors. To create new _Link Target_ records:

  1. From the **Loader** tab, click the **Choose** button in the **CSV File** fields and select the `2_link_target__sys.csv` file.
  2. From the **Object Type** dropdown, select **Link Targets (`link_target__sys`)**.
  3. From the **Action Type** dropdown, select **Create**.
  4. Click the **Start Load** button.

#### Creating Scientific Statement Target Records

_Scientific Statement Target_ records join _Scientific Statement_ records to _Link Target_ records. To create new _Scientific Statement Targets_ records:

  1. From the **Loader** tab, click the **Choose** button in the **CSV File** fields and select the `3_annotation_keyword_targets__sys.csv` file.
  2. From the **Object Type** dropdown, select **Scientific Statement Targets (`annotation_keyword_targets__sys`)**.
  3. From the **Action Type** dropdown, select **Create**.
  4. Click the **Start Load** button.

When bulk creating records with Vault Loader, note the following:

  * The bulk action only exports data from manually created link annotations with text selection. Vault does not export data from manual links with image selection, nor from Suggested, Approved, or Auto-Accepted Links.
  * The resulting _Scientific Statement_'s _Statement_ is defined by the selected text from the link annotation. You can edit these values before uploading.
  * <a href="/en/gr/602336/">Matching field values</a> in a _Scientific Statement_ record are defined by values in the same fields on the source document.
  * You must load all three files in numerical order in order to create _Scientific Statements_ with references.
  * The user performing the Loader action becomes the _Scientific Statement_ creator.

### Configuring the Statement Selector

When manually linking to statements, you can configure which field values display in the _Select anchors_ dialog. Navigate to **Admin > Configuration > Object > Scientific Statement > Fields**. Click the field, then select the **Display in default lists and hovercards** checkbox to display the field and its values in the dialog.

### Adding Scientific Statement Variations

Sometimes, the same statement can be worded in multiple ways. You can configure each _Scientific Statement_ record to match with variations on the statement by using Statement Variations.

Statement Variations allow you to add up to nine (9) alternate phrases to each _Scientific Statement_ record. For example, a _Scientific Statement_ might have the statement "Up to 70% of cancer patients may suffer from nausea or emesis following chemotherapy." Adding "Following chemotherapy, up to 70% of cancer patients may suffer from nausea or emesis" as a Statement Variation allows you to track both variations in the same _Scientific Statement_ record.

Statement Variations have their own lifecycle, and must be in the _Approved_ state in order to be used by Suggest Links.

When adding or updating Statement Variations, Vault does not evaluate excluded characters in statements. For example, Vault prevents adding the Statement Variation "The Natevba&copy; regimen is safe and effective" to a _Scientific Statement_ with a statement or statement variation value of "The Natevba regimen is safe and effective" because they are considered duplicates.

To add a Statement Variation:

  1. From the _Scientific Statement_ record detail page, open the **Statement Variations** panel and click the **Create** button.
  2. Enter the alternate **Statement**.
  3. Click **Save**, or click **Save + Create** to enter additional variations.

### Adding, Previewing, & Removing References {#references}

_References_ provide proof of the validity of a statement. They can be anchors or entire documents. You can add multiple references to each statement.

You can add a reference from the _Scientific Statement_ record detail page. Click the **Add** button under _References_ to open the _Select Anchors_ dialog. This window displays a list of all the documents in your library that you have _View Document_ permissions for and have a document type configured to enable referencing from suggested links. If you have _View Content_ permissions on the document, you will also see all anchors on those documents.

You can choose from the list, use the search bar to find documents, or add filters. You can also hover over the name of the document or anchor for more information, click the name to open the document or anchor, or click the **Preview Link** icon next to an anchor to view the target in a mini-browser window. To preview a document in a mini-browser, click the **View and select anchor in this document** link below the document name. If you have the <a href="/en/gr/2572/">_Create Anchors_</a> permission, this link will read **Select or create anchor in this document** and you can <a href="/en/gr/15303/#create_anchors">create new anchors</a> within the mini-browser. Click on the **plus** (**+**) icon next to each document or anchor you want to add in the _Select Anchors_ dialog, then click **Close** to add the references.

From the **Actions** menu next to each reference's name, you can select **Preview** to see a list of existing targets on a record, or select **Remove** to remove the reference and its related _Scientific Statement Target_ and _Link Target_ records.

You must have _View_ and _Execute_ permissions on the _Preview_ and _Remove_ object action permissions for the _Link Target_ object to use these actions. The _Business Administrator Actions_, _System Administrator Actions_, and _Vault Owner Actions_ standard permission sets include these permissions, but they must be added to other standard permission sets and any custom permission sets.

### Adding References to Permalink Targets on Scientific Statements

While creating statements, you can add references to permalink targets. Permalink targets are versionless and always link to the latest available version of the referenced document. You can create links to permalink targets such as documents, pages, bookmarks, and named destinations. To add references to permalink targets, [create a reference][1] using the **Permalink** target type. As a result, users can create Suggested Links and Auto-Accepted Links to Permalink targets.

Suggested and Auto-Accepted Links to permalink targets are only available when the following feature flags are enabled:

  * <a href="/en/gr/63262/">_Enable Copy Link and unlock Permalink Object Type_</a>
  * <a href="/en/gr/63262/#linking-to-permalinks">_Enable linking to permalinks_</a>
  * _Enable Suggested Links_

### Copying Scientific Statement Records

When copying a _Scientific Statement_ record, you can use <a href="/en/gr/32218/#hierarchical-copy">hierarchical copy</a> to create a new _Scientific Statement_ record with the same hierarchy of records by selecting the **Copy Related Records** checkbox in the **Hierarchical Copy** dialog. This will copy any related child _Scientific Statement Target_, _Scientific Statement Variation_, _Scientific Statement Asset_, _Scientific Statement Country_, or _Scientific Statement Product_ records to the new _Scientific Statement_ record.

To enable hierarchical copying, select the **Allow hierarchical copy** checkbox on the Parent Object field for the _Scientific Statement_ child objects.

### Preventing Duplicate Links {#duplicate-links}

When attempting to create a link annotation for the same page coordinates as a previously _Rejected_ link, Vault compares the ID of the new link against the ID of the _Rejected_ link. If the ID is the same, Vault does not create an annotation unless users perform the **Suggest Links with Rejected Links** user action.

In the event that multiple _Scientific Statements_ link to the same text coordinates, Vault creates an Auto-Link annotation for the exact match, if one is available. Vault places Auto-Links over the same text coordinates as document link annotations.

### Preventing Invalid Suggested Links

To prevent suggesting invalid links, Vault removes associated references from any _Scientific Statement_ records that reference them and, if the record is in _Approved_ state, returns it to _Draft_ state when:

  * A user deletes a targeted document or anchor.
  * A target document enters a lifecycle's _Obsolete_ state.
  * A target document's document type configuration is changed to be ineligible as a target for Suggested Links.
  * A target document's document type is changed to a different document type that is ineligible as a target for Suggested Links.

Vault prevents you from creating whole-document links to the current document version. Therefore, some situations may result in a Suggested Link or Auto-Link that does not include a link component for that reference in the resulting annotation. See <a href="/en/gr/602334/#self-links">About Self-Referencing Links</a> for more information.

### About Excluded Characters

Statements often contain certain characters, such as copyright and trademark symbols, whose presence or absence does not affect the meaning of the statement. Vault ignores these characters when evaluating whether a given text string is identical to a _Scientific Statement_ record's statement or Statement Variation.

For example, if copyright symbol &copy; is included in Excluded Characters, a _Statement_ value of "Cholecap works best with a Heart Healthy diet" matches both "Cholecap works best with a Heart Healthy diet" and "Cholecap&copy; works best with a Heart Healthy diet".

By default, the set of Excluded Characters is:

  * Copyright: &copy;
  * Registered: &reg;
  * Trademark: &trade;
  * Servicemark: ℠

### Editing & Disabling Excluded Characters

To edit the list of excluded characters, navigate to **Admin > Settings > General Settings** and click the **Edit** button. Then, in the _Documents_ panel, add or remove characters in the **Excluded Characters** field. Vault limits this field to 20 characters, including spaces. 

There is a known issue which causes Vault to ignore wildcards in statements and Statement Variations when \{curly brackets\}, asterisks(\*), or both are included in excluded characters.

Vault treats each character independently. For example, if you add the word "always" to the set, Vault will treat each letter ("a" and "l" and "w" etc.) as a separate excluded character.

To disable excluded characters, clear the **Exclude specific characters when matching Annotation Keywords to content** checkbox.

#### Excluding Subscript and Superscript Characters

By default, Vault excludes subscript and superscript characters at the end of words when matching _Scientific Statements_ to text. To include these characters, clear the **Exclude superscript and subscript characters when matching Annotation Keywords to content** checkbox.

## Disabling Manual Linking to Scientific Statements

By default, Vault allows users to add statement links to documents manually by selecting approved _Scientific Statement_ records when adding annotations. To disable this feature, navigate to **Admin > Settings > General Settings** and, in the _Documents_ section, clear the **Allow linking via selection of approved Annotation Keywords records** checkbox.

## About the Scientific Statement Lifecycle

By default, the _Scientific Statement Lifecycle_ (`annotation_keywords_lifecycle__sys`) is an <a href="/en/gr/30683/">object lifecycle</a> which applies to all _Scientific Statement_ objects. Newly created statements begin in the _Draft_ state and cannot enter the _Approved_ state unless a user adds at least one (1) valid reference. Only statements in the _Approved_ state are available for use in suggesting links. 

You can add custom lifecycle states and workflows to suit your organization's needs. You can also edit the lifecycle name as desired.

While configuring the _Scientific Statement Lifecycle_, you can enable and add entry criteria to one or more states to verify that a _Scientific Statement Target_ join record exists between the _Scientific Statement_ record and a _Link Target_ record.

To add this entry criteria to the _Scientific Statement Lifecycle_:

  1. Navigate to **Admin > Settings > Application Settings** and click **Edit**.
  2. Select the **Enable Statement Link Target Relationship Lifecycle Entry Criteria** checkbox.
  3. Click **Save**.
  4. Navigate to **Configuration > Object Lifecycles > Scientific Statement Lifecycle**.
  5. Click a **State**. We recommend adding this entry criteria to the _In Review_ state.
  6. In the _Entry Criteria_ section, select **Edit**.
  7. Click **Create Rule** and add entry criteria as desired, selecting **Statement Target Relationship Exists**.
  8. Click **Save**.

We recommend that you select the _Statement Types_ that require substantiation and allow the rest to proceed to their steady state without references attached.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Once enabled, you cannot disable the <strong>Enable Statement Link Target Relationship Lifecycle Entry Criteria</strong> setting.</p>
    </div>
  </div>
</div>



## Related Permissions

You must have _Create_, _Edit_, and _Delete_ permissions on the _Scientific Statement_, _Scientific Statement Target_, and _Link Target_ objects in addition to _Admin: Configuration: Objects: Create_ and _Edit_ permissions to create and configure objects.

You must have _Create_, _Edit_, and _Delete_ permissions on the _Scientific Statement_, _Scientific Statement Target_, and _Link Target_ objects to use Statement Management.

You must have the _Bulk Update_ document permission to perform the _Get Link Annotation Data_ bulk action.

[1]: #references
[2]: #platform-sl
[3]: #duplicate-links