Use an Employee Property as a Token

In addition to standard Employee, Candidate, and Interview letter tokens, you can also use custom employee properties as tokens. The contents of the employee property's Value field as shown in the Employment > Employee Properties screen of People for each recipient is populated into your letters. See Add Employee Properties in the HR Administration Guide.

When you distribute the letter, the employee property value for the token is populated in the letter text based on the effective date of the letter. A warning message is shown for any token that doesn't populate because the property's Value field is blank.

Six data types are supported in the property's Value field, and the values are inserted in letters in the following ways:

• Boolean: A true or false selection. In a letter, the choice populates as the words True or False.
• DateTime: A calendar date. In a letter, the date is populated according to the culture settings of the letter template.
• Numeric: A number. In a letter, the number is populated up to nine digits ranging from -99999999 to 999999999. You can use decimal values as long as the number (not including the decimal point) doesn’t have more than nine digits. Decimals can have a maximum precision of five digits.
• Picklist: A selection where users select from a drop-down list. In a letter, the selection is populated exactly as defined in the Name value of the Employee Property picklist configuration in HR Admin > Employee Properties.
• String: An alphanumeric value. In a letter, the string populates exactly as entered.
• Time: The time of the day. In a letter, the time is formatted to the culture settings of the letter template.

If the employee property's Assignable field selection is Many at a time, all of the corresponding values are populated in the letter as a comma-separated list. For example: Value 1, Value 2, Value 3, Value 4.

To set up and use an employee property as a token:

1. Go to HR Admin > Employee Properties, and click an existing employee property. Or click Add to create a new employee property. See Create Employee Properties in the HR Administration Guide.
2. Select Use Property as a Letter Management Token.
3. Complete all of the required fields for the property, then click Save. Make a note of the code in the Reference Code field in the General section. You reference this code when you create your token in Letter Management.
4. Go to the Employment > Employee Properties screen of People for each of the intended letter recipients and for each of them make sure that a value is saved in the Value field for each property that you want to use as a token.
5. Go to Letter Management > Template Designer and click an existing template.
6. Place the cursor in the area of the text editor where you want to add the token. Enter your token as {{EP_[EmployeePropertyXrefCodeX]}}, where [EmployeeProperty XrefCodeX] is the value in the property's Reference Code field.
7. For example, if you have an employee property with an XrefCode of 3 that keeps track of employee shirt size as a string value, the following sample paragraph populates the size in the recipient's letter:
8. Dear {{EMPLOYEE_FIRST_NAME}},
9. We are looking forward to welcoming you to our annual picnic. Our records show that your t-shirt size is {{EP_EmployeePropertyXrefCode3}}.