Workflow Dev: Email Templates - EscherLabs/Graphene GitHub Wiki

Overview

Graphene Workflow Custom Emails utilize the mustache templating language for injecting current data regarding the workflow into the emails themselves. Mustache is typically used in the following ways:

Simply Print the Data: {{my_data}}
Check to see if the data is "truthy" (non-empty / non-zero / non-null): {{#my_data}}Data is truthy{{/my_data}}{{^my_data}}Data is not truthy{{/my_data}}
Iterate through a list of something: {{#pizza_toppings}} Topping: {{name}} {{/pizza_toppings}}

Using these basic techniques in conjunction with the data available (below), it should be possible to construct an email which conveys the relevant information in a meaningful way.

Notes and Considerations

The template objects as outlined in this document, while similar, are fundamentally different from the template objects available for building workflow submission reports. The email templates only support Mustache syntax, whereas the report templates utilize Ractive, which is a superset of mustache. Additionally, the report templates employ a considerably degree of preprocessing to the "form" object, such that additional data fields are available that are not available in email templates.

Email Templates do not support HTML syntax, as they are sent entirely in plain text.

Available Mustache Data Objects

Submission ID:

Unique ID of the workflow submission

{{id}}

Report URL:

Unique URL associated with this submission (to view in a web browser)

{{report_url}} (This typically looks something like https://my.binghamtion.edu/workflows/report/12345)

Form Data:

Data object of any field from the form. (Note that this requires intimate knowledge of the form data and the form data structure. For example, if there is a field in the form, at the root level called favorite_pizza_flavor, you would be able to access it as follows:

{{form.favorite_pizza_flavor}}

Owner / Original Submitter User Information:

This is information about the original person who initiated / submitted this workflow submission. (The Owner)

{{owner.first_name}}
{{owner.last_name}}
{{owner.email}}
{{owner.unique_id}} (User's BNumber)

Actor User Information:

This is information about the person who most recently took an action on this workflow submission. (The Actor)

{{actor.first_name}}
{{actor.last_name}}
{{actor.email}}
{{actor.unique_id}} (Actor's BNumber)

If you want to know if the owner of the workflow is also the actor, you can do so with the following:

{{#owner.is.actor}}Owner is the Actor{{/owner.is_actor}}

Action(s):

This is the most recent action which was taken on this workflow submission by the actor.

{{action.label}} (The human readable label associated with this action -- this is probably what you want in most situation)
{{action.name}} (The internal name associated with this action)
{{action.type}}

This will print out a comma separated list of all available actions (which can be taken by the currently assigned user / group members) in the current state

{{#actions}}{{label}}, {{/actions}}

If you want to conditionally display some information depending on whether there is at least one available action in the current state, you may use the following:

{{#is.actionable}}There's at least one action to take{{/is.actionable}}

Workflow Submission Status:

This is the current status of the workflow:

{{status}} (open/closed/new)

You may alternatively access the previous status of the workflow submission:

{{previous_status}} (open/closed/new)

If you want to conditionally display some text based on whether the workflow is currently open or closed (based on the current status), you may use either of the following:

{{#is.open}}The workflow is open{{/is.open}}
{{#is.closed}}The workflow is closed{{/is.closed}}

Workflow Submission State:

State that the workflow is currently in (based on the state blocks in the workflow definition):

{{state}}

State that the workflow just left (based on the state blocks in the workflow definition):

{{previous_state}}

If you wish to conditionally display some information depending on whether the user is currently in the initial (starting) state, you may use the following:

{{#is.initial}}The workflow is in the initial state{{/is.initial}}

General Information about the Workflow (not this particular submission):

{{workflow.name}}
{{workflow.description}}
{{workflow.instance.group_id}}
{{workflow.instance.slug}}
{{workflow.instance.name}}
{{workflow.version.id}}
{{workflow.version.summary}}
{{workflow.version.description}}

Comment:

This is the most recent comment which was left by the user/actor when performing the most recent "action"

{{comment}}

You can also use standard mustache syntax to see if the actor left a comment at all

{{#comment}}The actor left a non-empty comment{{/comment}}

Current Assignment Information

You can access information about the current assignment for the workflow submission. This one is a little bit tricky, however, as you need to be aware of whether the submission is currently assigned to an individual user or a group.

{{assignment.id}} (currently assigned user_id or group_id)
{{assignment.type}} (user, group, internal)

If the assignment type is user, you may additionally access the following:

{{assignment.user.first_name}}
{{assignment.user.last_name}}
{{assignment.user.email}}
{{assignment.user.unique_id}}

If the assignment type is group, you may additionally access the following:

{{assignment.group.name}}
{{assignment.group.id}}
{{assignment.group.slug}}

If the assignment is of type group, you may also access information about each of the group members as well. The following example iterates through all group members, and prints out their first name, last name, email address, and bnumber.

{{#assignment.group.members}}
  {{first_name}}
  {{last_name}}
  {{email}}
  {{unique_id}}
{{#assignment.group.members}}

Default Email Example

The following is an example of a generic email which might be sent to the people who have been most recently assigned to a workflow, instructing them that they need to take action on that workflow submission.

{{#assignment.user}}{{first_name}} {{last_name}} - {{/assignment.user}}
{{#assignment.group}}"{{name}}" Group Member - {{/assignment.group}}

You have been assigned the "{{workflow.name}}" workflow, which was  
submitted by {{owner.first_name}} {{owner.last_name}}.

{{#is.closed}}The workflow is currently CLOSED and in the "{{state}}" state. {{/is.closed}}

{{^was.initial}}
    This workflow was last updated by {{actor.first_name}} {{actor.last_name}} who performed
    the "{{action.label}}" action.  

    {{#comment}}They also provided the following comment: "{{{comment}}}"{{/comment}}
{{/was.initial}}

{{^is.actionable}} There are no actions to take at this time.{{/is.actionable}} 

{{#is.actionable}} 
    {{#actions.1}}
        You may take any of the following actions: {{#actions}}"{{label}}", {{/actions}}
    {{/actions.1}}
    {{^actions.1}}
        You may take the following action: "{{actions.0.label}}"
    {{/actions.1}}
{{/is.actionable}}
{{#is.open}}The workflow is currently OPEN and in the "{{state}}" state.{{/is.open}}

{{#is.actionable}}
    To take actions, or view the history / current status, visit the following: {{report_url}}
{{/is.actionable}}
{{^is.actionable}}
    You may view the full history of this workflow here: {{report_url}}
{{/is.actionable}}