How-Tos

Full flow for sending out e-mail notifications

In this example, we will go through all the required steps in order to send out a simple email notification to a MACMA user.

Create an Event Type

Event types can only be created by modules via the REST API. For this example we will be creating an event type by sending the following payload to /api/v1/event-typers

{
  "eventTypeName": "Machine Restarted",
  "eventTypeDescription": "A sample event type for notifications related to a machine restarting",
  "moduleId": "CLIENT_ID_HERE",
  "dynamicVariables": [
    {
      "variableName": "MachineName",
      "variableType": "String",
      "dynamicVariableUseCase": "FilteringAndNotificationContent",
      "SupportsValueChange": true
    },
    {
      "variableName": "Region",
      "variableType": "String",
      "dynamicVariableUseCase": "FilteringAndNotificationContent",
      "SupportsValueChange": true
    },
    {
      "variableName": "EventDate",
      "variableType": "DateTime",
      "dynamicVariableUseCase": "FilteringAndNotificationContent",
      "supportsValueChange": true
    },
    {
      "variableName": "MacmaGroupName",
      "variableType": "MacmaGroup",
      "dynamicVariableUseCase": "FilteringAndNotificationContent",
      "supportsValueChange": false
    },
    {
      "variableName": "MacmaUserName",
      "variableType": "MacmaUser",
      "dynamicVariableUseCase": "FilteringAndNotificationContent",
      "supportsValueChange": true
    },
    {
      "variableName": "Assignee",
      "variableType": "MacmaUser",
      "dynamicVariableUseCase": "FilteringAndNotificationContent",
      "SupportsValueChange": false
    },
    {
      "variableName": "DefaultLink",
      "variableType": "Link",
      "dynamicVariableUseCase": "NotificationContentOnly",
      "SupportsValueChange": false
    }
  ]
}

eventTypeName is the name of the event type that will be created.
eventTypeDescription is the description of the event type.
moduleId value needs to be the MACMA public client ID of the module that is calling this endpoint.
variableName is the name of the dynamic variable that will be available in the event type.
variableType is the data type of the dynamic variable. The following data types are available: String, DateTime, MacmaGroup, Device, DeviceType, MacmaUser, Link.
supportsValueChange when set to true, both variableValue and VariablePreviousValue must be provided in the event. If this variable is set to false, only variableValue needs to be provided.

This will create the Event Type Machine Restarted with the following variables:

MachineName (String)
Region (String)
EventDate (DateTime)
MacmaGroupName (MacmaGroup)
MacmaUserName (MacmaUser)
Assignee (MacmaUser)
DefaultLink (Link)

The API will return a HTTP 200 result containing the ID of the created Event Type.

Create Subscription

Now we will need to create a subscription which will determine what sort of notification will be sent out and what it contains. This can be done either via the UI and the REST API or the module can create a default subscription.

Example 1: Creating subscription from UI using REST API

The following POST request must be made to /api/v1/TENANT_ID_HERE/subscriptions:

{
  "notificationType": "Email",
  "subscriptionName": "Simple Email Notification",
  "subscriptionDescription": "string",
  "eventTypeId": "EVENT_TYPE_ID_HERE",
  "notificationSubject": "Machine Restarted!",
  "notificationContent": "The machine called {{MachineName}} has just restarted in region {{Region}}",
  "fromAddress": "user@example.com",
  "filters": {
    "operator": "And",
    "operands": [
        {
            "operator": "Equal"
            "variable": "Region",
            "value": "WEST-GERMANY"
        }
    ]
  },
  "macmaRecipients": [
    // MACMA IDs here for the recipients
  ]
}

EVENT_TYPE_ID_HERE must be replaced with the ID of the event type that was created in Step 1.

In this example, we create a subscription that will send out an email ONLY if the Region variable value is equal to WEST-GERMANY. This is important to keep in mind later when we send the event.

Example 2: Creating default subscription by module using REST API ( `EXPERIMENTAL` )

The following POST request must be made to /api/v1/TENANT_ID_HERE/default-subscriptions:

{
  "id": "ID_HERE",
  "title": {
    "en":"title of the default susb- en",
    "de":"title of the default susb- de"
  },
  "description": {
    "en": "description of the default susb- en",
    "de": "description of the default susb- de"
  },
  "eventTypeId": "EVENT_TYPE_ID_HERE",
  "alwaysOn": true,
  "defaultNotificationMethod": [
    "Email",
    "Push"
  ],
  "recipientRules": [
    {
      "variableName": "AssignedFrom",
      "valueToUse": "Current"
    },
    {
        "variableName": "AssignedFrom",
        "valueToUse": "Previous"
    }
  ],
  "filters": [
    {
      "operator": "And",
      "operands": [
        {
          "operator": "Equals",
          "variable": "machine name",
          "value": "GeneratorMachine01"
        },
        {
          "operator": "Equals",
          "variable": "machine name",
          "value": "GeneratorMachine02"
        }
      ]
    }
  ],
  "templates": [
    {
      "type": "Markdown",
      "description": {
        "en": "description of the email notification- en",
        "de": "description of the email notification- de"
      },
      "subject": {
        "en": "description of the email notification subject- en",
        "de": "description of the email notification subject- de"
      }
    },
    {
      "type": "Text",
      "description": {
        "en": "description of the push notification- en",
        "de": "description of the push notification- de"
      },
      "subject": {
        "en": "description of the push notification subject- en",
        "de": "description of the push notification subject- de"
      }
    }
  ],
  "moduleId": "MODULEID_HERE"
}

ID_HERE should be alphanumberic string of maximum length 36 characters. The inclusion of a hyphen in the string is optional.
title and description are the title and description of the default subscription in different languages in string. The language key must be a valid ISO 639-1 two letter language code (e.g, "en", "de").
EVENT_TYPE_ID_HERE must be replaced with the ID of the event type that was created in Step 1.
alwaysOn is a boolean value that determines if the subscription should be always on or not. Default value is set to false.
defaultNotificationMethod is an array of configured notification methods for the subscription. The possible values are "Email", "Push", "Printer".
recipientRules is an array to determine recipients for the subscription.
recipientRules is an array to determine recipients for the default subscription.Only users who are already subscribed to push notifications will receive notifications based on these rules. Users who are not subscribed will not receive push notifications.
filters is an array of filters to determine when the subscription should be triggered.
templates is an array of templates for the subscription. Use Markdown for long, formatted templates (email/printer) and Text for short, unformatted templates (push notifications). Template types match defaultNotificationMethod values.
templates is an array of templates for the subscription. The allowed characters for these templates are alphabetic (a-z, A-Z), numeric (0-9), and special characters (# * _ | ~ > < + - . () [] ` ! \ , @ : ? & % /).
templates is an array of templates for the default subscription. This is mandatory field to provide by module and it should not be empty. Available templates will be considered for precessing notification if relavent type is not available (ie. 'Markdown' template will be used for 'Email' notifications and 'Text' template will be used for 'Push' notificatoins. And for example email notifications 'Markdown' template is not available then other available template will be used for 'Email' notification).
MODULEID_HERE is the MACMA public client ID of the module that is calling this endpoint.

Send an Event

The final piece of the puzzle is to send an Event payload by making the following POST request to /api/v1/TENANT_ID_HERE/events:

{
  "eventTypeId": "EVENTTYPE_ID",
  "externalId": "RANDOM_GUID_VALUE",
  "dynamicVariables": [
    {
      "variableName": "MachineName",
      "variableValue": "GeneratorMachine01",
      "VariablePreviousValue": "previous Value",
    },
    {
      "variableName": "Region",
      "variableValue": "WEST-GERMANY",
      "VariablePreviousValue": "previous Value",
    },
    {
      "variableName": "Assignee",
      "variableValue": "ASSIGNEE_MACMA_USERID"
    },
    {
      "variableName": "DefaultLink",
      "variableValue": "LINK_PROVIDED_BY_EVENT"
    }
  ]
}

eventTypeId must be replaced with the ID of the event type that was created in Step 1.
variableName should be a dynamic variable of the event type exposed by module
variableValue should be the value of the dynamic variable and should satisfy the validations of the variableName datatype.

Validations
* If the variableName does not match the variableValue (e.g., Region != WEST-GERMANY), the created subscription will not be triggered, and no email will be sent. * If the Assignee variable is of type MacmaUser, the variableValue for Assignee must be a valid MacmaUser ID within the tenant where the event is sent (the tenant ID is part of the route in the Event API). * VariablePreviousValue will be required and it should be the previous value of the dynamic variable if supportsValueChange is true for the dynamic variable. Else it is not required and can be set to null. * Only one link can be accepted for each event type. If more than one link is added, an error message will be displayed stating that multiple link types are not allowed.

When this payload is sent, user with the particular userid will receive an email with the following:

Subject: Machine Restarted!
Content: The machine called GeneratorMachine01 has just restarted in region WEST-GERMANY