About Email Alert Gateways

Alert sources and escalations provide a way for you to alert users via email when a problem occurs. However, when you configure alert sources and escalations, setting the target email address is not enough to generate an email. You must also set up an email alert gateway, to provide headers (including a list of recipients), optional file attachments, and an email body.

Note: Alert sources allow you to specify an email body in the Alert Source Email tab. If you do not specify an email body for an alert source, the email gateway's email body is used. Escalations do not allow you to define an email body, so the email alert gateway's email body is always used.

Multiple headers with the same name are supported. RunMyJobs will combine them.

If you specify an email body in the Alert Source Email of an alert source, that email body will override any email body set on the email alert gateway.

Address Patterns

Email alert gateways use an Address Pattern field that supports glob matching rather than an explicit name. This lets you use a single email alert gateway to service a variety of different alert sources and escalations.

For example, assume an email alert gateway has an Address Pattern of *@example.com. Alert sources and escalations that use an Address of jdoe@example.com or troe@example.com will automatically use this email alert gateway, unless there is another email alert gateway with a more specific match.

Here are some example address patterns.

• *@example.com: Matches all recipients at example.com.
  • jdoe@example.com: MATCHES
  • jdoe@us.example.com: DOES NOT MATCH
• er?@example.com: Matches all three letter strings that start with er
  • erp@example.com: MATCHES
  • ER1@example.com: MATCHES
  • ERP1@example.com: DOES NOT MATCH

Email Addresses and Aliases

In addition to specifying an email address on an alert source or escalation, you can use an alias. An alias takes the format alias:<alias-name>). If you specify an alias in the Address field for an alert source or escalation, the alias is used to look up the email alert gateway only, and is not used as a recipient address.

Note: It is a best practice to keep the list of recipients on an email alert gateway's Headers and/or Email tab. However, if you specify an email address in the Address field of an alert source, that email address will be added as a recipient too.

The following table provides a few examples of email handling. For simplicity, this table assumes the email alert gateway's Address Pattern matches the alert source's Address value.

Alert Source: Address Field	Alert Source: Alert Source Email Tab*	Email Alert Gateway: Headers Tab	Email Alert Gateway: Email Tab*	Emails Sent To
alias:development	<none defined>	To: jdoe@example.com To: jsmith@example.com CC: emustermann@example.com	To=cberthier@example.com	To: jdoe@example.com, jsmith@example.com, cberthier@example.com CC: emustermann@example.com
cberthier@example.com	To=jsmith@example.com	To: jdoe@example.com	CC=emustermann@example.com	To: cberthier@example.com, jsmith@example.com, jdoe@example.com CC: emustermann@example.com

*For information about specifying email addresses in the Alert Source Email tab (for an alert source) or the Email tab (for an email alert gateway), see Specifying Recipients in the Email Body.

Variables

The variables that can be used in email alert gateways depend on the object that caused the alert to be fired. You can use all valid variables of the alert source along with the gateway-specific variables.

• Process Alert Sources
• Monitor Alert Sources
• Process Server Alert Sources
• Ad Hoc Alert Sources
• Email Alert Gateways (this topic)

Note: Note that the variable you use must have a value. Using the remoteStatus variable on an alert from a JDBC job (which does not have a remote status) will cause errors to be thrown. You can use conditional expressions to determine the alert source and object that caused the alert, and then determine which variables are available.

Headers

Email gateways also allow you to override email headers. This is useful if you want to (for example) customize the subject or add a reply-to address.

The Headers tab lets you specify header fields for a email alert gateway. You can use these to add recipients to the email or

There is a special email header that can be used to override the SMTP server, named X-Redwood-Server. You can also add other custom email headers that may be required by your email system. You can use substitution parameters in email gateways, which lets you (for example) dynamically set the subject of an email.

The substitution parameters that can be used in headers are listed in Scripting Contexts and Implicit Objects.

• ${address}: The addressee's address.
• ${messageTitle}: The title of the message.
• ${subject}: The subject.
• ${message}: The message.
• ${alertSource}: The alert source that triggered the alert.
• ${object}: The object that triggered the alert.

Mail headers starting with $MIME-Body-<name> set the MIME header <name> on the email body.

Valid MIME headers include:

• Content-Description: A description for an object in the email.
• Content-Disposition: Presentation information for the email (or part of it).
• Content-ID: Automatically generated globally unique identifiers.
• Content-Transfer-Encoding: Indicates whether or not a binary-to-text encoding has been used, and if so, which one.
• Content-Type: MIME type used (for example, text/plain).
• MIME-Version: MIME version used. Currently MIME-Version: 1.0 is the only value allowed.

Note: If the source of the email starts with < RunMyJobs will set the Content-Type to text/html. Otherwise, it will be set to text/plain. You can override this with the headers.

Processing Order

You might want to use multiple alert gateways (for example, if you want to use a different Alert Resend Delay, Alert Rate Interval, or Alert Rate Limit for the recipients). If you do, you must pay attention to both the Address Pattern and the Processing Order of each email alert gateway.

The reason is, there are two rules in play, and they are evaluated in this order.

1. Email alert gateways with lower Processing Order numbers are evaluated before email alert gateways with higher Processing Order numbers.

2. More-specific patterns (such as owner@example.com) are matched before less-specific patterns (such as *@example.com).

Consequently, the most specific address patterns must have the lowest processing order, or the wrong email alert gateway might be used. For example, an email alert gateway with an Address Pattern of *example.com and a processing order of 1 will take precedence over any an email alert gateway for help.example.com and a Processing Order of 2. Redwood recommends using a catch-all gateway with an extremely high processing order (for example, 99), to make sure all emails are sent.

Note: If there are multiple matching email alert gateways with the same Processing Order, which gateway is used is undefined.

Alerting Gateway Actions

Actions let you write script custom reactions to alerts in RedwoodScript. Stub code is already available to you and contains predefined objects.

Object	Class	Example Code
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.info("This is an informational message");
jcsEmailAlertGatewayPreSendActionContext	com.redwood.scheduler.api.scripting.variables.EmailAlertGatewayPreSendActionScriptObject	jcsEmailAlertGatewayPreSendActionContext.getMessage();
jcsSession	com.redwood.scheduler.api.model.SchedulerSession	jcsSession.getQueueByName("PRD_Queue");

Note: The jcsSession object is available only if you set an Action Subject.