Configuring Text and Claims Management

PromoMats provides the ability to create and manage reusable text assets through the Text Asset (annotation_keywords__sys) object. The Text Asset object includes two unique object types:

  • The Claims (claims__v) object type contains all the information for an individual claim, including the product, country, and match text.
  • The Reusable Text (reusable_text__v) object type contains information related to reusable text assets, including match text, product, country, and reusable text type.

You can navigate to Business Admin > Objects > Text Assets configure Text Asset records.

About Claims Linking

Claims allow you to automate the generation of reference links on claim statements in promotional materials. You can configure claims and associated references, allowing users to create four types of link annotations:

  • Suggested Links: When a document enters a given lifecycle state or when a user performs the Suggest Links user action on a document, Vault generates Suggested Links for non-exact text matches, which the user must review and accept or reject.
  • Approved Links: When a user accepts a Suggested Link, it becomes an Approved Link.
  • Auto-Accepted Links: When a document enters a given lifecycle state or when a user performs the Suggest Links user action on a document, Vault generates Auto-Accepted Links for exact text matches, which do not require review or approval.
  • Claim Links: Users can select the Claim type to manually select a claim based on matching fields.

Enabling & Disabling Suggested Links

Suggested Links must be enabled on the specific document lifecycle states where you want it to be available, and link annotations must be enabled in your Vault’s Application Settings.

To enable Suggested Links:

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

Next, you can add the Auto-Linking user action and entry action to any document lifecycle state. If you do not configure these actions, users can perform the Auto-Linking action by clicking on a document in any state. If you configure the user action or entry action, Vault only displays accordingly.

Next, you’ll need to add the Suggest Links user action and entry action to any document lifecycle state.

Enabling Auto-Linking on Upload

If you use standard document types in your Vault, you can enable auto-linking on upload, which allows Vault to automatically add Auto-Links to documents when users initially upload them. This removes the need to configure an entry action on a lifecycle state, improving efficiency and providing substantiation earlier in the document lifecycle. 

Auto-linking on upload is disabled by default. To enable it:

  1. Navigate to Admin > Settings > Application Settings.
  2. Click Edit.
  3. Under Text Asset Library Management, select the Auto-Link on Initial Upload checkbox.
  4. Click Save.

Managing the Claims and Reusable Text 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 claims either manually or from existing link annotations.
  • Review and approve claims via the Text Asset lifecycle. Vault only uses claims in the Approved state to suggest links.

Creating New Claim and Reusable Text Records

Claims and Reusable Text assets are managed as object records within Vault.

To create a new claim:

  1. From the Text Assets tab, click Create.
  2. In the Create Text Asset dialog, select Claim and click Continue.
  3. Enter the Primary Country where the claim will be used.
  4. Select a Primary Product.
  5. Enter the Match Text. This is the wording that will be used to suggest links to reference documents. By default, the match text must be between five (5) and 1500 characters.
  6. Optional: Enter a Category for the claim.
  7. Optional: Select a Language.
  8. Click Save, or to enter another claim, click Save + Create.

You can edit or add additional information to a claim by clicking Edit from the Claim Info page.

To create a new Reusable Text record:

  1. From the Text Assets tab, click Create.
  2. In the Create Text Asset dialog, select Reusable Text and click Continue.
  3. Optional: Enter the Primary Country where the text will be used.
  4. Optional: Select a Primary Product.
  5. Enter the Match Text. This is the wording that will be used to suggest reusable text to reference documents. By default, the match text must be between five (5) and 1500 characters.
  6. Optional: Enter a Reusable Text Type for the asset.
  7. Optional: Select a Language.
  8. Click Save, or to create another record, click Save + Create.

You can edit or add additional information to a claim by clicking Edit from the Reusable Text 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 and the Vault PromoMats UUID.
  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 Text Asset creation.

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

About the Source Text Asset Field

Source Text Asset is a system-controlled field that Vault automatically populates when you perform the Copy Record action. When you copy a Text Asset record, the Source Text Asset field on the new record populates with a link to the originating record. Vault populates the Source Text Asset field when you copy a single record (a “shallow” copy) and a structure of related records (a “deep” copy).

Relating Text Asset Records to Products and Countries

Using the join objects Text Asset Country and Text Asset Product, you can relate Text Assets to multiple products and countries.

You can also navigate to Admin > Settings > Application Settings and, under Claims & Reference Management, select the Enable Text Asset Country Object Record Creation SDK and Enable Text Asset Product Object Record Creation SDK checkboxes to enable automatic join record creation.

Users can search for Text Asset Country and Text Asset Product object records.

You can use the Get Link Annotation Data bulk document action and Vault Loader to create Text Asset, Link Target, and Text Asset 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 Using Bulk Document Actions.

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 Text Asset 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 Text Asset Targets object records.

Creating Text Assets 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 Text Asset fields not already present in the CSV. This is only necessary if you have added required fields to the Text Asset 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 Text Assets in the Approved state from approved documents, you must edit this column value before uploading.

To create new Text Asset 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 Text Assets (annotation_keywords__sys).
  3. From the Action Type dropdown, select Create.
  4. Important: Select the Record Migration Mode checkbox.
  5. Click the Start Load button.

When creating Text Asset records in the Approved state:

  • The Approved state must be defined in the CSV.
  • The Text Asset must pass validation for Approved state.

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

When creating Text Asset records in the Approved state, loading 1_annotation_keywords__sys.csv without loading one or both of the additional files results in Approved claims without references. Vault ignores these records when performing the Suggest Links action.

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 Text Assets Target Records

Text Asset Target records join Text Asset records to Link Target records. To create new Text Asset 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 Text Assets 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, Auto or Claim Links.
  • The resulting Text Asset’s Match Text is defined by the selected text from the link annotation. You can edit these values before uploading.
  • Matching field values in a Text Asset 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 Text Assets with references.
  • The user performing the Loader action becomes the Text Asset creator.

About the Create From Annotation ID Field

When executing the Get Link Annotation Data bulk document action, Vault generates a unique identifier for each batch and document, found in the create_from_annotation_id__sys column of the 1_annotation_keywords__sys.csv file. After loading the file to Vault Loader, this value is populated in the Create From Annotation ID field. You can filter on this field from the All Claims page to view all records from a single loader job. You can also add this field to Text Asset page layouts.

Configuring the Claim Selector

When manually linking to claims, you can configure which field values display in the Search: Claims dialog. Navigate to Admin > Configuration > Object > annotation_keywords__sys > Fields. Click the field, then select the Display in default lists and hovercards checkbox to display the field and its values in the Claims dialog.

Copying a Text Asset Record

When copying a Text Asset with multiple Match Text Variations and references, you can use hierarchical copy to create a new Text Asset record with the same match text variations and reference materials by selecting the Copy Related Records checkbox in the Copy Record dialog.

Adding Match Text Variations

Sometimes, the same claim can be worded in multiple ways. You can configure each Text Asset record to match with variations on the match text by using Match Text Variations and wildcards.

Match Text Variations allow you to add up to nine (9) alternate phrases to each Text Asset record. For example, a Text Asset might have the match text “Cholecap can significantly reduce LDL-C when used as directed.” Adding “When used as directed, Cholecap can significantly reduce LDL-C” as a Match Text Variation allows you to track both variations in the same Text Asset record.

Match Text Variations have their own lifecycle, and must be in the Approved state in order to be used by Suggest Links.

When adding or updating Match Text Variations, Vault does not evaluate excluded characters in match text. For example, Vault prevents adding the Match Text Variation “Cholecap© is number one” to a Text Asset with a Match Text or Match Text Variation value of “Cholecap is number one” because they are considered duplicates.

To add a Match Text Variation:

  1. From the Text Asset record detail page, open the Match Text Variations panel and click the Create button.
  2. Enter a Name for the match text variation.
  3. Enter the alternate Match Text.
  4. Click Save, or click Save + Create to enter additional match text variations.

Adding, Previewing, & Removing References

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

You can add a reference from the Text Asset 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 Create Anchors permission, this link will read Select or create anchor in this document and you can create new anchors 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 Text Asset 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 Text Assets

While creating claims, 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 using the Permalink target type. As a result, users can create Suggested Links and Auto-Accepted Links to Permalink targets.

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

About Duplicate Text Asset Records

You can create multiple Text Asset records with the same field and match text values. However, you can only move one (1) of these duplicate Text Asset records into the Approved state. To approve a different Text Asset record with the same field and match text values, you must first move the previously approved record into a non-steady state.

To prevent PromoMats from suggesting invalid links, Vault removes associated references from any Text Asset 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 About Self-Referencing Links for more information.

Adding Synonyms

You can also configure search synonyms for match text by navigating to Admin > Settings > Search Settings and setting up a thesaurus, allowing the Suggest Links action to find and match text containing synonyms. See Configuring Search Synonyms for more information.

Disabling Manual Linking to Text Assets

By default, Vault allows users to add claim links to documents manually by selecting approved Text Asset 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.

To disable Auto-Accepted Links, navigate to Admin > Settings > General Settings and, in the Documents section, clear the For Suggested Links, bypass Approve step on exact matches checkbox.

Using Wildcards

Claims often include variable content such as adjectives, footnote references, and trademark symbols. Using wildcards in match text allows Vault to match content in a document to a Text Asset record, even when variable words and characters exist. You can use wildcards in both primary match text and in Match Text Variations.

Wildcards are formatted as {*}.

There are two types of wildcards. Standalone wildcards have a space on each side and can represent up to ten whole words. For example, “Cholecap is {*} good” would match “Cholecap is good,” “Cholecap is very good,” and “Cholecap is the gold standard of good.” Vault ignores standalone wildcards at the beginning and end of match text.

Attached wildcards are used at the beginning, middle, or end of a word and add an unlimited number of characters to that word only. For example, “Chole{*} works well” matches “Chole works well”, “Cholecap works well”, and “Cholecap1 works well”.

Each match text entry can include up to three (3) wildcards. When two or more wildcards of the same type appear consecutively, Vault only uses the first wildcard and ignores any subsequent consecutive wildcards. For example, either “when taking Cholecap {*} for the first time” or “when taking Cholecap {*} {*} for the first time” matches “when taking Cholecap for the first time” and “when taking Cholecap OTC XR for the first time.” When two wildcards of different types appear consecutively, Vault uses both wildcards.

Vault counts wildcards as plain text characters when validating minimum and maximum match text length.

About Excluded Characters

Claim statements often contain certain characters, such as copyright and trademark symbols, whose presence or absence does not affect the meaning of the claim. Vault ignores these characters when evaluating whether a given text string is identical to a Text Asset record’s Match Text or Match Text Variation.

For example, if copyright symbol © is included in Excluded Characters, a Match Text value of “Cholecap works best with a Heart Healthy diet” matches both “Cholecap works best with a Heart Healthy diet” and “Cholecap© works best with a Heart Healthy diet”.

By default, the set of Excluded Characters is:

  • Copyright: ©
  • Registered: ®
  • Trademark: ™
  • 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 Match Text and Match Text 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 Text Assets to text. To include these characters, clear the Exclude superscript and subscript characters when matching Annotation Keywords to content checkbox.

About the Text Assets Lifecycle

The Text Assets lifecycle is an object lifecycle which applies to all Text Asset objects. Newly created claims begin in the Draft state and cannot enter the Approved state unless a user adds at least one (1) valid reference. Only claims 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.

While configuring the Text Asset lifecycle, you can enable and add entry criteria to one or more states to verify that a Text Asset Target join record exists between the Text Asset record and a Link Target record.

To add this entry criteria to the Text Asset lifecycle:

  1. Navigate to Admin > Settings > Application Settings and click Edit.
  2. Under Claims & Reference Management, select the Enable Text Asset Relationship Entry Criteria checkbox.
  3. Click Save.
  4. Navigate to Configuration > Object Lifecycles > Text Asset 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 Text Asset Target Relationship Exists.
  8. Click Save.

You must have Create, Edit, and Delete permissions on the Text Asset, Text Asset Target, and Link Target object 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 Text Asset, Text Asset Target, and Link Target objects to use Text and Claims Management.

You must have the Bulk Update document permission to perform the Get Link Annotation Data bulk action.