The emails sent out for invitations to new reviews, welcome emails for new users, updates to reviews, etc, are based on template wordings for each Please Review server.

If there is a requirement to change any of these wordings, this article covers how to do this.

The templates are stored on the server, under config\EmailTemplates and are of a .xsl format.

If Ideagen host the customers, a zip of the current email templates can be provided for users to edit and return to Support. This should be just the email templates (.xsl files) itself and not any of the sub folders that may be there for possible integrations with Please Review unless those integrations are in use. If an integration is in use, see the further notes below.

If there is a test instance or non-production instance, then users might want to try it on one of those instances first so be sure to clarify which instance the templates relate to that are to be edited.

The template files can be loaded into a plain text editor such as Notepad, Crimson Editor, Notepad++, etc on Windows or Text Wrangler, BBEdit, etc, on a Mac.

Editing the templates - short version

Users should only edit the bits that look proper text of the email and not the bits inside the < > signs.

If editing the files directly are too complicated, then users can provide us what they would like the templates to say. However, users should be aware that this would not necessarily cover any optional text that changes in certain scenarios and that it could involve a longer turnaround time to update the templates as we would need more time to work on them, than if they had just supplied us with the updated templates.

For more in-depth editing details see the technical details further below.

Integrated customer templates

If a Please Review installation has an integration, then the email templates that are sent out to the users can be configured to be based on the authentication basis they use. ie. if they are using Veeva for authentication, it would use email templates under config\EmailTemplates\Veeva for that user, if that system was configured accordingly to do this. If they have multiple forms of authentication added, the template used should be the based on the authentication type it finds first for that user, if it is Please Review sending that email.

Uploading templates to servers

Whenever anyone puts template changes on a server, it is always prudent to BACKUP the changed files and/or the entire templates folder before putting the new ones in place in case there is an error or a request to roll back to the previous version.

After any change, the TaraService would need to be restarted for the change to take effect. This can be done at any time, as anything it is in the middle of processing will be retried at least once. However, restarting in quick succession should be avoided as this could cause a task to fail incorrectly if it is on its last attempt to process a task.

If unsure if a template will work, then we recommend testing this on a test instance first, if possible.

Note that you can use the XML plug in in NotePad++ to do simple things like like check if the file is a valid XML file. If it fails that test, then you know straight away it isn't going to work.


Editing the templates - technical further details

The file consists of various header information needed to establish the file format and also some include references to include other templates in this. For example "<xsl:import href="footer.xsl" />" includes the contents of the footer.xsl file in this file, along with these lines that call various bits stored in the footer.xsl file, near the end of the email content. What the below is doing is calling the bit of text that says 'do not reply to this email' but ONLY IF the from address was the system address. If the email originated from the user, then it won't include that (That, in itself, is included in the footer.xsl file from the DoNotReply.xsl file). After that, it then includes the standard footer text, taken from the footer.xsl file.

<xsl:call-template name="SendWithDoNotReply">
  <xsl:with-param name="UseDoNotReply" select="$fromsystem" />
</xsl:call-template>
        
<xsl:call-template name="standard-footer" />

The to and from addresses should be self-explanatory, in that they are pulled from the system. Whether an email is sent from the system address or from the user depends on the type of email involved and what the settings are in the system. A password reset email will come from the system address. An invitation for a review will come from the review owner. These are the defaults but if from address in the templates are changed, this will affect this. It is recommended not to change this in the template as the root workgroup management setting "Email's From System Suffixes" controls whether or not to send from the users or from the system address for emails that would normally send from the users. Just to also add here that experience has shown us that end users tend to reply to emails even if they have the message about not replying to the email so we always recommend companies either whitelist the IP of the Please Review server or add it to their SPF record for their domain to allow emails being sent from the user's addresses not to be incorrectly blocked/filtered as spam, to avoid replies to such emails being lost. Please see Common email sending questions for more details on that.

If you look at the email template under the <body> tag, this is the main body of the email, and you will see something like:

Dear <xsl:value-of select="Recipient/@FullName"/>,

You have been registered on the Please Review document collaboration application.

Your username is <xsl:value-of select="RecipientExtSource/@SubjectRef"/>

The bits inside the < > tags are bits that are inserted into the document from Please Review based on various values. If you read what they are saying, they should be fairly self-explanatory.

As the file is an xml based file, users should never use the <, > or & (less than, greater than, ampersand) signs in the document for actual content they want included in the email. They will need to use the xml/html entity tag versions of these: &lt;  &gt;  &amp; 

If there are bits like the below, this represents different text that would appear in the template based on different scenarios. That is to say what appears is dependent on the review/user data/etc in the Please Review. It should be possible to get an idea of what the conditions are by reading what is in the test data and also what the text is that it would include.

  <xsl:choose>
         <xsl:when test="some test">

some text

       </xsl:when>
          <xsl:otherwise>

some other text
 
        </xsl:otherwise>
        </xsl:choose>

Other than that, users can edit the text outside of any < > signs pretty much as they want.

If users want to insert other data from Please Review that is not already included in the template, then it might be a bit of trial and error to see if that is possible or raising this with Support to see if it is possible.

We do not currently have a list of what data could be inserted into templates that we can provide.

Plain text note

The emails are plain text so any links would be made links by the resulting mail application. Also note that for integrations we can't link to review itself unless the integration allows it. This is why Veeva templates link to the inbox instead of the review.

Rich text templates are not supported. As such, we cannot make parts bold, underlined or change fonts, include images or icons.