JTL tags (short for Janrain Templating Language tags) provide a way for you to dynamically insert content into your transactional emails and (to a lesser extent) your two-factor authentication (2FA) messages. For example, in the following 2FA message the access code (217033) is dynamically generated and inserted into the message at the time the message is sent:

Couldn’t you just hardcode 217033 into your message text? Well, sure you could, but then every user who tried to log on would get the access code 217033 (which, needless to say, would do those users very little good). Instead, unique access codes must be generated each time a 2FA message is sent, and each user must get his or her own access code.

So how do you include an access code in a 2FA message without, well, actually including that access code in the message text? The answer is surprisingly simple: you use the JTL tag {{code}} instead. When a 2FA message is sent, this JTL tag tells the Identity Cloud to replace the tag with a newly-generated access code. For example, here’s what the HTML version of a 2FA message might look like:

<p>{{site_name}}: Your secure access code is {{code }. Do not share this code with anyone. {{site_name}} will never ask you for it.</p>

And, as we’ve already seen, that results in a 2FA message similar to this one:

Of course, sharp-eyed observers may have noticed a similar-looking bit of text in our sample message: {{site_name} }. Is that another JTL tag? As it turns out, it is: the {{site_name} } tag inserts the value of the site_name setting in the application client. By using the JTL tag, that means multiple sites can use the same 2FA message, with the message being “personalized” with the value of the site­_name setting.

📘

In case you’re wondering, in the preceding example the site name is Hosted Login v2 Login Client.

The approach is also used with transactional emails. Note the JTL tag (highlighted in red) in the following email text:

Your password has been updated for {*#settings*}{*&site_name*}{*/settings*}

In this document, we’ll detail the JTL tags available for your use when modifying two-factor authentication messages and transactional emails. These tags include the following:

• {{site_name}}
• {{code}} 
• {*#settings}{&site_name*}
• {*#user*}{*&given_name*}
• {*password_recover_url*}
• {*email_verification_url*}

Two-factor authentication tags

As you know, two-factor authentication messages transmit an access code to a user; the user must then enter that access code into an onscreen form in order to complete the authentication/registration process. Note that only two JTL tags are available for use in 2FA messages: {{site_name}} and {{code}}, as described below.

{{site_name}}

Name of the website, as specified by the site_name setting of the application client used when logging on to the site. In the following 2FA message, the value of the  {{site_name}} tag is Hosted Login v2 Login Client::

This JTL tag is used on the following 2FA messages:

• secondFactor
• resendVerification
• registrationVerification

{{code}}

The 2FA access code that must be entered in order to complete the authentication process. For example, in the following email the value of the {{code}} tag is 826798:

Although you can modify the text of your 2FA messages, those messages must include the {{code}} tag. If you remove this tag, the user won’t receive their access code and, as a result, won’t be able to complete the authentication process.

This JTL tag is used on the following 2FA messages:

• secondFactor
• resendVerification
• registrationVerification

Transactional email tags

Transactional emails offer a little more flexibility than 2FA messages; if nothing else, transactional emails can employ four default tags as opposed to two default tags . These "extra" tags are available because:

• There are more transactional email types than there are 2FA messages.

• Transactional emails carry out more tasks than 2FA messages. (2FA messages really only have one job: present the user with an access code.)

• Some transactional emails are sent after a user has logged on. Because post-login users are known users, that means these emails can contain information retrieved from the user’s user profile.

The following sections of this article cover the following topics:

• The {*#settings*}{*&site_name*}{*/settings*} tag
• The {*#user*}{*&given_name*}{*/user*} tag
• The {*password_recover_url*} tag
• The {*email_verification_url*} tag

The {*#settings*}{*&site_name*}{*/settings*} tag

Name of the website as specified by the site_name setting of the application client used when logging on to the site. The site_name is used in transactional emails and also shows up on various Hosted Login screens; for example, in Hosted Login v2 the site_name (in this example, Identity Cloud Documentation) appears on the sign-in screen:

The {*#settings*}{*&site_name*}{*/settings*} JTL tag is used with the following transactional emails:

• emailAddressChanged
• passwordChanged
• passwordRecover
• registrationConfirmation
• registrationVerification
• resendVerification
• ccp_emailAddressChanged
• ccp_passwordRecover
• ccp_registrationVerification

The {*#user*}{*&given_name*}{*/user*} tag

Given name (first name) of the user. The value for the {*#user*}{*&givenName*}{*/user*} JTL tag is taken from the givenName attribute in the user’s user profile. For example, in the following email the value of the {*#user*}{*&givenName*}{*/user*} tag is Greg:

This JTL tag is used on the following transactional emails:

• ccp_emailAddressChanged
• ccp_passwordRecover
• ccp_registrationVerification

The {*password_recover_url*} tag

Unique URL a user is directed to in order to reset a forgotten password. For example, in the following email the value of the {*password_recover_url*} tag is https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/reset-password?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7&code=tkks8pb49ms5c2:

The {*password_recover_url*} value is created by combining the value of the password_recover_url setting found in the application client with a unique access code. Each password recovery URL can only be used once.

This JTL tag is used on the following transactional emails:

• passwordChanged
• passwordRecover
• ccp_passwordRecover

The {*email_verification_url*} tag

Unique URL a user is directed to in order to verify an email address. For example, in the following email the value of the {*email_verification_url*} tag is https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/verify-account?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7&verification_code=5fhtjdpq9fzqkkze2mhfx5heakxstrbe:

The {*email_verification_url*} value is created by combining the value of the verify_email_url setting found in the application client with a unique access code. Each email verification URL can only be used once.

This JTL tag is used on the following transactional emails:

• emailAddressChanged
• registrationVerification
• resendVerification
• ccp_emailAddressChanged
• ccp_registrationVerification