Email Templates: Difference between revisions

From Obsidian Scheduler
Jump to navigationJump to search
← Older edit
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
As of version 2.0, Obsidian supports customizable templates for all email notifications.
As of version 2.0, Obsidian supports customizable templates for all email notifications.


== Template Basics ==
If you have questions or require help building your own templates, please [[Contact Carfey Software|contact us]] for free support.
 
== Template Basics & Language ==


Obsidian comes with two basic email templates that are suitable for most users. For those that wish to have more control, templates can be configured in the '''[[Admin Templates|Email Templates]]''' screen.
Obsidian comes with two basic email templates that are suitable for most users. For those that wish to have more control, templates can be configured in the '''[[Admin Templates|Email Templates]]''' screen.


Both subject and body fields can be templated. Note that body templates are used for '''HTML only'''.
Both subject and body fields can be customized through  templates. Note that body templates are used for '''HTML only'''.


== Templating Language ==
Obsidian email templates use [http://mustache.github.io/ Mustache], which is a logic-less templating language commonly used in various applications. Specifically, Obsidian uses [https://github.com/samskivert/jmustache jMustache], and it can be referred to when looking for feature support and general syntax in your templates.


Obsidian email templates use [http://mustache.github.io/ Mustache], which is a logic-less templating language commonly used in various applications. Specifically, Obsidian uses [https://github.com/samskivert/jmustache jMustache], and it can be referred to when looking for feature support and general syntax in your templates.
'''Note:''' Obsidian cannot guarantee that configured templates are valid. You are responsible for ensuring the correctness or your templates according to the information provided below. If you have configured Obsidian to use invalid templates that fail, Obsidian will fall back to internal templates so that notifications are not lost.


== Templating Variables ==
== Templating Variables ==


The following table documents all data elements that are available in email templates. Note that some data elements are only available in certain contexts, so your templates should be written accordingly. The ''Available Scope'' column indicates what types of events the variable is used in. For example, some variables are only present for job-related event categories, and some are only present for Job Run events.
The following table documents all data elements that are available in email templates. Note that some data elements are only available in certain contexts, so your templates should be written accordingly. The ''Available Scope'' column indicates which types of events the variables are used in. For example, some variables are only present for job-related event categories, and some are only present for Job Run events.


If you wish to see a sample template, simply navigate to the '''[[Admin Templates|Email Templates]]''' screen in the admin UI, and take a look at the default templates that are pre-installed.
If you wish to see a sample template, simply navigate to the '''[[Admin Templates|Email Templates]]''' screen in the admin UI, and take a look at the default templates that are pre-installed.
Line 22: Line 24:
| subject || Text || Always || This the basic event summary message.
| subject || Text || Always || This the basic event summary message.
|-
|-
| detailItems || Text (multiple) || Always || The list of all detail messages provided with the event. For example, when a job's configuration is updated, a separate item for each change will be represented here. In some cases, this may be empty.
| detailItems || Text (multiple) || Always || The list of all detail messages provided with the event. For example, when a job's configuration is updated, a separate item for each change will be represented here. For job execution failures, this will contain the stack trace. In some cases, this may be empty.
|-
|-
| detail || Text || Always || This the combined form of ''detailItems''. In some cases, this may be empty.
| detail || Text || Always || This the combined form of <code>detailItems</code>. In some cases, this may be empty.
|-
|-
| hostName || Text || Always || The host name / designator that originated the event.
| hostName || Text || Always || The host name / designator that originated the event.
|-
|-
| hostUrl || Text || Always || The host URL as configured in the Systems tab. This can be used to link to the Obsidian installation in emails.
| hostUrl || Text || Always || The host URL as configured in the [[Admin Scheduler Settings|scheduler settings]] screen. This can be used to link to the Obsidian installation in emails.
|-
|-
| hasDetail || Boolean || Always || Indicates if any ''detailItems'' exist. Can be used for conditionals.
| hasDetail || Boolean || Always || Indicates if any <code>detailItems'</code> exist. Can be used for conditionals.
|-
|-
| level || Text || Always || Indicates the level of the event. One of: <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, <code>FATAL</code>.
| level || Text || Always || Indicates the level of the event. One of: <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, <code>FATAL</code>.
|-
| category || Text || Always || Indicates the category of the event. Available as of 2.3. One of: <code>SYSTEM_PARAMETER</code>, <code>QUEUE</code>, <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RUN</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>.
|-
| levelDisplayName || Text || Always || Indicates the level of the event, in a pretty format. Available as of 2.3. One of: <code>Info</code>, <code>Warning</code>, <code>Error</code>, <code>Fatal</code>.
|-
| categoryDisplayName || Text || Always || Indicates the category of the event, in a pretty format. Available as of 2.3. One of: <code>System Parameter</code>, <code>Queue</code>, <code>Job</code>, <code>Job Chain</code>, <code>Job Config</code>, <code>Job Run</code>, <code>Job Recovery</code>, <code>Licence</code>.
|-
|-
| recipients || Text (multiple) || Always || The email addresses of all recipients of this message.
| recipients || Text (multiple) || Always || The email addresses of all recipients of this message.
Line 48: Line 56:
| info || Boolean || Always || Indicates if the level was <code>INFO</code>.
| info || Boolean || Always || Indicates if the level was <code>INFO</code>.
|-
|-
| job || Complex Object || Job Events only || For any job-related category, this field is populated. Attributes that can be accessed on the job are: <code>id</code>, <code>jobClss</code>, <code>minExecutionDuration</code>, <code>maxExecutionDuration</code>, <code>nickname</code>, <code>pickupBufferMinutes</code> and <code>recoveryType</code>.
| job || Complex Object || Job Events only || For any job-related category, this object provides the basic job configuration. Attributes that can be accessed on the job are: <code>id</code>, <code>jobClass</code>, <code>minExecutionDuration</code>, <code>maxExecutionDuration</code>, <code>nickname</code>, <code>pickupBufferMinutes</code> and <code>recoveryType</code>.
|-
| jobState || Complex Object || Job Events only || For any job-related category, this object provides the current job schedule configuration, or for Job Run events, the schedule applicable to that job history record. Attributes that can be accessed on the jobState are: <code>effectiveDate</code>, <code>endDate</code>, <code>jobStatus</code> and <code>schedule</code>.
|-
| currentSchedule || Text || Job Events only || This is a simplified way to access <code>jobState.schedule</code>.
|-
| jobHistory || Complex Object || Job Run Events only || For any Job run events (i.e.. completion or failure), this object contains information on the job execution (aka history). Attributes that can be accessed on the job are: <code>adHoc</code> (boolean), <code>resubmission</code> (boolean), <code>runningHost</code>, <code>scheduledTime</code> and <code>submissionMode</code>. The field <code>chainedFrom</code> provides access to the source chain job history when applicable, which has the same format as this <code>jobHistory</code> object. From either this object or <code>chainedFrom</code>, the <code>job</code> field provides access to the job configuration in the same format as the <code>job</code> element described above.
|-
| jobResults || List of Objects || Job Run Events only || This field contains saved job results as a list of objects with two attributes: <code>key</code> for the name and <code>value</code> for a list of the applicable values. Example: iterate over all results and output the values separated by commas: <pre>{{#jobResults}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobResults}}</pre>
|-
| jobResultMap || Map Object || Job Run Events only || This is an alternate format of <code>jobResults</code> stored in a map. This allows you to easily access a specific result by name. Example: <pre>{{#jobResultMap.outputFiles}}{{.}}{{/jobResultMap.outputFiles}}</pre>
|-
| jobParameters || Complex Object || Job Events only || This field contains saved job parameters as a list of objects with two attributes: <code>key</code> for the name and <code>value</code> for a list of the applicable values . Example: iterate over all results and output the values separated by commas: <pre>{{#jobParameters}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobParameters}}</pre>
|-
| jobParameterMap || List of Objects|| Job Events only ||  This is an alternate format of <code>jobParameters</code> stored in a map. This allows you to easily access a specific parameter by name. Example: <pre>{{#jobParameterMap.archiveDirectory}}{{.}}{{/jobParameterMap.archiveDirectory}}</pre>
|}
|}


Line 69: Line 91:
Host Name: {{hostName}}
Host Name: {{hostName}}
Host Url: {{hostUrl}}
Host Url: {{hostUrl}}
Level: {{level}}
Level: {{level}} - {{levelDisplayName}}
Category: {{category}} - {{categoryDisplayName}}
Recipients: {{#recipients}}{{^-first}}, {{/-first}}{{.}}{{/recipients}}
Recipients: {{#recipients}}{{^-first}}, {{/-first}}{{.}}{{/recipients}}
Subject: {{subject}}
Subject: {{subject}}

Latest revision as of 17:31, 1 July 2016

As of version 2.0, Obsidian supports customizable templates for all email notifications.

If you have questions or require help building your own templates, please contact us for free support.

Template Basics & Language

Obsidian comes with two basic email templates that are suitable for most users. For those that wish to have more control, templates can be configured in the Email Templates screen.

Both subject and body fields can be customized through templates. Note that body templates are used for HTML only.

Obsidian email templates use Mustache, which is a logic-less templating language commonly used in various applications. Specifically, Obsidian uses jMustache, and it can be referred to when looking for feature support and general syntax in your templates.

Note: Obsidian cannot guarantee that configured templates are valid. You are responsible for ensuring the correctness or your templates according to the information provided below. If you have configured Obsidian to use invalid templates that fail, Obsidian will fall back to internal templates so that notifications are not lost.

Templating Variables

The following table documents all data elements that are available in email templates. Note that some data elements are only available in certain contexts, so your templates should be written accordingly. The Available Scope column indicates which types of events the variables are used in. For example, some variables are only present for job-related event categories, and some are only present for Job Run events.

If you wish to see a sample template, simply navigate to the Email Templates screen in the admin UI, and take a look at the default templates that are pre-installed.

Variable Name Type Available Scope Notes
subject Text Always This the basic event summary message.
detailItems Text (multiple) Always The list of all detail messages provided with the event. For example, when a job's configuration is updated, a separate item for each change will be represented here. For job execution failures, this will contain the stack trace. In some cases, this may be empty.
detail Text Always This the combined form of detailItems. In some cases, this may be empty.
hostName Text Always The host name / designator that originated the event.
hostUrl Text Always The host URL as configured in the scheduler settings screen. This can be used to link to the Obsidian installation in emails.
hasDetail Boolean Always Indicates if any detailItems' exist. Can be used for conditionals.
level Text Always Indicates the level of the event. One of: INFO, WARNING, ERROR, FATAL.
category Text Always Indicates the category of the event. Available as of 2.3. One of: SYSTEM_PARAMETER, QUEUE, JOB, JOB_CHAIN, JOB_CONFIG, JOB_RUN, JOB_RECOVERY, LICENCE.
levelDisplayName Text Always Indicates the level of the event, in a pretty format. Available as of 2.3. One of: Info, Warning, Error, Fatal.
categoryDisplayName Text Always Indicates the category of the event, in a pretty format. Available as of 2.3. One of: System Parameter, Queue, Job, Job Chain, Job Config, Job Run, Job Recovery, Licence.
recipients Text (multiple) Always The email addresses of all recipients of this message.
fatal Boolean Always Indicates if the level was FATAL.
error Boolean Always Indicates if the level was ERROR.
errorOrHigher Boolean Always Indicates if the level was FATAL or ERROR.
warn Boolean Always Indicates if the level was WARNING.
warnOrHigher Boolean Always Indicates if the level was FATAL, ERROR or WARNING.
info Boolean Always Indicates if the level was INFO.
job Complex Object Job Events only For any job-related category, this object provides the basic job configuration. Attributes that can be accessed on the job are: id, jobClass, minExecutionDuration, maxExecutionDuration, nickname, pickupBufferMinutes and recoveryType.
jobState Complex Object Job Events only For any job-related category, this object provides the current job schedule configuration, or for Job Run events, the schedule applicable to that job history record. Attributes that can be accessed on the jobState are: effectiveDate, endDate, jobStatus and schedule.
currentSchedule Text Job Events only This is a simplified way to access jobState.schedule.
jobHistory Complex Object Job Run Events only For any Job run events (i.e.. completion or failure), this object contains information on the job execution (aka history). Attributes that can be accessed on the job are: adHoc (boolean), resubmission (boolean), runningHost, scheduledTime and submissionMode. The field chainedFrom provides access to the source chain job history when applicable, which has the same format as this jobHistory object. From either this object or chainedFrom, the job field provides access to the job configuration in the same format as the job element described above.
jobResults List of Objects Job Run Events only This field contains saved job results as a list of objects with two attributes: key for the name and value for a list of the applicable values. Example: iterate over all results and output the values separated by commas: 
{{#jobResults}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobResults}}
jobResultMap Map Object Job Run Events only This is an alternate format of jobResults stored in a map. This allows you to easily access a specific result by name. Example: 
{{#jobResultMap.outputFiles}}{{.}}{{/jobResultMap.outputFiles}}
jobParameters Complex Object Job Events only This field contains saved job parameters as a list of objects with two attributes: key for the name and value for a list of the applicable values . Example: iterate over all results and output the values separated by commas: 
{{#jobParameters}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobParameters}}
jobParameterMap List of Objects Job Events only This is an alternate format of jobParameters stored in a map. This allows you to easily access a specific parameter by name. Example: 
{{#jobParameterMap.archiveDirectory}}{{.}}{{/jobParameterMap.archiveDirectory}}

Sample Syntax

The following shows various ways data can be accessed from within an Obsidian email template. This example lacks HTML formatting and is meant to show how to access and display different variables available to your templates. 

Current Job Schedule: {{currentSchedule}}
Detail: {{detail}}
{{#detailItems}}
Detail {{-index}}: {{.}}
{{/detailItems}}
Error: {{#error}}true{{/error}}{{^error}}false{{/error}}
Error or Higher: {{#errorOrHigher}}true{{/errorOrHigher}}{{^errorOrHigher}}false{{/errorOrHigher}}
Fatal: {{#fatal}}true{{/fatal}}{{^fatal}}false{{/fatal}}
Warn: {{#warn}}true{{/warn}}{{^warn}}false{{/warn}}
Warn or Higher: {{#warnOrHigher}}true{{/warnOrHigher}}{{^warnOrHigher}}false{{/warnOrHigher}}
Info: {{#info}}true{{/info}}{{^info}}false{{/info}}
Host Name: {{hostName}}
Host Url: {{hostUrl}}
Level: {{level}} - {{levelDisplayName}}
Category: {{category}} - {{categoryDisplayName}}
Recipients: {{#recipients}}{{^-first}}, {{/-first}}{{.}}{{/recipients}}
Subject: {{subject}}
Job: {{#job}}{{id}} {{nickname}} {{pickupBufferMinutes}} {{recoveryType}} {{jobClass}} {{minExecutionDuration}} {{maxExecutionDuration}}{{/job}}
Job State: {{#jobState}}{{effectiveDate}}-{{endDate}} {{jobStatus}} {{schedule}}{{/jobState}}
Job History: {{#jobHistory}}{{adHoc}} {{resubmission}} {{scheduledTime}} {{submissionMode}} {{runningHost}}{{#chainedFrom}}; Chained from: {{this.job.nickname}} ({{this.scheduledTime}}){{/chainedFrom}}{{/jobHistory}}
Job Results: {{#jobResults}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobResults}}
Job Results by Name: {{#jobResultMap}}{{#result1}}{{^-first}}, {{/-first}}{{.}}{{/result1}}{{/jobResultMap}}
Job Results by Name (short): {{#jobResultMap.result2}}{{.}}{{/jobResultMap.result2}}
Job Parameters: {{#jobParameters}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobParameters}}
Job Parameters by Name: {{#jobParameterMap}}{{#param1}}{{^-first}}, {{/-first}}{{.}}{{/param1}}{{/jobParameterMap}}
Job Parameters by Name (short): {{#jobParameterMap.param2}}{{.}}{{/jobParameterMap.param2}}
Retrieved from "https://wiki.obsidianscheduler.com/doc/index.php?title=Email_Templates&oldid=2952"