Defining Relational Tokens (Registration & Dossier Management)

Registration & Dossier Management allows you to create Relational Token components for use in certain object records and MDL components to automate certain functions by leveraging hierarchical object relationships. When users run 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. 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. Similar to pre-defined tokens that resolve to a value, Relational Tokens allow you to leverage relationships between objects, giving you 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.

Recursive Relational Tokens

You can create recursive Relational Tokens, meaning Vault continues to apply the Relational Token to all generated records created as the token resolves through the hierarchy for the specified object until Vault can create no more additional records. 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 you want Vault to apply any VQL Criteria on the Relational Token at record creation or post-recursive record creation.

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 Requirements with EDLs and EDL Items based on hierarchical product relationships. If you link the Relational Token to an Object Mapping, Vault automatically populates mapped fields on the new records. This action supports up to 30 Relational Tokens in the Requirement parent-child structure.
Split Registration Item: Creates and relates Registration Items from a source Registration Item. If you link the Relational Token to an Object Mapping, Vault automatically populates mapped fields on the new records.

Note: If you link any of these actions to Relational Tokens that create cycles with the specified parent token, the action will fail.

Format

The format of Relational Tokens in RegulatoryOne differs from Vault information tokens and tokens used elsewhere in Vault, such as in messages, document numbers, and 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 Name (such as product__c).

Registration & Dossier Management does not include 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 always 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.

Configuration Overview

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

Optional: Create Object Mappings with Field Mappings to define how Vault populates fields based on token resolution. To use a Relational Token to generate registration data for Local Impact Assessments, you must create an Object Mapping before creating the Relational Token.
Create the applicable Relational Tokens.
After creating the applicable root Relational Tokens and before configuring any supported actions, use MDL to link the actions to root tokens.
Update relevant object records and MDL components to reference the applicable Relational Tokens.

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. To use a Relational Token to generate registration data for Local Impact Assessments, you must link it to a pre-defined Object Mapping by populating the Request Object Mapping field.

After you create an Object Mapping with Field Mappings, you can link it to Relational Tokens by populating the applicable fields on a Relational Token’s Details page:

Request Object Mapping: When you select an Object Mapping in this field, Vault populates fields on Registration Items when users run the Generate Registration Data and Split Registration Items actions. The selected Object Mapping’s Target Object must be Registration Item. You must select an Object Mapping in this field to populate Registrations when users run the Generate Registration Data action.
Request Requirement Object Mapping: When you select an Object Mapping in this field, Vault populates fields on Requirements when users run the Generate Requirements action. The selected Object Mapping’s Target Object must be Requirement.
EDL Object Mapping: When you select an Object Mapping in this field, Vault populates fields on EDLs when users run the Generate Requirements action. The selected Object Mapping’s Target Object must be EDL.
EDL Item Object Mapping: When you select an Object Mapping in this field, Vault populates fields on EDL Items when users run the Generate Requirements action. The selected Object Mapping’s Target Object must be EDL Item.

The Source Object of any selected Object Mapping must match the token’s Object. See Defining Object Mappings & Field Mappings for more details.

Creating Relational Tokens

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

All objects and fields referenced in the token must be active. When entering specific object field names, you must enter the values in “Field.[field_name__v]” format. For example, Field.name__v.

To create a Relational Token:

Navigate to Admin > Configuration > Relational Token.
On the All Relational Tokens page, click Create.
Enter a unique Name. Vault automatically adds the __c suffix to the Name you enter.
Specify if the token is Active. If you select No, Vault ignores the inactive token when supported actions run.
Enter a unique Label. This field does not support spaces.
Select the Object this token refers to.
Enter the Field Label for a field on this token’s Object. When the Generate Requirements action runs, this field is used as a label when the token resolves in a generated record. Vault ignores this field when the Generate Registration Data and Split Registration Items actions run.
Optional: Enter any VQL Criteria to apply on object records when the token is used, such as formulation_classification__c="formula__c". This field does not support IN or LIKE operators.
Optional: Select a Parent Token.
Select the Parent Token Reference Field Type to determine how the Parent Token is processed relative to this token:
- Self: The Parent Token Reference Field is on this token’s Object.
- Parent: The Parent Token Reference Field is on the parent token’s Object.
- Composition: The Parent Token Reference Field is on a separate join or composition object that has a relationship to this token’s Object.
- None: This token has no parent. Select this option if you did not select a Parent Token.
Select the Parent Token Object. If you selected Self or None as the Parent Token Reference Field Type, select this token’s Object.
For Composition types only: Enter the name of the Parent Token Child Field of the inbound relationship. This field must be on the Parent Token Object.
Enter a Parent Token Reference Field depending on the specified Parent Token Reference Field Type. If you selected Self or Parent, enter a field on this token’s Object. If you selected Composition, enter a field on the parent token’s Object. If you selected None, enter Field.ID.
Optional: Specify that this token is recursive by entering values for the following fields. If this token is not recursive, leave these fields blank:
- Recursion Type: Select Self if the Recursion Reference Field is on this token’s Object. Select Composition if the Recursion Reference Field is on a join or composition object related to this token’s Object. Do not select Self_Reference.
- Recursion Object: Select the inbound object. For Composition recursion type, this specifies the object of this token’s inbound relationship. For Self recursion type, select this token’s Object.
- Recursion Reference Field: Enter the name of the field on the Recursion Object on which recursion is applied.
- Recursion Child Field: If you selected Composition for Recursion Type, enter the name of a field on the Recursion Object to specify this token’s inbound relationship. Otherwise, leave this field blank.
- Use VQL Criteria Post Recursion: Select Yes or No to determine if Vault applies the VQL Criteria of this token as new records are created or post-recursive record creation. If you did not define any VQL Criteria for this token, select No.
To specify fields Vault will automatically populate when this token resolves, select one (1) or more pre-defined Object Mappings with the same Source Object as this token’s Object. You must select a Request Object Mapping if you plan to use this token to generate registration data. Otherwise, these fields are all optional:
- Request Object Mapping: Select an Object Mapping with a Target Object of Registration Item to populate Registration Items when the Generate Registration Data and Split Registration Items actions run.
- Request Requirement Object Mapping: Select an Object Mapping with a Target Object of Requirement to populate Requirements when the Generate Requirements action runs.
- EDL Object Mapping: Select an Object Mapping with a Target Object of EDL to populate EDLs when the Generate Requirements action runs.
- EDL Item Object Mapping: Select an Object Mapping with a Target Object of EDL Item to populate EDL Items when the Generate Requirements action runs.
Click Save.

Note: When creating recursive Relational Tokens, never select Self_Reference in the Recursion Type field.

Editing Relational Tokens

To edit a Relational Token, navigate to the applicable Relational Token and select Edit from the All Actions menu. After you make the applicable changes, click Save.

Deleting Relational Tokens

To delete a Relational Token, navigate to the applicable Relational Token and select Delete from the All Actions menu. Then, click Continue to proceed with the deletion.

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. See About RegulatoryOne Component Types for more 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 and attributes:

The Token Label and Name fields on Requirement Library object records
The Relational Token field on Split Rule object records
The Relational Token attribute on Registration Attribute MDL components

Using Relational Tokens in Requirement Libraries to Generate Requirements

To update a Requirement Library record to use a Relational Token to generate Requirements:

Navigate to the appropriate Requirement Library record.
Click Edit.
In the Token Label field, enter the appropriate token’s Label, such as “product”.
In the Name field, include the appropriate token’s Label by enclosing the token within curly brackets, such as “{product}”. You can enter a combination of a token and text, such as using a token called “{product}” where the Product record is “Lipstick” alongside the text “SDS” so that when the token resolves and Vault generates the new appropriate record, the name of the record would be “Lipstick SDS”.
Click Save.

Limitations

The following limitations apply to using Relational Tokens to generate Requirements:

Vault creates up to 100,000 Requirement records and 35,000 total records as Relational Tokens resolve when users trigger record generation.
Vault supports up to ten (10) levels for Relational Token hierarchies for Requirement Libraries.
Vault supports a maximum of 100 root-level Requirement Library records.

Using Relational Tokens in Split Rules to Generate Registration Items

You must reference a pre-defined token in the Relational Token field when creating a new Split Rule record, 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 to Map Registration Item Fields

You can reference a pre-defined Relational Token linked to an Object Mapping in the Relational Token (relational_token) attribute on Registration Attribute (Registrationattribute) components to support the Local Impact Assessment, Generate Registration Data, and Run Global Impact Assessment actions. See About RegulatoryOne Component Types for more details about how to create Registration Attribute components in MDL, which maps Registration Item field attributes.

About Job Status & Error Logging

When users run 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

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

Type	Permission	Controls
Security Profile	Admin: Configuration: Configuration: All Configuration	Ability to create and modify Relational Tokens.
Security Profile	Application: Vault Actions: API: Metadata API	Ability to access the All Relational Tokens page from the Application Configurations section of the Configurations page.
Security Profile	Objects: All Objects: Object Permissions: Create, Edit	Ability to create and modify Relational Tokens.
Security Profile	Pages: All Pages: Relational Token Details: View	Ability to view the Details page for individual Relational Tokens.
Security Profile	Pages: All Pages: Relational Token List: View	Ability to view the list of Relational Tokens on the All Relational Tokens page.