Configuring Email Template Triggering in ClientSpace Classic

The purpose of this document is to describe the new ClientSpace Email Template Triggering functionality and provide insight into its configuration.

Overview

Email Template Triggering allows Notification Messages via Email and/or Slack to be generated upon Dataform save, much like Template Task Triggering. Based on meeting a set of Trigger Conditions, an Email Template associated with a specific dataform will be populated with live data (replaceable fields) and a notification message will be sent to a set of Email Recipients or to a Slack Channel. For an Email Notification, the Subject and Body fields will be replaced with live data and issued to the Recipients. For Slack Notification, only the Subject field will be replaced with live data and sent to the Slack Channel. 

Email Template Triggering occurs within the Dataform Save Pipeline process, AFTER the Dataform has been saved and after Template Task Triggering.  The process can utilize Dataform field values or Server Data Procs (1 and 2) to establish Trigger Conditions. 

The Email Template and Email Template Notification and Triggering (consisting of Configuration, Recipients and Conditions fieldsets) information must be configured in order to implement this functionality. 

Notification will be via Email only unless Slack Notification is enabled.  Slack Notification can only be enabled by a NetWise System Administrator as described in the ‘Enabling Slack Notification’ portion of this document.  Additional setup is required when implementing Slack Notification (see ‘Slack Notification Setup’ below)

Process Operation

After all configuration is completed, the process operates as follows:

• Dataform is Saved
• Business Rules are run
• If Business Rules Hard and Soft Errors pass, Task Triggering is executed
• Email Template Triggering is now evaluated on Templates for the associated Dataform:
  • If a Template or Templates meet the trigger requirements and Execute On selection:
    • The Email Template Subject and Body fields are merged with data from the Merge Stored Procedure and Dataform to produce the Notification Subject and Body data
    • If the Notification Type is ‘Email’ or ‘Both’:
      • An HTML Email will be sent to all ‘To’ and ‘CC’ Recipients from the ‘From’ Recipient with the ‘Subject’ and ‘Body’ information
  • If the Notification Type is ‘Slack’ or ‘Both’ and Slack Notification is configured and enabled:
    • A Slack Notification containing only the ‘Subject’ will be sent to the ‘Channel’ from the ‘Username’ on the associated API Configuration form

Email Template Base Configuration

Email Templates can be one of two types: ‘Not Triggered’, and ‘Triggered’. 

‘Not Triggered’ Templates are typically used for custom implementations (e.g., NPS Survey, etc.) and are not discussed in detail in this document.  If an Email Template is ‘Not Triggered’, the Email Template Notification and Triggering configuration fields will not appear.  

Templates of the ‘Triggered’ type will be evaluated during the Dataform Save process to determine if a notification should be issued.

For both ‘Not Triggered’ and ‘Triggered’ Template Types, the following fields must be configured:

• Template Code: unique value to identify this Template
• Template Type: ‘Triggered’ must be selected for this functionality
• Template Name: readable template name
• ‘From’ Email Override: Optional parameter to override the from selector
• Description: readable description
• Subject: text data containing the Email Notification Subject test can contain replaceable fields
• Body: HTML text data containing the Email Notification Body text can contain replaceable fields.

Email Template Notification and Triggering Configuration

Email Templates of the Triggered type contain an additional fieldset of configuration fields called Email Template Notification and Triggering.  In addition to the Email Template fields described for the Not Triggered type, the fields in this fieldset establish the notification type, table configuration, recipients and Trigger Conditions (with optional Condition Expression).

• Configuration Fieldset
  • Notification Type: The type of Notification to be issued: either ‘Email’, ‘Slack’ or ‘Both’.  The default type is ‘Email’.  An Aplication Variable (accessible only via the database) determines whether Slack Notifications can be utilized.  If Slack Notification is not enabled, this field is read-only and always set to ‘Email’.  Contact Netwise if you use Slack in your organization and would like to implement this feature.
  • API Configuration: If the Notification Type is ‘Slack’, and API Configuration form of type ‘Slack’ must be selected.  If the Notification Type is ‘Email’ this field will be cleared and set to read-only.  Consult the ‘Slack Notification Setup’ below for details in configuring the system for Slack Notification.
  • Table Name: The Dataform with which this Email Template will be associated.  Multiple Templates can be associated with the same Dataform.  NOTE: at this time only ‘gen_’ tables are supported.
  • Execute On: determines if this Template Triggering should be evaluated on Inserts, Updates or both Inserts and Updates
  • Trigger Field: if selected and this Dataform Field is NOT DIRTY when the form is saved, a notification is not sent. If this Dataform field is dirty when the form is saved, Trigger Conditions and the Condition Expression are evaluated
  • Pipeline: determines which Dataform Save Pipeline will cause this Template Triggering to be evaluated.  For example, when importing a Dataform, the “Convert” Pipeline may be used.  If this Email Template Triggering is configured to utilize the “Default” Pipeline, this Email Template will be ignored when the Import process creates or updates the Dataform
  • Merge Procedure: a stored procedure (details below) that will provide the replaceable fields for the Subject and Body of this Email Template.  If left empty, all ‘Table Name’ Dataform fields will be available for merge
    • Clicking on the ‘folder’ icon to the right of the input text box will provide the user with a list of the replaceable fields from the Table Name Dataform and the actual stored procedure if provided. The list can be copied to your clipboard.

Recipients

• Recipient Procedure: an OPTIONAL stored procedure (details below) that can be used when selecting the ‘From’, ‘To’ and ‘CC’ Email Recipient addresses to which notification will be sent when implementing the Recipient selector
  • Clicking on the ‘folder’ icon to the right of the input text box will provide the user with a list of the ‘From’, ‘To’ and ‘CC’ Email Addresses from the actual stored procedure.  The list can be copied to your clipboard.
• Recipient Selector: a typical dashboard with Add, Edit and Delete functionality.  Email Recipients are chosen using this Dashboard.  If both ‘From’ and ‘To’ Recipients are not selected this Template will NOT send notifications.  The operation of the Recipient Selector is detailed below.

Conditions

• Condition Expression: A pseudo-Boolean equation that can be used to combine multiple Trigger Conditions for evaluation.  If the result of the Expression evaluation is ‘True’, the Trigger Conditions will be considered met and the Email Template notification will be issued.  If a Condition Expression is not provided, ANY Trigger Condition from the set of Trigger Conditions that is met will cause the Email Template notification to be issued (this is ‘OR’ Boolean logic), assuming the Trigger Field (if provided) IS DIRTY.
• Trigger Conditions:  A typical dashboard with Add, Edit and Delete functionality. Trigger Conditions are chosen using this Dashboard. Zero to many data comparisons will determine if the Email Template should issue a notification email. If a Condition Expression is not provided, Trigger Conditions are OR’d so that if any condition is met the Template will trigger.  IF NO TRIGGER CONDITIONS ARE PROVIDED, ONLY THE TRIGGER FIELD WILL DETERMINE IF A NOTIFICATION SHOULD BE ISSUED! 
  • Field Source: the source of the Trigger Field (Dataform or server data proc)
  • Trigger Field: the field to be evaluated
  • Operator: determines the type of test to be performed
  • Trigger Value: the value of Trigger Field to evaluate. Some Operators do not require a Trigger Value (e.g., Is Dirty).
  • Condition Expression Label: Used to populate the Condition Expression evaluation equation.

Recipient Selector

Recipients are selected by choosing a Source and a Field value, and an associated ‘Type’ for that Recipient.  Only one ‘From’ type can be selected; an error will be displayed if multiple ‘From’ types are selected.  There is no limit on the number of ‘To’ and ‘CC’ types selected.  Duplicates will be eliminated when the notification is issued.  If this is a Slack Notification only Template, the Recipient Selection is ignored.

• Recipient Source and Recipient Field: Choose the location from which this Recipient will be located:
  • The ‘Table Name’ dataform
    • Any dataform field that accesses the User or Contact Table will be available
    • The Recipient Procedure
      • All stored procedure fields will be available
      • When a Recipient Field is selected from the list, the ‘Type’ will automatically be populated but can be overridden.
    • An Adhoc Email
      • The ‘Adhoc Email’ field will enable and an email address (or multiple addresses separated by semi-colon) can be entered.
      • NOTE: No validation is performed on the Adhoc Email address.

• • • Dataform Subscribers
      • Selecting dataform subscribers will email anyone subscribed to receive notification of dataform changes.  This option may only be selected once from the list.

Trigger Condition Selector

Trigger Conditions are configured as follows:

• Field Source: can be the Email Template Triggering Dataform, Server Data Proc1 or Server Data Proc2
• Trigger Field: will display a list of available Dataform Fields or Server Data Proc fields to be used as the basis of the condition
• Operator: displays a list of available comparisons based on the data type of the Trigger Field.  Not every operator is available for every data type, only those that are appropriate to the data type will be displayed:
  • Equals
  • Does Not Equal
  • Contains
  • Starts With
  • Empty
  • Not Empty
  • Is Dirty
  • Greater Than
  • Greater Than or Equal
  • Less Than
  • Less Than or Equal
• Trigger Value: the comparison to make on the Trigger Field, depending on the Operator selected

Enabling Slack Notification

As mentioned, the default Notification Type is ‘Email’ only.  Slack Notification can be enabled by a NetWise System Administrator as follows:

• In tblApplication, the ‘app-bln-enable-slack’ value must be set to ‘1’
• In the ‘Email Template Notification Type’ lookup group, the ‘Slack’ and ‘Both’ lookups must be Active

If these configurations are performed, the ‘Notification Type’ field on the Email Template will be enabled. 

Slack Notification Setup

To utilize Slack Notification, additional configurations must be completed:

• Slack: a ‘Web Hook’ (or multiple Web Hooks) must be created for the Slack Team appropriate to this installation.  Visit https://api.slack.com/incoming-webhooks to create a Web Hook which will be used by the Slack Notification process to deliver Slack Messages based on Email Templates.
  • Web Hook Url: when the Web Hook is created, a Url will be generated by Slack.  This will be in the format
    https://hooks.slack.com/services/9-char/9-char/authenticationcode
    The entire Url minus the authenticationcode will be set in the API Configuration Endpoint (including the trailing ‘/’), and the authenticationcode will be set in the API Configuration Password field for encryption
  • Web Hook Channel: when the Web Hook is created you will need to provide a default ‘Channel’.  This will be overridden by the API Configuration Secondary ID field for each Configuration
  • API Configuration: Multiple API Configurations can be created.  The Email Template will be configured with the appropriate API Configuration to suit its purpose
    • API Type: Slack
    • Application Code: unique, user specified, as in ‘SLACK01’
    • Application Name: user specified, as in ‘Notification Channel’
    • Username: the name of the Notification BOT that will appear in the Slack window (e.g. ‘ClientSpace Case Creation Notification’
    • Password: the authentication code obtained from the end of the Web Hook Url
    • Description: user specified, description of this configuration
    • Endpoint: the Url obtained when creating the Web Hook, without the authentication code, MUST END WITH ‘/’
      • https://hooks.slack.com/services/ABCDEFGHI/JKLMNOPQR/
• Secondary ID: the Slack Channel (without the ‘#’) to which the Notifications will be sent
• Logging Level: not implemented
• Additional Parameters: not implemented

Additional Considerations

• Since Slack Notifications only contain the ‘Subject’ line, it can be configured with a ‘LinkTo’ and a ‘GenKey’ to provide a link to open the dataform that was just modified.  If the Email Template is only a Slack Notification, the ‘Body’ field is ignored (but it is still required to save the Email Template).  For example:
  • Subject: Dataform has changed, the key = {GenKey},  Click <https://master.dev.clientspace.net/next/linkto/{TableCode}/{GenKey}|here> to view form

Clicking the link in the example subject above will open the Dataform in Next.  It is important to note: The {TableCode} must either be returned by the Merge Procedure or looked up in the ProjectTypes table and hardcoded (minus the curly braces) into this link.  The resulting Slack Notification will appear as:

Attachments

 With Release 50 we added the ability to attach forms to triggered emails directly from file upload dataform fields, either from a related workspace Single form, or from the triggering dataform regardless of whether it is a single or multiform.  This gives you the ability to automatically attach specific documents to a triggered email response.  An example of this might be a triggered email that sends loss run data to a Workers’ Comp Carrier when the file is attached to the collateral form.  You can configure automatic attachments by clicking Add in the attachments area – a new dialog will appear:

1. Dataform –  Provides a list of the Single forms with file upload fields, as well as the triggering dataform selected above, regardless of whether it is a single or multi form.
2. Field -  Provides a list of the file upload attachment fields from the dataform selected in Step 1.  Selecting a field will attach the document currently “Pinned” in that field.

Once the field(s) have been selected and the changes published, the email template will begin attaching the requested document(s) on any triggered email generated from that template.

Email Template Publishing and Cloning

Email Templates must be published in order to be evaluated.  Once a Template is published, it IMMEDIATELY becomes eligible for triggering evaluation and notification.

A status message appears at the top of the Email Template page indicating whether the current Template is Published (green text) and active or Unpublished (red text) and off-line. 

When creating (adding) and designing an Email Template, new Templates are NOT PUBLISHED by default.  If a Template is currently unpublished, use the Save button to maintain the unpublished status and allow the user to save changes without publication.  If a Template is currently published, the Save button will maintain that status and immediately allow changes to take effect in the Dataform save pipeline. 

To publish a new Template, click the ‘Publish’ button.  A confirmation warning will be presented to verify that the user wishes to publish the Template. 

Published Templates can be unpublished, essentially taking them off-line and no longer active in the Dataform save pipeline. A confirmation warning will be presented to verify that the user wishes to unpublish the Template.

Existing Email Templates can be ‘Cloned’ or copied to a new Template.  The following fields are copied from the existing Template:

• Template Type
• ‘From’ Email Override
• Description
• Subject (with replace fields)
• Body (with replace fields)
• Additionally, for Triggered Template Types:
  • Notification Type
  • API Configuration
  • Table Name
  • Execute On
  • Trigger Field
  • Pipeline
  • Merge Procedure
  • Recipient Procedure

The remaining fields Template Code, Template Name, Recipients, Condition Expression and Trigger Conditions are NOT cloned and must be configured. 

Newly Cloned Templates are not published until the user publishes them.

Recipient Procedure Design and Construction

This procedure provides the ‘FROM’, ‘TO’ and ‘CC’ information for the Email Template notification process. 

Contact your NetWise Account manager if you would like to have a custom recipient procedure created for your installation. 

Merge Procedure Design and Construction

This procedure provides the replaceable fields for the Email Template notification process.  Contact your NetWise Account manager if you would like to have a custom recipient procedure created for your installation. 

Email Template Triggering and Notification Methodology

As mentioned, Email Template Notification can be driven by field triggering if desired.  Here are some important notes on how triggering is implemented on ‘Triggered’ Email Templates (f the Template Type is ‘Not Triggered’, this Template will not deliver notification based on the Dataform Save Pipeline, some other method must be implemented)

• A ‘Table Name’ (dataform) must be selected.   It is only during the save of that dataform will this Email Template be evaluated for Triggering and Notification
• ‘Execute On’ determines when the Template Triggering will be evaluated.  For example, if an existing Dataform is being edited and the ‘Execute On’ is set to Insert only, the Template will not deliver notification
• ‘Pipeline’ determines which type of Dataform save will be used to evaluate Email Template Triggering.  For example, if a header link performs a submit action on the default pipeline and the ‘Pipeline’ selected is not ‘Default’, the Template will not be evaluated for Triggering
• If a ‘Merge Procedure’ is not specified, Notification may still occur but the ‘Body’ of the Template will only be merged with the current ‘Table Name’ dataform values
• Triggering Rules
  • no Trigger Field chosen:
    • no Trigger Conditions configured:
      • Condition Expression ignored
      • will trigger on each dataform save
  • has Trigger Conditions configured:
    • no Condition Expression
      • if any Trigger Condition is met, will trigger (OR)
    • Condition Expression
      • all Trigger Conditions will be evaluated
        • results passed into Condition Expression
        • if any Condition Expression value is NOT a valid Label, will not pass Condition Expression evaluation
        • Condition Expression evaluation = True, will trigger
• has Trigger Field selected:
  • if Trigger Field IS NOT DIRTY, will not trigger
  • if Trigger Field IS DIRTY
    • no Trigger Conditions
      • Condition Expression ignored
      • will trigger
    • has Trigger Conditions
      • no Condition Expression
        • any Trigger Condition met, will trigger
        • Condition Expression
          • all Trigger Conditions will be evaluated
          • results passed into Condition Expression
            • if any Condition Expression value is NOT a valid Label, will not pass Condition Expression evaluation
            • if Condition Expression evaluation = True, will trigger
            • Condition Expression general information
              • Condition Expression works in conjunction with Trigger Conditions to determine if the Email Template should issue a Notification
              • Condition Expression is optional.  If no Condition Expression is provided, any Trigger Condition that is met (passes) will cause a Notification to be issued, even if all other Trigger Conditions failed
              • If a Condition Expression is provided, any Trigger Condition that does not contain a Label will be ignored
              • A Label that is entered into a Condition Expression that is not a valid Label (i.e. a Label that has not been specified on a Trigger Condition) could cause the Trigger Condition evaluation to fail and prevent a Notification from being sent
              • Condition Expression Functionality
                • Each Trigger Condition is evaluated and a TRUE (condition is met) or a FALSE (condition is not met) is returned.  If a Trigger Condition tests that ‘Field1’ Is Dirty and that field was changed before the save, the result of that Trigger Condition is TRUE.  If it was not changed the result of the Trigger Condition is FALSE
                • The result of each Trigger Condition evaluation is added to the Condition Expression in the location of the Label in the expression
                • Once all Trigger Conditions are evaluated, the Condition Expression construction has been completed
                • The completed Condition Expression is then evaluated via Boolean logic defined by the Expression and a TRUE or FALSE result is returned
                • If the result is TRUE, an Email Template Notification will take place.  If FALSE, no notification will be issued
                • Sample Trigger Conditions and Condition Expression (assumes Trigger Field IS DIRTY or not provided)
                  • Trigger Condition #1
                    • Trigger Field: ‘Field1’
                    • Operator: ‘Empty’
                    • Label: “TC1”
                  • Trigger Condition #2
                    • Trigger Field: ‘Field2’
                    • Operator: ‘Equals’
                    • Trigger Value: “FL”
                    • Label: “TC2”
                  • Trigger Condition #3
                    • Trigger Field: ‘Field3’
                    • Operator: ‘Contains’
                    • Trigger Value: “Approved”
                    • Label: “TC3”
                • Condition Expression populated with {TC1} AND ({TC2} OR {TC3}), Trigger Conditions are evaluated as a Boolean expression:
                  • {TC1} AND ({TC2} OR {TC3})  This Expression evaluates as follows:
                  • if Field1 is empty AND either Field2 is set to “FL” OR Field3 contains the text “Approved”, the Email Template Notification will be issued
                  • If Field1 contains a value, Notification will not take place
                  • If Field1 is empty and Field2 is set to “CA” and Field3 contains the text “Approved”, Notification will take place
                • Condition Expression NOT populated, Trigger Conditions are evaluated individually (OR logic):
                  • If Field1 is empty, notification will take place regardless of Field2 and Field3
                  • If Field1 is populated and Field2 is set to “FL”, notification will take place
                  • If Field1 is populated and Field2 is set to “CA” and Field3 contains “Approved”, notification will take place

For further help configuring email template triggering, or to request a quote for custom stored procedures, please contact your PrismHR account manager or create an Extranet Case.

Related articles

• Page:
  Configuring Email Integration For Your Installation
• Page:
  Organization and Workspace Security Configuration
• Page:
  Security Entities
• Page:
  Configuring Links
• Page:
  Administering Email Templates