tib formvine 3.3.3 email customization guide...Customizing email |10 Chapter 1 Customizing email...

Two-Second Adv

TIBCO Formvine®

Email Customization GuideSoftware Release 3.3.3June 2015

antage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.TIBCO, Two-Second Advantage, TIBCO Hawk, TIBCO Rendezvous, TIBCO Runtime Agent, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, TIBCO Designer, TIBCO ActiveMatrix Service Gateway, TIBCO BusinessEvents, TIBCO BusinessConnect, and TIBCO BusinessConnect Trading Community Management are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 2010-2015 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

TIBCO Formvine Email Customization Guide

Contents | 4

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Typographical conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

How to contact TIBCO support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 1 Customizing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Overview of Formvine emails. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Why customize?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

What is customizable? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Customizing email templates and properties files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Headers and footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Questions to ask about headers and footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Customizing headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Configuring footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Email text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Default email template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Project-specific variables in email text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Configuring user account email text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Configuring notification email text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Configuring system email text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Preface | 5

Preface

This document describes what can be customized with respect to TIBCO Formvine® email communications. The guide will help you implement the messaging and voice you want to use. The tone of your communications can determine how your users perceive Formvine®.

Topics

• Related documentation, page 6

• Typographical conventions, page 8

• How to contact TIBCO support, page 9

For the latest version of this document, go to https://docs.tibco.com/products/tibco-formvine


Preface | 6

Related documentation

The following are included in the Formvine documentation set, which is available at: https://docs.tibco.com/products/tibco-formvine

• TIBCO Formvine Concepts Guide—Describes how Formvine addresses business needs and explains the characteristics of the people who use Formvine.

• TIBCO Formvine Installation and Implementation Checklists—Provides requirements checklists for installing and customizing Formvine.

• TIBCO Formvine Installation Guide—Provides installation instructions.

• TIBCO Formvine Implementation Guide—Explains options for customizing branding, the Formvine application, and Formvine controls. Provides instructions for implementing the customizations.

• TIBCO Formvine Email Customization Guide (this document)—Explains options for customizing messaging and provides instructions for implementing the customizations.

• TIBCO Formvine Administration Guide—Provides information on reporting, troubleshooting, and adding templates to your implementation

• TIBCO Formvine Application Programming Interface Reference Guide—Describes the TIBCO Formvine application programming interface (API).

• TIBCO Formvine External User Group Source Programming Interface Reference Guide—Describes the service provider interface to an external user group source.

Additional information about Formvine is available here:

• For the latest updates on Formvine installation and configuration requirements, see the readme file on the Formvine Documents page.

• For information on the current Formvine release, including closed and known issues, see the product release notes on the Formvine Documents page.

The Formvine Resource Center at resources.formvine.com hosts:

• Quick Install—Helps you install Formvine in minutes.

• Quick Start—Helps your project owners get started with Formvine.

• Help—Gives instructions on all aspects of using Formvine, and includes descriptions of all the Formvine templates.

• Videos—Links to the Formvine video channel, where you can see videos about using Formvine and integrating Formvine with other systems.


http://resources.formvine.com

Preface | 7

• TIBCOmmunity—Links to the Formvine TIBCOmmunity page, where you can get even more information about Formvine, ask questions, and participate in conversations to make the most of your Formvine installation.

• Tech Docs—Links to the Formvine documentation page at: https://docs.tibco.com/products/tibco-formvine

• Contact Us—Let us know how we can help.


https://docs.tibco.com/products/tibco-formvine

Preface | 8

Typographical conventions

The following typographical conventions are used in this manual.

Table 1 General typographical conventions

Convention Use

install_directory The directory where Formvine is installed.

TIBCO_FV_HOME The Formvine home directory: install_directory/fv/3.3

formvine_url URL for project owners to access Formvine, specified at installation:https://host:port/fv

italic font Italic font is used for new terms and variables in email text.

code font italic Variable name.

code font Commands, filenames, pathnames, property names and value, code examples, and command output.

bold code font Code that you type in a command window or a properties file.

brackets [ ] Links in the body text of an email.

Information that is of special interest or importance, for example, an additional action required only in certain circumstances.

An idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

Potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Security consideration. Check with your IT department and/or database administrator.


Preface | 9

How to contact TIBCO support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows:

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:https://support.tibco.com

— Entry to this site requires a username and password. If you do not have a username, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

Customizing email | 10

Chapter 1 Customizing email

Email customization in TIBCO Formvine® provides an opportunity for you to extend your company branding and messaging to your Formvine®users, which might include your employees, customers, or the general public. By customizing, you can add to the credibility of the email, which will help reassure users who might be wary of spam and phishing.

This chapter explains the possible customizations for the email generated by Formvine. You can change the style, the headers and footers, the default subject line, and the default text.

HTML and CSS skills are required for the customizations described in this chapter. As a best practice, we recommend that you make a backup copy of each file before editing.

Topics

• Overview of Formvine emails, page 11

• Why customize?, page 14

• What is customizable?, page 15

• Customizing email templates and properties files, page 16

• Headers and footers, page 19

• Email text, page 25

IMPORTANT NOTE: All of the customizations described in this chapter must be reimplemented when a new version of Formvine is installed. For this reason, we recommend that you record all of the changes you make to the system. For more information on the upgrade procedure, see the note in the following section: Customizing email templates and properties files, page 16


Overview of Formvine emails | 11

Overview of Formvine emails

Formvine can generate the following types of email.

• User account emails are generated by Formvine for registration-related events, including registration activation and confirmation, as well as password reset.

• System emails are generated by Formvine form system-related events, including adding and removing project owners.

• Notification emails are alerts configured and generated by a project owner for a specific project.

The following table describes the types of email that are generated by specific Formvine events. Email identified in the Type column as Formvine-generated cannot be disabled by the project owner. Notification emails identified as project-owner generated are optionally generated by the project owner on a project-by-project basis.

Table 2 Email workflow

Action Email generated Description Type

Registration Registration activation

Contains a link to activate registration. Optional. (Formvine directory implementation only.)

Formvine-generated

Registration Registration confirmation

Contains a link to Formvine and to the Formvine Resource Center; confirms registration. Optional. (Formvine directory implementation only.)

Formvine-generated

Password reset Password reset activation

Contains a link to reset password activation page. Auto-generated by Formvine. (Formvine directory implementation only.)

Formvine-generated

Record created Receipt to submitter Receipt to submitter. Optional; configurable by project owner. Can optionally contain data submitted to form.

Project-owner generated

Record created Notification of submission to list(s)

Notification of project submission to recipients identified by email addresses, user names, or by form field. Optional; configurable by project owner. Can optionally contain data submitted to form.




Record updated

Receipt to submitter Receipt to submitter when he or she updates project data. Optional; configurable by project owner. Can optionally contain data submitted to form.


Record updated

Notification of submission to list(s)

Notification of submission updated to recipients identified by email addresses, user names, or by form field. Optional; configurable by project owner. Can optionally contain data submitted to form.


Record created or updated that results in task assignment

Notification of pending task to task assignee

Notification of task pending on submitted form or updated submission, sent to person assigned to complete task. Optional; configurable by project owner. Can optionally contain data submitted to form.


Task completed

Confirmation to task assignee

Confirmation of task completion to task assignee. Optional; configurable by project owner. Can optionally contain data submitted to form.


Task completed

Notification of task completion to submitter of form

Notification of task completion to submitter. Optional; configurable by project owner. Can optionally contain data submitted to form.


Task completed

Notification of task completion to list(s)

Notification of task completion to recipients identified by email addresses, user names, or by form field. Optional; configurable by project owner. Can optionally contain data submitted to form.


Owner added Confirmation to new owner

Confirmation to owner added to project. Auto-generated by Formvine. Contains a link to project. Return address is email address of project owner who added this owner.

Formvine-generated

Table 2 Email workflow (Cont’d)




Owner removed

Notification to removed owner

Notification to owner removed from project. Auto-generated by Formvine. Return address is email address of project owner who removed this owner.

Formvine-generated

Table 2 Email workflow (Cont’d)



Why customize? | 14

Why customize?

The content and styling of Formvine emails are based on templates and are written generically to accommodate many use cases. Customizing these templates on a system-wide basis makes the emails more specific to your company and use case. Customization also helps reinforce your company messaging and highlight your company brand.

If form submitters are outside your enterprise, you can tailor the default notification email text to extend your company message to these recipients. Alternatively, if most form submitters are internal, you can make the tone match your company intranet’s voice and style. As you work through these customizations, consider your target audience and the type of messaging they are most likely to respond to.

Some of the options that you might customize system-wide can also be altered by the project owner. For example, a project owner can change the subject line for notification emails and add additional text, including form data and project-specific variables, to the default message.

For help or questions, all emails include an email link to your Formvine support email address. For certain types of emails (for example, those that are sent to recipients outside your enterprise), you might want to remove this link, as internal support resources might not be available to the recipient.


What is customizable? | 15

What is customizable?

The following diagram illustrates what parts of an email can be customized. You customize some of the pieces based on system requirements while project owners can configure others, based on project requirements.

The implementation settings (the black labels in the figure) are system-wide. A project owner’s settings (the red labels) apply to a specific project and override the project default that is based on customized system-wide settings.

Figure 1 Anatomy of an email


Customizing email templates and properties files | 16

Customizing email templates and properties files

To edit Formvine emails, you will edit both templates and properties files. These files are located in the following folder: TIBCO_FV_HOME/WebContent/WEB-INF/config/templates/email

Table 3 lists the files in the folder, what they are used for, and if they are editable.

Customization changes are changes made to files in the TIBCO_FV_HOME/WebContent folder. They are not carried forward when you upgrade. You will need to reimplement any changes made to files in this folder.Reapplying customizations after an upgrade is not a matter of copying the customized file from before the upgrade. In some cases, where the underlying file is changed in the upgrade, the actual customizations will have to be applied directly to the new file after upgrade. That is why it is important to back up the default file shipped with Formvine before customizing and also back up customized files before the upgrade.Configuration changes are different from customizations. Configuration changes are the changes applied to configuration property files such as features.properties. These changes are migrated during the upgrade process. You do not have to reapply them after an upgrade.If you are running Formvine on an application server other than the embedded Tomcat, you need to make the corresponding changes to the WAR file and redeploy.

Table 3 Files in email templates folder

Filename Description Editable?

datatable.vm Default template for styling of data table inserted into notification emails.

No

default.vm Default template file. This template is used when Formvine cannot locate an appropriate email template.

Yes

footer.vm Template for footer displayed on emails. Yes

header.vm Template for header displayed on emails. This header displays on all emails, regardless of type.

Yes



notification.properties Properties controlling when templates are used and what project-specific data is available.

No

notificationdefault.properties

Properties for default subject lines and default notification email text for personalized message. Text contains project-specific data variables.

Yes

notificationstyle.properties

Properties to set default email style. No

supportmessage.vm Default text for the support paragraph in email templates.

Yes

User account emails (Formvine directory version only)

user.registered.vm Template for user account email generated for registration activation. Subject line set in notificationdefault.properties.

Yes

user.registrationconfirmed.vm

Template for user account email generated for registration confirmation. Subject line set in notificationdefault.properties.

Yes

user.passwordreset.vm Template for user account email generated for password reset request. Subject line set in notificationdefault.properties.

Yes

Notification email

record.created.vm Template for notification email sent to form submitters and lists of people when a form is submitted. Contains default, configurable, preamble text. Default personalized text and subject line are edited in notificationdefault.properties. Project owner can overrwrite personalized text and subject line.

Yes

Table 3 Files in email templates folder (Cont’d)




record.updated.vm Template for notification email sent to form submitters and lists of recipients when data is updated by submitter. Contains default, configurable, preamble text. The personalized text and subject line for the record updated notification email cannot be customized independently.

Yes

task.assigned.vm Template for notification email sent to task assignee when a task is assigned. Default personalized text and subject line are edited in the notificationdefault.properties file. Project owner can overrwrite default personalized text and subject line.

Yes

task.completed.vm Template for notification email sent to form submitters, task asignees and lists of people when a task is completed. Default personalized text and subject line are edited in notificationdefault.properties. Project owner can overrwrite default personalized text and subject line.

Yes

System emails

project.owneradded.vm Template for system email generated when a project owner adds another project owner. Subject line set in notificationdefault.properties.

Yes

project.ownerremoved.vm Template for system email generated when a project owner removes another project owner. Subject line is set in notificationdefault.properties.

Yes

Table 3 Files in email templates folder (Cont’d)



Headers and footers | 19

Headers and footers

Although you can’t apply CSS to a Formvine email, you can customize the header and footer (Items 3 and 8 in Figure 1, Anatomy of an email, page 15). For example, if you are confident that all recipients are familiar with the Formvine brand and TIBCO, you can use the default header and footer. Alternatively, you can add your Formvine brand to the header and your company logo to the footer.

As another option, you can customize headers and footers by email type. For example, you can have user account and system emails use one type of header and footer, and set up notification emails to use another type. This strategy allows recipients familiar with Formvine to receive emails branded with your company’s Formvine logo and the Formvine footer, while recipients who are not familiar with Formvine receive emails branded with only your company logo in the header and footer. This can reassure recipients that the email comes from a trusted source.

The Formvine generic implementation includes headers and footers for user account and system emails, but not for notification emails. Here's an example of a user account email with a logo and generic footer.

Figure 2 User account email - generic implementation



Here's what we did with the same email for Formvine.com. We updated the header with the Formvine.com logo and added a footer with the TIBCO logo.

Figure 3 User account email - reference implementation

Questions to ask about headers and footers• For user account and system emails, do you want to add your brand to the

header? Do you want to add your company logo to the footer?

• For notification emails, do you want to add a header with your Formvine brand, just your company logo, or both? Do you want to include a footer?

• Does your Legal department have a required Privacy Policy or Terms and Conditions statement that you would link to from the footer?

Recommendations• Add your Formvine brand to user account and system email headers.

• Add a header with just your company logo or other familiar mark to notification emails give the recipient context and confidence.

• Include a footer to reassure your recipients.


Customizing headersTo display the same header on all emails, regardless of type, you customize the header in a single file. To display different headers on different email and notification types, you configure the header in the individual template files.

• If you’re configuring the header and using your customized version in all types of emails, follow the instructions in the section called Using the same header in all email types, page 21.

• If you’re using different headers in the different types of emails (user account, system, and notification), follow the instructions in the section called Using a different header in different types of emails, page 22.

Using the same header in all email types

The instructions in this section tell you how to display the same header on all types of email generated by Formvine. Before you start, you’ll need your Formvine brand (the standard Formvine brand with your company mark), sized to about 41 pixels high. The width is not critical.

Shut down the Formvine server before implementing these changes.

1. Post your branded logo to:TIBCO_FV_HOME/WebContent/versionedfiles/images/logos

2. Navigate to the following folder: TIBCO_FV_HOME/WebContent/WEB-INF/config/templates/email

3. Make a backup copy of header.vm and open it in a text editor.

4. Point to your Formvine brand using an HTML image tag. Place your new code after the last line of code in the file: <div style="$notificationstyle.get ('notification.headerstyleinner')...">Note: You don’t need to add a closing </div> tag to the header.vm file; this is inserted when the header is merged into the appropriate template file.Example: In your line of code, you can use the $server.base_url project variable to point to the Formvine URL. <img src="${server.base_url}/versionedfiles/images/logos/ MyFormvineBrand.png">

5. To use this header in notification emails, add the following text to all notification email templates as the first line in the file: #emailHeader()

6. Save the file and restart Formvine. Experiment with the final result by working through a notifications scenario and examining the resulting emails.

Using a different header in different types of emails

The instructions in this section tell you how to configure two headers: one for user account and system emails and the other for notification emails. To do this, you set email headers in each type of email template file. You can’t set the header in the header.vm file, as in the previous set of instructions, as this header is displayed on all emails, regardless of type.

• To configure the header on user account and system emails, follow the instructions in the procedure called Configure the header on user account and system emails, page 22.

• To use your company logo in the header for notification emails, follow the instructions in the procedure called Use your company logo in notification email headers, page 23.

Configure the header on user account and system emails

These instructions tell you how to customize the header for user account and system emails. Before you start, you’ll need your branded logo, sized to about 41 pixels high. The width is not critical. Shut down the Formvine server before implementing these changes.

1. Post your Formvine brand to: TIBCO_FV_HOME/WebContent/versionedfiles/images/logos


3. Make a backup copy of user.registered.vm and open it in a text editor.

4. Remove the first line: #emailHeader()

5. Add a tag. In the tag, point to your brand, for example: <img src="${server.base_url}/versionedfiles/images/logos/ MyFormvineBrand.png" width="159" height="41" alt="My branded Formvine logo"> Note: In your line of code, use the $server.base_url project variable to point to the Formvine URL.

6. Save the file and restart Formvine. Experiment with the final result by working through a registration scenario and examining the email.

Repeat Steps 3 - 6 for additional user account email templates and the system email templates.

Use your company logo in notification email headers

These instructions tell you how to use your company logo in notification email headers. Before you start, you’ll need your company logo, sized to about 41 pixels high. The width is not critical. Shut down the Formvine server before implementing these changes.

1. Post your sized company logo to: TIBCO_FV_HOME/WebContent/versionedfiles/images/logos


3. Make a backup copy of record.created.vm and open it in a text editor.

4. Add a tag as the first line of code in the file. In the tag, point to your logo, for example: <img src="${server.base_url}/versionedfiles/images/logos/ MyFormvineBrand.png" width="159" height="41" alt="My small company logo"> Note: In your line of code, use the $server.base_url project variable to point to the Formvine URL.

5. Save the file and restart Formvine. Experiment with the final result by working through a registration scenario and examining the email.

Repeat Steps 3, 4, and 5 for the rest of the notification email templates.

Configuring footersThe footer used in notification emails is the same footer that is used in user account and system emails. Only one footer can be set for all email types; you can choose to include it or not.

• If you’re configuring the footer, follow the instructions in the section called Configuring the footer displayed in user account and system emails, page 24.

• If you’re adding a footer to notification emails, follow the instructions in the section called Adding a footer to notification emails, page 24.


Configuring the footer displayed in user account and system emails

These instructions tell you how to configure the footer. The footer is always displayed in user account and system emails. Before you start, you need your company logo, about 15 pixels high, and text for any links, like a Privacy Policy, as well as the link location. Shut down the Formvine server before implementing these changes.

1. Post your company logo to a public, secure, URL and post your linked to HTML pages in a public, secure, location.


3. Make a backup copy of footer.vm and open it in a text editor.

4. Add an HTML link to your logo and/or your customized text or links after the existing footer: TIBCO Formvine® Copyright 2009-2014 TIBCO Software Inc. All rights reserved.

5. Save the file and restart Formvine. (Your browser might require that you clear the cache before reloading Formvine.) We recommend that you experiment with the final result by registering a user or by adding and removing project owners and examining the resulting emails.

Adding a footer to notification emails

The instructions in this section tell you how to add the footer to a notification email. Shut down the Formvine server before implementing these changes.


2. Make backup copies of the following files, then open each one in a text editor.

— record.created.vm

— record.updated.vm

— task.assigned.vm

— task.completed.vm

3. Add the following line of code as the last line in the file: #emailFooter()

4. Save each file and restart Formvine. (Your browser might require that you clear the cache before reloading Formvine.) We recommend that you experiment with the final result by working through a notification and task scenario and examining the resulting emails.


Email text | 25

Email text

When implementing Formvine, you can create default text that is customized specifically for your company and use case. In addition, a project owner can edit various aspects of a notification email, including the subject line and email text. Project owners can also insert variables into notification emails to include data submitted to the form or project-specific data, such as submitter or task assignee name and email address.

Emails are created with the Java-based Velocity scripting language. More about Velocity can be found here:

http://velocity.apache.org/engine/releases/velocity-1.6.4/user-guide.html

Default email templateFormvine provides a template for a default email. This template is used when Formvine cannot locate an appropriate email template. The file is called default.vm and is located in the email configuration folder of your installation: TIBCO_FV_HOME/WebContent/WEB-INF/config/templates/email

Do not edit this file.

Project-specific variables in email textYou can add data and flexibility to your emails by using project-specific variables. Project-specific variables represent pieces of data that are associated with a project, like project name and description, details about who created a record and what time it was created, or the details for who submitted a record. These variables are replaced with values from the specific project when Formvine generates an email.

When you’re updating the default personalized text and subject lines, you can add project-specific variables. Variables are proceeded by $ and enclosed in curly brackets: ${...} For example, the variable ${project.title} is used in most default subject lines and is replaced with the title of the project.

For system emails, we recommend that you retain the ${project.title} variable used in the subject line, the URL variable (${server.base_url}), and the support email link (${server.support_email}).


Email text | 26

Additional project-specific variables are available for notification emails. Table 4 shows the available project-specific variables and the applicable notification email type.

Table 4 Project-specific variables in notifications

Description Applicable notification type

${project.title} Project title All. Used by default.

${project.description} Project description All

${server.base_url} The URL to access Formvine All

${server.base_url_anon} The URL to access anonymous forms

Note: This can be different from the above URL for an SSO implementation.

All

${server.support_email} The support email address. Consider your audience: potential recipients of emails should be able to access this email address. In the TIBCO reference implementation, we removed support email links from notifications because our internal support would not be able to help external submitters or task assignees.

All

${record.created} Record created timestamp. All

${record.updated} Record updated timestamp. All

${record.creator_fullname}${record.creator_lastname}${record.creator_firstname}${record.creator_email}

Details of the person who created the record (full name, email, first name, last name). This is the original submitter.

All

${record.updater_fullname}${record.updater_lastname}${record.updater_firstname}${record.updater_email}

Details of the person who updated the record (full name, email, first name, last name). If there are no updates, this is the person who created the record.

All


Email text | 27

Configuring user account email textIf you are using a Formvine directory implementation, where users self-register, Formvine can generate the following emails:

• The registration activation email can be sent after a user clicks Submit on the Registration page. It includes a link for registration activation. This optional email can be turned on or off at installation. (If the email is turned off, the user is automatically registered and signed in after registering.)

• The registration confirmation email is sent when the account is activated and confirms the registration. It introduces the new user to the public Resource Center.

• The password reset email is sent to a registered user who requests a password reset. The email contains a link that activates the Password Reset page, where the user can complete the password reset process.

For help or questions, these emails include an email link to your internal Formvine support. Because these emails may be the first communication from Formvine to your users, you might want to customize the content and voice to suit your audience.

${submitter_fullname}${submitter_lastname}${submitter_firstname}${submitter_email}

Details of the person who completed the task (full name, email, first name, last name).

Task completed

Table 4 Project-specific variables in notifications (Cont’d)

Description Applicable notification type

Formvine implementations using a corporate directory for users and groups do not require user account emails, as users cannot manage their account through Formvine.


Email text | 28

Registration activation email

The following table shows the subject line and text for the registration email for both the generic implementation of Formvine and the Formvine.com reference implementation. You can see how we updated text for the Formvine.com.

Configure the registration activation email

Files to edit are located in: TIBCO_FV_HOME/WebContent/WEB-INF/config/ templates/email/

After editing, save the file and restart the server.

Default subject line

Formvine.com Default email text Formvine.com

Formvine registration activation

Formvine. com registration activation

Hello full name,

Thanks for registering with Formvine! Click the link below to confirm your registration: [Confirm registration]

If you did not sign up for an account, ignore this message and the account will not be created.

Questions? Email name at: support email

Hello full name,

Thanks for registering with Formvine.com! Click [here] to confirm your registration.

If you did not sign up for an account at Formvine.com, ignore this message and the account will not be created.

Questions? Email Formvine.com support at: support email

Property File where property is used Configuration information

Subject line notificationdefault.properties

Default subject line. Change default value (in bold) as needed.

user.registered.subject = Formvine registration activation

Body text user.registered.vm Modify text in the Velocity template file as needed.


Email text | 29

Registration confirmation email

The table below shows the subject line and text for the registration confirmation email for both the generic and reference implementation.


Formvine. com Default email text Formvine.com

Formvine registration confirmed

Welcome to Formvine!

Hello first name,

Welcome! Your registration with Formvine has been confirmed and you're ready to start creating projects.

To access Formvine, click [here].


You can visit the Formvine Resource Center to learn about the product and get involved with the community.

Hello first name,

Your registration with Formvine.com has been confirmed, so...welcome!

If there’s something you had in mind to do with Formvine, [jump right in]—it’s easy to get started.

If you’re wondering what Formvine can do for you, keep reading (and then jump in).

No matter what you need to get done, collecting, managing and communicating information is, at best, a chore. If you add sharing the results and getting approvals to the mix, it becomes a real headache. And if you need to round up IT resources to help, the job may never get done.

Formvine simplifies everything. It lets you collect and organize your information and get the right info to people when they need it. It even sends requests and processes approvals so you don’t have to wade through emails and spreadsheets. Best of all, it’s so easy, anyone can do it.

[Check out the Resource Center] to learn everything you need to know about collecting and using information with Formvine.

Formvine.com is a free service and very useful. Formvine Enterprise can do even more for your company—contact us to learn more.

--The Formvine Team

P.S. Look for emails from us over the next month where you’ll learn about getting the maximum value out of Formvine.


Email text | 30

Configure the registration confirmation email



Password reset email

This table shows the password reset email for both implementations.




user.registrationconfirmed.subject = Formvine registration confirmed

Body text user.registrationconfirmed.vm

Text is modified in the Velocity template file.


Formvine.com Default email text Formvine.com

Formvine password reset

Formvine. com password reset

Hello full name,

You have requested a password reset for your Formvine account. Click the link below to start your password reset process: [Password Reset]


Hello full name,

You have requested a password reset for your Formvine.com account. Click [here] to start your password reset process.

Questions? Email Formvine.com support at: support email


Email text | 31

Configure the password reset email



Configuring notification email textProject owners set up notification emails on a project-by-project basis. Notification emails are sent when forms are submitted or a submission is updated by the submitter, and when tasks are assigned or completed. Notification emails can be sent to the submitter, task assignee, and to any number of email address lists.

The base template for each type of notification email can adopt multiple flavors, depending on the situation. For example, when a form is submitted, the notification email sent to the form submitter has a different subject line than the notification email sent to a list of people announcing that the form received a submission.

A project owner can customize the subject line, the default personalized message, include the data submitted to the form, as well as add individual form data and project-specific variables. You can consider adding or removing project-specific variables, but be sure to keep the project name variable ${project.title}to help orient recipients.

By default, we provide a single template for all audiences. However, you can customize this template for different audiences.

It’s a good idea to customize headers in notification emails to use your company logo. This will help reassure recipients that the email comes from a trusted source. See the section called Use your company logo in notification email headers, page 23 for information.




user.passwordreset.subject = Formvine password reset

Body text user.passwordreset.vm Text is modified in the Velocity template file.


Email text | 32

Formvine can generate the following types of notification emails:

• Project owners can send record created notification emails when a form is submitted. One version of this notification email can be sent to the person who submitted the form. Additional versions can be sent to one or more email addresses collected into one or more lists. Each can be individually customized for default subject line and default personalized text. Non-editable explanatory text is included in the body of the email. This text is not displayed in the user interface for notification configuration.

• Project owners can also send record updated notification emails, sent as confirmation to a submitter when the submitter updates a record. This notification email can also be sent to one or more email addresses collected into one or more lists. This notification email uses the customizations applied to the record created notification email. Non-editable explanatory text is included in the body of the email.

• Project owners can send notification emails for task forms:

— A task assigned notification email can be sent on form submission or submission update, when a pending task is created/assigned. This notification email is sent to the task assignee.

— A task completed notification email can be sent on task completion. One version of this email can be sent to the original submitter of the form. Additional versions can be sent to one or more email addresses collected into one or more lists. A third version can be sent to the task assignee.

Support message

We recommend that you remove the support message from notification emails.

Remove the support message

1. Navigate to the following folder:TIBCO_FV_HOME/WebContent/WEB-INF/config/templates/email

2. Backup the template you want to modify and open it in a text editor.

3. Remove the following code:#parse("/email/supportmessage.vm")<a style="#astyle()" href="mailto:${server.support_email}?subject=Question about Formvine submission">${server.support_email}</a>

4. Save the file.

5. Repeat Steps 2, 3, and 4 for each notification email template.

Email text | 33

Record created notification email

The table below shows the subject line and text for the record created notification email that is sent to the form submitter as a receipt. We edited the default text slightly for the Formvine at TIBCO implementation. In the table below, the non-editable explanatory text is the first paragraph of the email body.

This table shows the subject line and text for the record created notification email that is sent to a list of people when a form is submitted. We edited the email text for the Formvine at TIBCO implementation. In the table below, the non-editable explanatory text is the first paragraph of the email body.


Formvine at TIBCO Default email text Formvine at TIBCO

Your project name submission was received

Thank you for your response to Formvine project name

Your new submission to Formvine project project name was received.

Thank you.

This email was generated to let you know your response to the Formvine project project name was received.

Thank you.



Data in project name has been updated

A new response was received for Formvine project project name

A new submission was received for Formvine project project name.

Thank you.

A response was submitted to the Formvine project project name.


Email text | 34

Configure the record created notification email

The properties below edit the subject line and default body text for the record created notification.

File to edit: TIBCO_FV_HOME/WebContent/WEB-INF/config/ templates/email/notificationdefault.properties


Record updated notification email

The record updated notification email uses the same default text as the record created notification email; any modifications you make will be applied to both record created and updated notification emails.

Property Configuration information

Subject line for record created notification to form submitter

Default subject line. Change default value (in bold) as needed. We recommend keeping the project title variable.

record.created.submitter.subject = ${project.title}: Your ${project.title} submission was received

Body text for record created notification to form submitter

Default body text. Change default value (in bold) as needed

record.created.submitter.message = Thank you.

Subject line for record created notirication to list


record.created.list.subject = Data in ${project.title} has been updated

Body text for record created notification to list

Default body text. Change default value (in bold) as needed

record.created.list.message = Thank you.


Email text | 35

Task assigned notification email

The table below shows the subject line and text for the task assigned notification email that is sent to the task assignee when a form with a task is submitted. We edited the email text for the Formvine at TIBCO implementation.

Configure the task assigned notification email





project name: A task was assigned to you

A task for project name was assigned to you

This email was generated to let you know that a task for the Formvine project project name was assigned to you.

Click the following link to see the assigned task and sign in, if required: [Pending task]

A task for the Formvine project project name was assigned to you. Sign into Formvine to see the task.


Subject line for Task assigned notification to task assignee


task.assigned.assignee.subject = ${project.title}: A task was assigned to you

Body text for task assigned notification to task assignee

Default body text. Change default value (in bold) as needed. We recommend keeping the project title variable and leaving the bold font.

task.assigned.assignee.message = This email was generated to let you know that a task for the Formvine project ${project.title} was assigned to you.

Email text | 36

Task completed notification email

The table below shows the subject line and text for the task completed notification email that is sent to the task assignee as a confirmation upon task completion. We did not change the email text for the Formvine at TIBCO implementation.

The table below shows the subject line and text for the task completed notification email that is sent to the form submitter when the task is completed for his or her submission. We edited default text for the Formvine at TIBCO implementation.

This table the subject line and text for the task completed notification email that is sent to a list of people when a task is completed. We edited the email text for the Formvine at TIBCO implementation.



project name: A task was completed by you or by the owner

Task for project name was completed by you or by the owner

This email confirms that you (or the owner of the project, on your behalf) completed a task for the Formvine project project name.

This email confirms that you (or the owner of the project, on your behalf) completed a task for the Formvine project project name.



project name: Your submission was completed

Your submission to project name was completed

This email was generated to let you know your submission to Formvine project project name was completed.

This email was generated to let you know your submission to the Formvine project, project name, was completed.


Formvine at TIBCO subject line

Default email text Formvine at TIBCO email text

project name: A task was completed

A task for project name was completed

This email was generated to let you know that a task for the Formvine project project name was completed.

A task for the Formvine project project name was completed.


Email text | 37

Configure the task completed notification email




Subject line for task completed email to task assignee


task.completed.assignee.subject = ${project.title}: A task was completed by you or by the owner

Body text for task completed email to task assignee


task.completed.assignee.message = This email confirms that you (or the owner of the project, on your behalf) completed a task for the Formvine project ${project.title}.

Subject line for task completed notification to form submitter


task.completed.submitter.subject = ${project.title}: Your submission was completed

Body text for task completed notification to form submitter


task.completed.submitter.message = This email was generated to let you know your submission to the Formvine project ${project.title} was completed.

Subject line for task completed notification to list


task.completed.list.subject = ${project.title}: A task was completed

Body text for task completed notification to list

Replace the default body text as needed. We recommend keeping the project title variable and leaving the bold font.

task.completed.list.message = This email was generated to let you know that a task for the Formvine project ${project.title} was completed.

Email text | 38

Configuring system email textFormvine generates the following system emails:

• The owner add email is sent when a project owner adds an additional owner to a project. The email is sent to the new owner.

• The owner remove email is sent when a project owner removes another owner from a project. The email is sent to the removed owner.

The return address on these two emails is that of the project owner, not the Formvine administration account. This allows the recipient to reply directly to the project owner. By necessity, system emails include the project name. For help or questions, these emails also include a link to your internal Formvine support.

Owner add email

The table below shows the subject line and text for the system email that’s sent when a project owner adds another project owner. We did not change the text from the generic text for the Formvine at TIBCO implementation.



You have been added to project name

You have been added as an owner to project name

Hello full name,

This email was generated to let you know that you have been added as an owner to the Formvine project, project name.

To access this project, click the following link and sign in, if required: [Formvine]


Hello full name,

This email was generated to let you know that you have been added as an owner to the Formvine project, project name.

If you feel you have been added in error, you should reply to this email.

To access this project, click [here] and sign in if required.

Questions? Email your administrator at: support email


Email text | 39

Configure the owner add email



Owner remove email

This table shows the subject line and text for the system email that’s sent when a project owner removes another project owner. We did not change this text for the Formvine at TIBCO implementation.


Subject line for owner add email



project.owneradded.subject = You have been added to ${project.title}

Body text for owner add email

project.addrolemember.vm




You have been removed from project name

You have been removed from Formvine project name

Hello full name,

This email was generated to let you know that you have been removed as an owner from the Formvine project, project name. You may have rights or roles other than owner which would not cause a notification.

If you feel you have been removed in error, you should reply to this email.

You can access your remaining projects by clicking here and signing in, if required: [Formvine]


Hello full name,

This email was generated to let you know that you have been removed as an owner from the Formvine project, project name.

If you feel you have been removed in error, you should reply to this email.

You can access your remaining projects by clicking [here] and signing in, if required.

Questions? Email your administrator at: support email


Email text | 40

Configure the owner remove email




Subject line for owner remove email



project.ownerremoved.subject = You have been removed from ${project.title}

Body text for owner remove email

project.removerolemember.vm



tib formvine 3.3.3 email customization guide...Customizing email |10 Chapter 1 Customizing email...

Documents

Transcript of tib formvine 3.3.3 email customization guide...Customizing email |10 Chapter 1 Customizing email...