Difference between revisions of "Sending Emails"
(→Must issue a STARTTLS command first) |
(→Additional Email Configuration) |
||
(22 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
== config_email_global.xml == |
== config_email_global.xml == |
||
+ | File '''<code>config_email_global.xml</code>''' is the configuration file for setting up the sender's email credentials for all emails that are sent by the LRM process. |
||
− | |||
− | File '''<code>config_email_global.xml</code>''' is the configuration file for setting up the sender's email credentials for all emails that are sent by the LRM process. It is located in the global '''<code><HOME>/Lingoport_Data/L10nStreamlining/config</code>''' folder. |
||
The '''config_email_global.xml''' file is used by a project's ''Notifications'' Jenkins job in order to send out status emails. This Jenkins job is, by default, set to run once a week. |
The '''config_email_global.xml''' file is used by a project's ''Notifications'' Jenkins job in order to send out status emails. This Jenkins job is, by default, set to run once a week. |
||
Line 9: | Line 8: | ||
* interval between the sending of status emails |
* interval between the sending of status emails |
||
* flag indicating whether to send out the 'No Files to Prep' email |
* flag indicating whether to send out the 'No Files to Prep' email |
||
+ | |||
+ | === Location of the global email configuration file === |
||
+ | The default location for this file is the '''<code><HOME>/Lingoport_Data/L10nStreamlining/config</code>''' folder. As with other LRM config files, this file can be moved to either the group's config folder ('''<code><HOME>/Lingoport_Data/L10nStreamlining/<group name>/config</code>''') or the project's config folder ('''<code><HOME>/Lingoport_Data/L10nStreamlining/<group name>/projects/<project name>/config</code>''') depending on the level of granularity required. For example, if a specific project requires a different email sender then is defined at the global level, then copy the global email config file to the project level and make the required changes. |
||
=== Email Credentials Configuration === |
=== Email Credentials Configuration === |
||
Line 20: | Line 22: | ||
* '''sender-password''' - not required |
* '''sender-password''' - not required |
||
+ | The first step in configuring the global email file is to verify, with your IT department, the mail server credentials. |
||
[[Sending_Emails#Send_Email_Command|Send email command]] may be used to test the configuration values. |
[[Sending_Emails#Send_Email_Command|Send email command]] may be used to test the configuration values. |
||
Line 49: | Line 52: | ||
In addition, there are configuration settings for when to send out notification emails and whether or not to send out the 'No Files to Prep' email. |
In addition, there are configuration settings for when to send out notification emails and whether or not to send out the 'No Files to Prep' email. |
||
* '''dashboard-url''' - Dashboard URL used as the link destination for the email Log In button |
* '''dashboard-url''' - Dashboard URL used as the link destination for the email Log In button |
||
− | * '''notify-changes-email-interval''' - By default, the ''Notification'' email |
+ | * '''notify-changes-email-interval''' - By default, the ''Notification'' email interval is set to 1 (every day) and is also dependent on how often the Jenkins Notification job is run. If no notification email is desired then set the interval to a number > 365. |
− | * '''late-kits-email-interval''' - By default, the ''Late Prep Kits'' email |
+ | * '''late-kits-email-interval''' - By default, the ''Late Prep Kits'' email interval is set to 1 (every day) but is dependent on the number of days late and on how often the Jenkins Notification job is run. If no late kit email is desired then set the interval to a number > 365. |
* '''number-days-late''' - By default, a prep kit is deemed late if it is 7 days late. |
* '''number-days-late''' - By default, a prep kit is deemed late if it is 7 days late. |
||
* '''send-no-files-to-prep-email''' - By default, the ''No Files to Prep'' email will be sent out when there is a request to prep a kit but there are no files to prep. If a Jenkins job is created that automatically attempts to prep a kit, then this value should be set to ''0'' so that the email is not sent. Otherwise, the email recipient's inbox may be inundated with 'No Files to Prep' emails. |
* '''send-no-files-to-prep-email''' - By default, the ''No Files to Prep'' email will be sent out when there is a request to prep a kit but there are no files to prep. If a Jenkins job is created that automatically attempts to prep a kit, then this value should be set to ''0'' so that the email is not sent. Otherwise, the email recipient's inbox may be inundated with 'No Files to Prep' emails. |
||
− | === |
+ | === Encrypted Password === |
+ | The <code><sender-password></code> can be configured with the <code>encrypted</code> attribute set to true, as in |
||
+ | <pre> |
||
+ | ... |
||
+ | <email-sender>mailuser@company.com</email-sender> |
||
+ | <sender-password encrypted="true">UUIasd455</sender-password> |
||
+ | ... |
||
+ | </pre> |
||
+ | |||
+ | To encrypt the password, use the <code>encrypt</code> command line on <code>lrm-common.jar</code> file. For instance: |
||
+ | |||
+ | '''<code>> java -jar <LRM_INSTALLATION_PATH>/lib/lpcommon.jar --encrypt</code>''' |
||
+ | |||
+ | which will prompt you for the text (here the password) to encrypt and will provide the result on the console. |
||
+ | |||
+ | == Java Options for sending emails == |
||
It may be necessary to explicitly set the email port and/or STARTTLS flag rather than rely on the default mail server values. In addition, the email session debug mode can be enabled. |
It may be necessary to explicitly set the email port and/or STARTTLS flag rather than rely on the default mail server values. In addition, the email session debug mode can be enabled. |
||
Line 70: | Line 88: | ||
:: <span style="background-color: #eaecf0;>export _JAVA_OPTIONS='-Dmail.smtp.port=25'</span> |
:: <span style="background-color: #eaecf0;>export _JAVA_OPTIONS='-Dmail.smtp.port=25'</span> |
||
− | + | === Enable/Disable STARTTLS === |
|
The expected java option for explicitly enabling/disabling STARTTLS is: |
The expected java option for explicitly enabling/disabling STARTTLS is: |
||
* mail.smtp.starttls.enable |
* mail.smtp.starttls.enable |
||
Line 80: | Line 98: | ||
STARTTLS is automatically enabled for the SMTPS protocol. |
STARTTLS is automatically enabled for the SMTPS protocol. |
||
− | + | === Enable Email Session Debug mode === |
|
The expected java option for explicitly enabling/disabling the email session debug mode is: |
The expected java option for explicitly enabling/disabling the email session debug mode is: |
||
* mail.debug.mode |
* mail.debug.mode |
||
Line 88: | Line 106: | ||
:: <span style="background-color: #eaecf0;>export _JAVA_OPTIONS='-Dmail.debug.mode=true'</span> |
:: <span style="background-color: #eaecf0;>export _JAVA_OPTIONS='-Dmail.debug.mode=true'</span> |
||
− | + | == Send Email Command == |
|
+ | The ''send email command'' is used to test sending an email using your mail server credentials. Before starting, verify with your IT department the mail server credentials otherwise errors will occur. |
||
− | The ''send email command'' is accessed through the lpcommon.jar file and is located in the <code>lib</code> folder (i.e. ../lrm-server-x.x/lib). This command is used to test the configured mail server. Before running this command, you may want to [[Sending_Emails#Enable_Email_Session_Debug_mode |enable the email session debug mode]]. |
||
+ | |||
+ | The ''send email command'' is accessed through the lpcommon.jar file and is located in the <code>lib</code> folder (i.e. ../lrm-server-x.x/lib). This command is used to test the configured mail server. Before running this command, you may want to [[Sending_Emails#Enable_Email_Session_Debug_mode |enable the email session debug mode]]. |
||
In order to run the send email <code>-sse</code> or <code>--send-smtp-email</code> command, you must specify an existing location for the error log. |
In order to run the send email <code>-sse</code> or <code>--send-smtp-email</code> command, you must specify an existing location for the error log. |
||
Line 100: | Line 120: | ||
* '''Email Recipients''' denoted by option <code>-r</code> or <code>--recipients</code> |
* '''Email Recipients''' denoted by option <code>-r</code> or <code>--recipients</code> |
||
− | + | === Sending Email with SMTP protocol and no authorization === |
|
To test sending an email using the SMTP protocol with no authorization run the following command: |
To test sending an email using the SMTP protocol with no authorization run the following command: |
||
:: <span style="background-color: #eaecf0;>java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com </span> |
:: <span style="background-color: #eaecf0;>java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com </span> |
||
Line 107: | Line 127: | ||
* Email protocol is `smtp` (which is the default) |
* Email protocol is `smtp` (which is the default) |
||
* Authorization `mail.smtp.auth` is set to `false` |
* Authorization `mail.smtp.auth` is set to `false` |
||
− | * Connection successful |
||
+ | If errors occurs then you'll need to change your email send options. For error examples see [[Sending_Emails#Error_Messages|Email Error Messages]]. |
||
+ | === Sending Email with SMTP authorization === |
||
− | An error such as ''Must issue a STARTTLS command first'' indicates that STARTTLS must be enabled either through: |
||
− | * setting the authorization to SMTPS |
||
− | * explicitly setting STARTTLS through the java option [[Sending_Emails#Enable.2FDisable_STARTTLS|mail.smtp.starttls.enable]], setting the [[Sending_Emails#Sending_Email_with_SMTP_authorization|authorization to SMTP]] and setting the password. |
||
− | |||
− | If the debug log indicates that the port is incorrect then you may need to explicitly set ''mail.smtp.port'' through its [[Sending_Emails#Email_Protocol_Port_Number|java option]]. |
||
− | |||
− | ==== Sending Email with SMTP authorization ==== |
||
To test sending an email using the SMTP protocol with SMTP authorization run the following command: |
To test sending an email using the SMTP protocol with SMTP authorization run the following command: |
||
:: <span style="background-color: #eaecf0;>java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com '''-sa mail.smtp.auth''' -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com </span> |
:: <span style="background-color: #eaecf0;>java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com '''-sa mail.smtp.auth''' -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com </span> |
||
Line 124: | Line 138: | ||
* Authorization `mail.smtp.auth` is set to `true` |
* Authorization `mail.smtp.auth` is set to `true` |
||
− | If errors occurs then you'll need to change your email send options. For error examples see [[Sending_Emails# |
+ | If errors occurs then you'll need to change your email send options. For error examples see [[Sending_Emails#Error_Messages|Email Error Messages]]. |
− | + | === Sending Email with SMTPS protocol === |
|
To test sending an email using the SMTP protocol with SMTP authorization run the following command: |
To test sending an email using the SMTP protocol with SMTP authorization run the following command: |
||
:: <span style="background-color: #eaecf0;>java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com '''-sa mail.smtps.auth''' -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com '''-ep mypassword''' </span> |
:: <span style="background-color: #eaecf0;>java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com '''-sa mail.smtps.auth''' -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com '''-ep mypassword''' </span> |
||
Line 134: | Line 148: | ||
* Authorization `mail.smtp.auth` is set to `false` |
* Authorization `mail.smtp.auth` is set to `false` |
||
− | If errors occurs then you'll need to change your email send options. For error examples see [[Sending_Emails# |
+ | If errors occurs then you'll need to change your email send options. For error examples see [[Sending_Emails#Error_Messages|Email Error Messages]]. |
+ | |||
+ | === Error Messages === |
||
+ | The first step in trouble shooting any email messages is to verify, with your IT department, the mail server credentials. |
||
− | ==== Send Email Error Messages ==== |
||
If you're unable to send an email successfully then you may want to enable the debug mode for the email session. This will provide additional information regarding the progress of the session. Set the debug mode through [[Sending_Emails#Enable_Email_Session_Debug_mode|java options]]. |
If you're unable to send an email successfully then you may want to enable the debug mode for the email session. This will provide additional information regarding the progress of the session. Set the debug mode through [[Sending_Emails#Enable_Email_Session_Debug_mode|java options]]. |
||
+ | After enabling the debug mode, the error messages should provide explicit information regarding the reason for the failure. There are a few error messages that may not be so obvious. These are: |
||
− | |||
− | + | * Connection is not successful due to invalid port number: |
|
− | + | :: The default port number will be used when setting up the connection. If you're unable to change the default port number then you'll need to explicitly set it via [[Sending_Emails#Email_Protocol_Port_Number|java options]]. |
|
+ | * Must issue a STARTTLS command first. This error indicates that STARTTLS must be enabled. This error occurs when the protocol is SMTP. You can attempt to fix this error by: |
||
− | |||
+ | :: Setting the authorization to SMTPS (connection may require a password) |
||
− | ===== Must issue a STARTTLS command first ===== |
||
+ | ::: or |
||
− | An error such as ''Must issue a STARTTLS command first'' indicates that STARTTLS must be enabled. This error occurs when the protocol is SMTP. You can attempt to fix this error by: |
||
+ | :: Explicitly setting STARTTLS through the java option [[Sending_Emails#Enable.2FDisable_STARTTLS|mail.smtp.starttls.enable]] and adding the password to the command line (<code>-ep</code>) |
||
− | * setting the authorization to SMTPS |
||
− | * explicitly setting STARTTLS through the java option [[Sending_Emails#Enable.2FDisable_STARTTLS|mail.smtp.starttls.enable]] and adding the password to the command line (<code>-ep</code>) |
||
− | |||
− | === Encrypted Password === |
||
− | The <code><sender-password></code> can be configured with the <code>encrypted</code> attribute set to true, as in |
||
− | <pre> |
||
− | ... |
||
− | <email-sender>mailuser@company.com</email-sender> |
||
− | <sender-password encrypted="true">UUIasd455</sender-password> |
||
− | ... |
||
− | </pre> |
||
− | |||
− | To encrypt the password, use the <code>encrypt</code> command line on <code>lrm-common.jar</code> file. For instance: |
||
− | |||
− | '''<code>> java -jar <LRM_INSTALLATION_PATH>/lib/lpcommon.jar --encrypt</code>''' |
||
− | |||
− | which will prompt you for the text (here the password) to encrypt and will provide the result on the console. |
Latest revision as of 16:56, 7 December 2021
Contents
config_email_global.xml
File config_email_global.xml
is the configuration file for setting up the sender's email credentials for all emails that are sent by the LRM process.
The config_email_global.xml file is used by a project's Notifications Jenkins job in order to send out status emails. This Jenkins job is, by default, set to run once a week.
There are 3 types of information contained in the config_email_global.xml file.
- email configuration
- interval between the sending of status emails
- flag indicating whether to send out the 'No Files to Prep' email
Location of the global email configuration file
The default location for this file is the <HOME>/Lingoport_Data/L10nStreamlining/config
folder. As with other LRM config files, this file can be moved to either the group's config folder (<HOME>/Lingoport_Data/L10nStreamlining/<group name>/config
) or the project's config folder (<HOME>/Lingoport_Data/L10nStreamlining/<group name>/projects/<project name>/config
) depending on the level of granularity required. For example, if a specific project requires a different email sender then is defined at the global level, then copy the global email config file to the project level and make the required changes.
Email Credentials Configuration
The email configuration consists of the following xml elements:
- smtp-host - server that will send the email
- smtp-auth - authentication mechanism, if applicable
- mail.smtp.auth - smtp protocol with smtp authentication
- mail.smtps.auth - smtps protocol with smtps authentication
- none' - smtp protocol with no authentication
- email-sender - valid email address
- sender-password - not required
The first step in configuring the global email file is to verify, with your IT department, the mail server credentials. Send email command may be used to test the configuration values.
Example No Authorization Email Configuration
Test your email configuration using the -se command for no authorization.
<smtp-host>smtp.gmail.com/<smtp-host> <smtp-auth>none</smtp-auth> <email-sender>joe@mycompany.com</email-sender> <sender-password encrypted="false">mypassword</sender-password>
Example SMTP Authorization Email Configuration
Test your email configuration using the -se command for SMTP authorization.
<smtp-host>smtp.gmail.com/<smtp-host> <smtp-auth>mail.smtp.auth</smtp-auth> <email-sender>joe@mycompany.com</email-sender> <sender-password encrypted="false"></sender-password>
Example SMTPS Authorization Email Configuration
Test your email configuration using the -se command for SMTPS authorization.
<smtp-host>smtp.gmail.com/<smtp-host> <smtp-auth>mail.smtps.auth</smtp-auth> <email-sender>joe@mycompany.com</email-sender> <sender-password encrypted="false">mypassword</sender-password>
Additional Email Configuration
In addition, there are configuration settings for when to send out notification emails and whether or not to send out the 'No Files to Prep' email.
- dashboard-url - Dashboard URL used as the link destination for the email Log In button
- notify-changes-email-interval - By default, the Notification email interval is set to 1 (every day) and is also dependent on how often the Jenkins Notification job is run. If no notification email is desired then set the interval to a number > 365.
- late-kits-email-interval - By default, the Late Prep Kits email interval is set to 1 (every day) but is dependent on the number of days late and on how often the Jenkins Notification job is run. If no late kit email is desired then set the interval to a number > 365.
- number-days-late - By default, a prep kit is deemed late if it is 7 days late.
- send-no-files-to-prep-email - By default, the No Files to Prep email will be sent out when there is a request to prep a kit but there are no files to prep. If a Jenkins job is created that automatically attempts to prep a kit, then this value should be set to 0 so that the email is not sent. Otherwise, the email recipient's inbox may be inundated with 'No Files to Prep' emails.
Encrypted Password
The <sender-password>
can be configured with the encrypted
attribute set to true, as in
... <email-sender>mailuser@company.com</email-sender> <sender-password encrypted="true">UUIasd455</sender-password> ...
To encrypt the password, use the encrypt
command line on lrm-common.jar
file. For instance:
> java -jar <LRM_INSTALLATION_PATH>/lib/lpcommon.jar --encrypt
which will prompt you for the text (here the password) to encrypt and will provide the result on the console.
Java Options for sending emails
It may be necessary to explicitly set the email port and/or STARTTLS flag rather than rely on the default mail server values. In addition, the email session debug mode can be enabled.
There are 3 email settings that may be set through java options:
- Email Server Port
- SMTP STARTTLS enabled
- Email Session Debug mode enabled
Email Protocol Port Number
The expected java option for explicitly setting the protocol port number is:
- mail.smtp.port
Linux example if setting java options within a shell session.
- export _JAVA_OPTIONS='-Dmail.smtp.port=25'
Enable/Disable STARTTLS
The expected java option for explicitly enabling/disabling STARTTLS is:
- mail.smtp.starttls.enable
Linux example if setting java options within a shell session.
- export _JAVA_OPTIONS='-Dmail.smtp.starttls.enable=true'
STARTTLS is automatically enabled for the SMTPS protocol.
Enable Email Session Debug mode
The expected java option for explicitly enabling/disabling the email session debug mode is:
- mail.debug.mode
Linux example if setting java options within a shell session.
- export _JAVA_OPTIONS='-Dmail.debug.mode=true'
Send Email Command
The send email command is used to test sending an email using your mail server credentials. Before starting, verify with your IT department the mail server credentials otherwise errors will occur.
The send email command is accessed through the lpcommon.jar file and is located in the lib
folder (i.e. ../lrm-server-x.x/lib). This command is used to test the configured mail server. Before running this command, you may want to enable the email session debug mode.
In order to run the send email -sse
or --send-smtp-email
command, you must specify an existing location for the error log.
In addition to the log file, there are 5 other required fields.
- SMTP Host denoted by option
-sh
or--smtp-host
- Senders email address denoted by option
-es
or--email-sender
- Email Subject denoted by option
-subj
or--subject
- Email Message denoted by option
-msg
or--message
- Email Recipients denoted by option
-r
or--recipients
Sending Email with SMTP protocol and no authorization
To test sending an email using the SMTP protocol with no authorization run the following command:
- java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com
In looking at the console log you should see the following:
- Email protocol is `smtp` (which is the default)
- Authorization `mail.smtp.auth` is set to `false`
If errors occurs then you'll need to change your email send options. For error examples see Email Error Messages.
Sending Email with SMTP authorization
To test sending an email using the SMTP protocol with SMTP authorization run the following command:
- java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com -sa mail.smtp.auth -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com
In looking at the console log you should see the following:
- Email protocol is `smtp`
- Authorization `mail.smtp.auth` is set to `true`
If errors occurs then you'll need to change your email send options. For error examples see Email Error Messages.
Sending Email with SMTPS protocol
To test sending an email using the SMTP protocol with SMTP authorization run the following command:
- java -jar lpcommon.jar -sse -lf /var/lib/jenkins/test/error.log -sh smtp.gmail.com -sa mail.smtps.auth -es myemail@mycompany.com -subj test -msg "This is a test" -r anotheremail@email.com -ep mypassword
In looking at the console log you should see the following:
- Email protocol is `smtp` (which is the default)
- Authorization `mail.smtp.auth` is set to `false`
If errors occurs then you'll need to change your email send options. For error examples see Email Error Messages.
Error Messages
The first step in trouble shooting any email messages is to verify, with your IT department, the mail server credentials.
If you're unable to send an email successfully then you may want to enable the debug mode for the email session. This will provide additional information regarding the progress of the session. Set the debug mode through java options. After enabling the debug mode, the error messages should provide explicit information regarding the reason for the failure. There are a few error messages that may not be so obvious. These are:
- Connection is not successful due to invalid port number:
- The default port number will be used when setting up the connection. If you're unable to change the default port number then you'll need to explicitly set it via java options.
- Must issue a STARTTLS command first. This error indicates that STARTTLS must be enabled. This error occurs when the protocol is SMTP. You can attempt to fix this error by:
- Setting the authorization to SMTPS (connection may require a password)
- or
- Explicitly setting STARTTLS through the java option mail.smtp.starttls.enable and adding the password to the command line (
-ep
)
- Setting the authorization to SMTPS (connection may require a password)