Using Customer Keys (Placeholders) in Document Templates

Introduction

Custom Keys (Placeholders) are used within document templates to automatically populate information during document generation.

A Custom Key (Placeholder) is any text enclosed within double curly brackets {{ }}. During document generation, the system attempts to replace these Custom Keys with the corresponding values available within the system or values configured by the administrator.

Custom Keys help organizations create reusable document templates that can be generated for multiple employees without manually updating employee-specific information each time.

Understanding Custom Keys (Placeholders)

Any text enclosed within double curly brackets {{ }} is treated as a Custom Key (Placeholder) by the system.

Examples:

• {{Employee.Name}}
• {{Employee.Designation}}
• {{Employee.DateOfJoining}}
• {{Company.OrganisationName}}
• {{Today's.Date}}
• {{Name}}

When a document template is uploaded, the system identifies all Custom Keys available within the document and displays them for review and configuration.

The system provides a large library of predefined Custom Keys across various categories. These Custom Keys can be used directly within document templates to automatically populate information available within the system.

Administrators can also create their own Custom Keys whenever additional information needs to be captured during document generation.

How Custom Keys Work

During document generation, the system evaluates each Custom Key (Placeholder) available within the template.

Predefined System Keys

If a Custom Key matches a predefined system key:

• The system automatically attempts to populate the corresponding information.
• If the information is available, the value is populated automatically.
• If the information is unavailable, the field remains blank and can be updated manually before generating the document.

Examples: {{Employee.Name}}, {{Employee.Designation}}, {{Employee.DateOfJoining}}, {{Company.OrganisationName}}

Administrator-Defined Custom Keys

Administrators can create their own Custom Keys when additional information needs to be captured during document generation.

Examples:  {{EmployeeDemonstratedBehaviour}}, {{VariableMonthlySalary}}, {{ExtensionDuration}}, {{ProjectAllowance}},  {{TrainingCompletionStatus}}

For administrator-defined Custom Keys, administrators can configure:

• Default values
• Formula-based values

During document generation:

• If a default value has been configured, the configured value is used.
• If a formula has been configured, the value is calculated automatically based on the defined formula.
• If no value, default value, or formula has been configured, the field remains blank and can be updated manually before generating the document.

Custom Key Examples

Example 1: Using Predefined Custom Keys

The following appointment letter template uses predefined Custom Keys available within the system.

Result: All Custom Keys were automatically replaced using information available within the system.

Example 2: When Information for a Predefined System Key Is Unavailable

The following template uses the predefined Custom Key {{Employee.Designation}}.

Result: When information for a predefined System Key is unavailable, the field remains blank. The user can review the generated document and manually provide a value before completing document generation.

Example 3: Using an Administrator-Defined Custom Key

The following template contains the administrator-defined Custom Key {{ExtensionDuration}}

Template Content: Your probation period has been extended by {{ExtensionDuration}}.

Result:  Administrator-defined Custom Keys can be populated using:

• A value entered during document generation.
• A configured default value.
• A modified value entered during document generation, even when a default value exists.

Example 4: Using Formula-Based Custom Keys

The following template contains administrator-defined Custom Keys used to generate a salary structure within an appointment letter.

Template Content

Formula Configuration

Generation Details/ Output

Result: Formula-based Custom Keys can be used to automatically calculate salary components and populate compensation-related documents.

___________________________________________________________________________________________________________

Using Supporting Custom Keys

In some scenarios, administrators may create Custom Keys that are not directly used within the document template. These Custom Keys are created to simplify calculations and support other formula-based Custom Keys. For example, consider the following formula used to calculate Provident Fund:

(if(AnnualCTC>180000,21600,AnnualCTC*0.12))/12

While this formula can be used directly within {{MonthlyPF}}, administrators may prefer to split the calculation into smaller components.

Supporting Custom Key Configuration

In this example:

• AnnualPF is used only to calculate the annual Provident Fund amount.
• MonthlyPF uses the AnnualPF value to calculate the monthly Provident Fund amount.
• The document template contains only {{MonthlyPF}}.
• AnnualPF is never displayed in the generated document.

Why Use Supporting Custom Keys?

Supporting Custom Keys can help administrators:

• Simplify complex formulas
• Improve readability of calculations
• Reuse calculations across multiple Custom Keys
• Make future maintenance easier

For example, if Provident Fund calculation rules change, the administrator only needs to update the formula configured for AnnualPF rather than updating multiple formulas throughout the template.

Example

Although AnnualPF does not appear in the document template, it is still evaluated during document generation and used to calculate values for other Custom Keys.

Where It Reflects: Configured Custom Keys are used during document generation. The values populated for each Custom Key are reflected in the generated employee document.

Important Notes

• Any text enclosed within {{ }} is treated as a Custom Key (Placeholder) by the system.
• The system provides a large library of predefined Custom Keys that can be used within document templates.
• Administrators can create additional Custom Keys when required.
• Default values can be configured for Custom Keys.
• Formula-based Custom Keys can be used to calculate values dynamically.
• If a Custom Key does not have a value available during document generation, it may remain blank until updated manually.
• Custom Keys can be used across various document types including appointment letters, offer letters, increment letters, experience letters, and other employee communications.

Related Articles

Document Templates: Overview
https://hrstop.thedocs.in/1924/Document-Templates-Overview

Adding a Document Template
https://hrstop.thedocs.in/16/Adding-document-template

How to Input CTC for Auto Calculated Salary Components in Letters
https://hrstop.thedocs.in/1159/How-to-Input-CTC-for-Auto-Calculated-Salary-Components-in-Letters