Email Integrations/Creating Customized Emails

Introduction

Email integrations are quick and easy to use - they create personalized emails that can automatically send upon the completion of a form, or when a stage of a process is completed. The integration can be static, meaning that you can configure the exact specifications of the email beforehand. However, you can also incorporate tokens into the email integration. Since HTML format emails can be created, this reduces the need to attach PDF copies of the completed form details, as all/part of the details captured (the extent to which can be configured) in the form filling process can be brought through into the email itself, giving the form filler easier access (no need to open an attachment). 

Note: When considering creating emails for internal use we advise using Dashboard instead.

Step-by-Step Guide to Creating and Using an Email Integration

1. In the forms designer, click on the cog in the top right of the screen. Click ‘Integrations Manager’ on the drop down list.

2. Click ‘New Integration’ from the menu in the top left.

3. You should now be presented with several fields that you need to answer:

• Category - Choose a category for your integration - these categories can be found on the left of your screen in the integrations manager interface - they help to organize your integrations
• Integration Name - Give your integration a name
• Type - Select ‘Email’
• LIM - Select your local LIM
• Data Type - Select ‘Integration/Lookup’

More information on the integration manager

The ‘Allow Offline’ field allows you to choose whether or not you would like your integration to be available offline. The 'Enable Lookup V2 Validation' field, which, although it does sound like it will enable Integrations V2, does not do anything of the sort. This should always be left as 'no'.

Note: This is a deprecated feature that will be removed soon.

If you would like to be notified if your integration fails, you can add an email address in the failure notification section. Every time an integration is attempted to be carried out, there will be a unique log for each attempt. Thus, answering ‘Yes’ to ‘Log Only On Error’ will ensure these logs only occur when the integration fails.

Once you have completed the fields on this page, click ‘Next’.

4. You should now be presented with several fields related to the specifications of the email that will be sent out. Tokens can be extremely useful here, because you may not want every single email sent out to be exactly the same - for example, if you wanted the email recipient to be whatever email address was provided by the form filler, tokens can make that happen. Use the token assistant on the right hand side of your screen to locate your form and then locate your required token. It should be noted that email integrations use the tokens in the stage they are on. Therefore, for the tokens to, say, populate on submission/creation of the second stage, the fields should be present in your second stage form.

• Subject - The subject of the email that citizens will receive.
• Sender Name - The name of the sender that will appear in the inbox (this, amongst others, may of course be set to a no-reply name, a generic email account, or a specific user email account as required).
• Sender Address - The email address of the sender
• Recipients (To) - The email address of the recipient - multiple recipients can receive the email by separating the email addresses with a comma - this will work irrespective of whether there are spaces before or after the comma (this can also be done for the recipients CC and BCC fields. Note: if you use more than one token for this field, the email will still send as long as at least one of the tokens has a value; they don’t all need to have a value. It is also possible to use groups tokens to send email to groups.
• PDF Attachments - Type in the PDF integrations that you want to attach to this email and select from the list  (or you may prefer to include all information in the email itself).  There is no need to include the printable integrations in the form integrations section if included here within email integration.
  It is not possible to add static PDF files that have NOT been created as Printable integrations within the product.  Our recommendation would be to store these on a publicly facing web server or S3 bucket and reference as a hyperlink.
• Message - The message of the email that form fillers will receive. The message editor enables any level of bespoke email content to be created; HTML or plain text can be used.
• Attachments - list any upload field attachments that you wish to include from the form submission here, multiple uploads are possible simply separate the upload field with a pipe eg {upload1} | {upload2} | {upload3} | {subform1/file1}  (there can only be one file per upload field)

Once you have completed this section, click ‘Submit’. Your integration has been created.  You can use the Test assistant to test the output is as required - without the need to complete the form itself
 

5. Back in your process, click the pencil icon on the stage you would like to use the integration in

6. Click on the ‘Integrations’ tab

7. On the first drop down box, select email. On the second one, select the name of the integration you just created. Then click ‘Add’

8. For Condition, you can add a condition for the email to be sent if you want to - such as requiring a certain field in your form to contain certain text. For the ‘Type’ field, you can choose how you would like the integration to occur - i.e on submission of the form, for example. Click Submit and your email integration will be implemented into your process!

Further Information

• Email message: when writing the message of the email, it is possible to edit the email source code to fine tune the look and feel of the email by clicking Tools > Source Code.
  We advise using Notepad++ to create your email and copying this into the source code of the email. This will avoid unnecessary tags being added into your HTML and retain the desired format for output.
  
  Font sizes are measured in Pixels (px) not Point (pt)
  
  If you need to use tokens which contain HTML that needs to be encoded, prefix the token with a # symbol. For example, {#textField}. The # will tell the integration to encode, not print, the HTML (this can be used with <br/> tags to preserve line breaks).

• Subforms: content from subforms can also be included using @AF:repeat and @AF:if. If you want data from a subform to appear in an email using {visiblesummary}, {unhiddensummary} or another summary token, you will need to ensure that the 'summary field' checkbox is ticked in the individual field settings. These tokens will only pull data marked as summary from subforms.

• Email Attachments: The data name for the upload fields in your form should be used as tokens. If you have multiple upload fields in your form, you can separate the tokens with a pipe bar, for example {upload1} | {upload2}.
  It is not possible to attach PDFs from outside the system via this route - you would need to reference as a link in the body of the email

• Test Assistant: You can use the test assistant, found on the right hand side of your screen, to test your integration - thus avoiding the need to complete a form to create the output emails.

• Using {TaskURL} and {PublicTaskURL}: These tokens can be used within email integrations to open a created stage of a process to continue the process; the email recipient will see a link to open the process. More information on {TaskURL} and {PublicTaskURL}.

• Using {prev_data}: The decision has been made to only allow the {prev_data} token for use with file integrations in Integrations V2. Thus, it is not working for adding a printable to an email integration in Integrations V2. A solution would be to include the required pdf in the 'PDF Attachments' field of the email integration. Either use af:if statements inside the printable to customise the content, or have separate email integrations with run conditions on them.

• Sending Mass Emails: If sending an email to a group of users, only the first 50 users will receive the email. We actively recommend against trying to use the Firmstep Platform to send mass emails or notifications. This should be handled by an external system designed for mass communication, such as govDelivery

• Updating Emails: Changes made to integrations are instantaneous, and any processes using them will automatically use the updated version.

• Typing in the message field when creating an email integration can become unresponsive with the cursor always returning to the start. This happens when you select a word that is followed by a special character and try to type over it.  Avoiding doing this will prevent the issue. Instead, delete the selection and then type the new text. This is a known issue with the text editor we utilize.

• If integrations fail to output, check that there is no rogue HTML (eg. <span style...></span>). Typing your HTML email in a plain text editor like Notepad ++ will improve the email's quality. Pasting your copied text as plain text is also helpful.

• Please note that if the font you select is not an email safe font it may not show correctly on the readers device.

• If email integrations are sent from LIM14 then they are likely to be regarded as spam by recipients email services.  We advise to change to local LIM to prevent this issue.

• {allsummary} or {unhiddensummary} - when used these will include additional line spacing and will not include static text - customized emails can be created using individual form tokens for a more aesthetic look or using a standard HTML field (using relevant tokens for individual forms) to repeat in emails/printables.

• Using a special character or an apostrophe in the subject line of an email can cause errors to occur. Switching to v2 integrations and new queue processor will resolve this.

• In the integrations logs, emails sent to multiple recipients separated by commas show as having sent only to the first recipient. The email sends correctly to all recipients, but the log does not display them all.

• Error: ['EMAIL']: TypeError: error:0606506D:digital envelope routines:EVP_DecryptFinal_ex:wrong final block length: This error is displayed if the LIM returned a plain text error message, so that when we tried to decrypt the response it could not be displayed and displays the error instead.

• The editor will make sure that any HTML entered is valid. This includes ensuring that any text entered is surrounded by a block element (as required by HTML).  A workaround is to add <div>  ...   </div> around the HTML entered as this will ensure all text is within a block element.

• <pre> tags do not wrap--this is expected behavior for the tag both inside and outside of the Firmstep platform. The effect this has is that a <pre> tag is used in an email or PDF integration, it will not wrap and the text within the tag will extend off the side of the screen. Custom CSS will therefore be required.