Instance Notifications

Instance Notifications are rules that are evaluated against the payload and notebook minute usage of instance organizations. When rule conditions evaluate true for a given instance organization, custom emails can be sent to instance members and/or organization members, and callback URLs may be invoked.

Viewing Notifications

A list of your instance’s notification rules can be found under the “Notifications” link in the Instance Manager’s subnavigation. Clicking a notification rule’s name takes you to a detail page where you can edit the rule (if you have administrator privileges) and also see a log of recent true evaluations of the rule against target organizations.

Adding Notifications

To add a new notification rule, click the “Add Notification” button at the top right corner of the notifications list. The button is only present for instance administrators.

Rule Configuration

The following properties must be defined when creating a notification, as broken up into five sections:

General Settings

• Name: The name to give this notification rule. This is for internal use only; it is not exposed to recipients of messages generated by the rule.
• Enabled: Whether this rule should be evaluated on a daily basis. If the rule is not enabled, the conditions will not be evaluated daily, nor can the rule be manually executed.
• Description: Similar to “Name”, this field is for internal use only. Description is optional.

Target Organizations

Provide an advanced query for targeting which instance organizations to evaluate the rule against. Queries that explicitly target no organizations are not allowed.

Notification Rules

Next, define the rule type and the conditions against which to evaluate the rule for sending notifications …

• Rule Type: Choose whether to evaluate the rule against each target organization’s Payload Usage or Notebook Minute Usage relative to the organization’s monthly limit.
• Threshold (Percent of Limit): Provide a number between 0 and 1,000 to represent the percentage of resource usage (as defined in the rule type) that should trigger a notification. Note: When creating “Notebook Minute Usage” rules, it is nearly impossible for an organization to exceed 100% of its limit.
• Maximum Notification Frequency: While the rule conditions will be evaluated against each target organization on a daily basis, emails and callback URL requests will only be sent either Once per billing cycle (monthly) or Daily as selected here.

Email Recipients

Choose whether to send an email to one or more recipients when the notification rules evaluate as true for a given target organization. If opting not to send emails, then Callback URL is required.

If choosing to send emails, you must provide the following …

• Email Subject Template: Enter a string template to serve as the subject line of the email. Templates render against the notification context.
• Body Template: Provide HTML in the form of a string template for the email body. Templates render against the notification context.

• Organization Recipients: Choose whether to send this email to …

  • All organization administrators
  • All organization members (except those with “None” permission)
  • No organization members

• Instance Recipients: Choose whether to send this email to …

  • All instance administrators
  • All instance members
  • No instance members
• Arbitrary Recipients: Optionally, enter one or more email addresses (maximum of 10) to send a notification to outside of the options selected above. If both No organization members and No instance members are selected, at least one arbitrary email address must be provided.

For new notifications - or when enabling emails in existing notifications - Losant provides an example Email Subject Template and Body Template to use as a starting point.

Callback URL

Optionally, provide a callback URL to invoke with a POST request per organization matching the notification rules. If not providing a callback URL, then the Email Recipients option and all its sub-properties are required.

When the rule evaluates as true for a target organization, a POST request will be sent to the provided URL with the notification context in the request body.

Notification Context

The following context is available for reference within the email subject and body …

{
  date, // a Date object indicating when the notification was sent; in callback requests, this is the date in ISO string format
  limit, // the organization's payload or notebook minute limit at the time of sending
  notificationRule: { ... }, // an object representing the configuration of this notification rule, minus the ruleConfig.bodyTemplate property
  organization: { ... }, // an object representing the instance organization receiving this notification, including all resource usage and limits and organization tags
  organizationUrl, // the URL to the organization overview page for org members (NOT the instance org overview page for instance members)
  requestedById, // the ID of the entity that requested the rule execution; if this was system-generated, the value will be "00000000000000000000"
  requestedByType, // the ID of the entity that requested the rule execution; if this was system-generated, the value will be "system"
  value // the number of payloads or notebook minutes used by the organization at the time of sending
}

The same object is provided in the body of callback URL POST request, along with two additional properties …

{
  dataType, // always a value of 'NotificationRuleFire'
  jobId // a unique alphanumeric string per evaluation request; multiple organizations receiving a callback request from one invocation will share this value
}

Manual Executions

Instance administrators can manually execute a notification rule with its current settings by clicking the “Execute …” button in the top right corner of the rule’s detail page. When doing so, you may choose to Ignore Max. Frequency Check, which sends notifications to any target organizations evaluating true against the rule configuration regardless of if they have already received a notification this billing cycle or this day (depending on the rule’s “Maximum Notification Frequency”).

This feature, along with the option to ignore the frequency check, is especially useful when building out the notification email and callback logic; however, care should be taken to limit the target organizations to internal organizations and/or reduce the email recipients to test accounts so as not to spam organization members with unfinished and misleading messages.

Note: If the notification rule is not enabled, you may not invoke a manual execution.

Notification Log

On a notification rule’s detail page is a log of recent activity, which includes entries for each email / callback request generated by the rule. For example, if one execution of the rule matches against 10 of your instance’s 100 organizations, there will be 10 entries in the log corresponding to that execution (one entry per matching organization).

Each entry provides the following information:

• The instance organization that matched the rule
• Who requested the execution (or if it was system-generated)
• When the notification was sent

• The rules and values that led to the execution …

  • The rule type (payload or notebook minute usage) and threshold (percentage of value versus limit)
  • The notification’s maximum frequency (or, if this was a manual execution, if the rule’s max. frequency was bypassed)
  • The organization’s usage of the target resource at the time of the notification
  • The organization’s limit on the target resource at the time of the notification

• Whether an email was sent, and if so …

  • All the email addresses that received the message
  • The rendered email subject
  • The rendered HTML of the email body
• The callback URL that was invoked, if applicable

Deleting Notifications

Administrators can delete an instance notification rule by clicking the “Delete Instance Notification” link in the footer of a rule’s detail page, or by clicking the “Remove” (trash can) icon in a rule’s table row on the list page.

Deleting a notification rule cannot be undone. Its notification logs will no longer be accessible, and the rule will no longer execute for its target organizations. Consider disabling the notification as an alternative until you are sure it can be safely deleted.