Creating and Customizing Email Templates

Creating an email template requires creating a new Form definition within Process Director. In the Options section of the Create Form dialog, ensure that you check the Email Template checkbox. If this property isn't checked, Process Director will create a normal Form definition, which can't be used as an email template.

You can also use a custom ASCX file for your email template, just like you can when creating a regular Form definition. Simply select the option you desire from the dropdown marked "Online Form Designer". In nearly all use cases, the default choice of the Online Form Designer is the simplest option, but you have the option to create a custom ASCX control in ASP.NET using Visual Studio (assuming you have this license option).

Your email template is now stored in the Content List. You can edit the template by selecting the template to edit and then select the Edit tab.  You can make changes to your template in your preferred editor.

Email Templates and Controls #

While email templates are technically a type of Process Director Form, are generated by the Process Director server, and use the Online Form Designer to create their content and styling, email templates have limitations that normal data input Forms do not. An email template can only generate the plain text of an email message. Unlike a normal Form, an email template cannot use any data input controls. An email cannot display text, textarea, dropdown, or any other type of input control, nor can an email store form field information generated by end users in any way. Why is this?

Email messages are plain text messages. Even HTML email messages, with their styling and other HTML display elements, are simple text messages that just happen to include HTML markup as part of the plain text. Your email client, like Outlook, can convert the HTML markup to display the desired styling when you view the email message, but this is generated from the plain text of the email message itself. All email messages are nothing more than simple text files.

The only controls that can be used on an Email Template are controls that can be converted to plain text when the email is generated. This limitation enables only a limited set of controls like the System Variable control, which gets converted to plain text when the message is generated, or the Hotlink control that also gets converted to an HTML text hyperlink. A special control used only on email templates, the Email Data control, also converts to plain text to provide the subject and return addresses for the email message at run-time. All of the other data entry controls, such as the Input, Dropdown, Checkbox, etc., cannot function in an Email template. Data entry controls will not work in an email template, and users cannot provide any data to Process Director from an email message.

Moreover, email messages have no memory or user context. They can't accept or store user input, and can't even tell whether the person who opens and reads the email is the originally intended recipient. Once sent, a email template is just a text message, and has no other content outside the actual text of a message.

Use of images in email templates is not recommended, as most email clients strip all images from email messages and prevent them from displaying by default. There are methods to override this behavior for different email clients. Please see Microsoft's explanation of this behavior on their web site, as well as the Apple's explanation for similar behavior on the default Mail client on both iPhone/Ipad devices, and on the Macintosh.

If, despite the default image blocking on email clients, you decide to use an image, such as a logo, on an email template, you must use a fully qualified URL as the image URL. Partial or relative URLS will not be able to properly access the image. E.g., a URL like https://www.server.com/images/imagename.jpg will work, but a partial or relative URL like /images/imagename.jpg will not display the image.

Email Variables #

Variable substitutions are performed when an email file is processed for a process request. System variables can be added to the email, either by typing them in plain text, or by using the System Variable control. To see the complete list of system variables, please refer to the System Variables guide. Note that not all system variables are available for every event that generates an email.

The Subject, From Email, Mail Priority, From Display, Send As Attachment, Group Name and Cancel Email properties are contained in each email template as properties of the Email Data control.

EmailData Control #

The Email Data object enables you to customize various aspects of notification emails such as the email subject, reply-to addresses, etc. Inserting the Email Data control produces this object in your Form:

By double-clicking on it, you can open its properties dialog box , shown below, to edit its properties.

For information about this control's properties, please see the EmailData Control topic.

You can add multiple EmailData controls to an email template. Use the Condition Builder to optionally show and hide these by going to the control in the Form properties page and setting a condition on each EmailData tag created. Each tag has a unique ID.

Once you have multiple Email Data objects on the email template, you’ll need to set up conditional visibility of the objects. On the Forms Controls tab of the email template file, you can set conditions of what email data or email sections should be used like this:

This Email Data object will be visible when the email type is “Task Assigned”. There is more about these Email types in the next section, “Email Template Conditional Processing”, below. One more thing to note: when multiple Email Data objects’ conditional statements will evaluate as “true”, then PD will work through the separate Email Data objects  in order, and information in properties input boxes will be replaced by non-blank properties boxes of the next Email Data object. If any of the “Cancel Email” boxes are checked in any displayed Email Data objects, the email won't be sent.

There is one email type that is sent when a user's task is completed due to a condition that completes the task without the user's involvement. For example, a task may assigned to a group of users, but be set to complete when the first user in the assigned group completes the task. In this case, the default behavior is for all users to receive the task completion email. Essentially, for any function that causes a user to be marked as "Not Required", all assigned users will receive email notifications that the task is complete. If you don't want this behavior, add an EmailData tag or control to the email template with the "Cancel Email" option set to True. Be sure to place that Email Data control in a section that is visible when the email type is "not needed".

ASPX Format

<bpx:EmailData ID="StepName" runat="server" Subject="Subject line" MailPriority="High"
    FromEmail="{CREATE_USER, format=email}" FromDisplay="{CREATE_USER}" SendAsAttachment="True"
    GroupName="Group" CancelEmail="True">
</bpx:EmailData>

Email Template Conditional Processing #

The email templates can optionally contain Section tags that can control what portions of the email should be displayed under different conditions (e.g. value of a form field).  You can optionally display any control that has an ID which will display in the list of controls on the Form properties page. Conditional processing allows you to display a type of email to use such as the reminder email type. You can conditionally display controls based on the type of email. The following email types are available in Process Director:

• Task Assigned
• Reminder Email
• Task Timeout
• Task Canceled
• Step Started
• Step Stopped

Refer to the chapter on Form Definitions for more information on conditional processing. To test email templates that contain Form tags, upload the email template to Process Director as a Form but marked as an Email Template to have the built-in parser validate the use of your Form tags. This will only allow the email template to be validated; it won't be a valid Form.

Task Links in an Email #

The email templates can optionally contain links that allow the user to complete their task. This system tag will add the task URL to the link tag in the HTML email allowing the user to click on it to open in the browser and complete their task.

In the Online Form Designer:

{EMAIL_URL}

In .ascx:

<bpx:HTML ID="ControlName" runat="server" HTMLString="<a href='{EMAIL_URL}'>Click here to view the process</a>">
</bpx:HTML>

This system tag will return the URL that can be placed within an <A> tag on the HTML email.

Complete Links in an Email #

Email templates can contain links that allow the user to complete their task without having to view a Form.

{EMAIL_RESULT_LINKS, comments=1, confirm=1, separator="<br>", icon=1}

This system tag will return the possible branches to take. It creates an HTML link with the URLs for all of the possible results in a Process Timeline Activity assigned to the user.

ARGUMENT	TYPE	DEFINITION
comments	true/false(default value)	The user is prompted to comment if true
Confirm	true(default value)/false	The user is required to confirm the task has been completed
Separator	HTML tags	characters to separate the list of links
Icon	true(default)/false	Optional icons/images from the Timeline Activity results appear next to each of the links. NOTE: Process Timeline results don't have image icons.

Example

Possible Branches to Take:

{EMAIL_RESULT_LINKS, comments=1, confirm=1, separator="<br>", icon=1}


This system tag will return a comma separated list of all of the possible results from a result in a Process Timeline Activity assigned to the user. This tag is useful for reply options the recipient must use. The next process may be scanning to match text in the sent Email.

Example

Please enter one of these keywords in responding to this Email:

{Email_Result_List}
{EmailCompleteLink, text=Approve, comments=1, confirm=1, action=Approve}

This System Tag is a link to a web page allowing their user to complete their task.

Each EmailCompleteLink System Tag with its arguments corresponds to one result in a Process Timeline Activity. Remember to name this Email Template as the “Default Email template” in the Process Timeline definition.

ARGUMENT	TYPE	DEFINITION
Text	string	text to display on the link (e.g. Approve, Resubmit, Reject)
Comments	true/false(default value)	The user is prompted to comment if true
Confirm	true(default value)/false	The user is required to confirm the task has been completed
Action	string	The Process Timeline Activity result (e.g. Approve, Resubmit, Reject)

Example

{EmailCompleteLink, text=APPROVE, comments=true, confirm=true, action=APPROVED}

{EmailCompleteLink, text=RESUBMIT, comments=true, confirm=true, action=RESUBMIT}

{EMAIL_COMPLETE_URL, action=Approve, comments=1, confirm=1}

This system tag will return the URL that can be placed within an <A> tag on the HTML email.

ARGUMENT	TYPE	DEFINITION
Text	string	text to display on the link (e.g. Approve, Resubmit, Reject)
Comments	true/false(default value)	The user is prompted to comment if true
Confirm	true(default value)/false	The user is required to confirm the task has been completed
Action	string	The Process Timeline Activity result (e.g. Approve, Resubmit, Reject)

URL Access to the Process Instance #

Workflow (wd.aspx)

The Workflow object is the legacy process model used in early versions of Process Director. BP Logix recommends the use of the Process Timeline object, and not the Workflow object. The Workflow object remains in the product for backwards compatibility, but doesn't receive any new functionality updates, other than required bug fixes. No new features have been added to this object since Process Director v4.5. All new process-based functionality is solely added to the Process Timeline.

Description

This URL can be used for in Workflow emails. It is used to construct a hotlink back to the originating Workflow.

Parameters

PARAMETER NAME	DESCRIPTION
forminstid	The ID of the form instance to display.

Examples

This example will create a hotlink in an ASCX Email template which points back to the Workflow's Form

<bpx:HTML runat="server" HTMLString="<a href='{INTERFACE_URL}wd.aspx?forminstid={FORM_INSTANCE_ID}'>
    Click Here to View the Form Instance</a>">
</bpx:HTML>

Process Timeline (pd.aspx)

Description

This URL can be used for in Process Timeline emails. It is used to construct a hotlink back to the originating Process Timeline.

Parameters

PARAMETER NAME	DESCRIPTION
forminstid	The ID of the form instance to display.

Examples

This example will create a hotlink in an ASCX Email template which points back to the Process Timeline  Form

<bpx:HTML runat="server" HTMLString="<a href='{INTERFACE_URL}pd.aspx?forminstid={FORM_INSTANCE_ID}'>
    Click Here to View the Form Instance</a>">
</bpx:HTML>

Documentation Example #

You can use the software simulation below to walk through the process of creating a new email template.