Using Customer Keys (Placeholders) in Document Templates

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 field is populated and carried into the document.
• 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: {{EmployeeDearnessAllowance}}, {{VariableMonthlyBonus}}, {{GratuityAmount}}, {{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 Available within the System

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 administration-defined Custom Key {{ExtensionDuration}}:

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

Result: Administration-defined Custom Keys can be populated using a configured default value or a 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:

Formula Configuration:

Formula-based Custom Keys can reference other Custom Keys, allowing administrators to build complex calculations using multiple levels of formulas.

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

Using Supporting Custom Keys

Supporting Custom Keys do not need to be present within the document template to be used during calculations.

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

{{AnnualPF}}=if(AnnualCTC<180000,21600,AnnualCTC*0.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.

Supporting Custom Keys can help administrators:

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

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

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.

Best Practices

• Use predefined System Keys wherever possible.
• Create administrator-defined Custom Keys only when the required information is not available as a System Key.
• Use meaningful names for Custom Keys to make templates easier to maintain.
• Use Supporting Custom Keys to simplify complex formulas.
• Test templates with sample employee records before using them for production document generation.

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.
• Default values can be configured for Custom Keys.
• Formula-based Custom Keys can be used to calculate salary components 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.
• For salary letters where employee salary is already configured in HRStop Payroll, payroll-linked placeholders can be used to auto-populate salary tables. Refer to: Salary Placeholders in Document Templates using HRStop Payroll Data

Related Articles

• Document Templates: Overview
• Adding a Document Template
• Salary Placeholders in Document Templates using HRStop Payroll Data
• Editing a Document Template
• Generating Salary Letters by Entering CTC
• Generating a Document