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 predefined 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.
Update 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 predefined 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 and Update Requirements actions. 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 and Update Requirements actions. 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 and Update Requirements and Update Requirements actions. 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 predefined 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.

Note: After creating the necessary Relational Tokens, you must link each supported action to a root token. If you do not do this, the action will fail when run by users. We suggest using the recommended Relational Tokens as root tokens.

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 and Update Requirements actions run, 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 predefined 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 and Update Requirements actions run.
- EDL Object Mapping: Select an Object Mapping with a Target Object of EDL to populate EDLs when the Generate Requirements and Update Requirements actions run.
- EDL Item Object Mapping: Select an Object Mapping with a Target Object of EDL Item to populate EDL Items when the Generate Requirements and Update Requirements actions run.
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 using Relational Token Settings. If you do not do this, the actions will fail. We suggest using the recommended components to link supported actions to root tokens.

You must create Relational Token Settings for the following supported actions:

Generate Registration Data (GENERATE_REGISTRATION_DATA): The Generate Registration Data action on the Registration Item object. The Root Token (such as registration_item__c) must reference the Registration Item object.
Generate Requirements for Registration Item (GENERATE_REQUIREMENT): The Generate Requirements and Update Requirements actions on the Registration Item object. The Root Token (such as registration_item__c) must reference the Registration Item object.
Generate Requirements for Registration Objective (GENERATE_REQUIREMENT_FOR_RO): The Generate Requirements and Update Requirements actions on the Registration object. The Root Token (such as registration_objective__c) must reference the Registration object.
Split Registration Item (SPLIT_REGISTRATION): The Split Registration Item action on the Registration Item object. The Root Token (such as registration_item__c) must reference the Registration Item object.

Any objects referenced in Relational Tokens must be directly or indirectly related to the object defined by the root Relational Token for the supported action in order for the Relational Token to resolve when that action runs. For example, when the Generate Requirements action runs on a Registration Item record and a related Requirement Library references the packaging__c Relational Token in the Name field, the packaging__c Relational Token must be a direct or indirect child of the registration_item__c Relational Token.

Defining Relational Token Settings

To create a Relational Token Setting:

Navigate to Admin > Configuration > Relational Token Setting.
On the All Relational Token Settings page, click Create.
Enter a unique Name. Vault automatically adds the __c suffix to the Name you enter.
Enter a unique Label. This field does not support spaces.
Specify if the component is Active. If you select No, Vault ignores the inactive component when supported actions run.
Select a Root Token.
To link a generate requirements action (Generate Requirements for Registration Item or Generate Requirements for Registration Objective), select an active Requirement object type in the Generate Requirements Action Target OT field. The actions must reference different object types.
Select a supported Action.
Click Save.

Recommended Components

We recommend using specific Relational Tokens and Relational Token Settings to link each action to a root Relational Token. You may need to create these components if they are not already in your Vault.

Recommended Relational Tokens

We recommend using the following Relational Token components (a parent and a child) to use as root tokens linked to supported actions, which you can also use for other purposes as needed. You may need to create these components if they are not already in your Vault:

Attribute	Parent Token	Child Token
Name	`registration_objective__c`	`registration_item__c`
Label	registration_objective	registration_item
Object	Registration	Registration Item
Field Label	`Field.name__v`	`Field.name__v`
VQL Criteria	null	null
Parent Token	null	`registration_objective__c`
Parent Token Reference Field Type	None	Self
Parent Token Object	Registration	Registration Item
Parent Token Child Field	null	null
Parent Token Reference Field	`Field.id`	`Field.registration__v`
Recursion Type	null	null

Recommended Relational Token Settings

If you are using the recommended Relational Tokens (registration_objective__c and registration_item__c), we recommend also using the following Relational Token Setting components to link supported actions to root tokens, which you can also use for other purposes as needed. You may need to create these components if they are not already in your Vault:

Attribute	Generate Registration Data	Generate Requirements for Registration Item	Generate Requirements for Registration Objective	Split Registration Item
Name	`generate_registration_data__c`	`generate_requirement__c`	`generate_requirement_for_ro__c`	`split_registration__c`
Label	`generate_registration_data`	`generate_requirement`	`generate_requirement_for_ro`	`split_registration`
Root Token	`registration_item__c`	`registration_item__c`	`registration_objective__c`	`registration_item__c`
Associated Object Type RIR	null	The name of an active Requirement object type.	The name of an active Requirement object type.	null
Action	`GENERATE_REGISTRATION_DATA`	`GENERATE_REQUIREMENT`	`GENERATE_REQUIREMENT_FOR_RO`	`SPLIT_REGISTRATION`

Important: Relational Token Setting components for the GENERATE_REQUIREMENT and GENERATE_REQUIREMENT_FOR_RO actions must reference different Requirement object types for the Associated Object Type RIR attributes. After you save a Relational Token Setting, you cannot modify the Associated Object Type RIR value.

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 using the Generate Requirements and Update Requirements actions:

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 predefined 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 predefined 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 Defining Registration Attributes for more details.

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.