RegulatoryOne Registration & Dossier Management Vaults allow you to create Relational Token components for use in certain object records and MDL components to automate certain functions. When users trigger a supported action, Vault automatically generates and populates records based on how the token resolves to the related records of the object defined by the token. If you link a Relational Token to an Object Mapping, Vault also populates mapped fields with the same values in the source object records based on token resolution.

You can also use MDL to create Relational Tokens. You must use MDL to alter Relational Tokens and to access and create recursive Relational Tokens. See About RegulatoryOne Component Types for more details.

About Relational Tokens

Tokens are pieces of text with a specific format that Vault replaces with the values the token represents. Relational Tokens allow you to leverage relationships between objects; similar to a predefined token that resolves to a value, Relational Tokens allow you to have greater control over the configurability of the hierarchical object relationship values you want to reference. Relational Tokens point to a specified field on a specified object. Relational Tokens also allow you to have parent-child token relationships so that you can represent values throughout a product’s hierarchy.

Supported Actions

The following actions support Relational Tokens and generate or populate records based on token resolution:

  • Generate Registration Data: Populates mapped fields on a Registration Item with values from existing Registration Items for Local Impact Assessments. You must link the Relational Token to an Object Mapping to specify which mapped fields Vault populates.
  • Generate Requirements: Generates Registration Item Requirements with EDLs and EDL Items based on hierarchical product relationships. If you link the Relational Token to an Object Mapping, Vault will also automatically populate mapped fields on the new records.
  • Split Registration Item: Creates and relates Registration Items from a source Registration Item. If you link the Relational Token to an Object Mapping, Vault will also automatically populate mapped fields on the new records.

Format

The format of Relational Tokens in RegulatoryOne differs from tokens used elsewhere in Vault such as in messages, document numbers, Vault information tokens, or system-managed object record names. Depending on how you use a Relational Token, you will either reference the token’s label in curly brackets (such as “{Product}”) or the token’s API name (such as product__c).

RegulatoryOne does not contain any standard __v or system __sys namespace Relational Tokens; you can define Relational Tokens that best suit your organization’s needs. Relational Tokens that you create are custom tokens and have the __c custom namespace suffix.

Example

Review the following illustration for an example of how you could leverage the product hierarchy data model in your Relational Token definitions.

Relational Token Example

Configuration Overview

Configuring your Vault to use Relational Tokens involves the following steps:

Defining Object Mappings & Field Mappings

Before creating a Relational Token, ensure you have already created any optional Object Mapping components you want to link to the Relational Token so that Vault automatically populates the mapped fields with the same value in the source object records that resolve based on the Relational Token. If you plan to use a Relational Token to generate registration data for Local Impact Assessments, you must link it to a pre-defined Object Mapping.

After you create Object Mappings with Field Mappings, you can link them to the Relational Token by populating the applicable fields in the Object Mapping section when you create the new Relational Token. The drop-down menus in the Object Mapping section are disabled unless there is an existing object mapping with a Target Object matching the drop-down you select. For example, the Request Object Mapping drop-down is only active if there is an Object Mapping with a Target Object value of request__v.

See Defining Object Mappings & Field Mappings for more details about how to create Object Mappings with Field Mappings.

Creating Relational Tokens

Before creating a Relational Token, ensure you have already created any Object Mappings you want to link to the token. If you plan to use a Relational Token to generate registration data for Local Impact Assessments, you must link it to a pre-defined Object Mapping.

To create a Relational Token:

  1. Navigate to Relational Tokens.
  2. Click Create.
  3. Enter a unique Token Label.
  4. Enter the name of the Object this token refers to, such as formulation__v.
  5. Optional: Enter any VQL Criteria to apply on object records when the token is used, such as formulation_classification__c="formula__c".
  6. Optional: Enter a Description for the token.
  7. Enter a Field Label depending on how you plan to use this Relational Token:
  8. Optional: In the Parent section, select a parent token such as “Product”.
  9. Select the Parent Token Reference Field Type to determine how the parent token is processed relative to the current token:
    • Self: This option indicates that the token reference field is located on the object to which the token refers.
    • Parent: This option indicates that the token reference field is located on the object referred to in the parent token.
    • Composition: This option indicates that the token reference field is located on a separate join or composition object that has a relationship to the object to which the token refers.
    • None: This option indicates that the token has no parent and the Parent Token Reference Field is ID.
  10. Select the Parent Token. This field is not visible if you selected None for Parent Token Reference Field Type.
  11. Enter the Parent Token Reference Field. This field is not visible if you selected None for Parent Token Reference Field Type.
  12. Composition type only: Enter the Parent Token Object and Parent Token Child Field of the inbound relationship.
  13. Link this token to pre-defined Object Mappings by selecting one (1) or more mappings in the Object Mappings section. These fields are optional for Relational Tokens used to generate Requirements or split Registration Items. If you want to use this Relational Token to generate registration data for Local Impact Assessments, you must select an Object Mapping in the Request Object Mapping field. Vault automatically populates mapped fields based on token resolution. If you populate any of the Object Mappings fields, the Source Object on the Object Mapping must match the Object of this Relational Token. Select the applicable Object Mapping from the appropriate drop-downs depending on how you plan to use this Relational Token:
  14. Click Save.

Creating Recursive Relational Tokens

You can create recursive Relational Tokens, meaning Vault continues to apply the Relational Token to all generated records created as the Relational Token resolves through the hierarchy for the specified object until no more additional records can be created. For example, you can create a recursive Relational Token that generates requirements for all raw materials in a product hierarchy, including raw materials composed of other raw materials that are indirectly related to Formulations in the product hierarchy via Formulation Compositions. You can also specify if any VQL Criteria on the Relational Token is applied as new records are created or post recursive record creation.

See About RegulatoryOne Component Types for more details about how to create recursive Relational Tokens in MDL.

Linking Actions to Root Relational Tokens

After creating the applicable Relational Tokens and before configuring any of the supported actions, you must link each action to a root Relational Token. If you do not do this, the actions will fail when triggered by users. See About RegulatoryOne Component Types for details about how to create Relational Token Setting components in MDL, which link supported actions to root tokens.

Using Relational Tokens in Object Records & MDL Components

After creating a Relational Token, you can add it to certain object records and MDL components to use the token within a supported field. RegulatoryOne Registration & Dossier Management supports Relational Tokens in the following fields:

  • The Token Label field on Requirement object records
  • The Name field on Requirement object records
  • The Relational Token field on Split Rule object records
  • The Relational Token (relational_token) field on Registration Attribute (Registrationattribute) MDL components

Using Relational Tokens in Requirements

To update a record to use a Relational Token to generate Requirements from a dynamic template:

  1. Navigate to the appropriate Requirement record.
  2. Click Edit.
  3. In the Token Label field, include the token label, such as “Product”.
  4. In the Name field, include the appropriate Token Label by enclosing the token within opening and closing curly brackets such as “{Product}”. You can use a combination of a token and text in a field, such as using a token called “{Product}” where the Product record is “Lipstick” alongside the text “SDS” so that when the token resolves and the new appropriate record is created, the name of the record would be “Lipstick SDS”.
  5. Click Save.

Using Relational Tokens in Split Rules

You must reference an existing Relational Token when creating a new Split Rule records, which determines how Vault splits a source Registration Item into new and related Registration Items.

If you link a Split Rule with an Output Structure of Hierarchy to a recursive Relational Token, the Split Registration Items action creates and relates new Registration Items to mirror the same hierarchy of the records queried by the Relational Token. For example, if a gift set contains a travel kit and the travel kit includes a lotion, users can generate hierarchical Registration Items for the gift set. In that scenario, the travel kit Registration Item is a child of the gift set Registration Item, and the lotion Registration Item is a child of the travel kit Registration Item.

Using Relational Tokens in Registration Attributes

You can reference an existing Relational Token that is linked to an Object Mapping when creating Registration Attribute components in MDL to support generating registration data for Local Impact Assessments. This defines how Vault populates specified fields on Registration Item records when users trigger the Generate Registration Data action.

About Job Status & Error Logging

When users trigger any of the jobs below, Vault includes details about token resolution in the related job log, as well as any errors that occurred during the job instance:

  • Generate Requirements for Registration Item
  • Generate Requirements for Registration Objective
  • Split Registration Item

Limitations

The following limitations apply to Relational Tokens:

  • Vault creates a maximum of 100,000 Requirement records and 35,000 total records as Relational Tokens resolve when users trigger record generation.
  • Vault supports a maximum of 10 levels for Relational Token hierarchies for Requirements.
  • Vault supports a maximum of 100 root-level Requirement records.

You can complete all the steps in this article with the standard System Administrator or Vault Owner security profile. If your Vault users custom security profiles, your profile must grant the following permissions:

Type Permission Controls
Security Profile Admin: Configuration: Objects: Create, Edit Ability to create and modify Vault objects.
Security Profile Tabs: All Tabs: Relational Token: View Ability to view the Relational Tokens tab.
Security Profile Pages: All Pages: Relational Token Details: View Ability to view the Relational Tokens Details page on the Relational Tokens tab.
Security Profile Pages: All Pages: Relational Token List: View Ability to view the Relational Tokens List page on the Relational Tokens tab.