Sending an Alert

Once the configuration parameters are set for your alerting provider, you can start sending alerts from instances of your real-time digital twin model, whether it is a code-based model or a rules engine model.

.NET and Java Models

In C#, the API you can use to send alerts programmatically from your model’s implementation is defined as:

public abstract class ProcessingContext
{
  // [...]

  public abstract SendingResult SendAlert(string providerName, AlertMessage alertMessage);
}

• providerName (String): represents the name of the configuration you want to send your alert to, which must match the name of one defined in the model file

• alertMessage (AlertMessage): represents the content of the alert you want to send

In order to send an alert, you need to build an AlertMessage object with at least a title, message and severity. You also can provide optional custom properties as key/value pairs. The AlertMessage class is defined as follows:

/// <summary>
/// The AlertMessage objects contain all the data to send alerts to external services.
/// This includes properties such as title, message and severity. Finally, alerts can include snapshots of
/// properties along with the message.
/// </summary>
public class AlertMessage
{
    /// <summary>
    /// Title of the alert
    /// </summary>
    public string Title { get; set; }

    /// <summary>
    /// Severity of the alert. Stored as a string since different providers use different severity names
    /// </summary>
    public string Severity { get; set; }

    /// <summary>
    /// A more descriptive message about the alert
    /// </summary>
    public string Message { get; set; }

    /// <summary>
    /// Alerts can include additional custom properties
    /// </summary>
    public Dictionary<string, string> OptionalTwinInstanceProperties { get; set; } = new Dictionary<string, string>();
}

Note

Severity is expressed as a string because each provider uses different conventions. Make sure you refer to the provider’s specification for severity strings. For example, Splunk On-Call supports any strings but will not trigger an incident if the severity is not at least set to “CRITICAL”.

Example:

The following C# example shows a simple real-time digital twin model that records temperatures samples received in messages and sends an alert if at least 2 samples are over 100.

class TestAlertingProcessor : MessageProcessor<TestAlertingModel, TestAlertingMessage>
  {
      private const string SplunkDefault = "Splunk (default)"; // The model.json file must have an entry with this name.

      public override ProcessingResult ProcessMessages(ProcessingContext context, TestAlertingModel digitalTwin, IEnumerable<TestAlertingMessage> newMessages)
      {
          foreach (var message in newMessages)
          {
              digitalTwin.RecordedTemperatures.Add(message.Temp);
          }

          if (digitalTwin.RecordedTemperatures.Where(t => t > 100).Count() > 2)
          {
              AlertMessage alertMessage = new AlertMessage();
              alertMessage.Message = "Multiple high temperature readings observed";
              alertMessage.Severity = "CRITICAL";
              alertMessage.Title = "High temperature alert";
              alertMessage.OptionalTwinInstanceProperties = new Dictionary<string, string>();

              context.SendAlert(SplunkDefault, alertMessage);
          }

          return ProcessingResult.DoUpdate;
      }
  }

Rules Engine Models

In a rules engine model, you can trigger an alert by calling one of two built-in functions:

SEND_ALERT(providerName, severity, title, message)
SEND_ALERT_WITH_DATA(providerName, severity, title, message, dataCollection)

See SEND_ALERT and SEND_ALERT_WITH_DATA for more details.

Both of these functions take the following parameters:

• providerName (String): The name of the alert provider definition (must match an alert provider defined in the JSON definition file)

• severity (String): The severity of the alert

• title (String): The title of the alert

• message (String): The description of the alert

The only difference between the two functions is that SEND_ALERT_WITH_DATA also allows the caller to provide a data collection name, so that the alert also includes a snapshot of instance properties defined in the data collection.

Example:

IF Condition THEN SEND_ALERT("Slack1", "CRITICAL", "Condition was triggered", "Here are some details")