Email Alert Gateways
Alerting gateways specify the addressee as well as the content of the message that is to be sent to the operator.
Tabs & Fields
The following table illustrates the fields of each tab of Email Alert Gateway editor dialogs.
| Tab | Field | Description |
|---|---|---|
| Email Alert Gateway | Partition | The Partition where you wish to store the email alert gateway |
| Email Alert Gateway | Name | The name of the email alert gateway can contain any combination of US ASCII letters, digits, and underscores; limited to 80 characters. |
| Email Alert Gateway | Application | The Application of the email alert gateway |
| Email Alert Gateway | Description | The description of the email alert gateway can contain any combination of printable UTF-8 characters, limited to 255 characters. |
| Email Alert Gateway | Address Pattern | The email address pattern that this email alert gateway should use, note that you can use substitution parameters in this field |
| Email Alert Gateway | Processing Order | The order in which email alert gateways are processed, the first that matches will be used. |
| Email Alert Gateway | Alert Resend Delay (in minutes) | The delay in minutes before trying to resend a failed alert. |
| Email Alert Gateway | Alert Rate Limit | The number of alerts that can be sent to an address within the alert rate window. |
| Email Alert Gateway | Alert Rate Interval (in minutes) | The time interval in minutes for calculating the alert rate. |
| Documentation | Documentation | A comment about the email alert gateway |
| Headers | Name | The name of the email header to use; valid email headers include subject, to, bcc ... |
| Headers | Value | The value of the header. |
| File Attachments | Name | The short name of the file to attach to the email; the file name |
| Actions | Type | The type of action, limited to Presend on email alert gateways, they fire before an email is sent so you can suppress or customize it. |
| Actions | Enabled | This checkbox allows you to enable or disable the action; when unchecked, the action will never fire. |
| Actions | Library | You can specify a library here containing methods you would like to use. It is recommended to save your code in libraries so you can use it elsewhere. |
| Actions | Action Subject | The user under which the code in the action is performed. You must set an action subject if you want to use jcsSession |
| Actions | Source | The source of your code. |
| Actions | Stub Source | This code shows you where the action will be performed. |
| Body | The body of the email to send, see Customizing email messages for information on how you can customize it. | |
| Security | * | This is where you can specify who can access/change/remove the email alert gateway. |
Context-Menu
Email alert gateways support the following context-menu actions:
| Action | Description |
|---|---|
| Edit Security | Edit the security of the e-mail alert gateway |
| Duplicate | Make a copy of the e-mail alert gateway to create a similar one |
| Delete | Delete the e-mail alert gateway |
| Export > Export | Export the e-mail alert gateway into a CAR file |
| Export > Export with related objects | Export the e-mail alert gateway into a CAR file including referenced objects |
| Promote > Promote to system | Promote the object to a remote system |
| Promote > Edit further then promote | Edit the export rule set prior to promoting |
| Promote | Promote the e-mail alert gateway to another Redwood Server instance |
| Edit | Edit the e-mail alert gateway |
| Show Permalinks | Show links that can be used from third party applications to link to the object |
| Add to navigation bar | Add the current object to the navigation bar |
| New e-mail alert gateway | Create a new e-mail alert gateway |
| Show diagram | Display the dependencies in a diagram |
| Filter > New Filter | Create a new e-mail alert gateway filter |
| Filter > Edit Filter | Edit current e-mail alert gateway filter |
| Filter > Delete | Delete current e-mail alert gateway filter |
| Filter > Duplicate Filter | Create a copy of the filter |
| Filter > Export Filter | Export the filter into a CAR file |
| Filter > Add to navigation bar | Add the filter to a navigation bar |
| Filter > Create filter from search | Create a filter from the current IntelliSearch query |
Address Patterns
Email alert gateways use patterns rather than names so that gateways can apply to all recipients of a particular group and aliases with specific naming conventions can be used to minimize the number of required gateways.
Patterns support two wildcards:
*- matches any number of characters?- matches any single character.
Example:
*@example.com- matches all recipients at Example Inc. (example.com)jdoe@example.com- MATCHESjdoe@us.example.com- DOES NOT MATCH
er?@example.com- matches all three letter strings starting with ERerp@example.com- MATCHESER1@example.com- MATCHESERP1@example.com- DOES NOT MATCH
Variables
The variables that can be used in 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
- Alert Email Gateways
note
Note that the variable you use must be filled. 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 to determine which variables are available.
Headers
Email gateways also allow you to override email headers. This is handy if you want to adapt the subject or add a reply-to address, for example. 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, this allows you to dynamically set the subject of the email, for example.
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 yes, which one
- Content-Type - MIME type used, for example
text/plain - MIME-Version - MIME version used, currently
MIME-Version: 1.0is the only value allowed.
note
If the source of the email starts with < Redwood Server will set the Content-Type to text/html, otherwise it will be set to text/plain. You can override this with the headers.
Files
You can attach files of the failed process to the email. This allows the operator to troubleshoot the problem without the need to connect to the system and gives other addressees, like managers, information on what went wrong, if they need to know.
Usually, you would send stderr.log which should contain specific error messages. The standard output is usually stored in stdout.log, you can specify a short name of any process file.
Alerting Gateway Actions
Actions allow you to 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 only available when you set an Action Subject.
Gateway Emails
Gateways will always attempt to use the most specific email, the search is done in the following order:
- specific alert source email
- the gateway email
- the default email
The email type is detected by the first letter, if the first letter is a <, then the email type is set to HTML, otherwise a text email is sent. You can use specific constructs using REL expressions in your emails. For more information, see Creating and Configuring Alert Gateways.
Finding Email Alert Gateways
You can search for email alert gateways using filters and the Search Email Alert Gateways box on the Email Alert Gateways tab. This box is known as the IntelliSearch box and located under your username on the top right-hand side of the user interface. Filters allow you to specify a list of objects with static criteria. IntelliSearch allows you to specify complex queries in a simple way using prefixes. Prefixes are used to specify which property you are searching in and have short as well as long syntaxes. For example, if you want to display all email alert gateways with the term management in the comment, you would use the search criteria as follows:
c:management
You can search more than one property, as follows:
c:management n:corp
note
No spaces should be entered before or after the colon (: ).
See the Advanced Object Search for more information.
The following table illustrates the available prefixes for email alert gateways:
| Prefixes | Description |
|---|---|
| n, name | searches the name property |
| c, comm, comment | searches the documentation property |
| d, desc, description | searches the description property |
| a, application | searches the application property |
| cb, changedbefore | (internal) search for alert gateways that changed before a certain ISO-8601 period |
Deleting Email Alert Gateways
You can only delete gateways when no other objects relate to them. For example, if there are alert escalations that use the gateway, the gateway cannot be deleted until all alert escalations that use it have been modified. You can see all alert escalations that relate to the gateway in Related Objects in the lower detail pane and on the show page.
The table in related objects contains three columns:
- Type - the type of object with a link to it
- Related Object - the name of the object with a link to it
- Used As - objects can sometimes be used in different roles
Security
| Privilege | Description |
|---|---|
| EmailAlertGateway.Create | Create email alert gateways |
| EmailAlertGateway.Delete | Delete email alert gateways |
| EmailAlertGateway.Edit | Edit email alert gateways |
| EmailAlertGateway.View | Access email alert gateways |
You can grant privileges on two levels, Access and Admin; a privilege granted on Admin level allows the grantee to grant the privilege to other users. These privileges can be granted per partition or system-wide.
The Security tab allows you to specify which users can access, edit, and delete the email alert gateway.