Page History
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Introduction
This job template is used The JITL MailJob template can be used by a job to send mail from an Agent.
- The job template makes use of the SMTP protocol to send mail.
- The job template can be used to access any database for which a JDBC Driver is available with the Agent.
- The JS7 includes a number of JDBC Drivers for supported DBMS, see JS7 - Database. For other DBMS you can provide an individual JDBC Driver and store the Driver's .jar file with the .
- Connection Settings
- These includes settings such as the SMTP host, port etc.
- It is recommended that JS7 - Job Resources are used for this purpose as such settings tend to use the same values for any mail that should be sent.
- Mail Settings
- Such settings are specific for individual mails and include, for example, the subject and body of the mail.
- The job template can be used with a JS7 - Credential Store.
/lib/user_lib
directory of the Agent installationspecify settings from different sources:Usage
When defining the job considereither:
- invoke the Wizard that is available from the job properties tab in the Configuration view and select the JITL MailJob and relevant arguments from the Wizard
or
- specify the
JITL
job class and - to select the JITL job class,
- to specify the
com.sos.jitl.jobs.mail.MailJob
Java class name to provide variables and add arguments specifying what to send and where to send mail.mail should be sent as explained in the documentation below.
Example
Download (upload .json): pdwNotificationSOSMailPlainText.json
You can use the job wizard like this:
...
- Add an empty job from the instruction panel.
- Specify a name and a label for the job.
- Select an Agent.
In a next step invoke the job wizard that you find in the upper right corner of the job property editor. The wizard brings up the following popup window:
...
- From the list of available job template templates select the MailJob.
Then hit the "Next" button to make the job wizard display available job variablesarguments:
Explanation:
- Required job variables arguments include the
to
variable argument to specify the recipient of mailsmail. - Any other variables arguments are optional, provided that a job resource is used that specifies connection details to your mail server, see below. Otherwise individual settings such as the SMTP host, SMTP port etc. can be specified from arguments.
- Select the check box provided with each argument if you want this argument to be added to the arguments of the MailJob template.
When hitting the "Submit" button the wizard adds the required settings arguments to your the job that which should look like this:
The job arguments can be specified as follows:
Arguments
The com.sos.jitl.jobs.db.SQLExecutorJob
class accepts the following arguments:
...
hibernate_configuration_file
...
Specifies the configuration file (XML) format for Hibernate connections, see JS7 - Database. By default Agents ship without hibernate configuration files, however, if a file with the default name is available then it will be applied.
...
resultset_as_warning
...
Raises a warning if the SQL statement creates a result set.
...
exec_returns_resultset
...
If stored procedures are called that return a result set then this argument has to be set to true
in order to run the stored procedure as a query.
- from individual variables as configured using the job wizard,
- by using JS7 - Job Resources.
Use of Job Resources for Mail Settings
A number of settings for sending mail most probably carry the same values when used for different mail jobs. These include, for example, the SMTP host, SMTP port etc.
- You can specify such settings individually from variables that are assigned the job's arguments, see above.
- You can specify such settings from JS7 - Job Resources that can be re-used for any number of mail jobs.
Setting up a Job Resource for Mail Settings
You can create a job resource that includes any settings required to send mail.
- For details how to set up a job resource, follow instructions from the JS7 - Job Resources article.
- The example shown below is available for download: eMailDefault.jobresource.json
A job resource has two parts, one being the variables that can be specified from the "Arguments" sub-tab as shown here:
Explanation:
- The variable names specified are selected to match those used with the JITL
MailJob
template. - Note the use of variable names that start with
mail.smtp.
- These variable names correspond to Java properties available with the JavaMail API. Any of the JavaMail properties can be specified.
- You will find a full list of the available
mail.smtp.
properties from https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html - Required properties include (but are not limited to):
mail.smtp.host
mail.smtp.port
- When using a secure SSL connection note that:
- to use TLS, the
mail.smtp.starttls.enable
argument has to be used with the valuetrue
, to use SSL, themail.smtp.ssl.enable
argument has to be used with the valuetrue
. - different ports might be in use: for unencrypted connections port 25 is frequently used, for TLS connections port 465 or 587 is frequently used, for SSL connections port 587 is frequently used.
- optionally use the
mail.smtp.ssl.protocols
argument with a value such asTLSv1.2
orTLSv1.1,TLSv1.2
to specify one or more protocol versions that limit handshake with the mail server to the protocol versions specified. Depending on the Java version in use and possible modifications of thejava.security
file a number of protocols could be enabled that might not match the mail server's capabilities. Typically SSL handshaking starts from the highest protocol version accepted by both parties. However, it is not guaranteed that protocol negotiation will work perfectly. In such a situation it is recommended that the protocol version is specified using this argument.
- to use TLS, the
- For authentication the following settings are used:
- the
mail.smtp.user
setting is assigned the SMTP user account. - the
mail.smtp.password
setting is assigned the password.
- the
- When using OAuth2 authentication then the following settings are used:
- the
mail.smtp.auth
setting is assigned the valuetrue
. - the
mail.smtp.auth.mechanisms
setting is assigned the valueXOAUTH2
. - the
mail.smtp.user
setting is assigned the OAuth2 user account. - the
mail.smtp.password
setting is assigned the OAuth2 access token. - Some mail servers such as smtp.office365.com might require the older SASL mechanism to be used:
- the
mail.smtp.sasl.mechanisms.oauth2.oauthToken
setting is assigned the OAuth2 access token. - the
mail.smtp.password
setting is not specified.
- the
- the
The second part of a job resource is accessed using the "Environment Variables" sub-tab as shown here:
Explanation:
- Values of environment variables are assigned the corresponding variables as explained in the previous sectio.
- The purpose of the "Environment Variables" sub-tab is to propagate variables to shell jobs, should you operate jobs that require such environment variables for parameterization purposes.
- Note that the JITL
MailJob
is a job running in the Java Virtual Machine. It is not a shell job and therefore does not use environment variables.
Assigning a Job Resource for Mail Settings
Once a job resource has been created and deployed it can be assigned the JITL MailJob
to populate the job's arguments as shown in this screenshot:
Documentation
The Job Documentation including the full list of arguments can be found under: https://www.sos-berlin.com/doc/JS7-JITL/MailJob.xml
The MailJob class accepts the following arguments:
Name | Required | Default Value | Purpose | Example |
---|---|---|---|---|
to | yes | list of mail recipient's e-mail address, multiple e-mail addresses are separated by comma or semicolon | ops@example.com | |
| no | e-mail address used for sending mail | js7@example.com | |
| no | the free-text name of the account that sends mail | JS7 JobScheduler | |
| no | if no replies should be accepted then typically use an e-mail address such as | no-reply@example.com | |
| no | e-mail address of carbon copy recipient, multiple e-mail addresses are separated by comma or semicolon | ||
bcc | no | e-mail address of blind carbon copy recipient, multiple e-mail addresses are separated by comma or semicolon | ||
subject | yes | the mail subject, consider the use of ASCII 7bit characters | ||
body | yes | the mail body specified as plain text or HTML depending on the content_type setting | ||
content_type | no | text/plain | a content type text/plain specifies plain text mail, a content type text/html specifies use of HTML mails. | |
encoding | no | 7bit | the character encoding of subject and body, by default ASCII 7bit is used | |
charset | no | iso-8859-1 | by default Latin 1 (iso-8859-1) is used | |
attachment | no | the path to a file to be attached, multiple files are separated by semicolon | ||
attachment_content_type | no | application/octet-stream | the attachment content-type typically allows binary files | |
attachment_encoding | no | Base64 | any attached files are encoded with printable base64 characters | |
attachment_charset | no | iso-8859-1 | by default Latin 1 (iso-8859-1) is used | |
mail.smtp.host | yes | the hostname or IP address of the SMTP server | ||
mail.smtp.port | no | 25 | the port of the SMTP server | |
mail.smtp.user | no | the user account to be used in case that the SMTP server requires authentication | ||
mail.smtp.password | no | the password to be used in case that the SMTP server requires authentication | ||
mail.smtp. ... | no | any additional Java properties can be used as applicable to the JavaMail package | ||
credential_store_file | no | Location of a credential store database (*.kdbx) | ./config/private/jobs.kdbx | |
credential_store_key | no | Location of a credential store key file (*.key) | ./config/private/jobs.key |
The MailJob can be used with a credential store to hold sensitive arguments. For use of the credential_store_*
arguments see JS7 - Use of Credential Store with JITL Jobs.
Further Resources
Links
References
Display content by label | ||||
---|---|---|---|---|
|
...
resultset_as_variables
...
Specifies how a result set is forwarded to order variables for subsequent jobs:
false
: no result set is processed (default)column_value
: for the first record of the result set from each column name a variable is created that holds the column value.name_value
: the first two columns of the result set will be added to order variables. The values of the first column of each record included with the result set will become the variable names, the values of the second column will become the variable values.
Explanation:
- Note that it is possible to define more than one instruction with the
command
argument.
Such instructions are then carried out in the order in which they are written and must be separated by a semicolon.- Some DBMS might require and additional newline character.
- For example
update MY_TABLE set a='foo' where b='bar'; commit;
- Note also that order variables and arguments can be injected to the SQL statement(s) of the
command
argument by use of the${variable}
syntax.
Further information
...