Sending an email when an alert condition occurs

You can have the Z controller send an email to a recipient or list of recipients when an alert conditions occurs. To activate this function, you need to:

Ensure that you have installed the Communications Server Simple Mail Transfer Protocol (CSSMTP) on a system that runs on the same JESPLEX where the controller runs.
Add the EQQSMTP and EQQEMAIL DD statements to the HCL Workload Automation for Z JCL procedure. For detailed information, see SMTP data set (EQQSMTP) and Email data set (EQQEMAIL).
Set the MAIL parameter in the ALERTS statement.
Ensure that the MAILOPTS MAILEXTWRT is set to the actual JES external writer used by the Communication Server SMTP (CSSMTP).

You can set that the emails are sent for the following alert conditions:

DURATION: An operation in the current plan is active for an unexpectedly long time.
ERROPER: An operation in the current plan is set to ended-in-error status.
HIGHRISK: The risk level of a critical operation in the current plan has become High.
LATEOPER: An operation in the current plan becomes late, which means that it reaches its latest start time and does not have the status started, complete, or deleted.
OPCERROR: An HCL Workload Automation for Z subtask or subsystem ends unexpectedly.
POTENTRISK: The risk level of a critical operation in the current plan has become Potential.
SPECRES: The time that an operation in the current plan is waiting to allocate a given resource exceeds the time specified by the RESOPTS CONTENTIONTIME parameter.
WLMOPER: An operation in the current plan is promoted by WLM.

The EQQEMAIL data set includes:

The members containing the text of the emails.
If you do not specify any member, the default set in ALERTS MAIL is used. For each alert condition, one default member is defined.
Optionally, a customized member with the JCL to be used for sending the emails. To be effective, you must set this member in MAILOPTS(MAILJCLMEM).
You can use any text for the JCL, no parsing is performed by . For example, you could specify the following information:
```
//jobname  JOB (accounting.information),'programmer.name',CLASS=A,MSGCLASS=A,
//         NOTIFY=userID
//COPY           EXEC PGM=IEBGENER
//SYSPRINT       DD SYSOUT=*
//SYSIN          DD DUMMY
//SYSUT2         DD SYSOUT=(A,external_writer_name),SPIN=UNALLOC
//SYSUT1         DD *
```
A member named RULES (required).
This member contains the rules that must be met for the emails to be sent. Each rule consists of a FILTER, HEADER, and optionally a TEXTMEMBER, in the following format:
```
FILTER(expression1, expression2, ..., expressionn)
HEADER(header_text)
[TEXTMEMBER(member_name)]
```
Note: Each rule is associated with only one FILTER, HEADER, and TEXTMEMBER. If within a single rule you specify more than one FILTER, HEADER, or TEXTMEMBER only the first occurrence is considered valid.
Where:
FILTER(expression1, expression2, ..., expressionn)
The expressions to be satisfied for the email to be sent, separated by commas. All the expressions set must be met, otherwise the email is not sent. Each expression has the following format, which is not case-sensitive:
```
value=filter
```
where:

value

String of alphanumeric characters, included variables (for details about variables, see Variables allowed in the EQQEMAIL members). It cannot contain blanks.

filter

String of alphanumeric characters. It cannot contain blanks. You can use the wildcard characters asterisk (*) and percent sign (%).

For example, you can set a FILTER that includes all the applications whose name begins with MY and ended with error code 16, as follows:
```
FILTER(&OADID=MY*,&OERRCODE=16) 
```
HEADER(header_text)
Information used for the email header, separated by a semicolon (;). All the addresses are specified in the format local-part@domain, where:
local-part

Name of a user or box. You can use up to 64 characters.

domain
Name of the domain, up to 255 characters. The domain name is preceded by the at sign (@), if your interface is using the USA code page EBCDIC 1047. In all other cases, ensure that you use the hexadecimal value x'7c'. For example, if your interface uses:

The German code page EBCDIC 1141, the character corresponding to the hexadecimal value x'7c' is the section sign (§).

The Turkish code page EBCDIC 1026, the character corresponding to the hexadecimal value x'7c' is the Latin Capital S with Cedilla (Ş).

For the domain, you can set a default value in the MAILOPTS MAILDOMAIN statement.
As the header_text, you can specify the following information. Each piece of information can be set only once; if you specify more than one, only the first is considered.
Note: Although optional, at least one value among TO, CC, and BCC must be specified.

FROM: sender_address

Optional. Address of the email sender.
If you do not specify any, ensure that you set the default value in the MAILOPTS MAILFROM statement.

TO: recipient_address1, ..., recipient_addressn

Optional. Addresses of the primary recipients, separated by commas.

CC: recipient_address1, ..., recipient_addressn

Optional. Addresses of the copy recipients, separated by commas.

BCC: recipient_address1, ..., recipient_addressn

Optional. Addresses of the blind recipients, separated by commas.

SUBJECT: subject_text

Optional. Text of the email subject.

For example, you can set a HEADER with the following information:
```
HEADER(
   From: jennifer.clay@abc.com
   To: jonathan.doe@abc.it, william.smith@abc.de, howard.raw@mouse.fr
   CC: lucy.jones@cat.com
   Subject: Recovery procedure)
```
TEXTMEMBER (member_name)

Optional. The member containing the text of the email. If you do not specify any member, the default set in ALERTS MAIL is used. For each alert condition, one default member is defined.

Variables allowed in the EQQEMAIL members shows you the variables that you can use in the EQQEMAIL members. Variables are resolved only if they are meaningful for the event condition that you have set in ALERTS MAIL. Otherwise, the variable is ignored.

Table 1. Variables allowed in the EQQEMAIL members
Variable name (must be preceded by &)	Variable description	Max length	Alert condition
ALERCOND	Alert condition that generated the email (for details, see the alert conditions listed in ALERTS MAIL). It can assume the following values: DURATION ERROROPER HIGHRISK LATEOPER OPCERROR POTENTRISK SPECRES WLMOPER	10	DURATION, ERROROPER, HIGHRISK, LATEOPER, OPCERROR, POTENTRISK, SPECRES, WLMOPER
OADID	Application ID	16	DURATION, ERROROPER, HIGHRISK, LATEOPER, POTENTRISK, SPECRES, WLMOPER
OADOWNER	Occurrence owner.	16	DURATION, ERROROPER, LATEOPER, SPECRES, WLMOPER
OTOKEN	Occurrence token.	8	DURATION, ERROROPER, LATEOPER, SPECRES, WLMOPER
OAUGROUP	Authority group.	8	DURATION, ERROROPER, HIGHRISK, LATEOPER, POTENTRISK, SPECRES, WLMOPER
ODMY1	Occurrence input arrival date, DDMMYY.	6	DURATION, ERROROPER, HIGHRISK, LATEOPER, POTENTRISK, SPECRES, WLMOPER
OJOBNAME	Operation job name.	8	DURATION, ERROROPER, HIGHRISK, LATEOPER, POTENTRISK, SPECRES, WLMOPER
OOPNO	Operation number within the occurrence, right-justified and padded with zeros.	3	DURATION, ERROROPER, HIGHRISK, LATEOPER, POTENTRISK, SPECRES, WLMOPER
OWSID	Workstation ID for the current operation.	4	DURATION, ERROROPER, HIGHRISK, LATEOPER, POTENTRISK, SPECRES, WLMOPER
OJOBID	Job number.	8	DURATION, ERROROPER, WLMOPER
OERRCODE	Error code.	4	ERROROPER
RESNAME	Resource name.	44	SPECRES
RESWTTM	Resource waiting time	4	SPECRES
TASKNAME	HCL Workload Automation for Z task name.	16	OPCERROR

Troubleshooting

When errors occur in writing and sending the emails, messages are logged in the EQQMLOG file. You can set a further level of diagnosis by adding DIAGNOSE MONFLAGS(X'00000080') to the member of the EQQPARM library.

Additional debugging information are stored in the Communications Server Simple Mail Transfer Protocol (CSSMTP) log file.