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:
  1. 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.
  2. Add the EQQSMTP and EQQEMAIL DD statements to the Z controller JCL procedure. For detailed information, see SMTP data set (EQQSMTP) and Email data set (EQQEMAIL).
  3. Set the MAIL parameter in the ALERTS statement.
  4. Ensure that the MAILOPTS MAILEXTWRT is set to the actual JES external writer used by the Communication Server SMTP (CSSMTP).
  5. Optionally store your customized JCL member, to be used for sending the emails, in the EQQEMAIL data set.
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.
ERROROPER
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, which you set in ALERTS MAIL.
  • 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 HCL Workload Automation for Z. 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 taken into account.
    Where:
    FILTER(expression1, expression2, ..., expressionn)
    The expressions to be satisfied for the email to be sent, separated by commas. The email is sent when all the expressions in the filter are met; for each satisfied filter the corresponding email is 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 blank. 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, the member set in ALERTS MAIL is used as default. 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 the ALERTS MAIL parameter. 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.