Email Tool

The Email Tool enables sending emails as part of workflow processes in Joget DX. Depending on your configuration, it supports sending emails regarding data creation, updates, or both.

Configure email

To configure Email, drag and drop the Tool element onto the canvas in Process Builder, click on it, and select Mapping.

When adding Email in the field Tools, you will see the following fields available for configuration:

• To (Specific email address): Enter the recipient's fully qualified email address.
• To (Participant ID): Participant ID(s) according to its process flow. Multiple values can be accepted by separating them with semicolons.
  When To (Specific email address) and To (Participant ID) are populated, email will be sent to both.
• CC: A fully qualified address is expected. Multiple values can be accepted by separating them with semicolons.
  This allows you to send a copy of a message to someone interested but not the primary recipient.
• BCC: A fully qualified address is expected. Multiple values can be accepted by separating them with semicolons.
  Both Cc and Bcc forward a copy of the message to everyone you've listed. The main difference between Cc or Carbon copy and Bcc (Blind carbon copy) is that, with the latter, the recipients do not get to know each other.
• Subject: Enter the subject line for the email.
• Message: Type the email message here.
• HTML Content?: Check if the Message is intended to be HTML content.

SMTP settings

The SMTP Settings allows users to set up the parameters for sending emails through an SMTP server. If these settings are left empty, Joget will use the default SMTP configuration from the General Settings. Users can specify the sender's email address, SMTP host, port, and security type and provide authentication details like username and password. Proper configuration ensures emails are sent securely and reliably.

Fields to configure:

• From: Sender's email address. (e.g., no-reply@your-company-name.com).
• SMTP Host: Email server SMTP host (e.g., smtp.gmail.com).
• SMTP Port: Email Server SMTP Port.
  Typically, port 465 is for the SSL security option, and 587 is for TLS.
• Security: Choose between None, TLS, or SSL.
  Alternatively, you can click on the hash symbol to allow the input of hash variables.
• SMTP Username: Email server account username.
  On your Google email account, use your full email address.
• SMTP Password: Email server account password.
  The password submitted will be encrypted for security reasons.

Digital signature

The Digital Signature section provides options for digitally signing emails sent through the Email Tool. Users can specify the file path of the Keystore file (P12), the key store's passphrase, and the digital certificate's issuer alias. Digitally signing emails enhances their authenticity and integrity, ensuring the contents are not altered.

Fields to configure:

• Key Store File Path (P12): File path of the .pfx or .p12 file under the wflow folder in your Joget DX installation folder.
• Key Store Passphrase: Passphrase for the .jks file.
• Issuer Alias: The digital certificate's or signature's Issuer name (alias).

Error handling

The Error Handling section allows users to define the behavior when email sending fails. Users can specify the number of retries and the interval between retries. There is also an option to quickly validate and test email settings using the Send Test Email button. This section ensures that any issues in sending emails are managed efficiently and reliably.

Fields to configure:

• Number of Retries When Fail to Send Out Email: Number of retries when the email fails to be sent.
• Retry Interval (Seconds): Frequency of retries in seconds.

Attachments

The Attachments section provides options for attaching files to the emails sent through the Email Tool. Users can specify the source form and file upload fields and define file paths or URLs for attachments. Additionally, users can choose to embed images within the email content. This section ensures emails can include relevant files and multimedia elements as needed.

• Form: File attachment source form.
• Form Upload Fields:
  • Field ID: File attachment field ID(s) in the Form selected above.
  • Embed: Click the checkbox to embed the image attachment in the email and display the image using HTML, for example, <img src="cid:#form.table.FileUpload?url#" />.
• Files: This attribute allows one to define the file attachment freely by defining a system path or absolute URL.
  • Path: Source file path & filename.
  • Type:
    • System Path
    • URL
  • File Name: The file name will be used in the email attachment.
  • Embed: Click the checkbox to embed the image attachment in the email and display the image using HTML, for example, <img src="cid:cat.jpg" />.
    See Send List as attachment in Email Tool for more information.

ICS attachment

The ICS Attachment section allows users to attach an ICS file to the email, allowing recipients to add events to their calendars easily. Users can define event details such as name, start and end times, date format, timezone, description, location, organizer email, and attendees. This feature is useful for sending calendar invitations and ensuring recipients can easily schedule events.

Fields to configure:

• Attach ICS File: 

  Check this option to prepare an event and attach it as an ICS file in the email.
  When this attribute is checked, the details for the calendar ICS file must be filled in in the fields below.

  • Event Name
  • Start Date Time
  • End Date Time
  • Date Format
  • Timezone (e.g. America/Los_Angeles) (Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
  • All Day?
  • Event Description
  • Location
  • Organizer Email
  • Attendees ( Name and Email are mandatory fields if one chooses to add attendees)

  Important:

  • The organizer or sender email must not be the same as your destination/recipient email. If the sender and recipient emails are the same, you will not see the Add to Calendar box in your email.

  • Start date time 00:00 and end date time is 23:59 is considered as all day event.
    Advisable to not set time for an all day event when All day? is checked.

Images in email tool

In Joget DX, we introduced a new ?img2base64 hash variable escape char to convert the image tag src in the Rich text editor field to a base64 data string so that the Email Tool can display the image. The syntax is: #form.tableName.richTextFieldId?img2base64#.

Alternatively, starting from Joget DX v7.0.7, we can easily embed images via the Embed option in the Files property.

Sample app available below.

Additional resources

The Additional Resources links related articles and tutorials that offer further guidance and information on using the Email Tool and its features. These resources help users understand best practices, explore advanced configurations, and leverage the full potential of Joget's email capabilities. They are invaluable for users seeking to enhance their workflow processes with effective email communication.

• Email Tool
• Sending Email
• User Notification Plugin
• User Notification Tutorial
• Send JasperReports PDF in Email Tool
• Add Signature Form Element as Image into Email Content