Custom Templates for Transactional Email Service

Details Required to Create a Custom Template

To create a custom template, you will need:

• Template name and subject.
• Application(s) to associate the template with.
• The template content (.html and .txt files compressed in a zip).
• A list of template variables and their descriptions.

Zip File Format and Naming Conventions

• Place all template files (.html and .txt) in a single folder.
• The zip file must contain one .html file and one .txt file for each locale provided in the subject.
• Compress the folder into a .zip file.

Note the following conventions for the files:

• The .html file should be named <locale>.html
• The .txt file should be named <locale>.txt
• For example, if you have English and French content, the zip file should contain:
  • en.html
  • en.txt
  • fr.html
  • fr.txt
• The styles used in the .html file should be inline styles to ensure proper rendering across different email clients
• Use tables for layout in the .html file, as this is widely supported by email clients. Avoid using modern CSS layout techniques like flexbox or grid, as they may not render correctly in all email clients
• The .txt file should contain the plain text version of the email content, without any HTML tags or styling

How to Submit a Request for a Custom Template

1. Prepare the zip file as described above.

2. Fill this Template Submission Form with the following details:

   • Main point of contact for feedback.
   • Business Unit information.
   • Template name with no spaces.
   • Sender name to be displayed in the inbox, not in email_address.
   • Dynamic variables for the email body, such as recipient_first_name.
   • Comma-separated Trimble Identity Application IDs that should be authorized to use this template in Staging and Production. Avoid spaces in between. You can subscribe to the Transactional Email Service and find your Application IDs in the API Cloud Console.
   • Email content in HTML and text formats in a .zip file generated using the Template Generator Tool.
   • All variables must be specified in the template using the format {variable_name}.
   • Variables cannot contain -; use _ instead. For example, use {first_name} instead of {first-name}.
   • Allowed variable names must match this regular expression: [A-Za-z_][A-Za-z_0-9].
   • Subjects localized by language code in JSON format.

3. After you submit the form, you will receive an email with the Jira ticket ID and follow-up comments on approval status and templateID.

Example JSON for Subjects

{
  "de": {
    "subject": "Trimble-Einladung: Konto anlegen"
  },
  "fi": {
    "subject": "Trimble-kutsu: Luo tili"
  },
  "ru": {
    "subject": "Приглашение использовать продукт Trimble: создание учетной записи"
  },
  "bg": {
    "subject": "Покана за Trimble: Създаване на акаунт"
  },
  "fr": {
    "subject": "Invitation de Trimble : Créer un compte"
  },
  "hu": {
    "subject": "Trimble meghívó: Fiók létrehozása"
  },
  "en": {
    "subject": "Trimble Invitation: Create Account"
  }
}

Using Jinja in Custom Templates

Custom templates support Jinja for dynamic content. You can use Jinja if and for conditions, along with variable interpolation.

Example:

{% raw %}

{% if user.is_active %}
  Welcome, {{ user.name }}!
{% else %}
  Please activate your account.
{% endif %}

<ul>
{% for item in items %}
  <li>{{ item }}</li>
{% endfor %}
</ul>

{% endraw %}

Keep Jinja logic simple for easier maintenance. For more details, refer Jinja documentation.

How to Edit Custom Templates

To edit a custom template:

1. Update the template files as needed and create a new zip file.
2. Email template-management-ug@trimble.com with:
   • The updated zip file.
   • Application details.
   • Modified template variables, if any.
   • A summary of the changes.

How to Migrate Templates from Stage to Production

1. Finalize and test your custom template in Staging.
2. Email template-management-ug@trimble.com, or comment in the Jira ticket, with the tested zip file and a request to migrate it to Production.
3. Include any relevant application and template details.

Our team will review the request and migrate the template to Production.

See Best practices for more details and formatting recommendations.