Categories: USER GUIDE NOTIFICATIONS ENTERPRISE

Notifications

If you’ve purchased the Notification package or are running the Premium Enterprise version of step, you can subscribe to notifications about the status of test plan executions.

Currently, step supports two notification mechanisms: E-Mail, and Webhooks.

  • E-Mail: Notifications are delivered by sending E-Mails to specific mail addresses. This is a simple and proven procedure, but the format of these messages is fixed.
  • Webhooks: Notifications are delivered by performing HTTP requests to an external URL. In this case, the format of the data sent by the step server is well-defined, but an HTTP server is required on the receiving end, and the actual data processing is the responsibility of the remote server.

Configuring notifications is a two-step procedure: First, a notification gateway is defined which contains the generic configuration (e.g., Mail server, or Webhook endpoint). Second, individual notification triggers are configured, where notification-specific settings (e.g., mail recipient, or custom payloads for webhooks) are defined.

Define your notification gateways

To create a notification gateway, navigate to Admin > Settings > Notification gateways and click on the New button on the top right :

E-Mail notification gateway

Create a new notification gateway of type “E-Mail”, and fill the fields according to the settings you want to use :

  • Name : the name of your gateway
  • Type : the gateway type (E-Mail).
  • From Address : the mail address that is set as the mail sender
  • From Name : the display name of the mail sender
  • SMTP Server host : the SMTP server hostname
  • SMTP Server port : the SMTP server port
  • Username : the username to access the email account
  • Password : the password to access the email account

Example

The example below is using a Gmail account in order to setup a gateway :

Follow this link for more information about Google SMTP servers configuration.

Webhook notification gateway

Create a new notification gateway of type “Webhook”, and fill the fields according to the settings you want to use :

  • Name : the name of your gateway
  • Type : the gateway type (Webhook).
  • HTTP(S) Endpoint : the URL where notifications are sent to. HTTPS is strongly recommended, but not required.
  • Secret : any string. This is included in every message sent to the webhook endpoint, and can be used (in the webhook implementation) as a simple authentication factor to validate the authenticity of received messages.
  • Payload Description: a user-friendly description of the kind of payload that is sent to the webhook. This is displayed to step users when they define the notifications which are to be sent via this gateway. Attention: if this field is left empty, the notification payload will always be empty, and will not be user-configurable.

Examples

Use case: execution failed, no payload needed

Use case: execution succeeded, payload with plain-text message

Use case: execution succeeded, payload with list of mail addresses to inform

Setup your notification triggers

Once you have defined notification gateways, you can create notification triggers for the events you are interested in.

Create a test plan, execute it, open the last execution, and then click on the Add notification link on the bottom right :

Alternatively, you can add notifications directly via the Notification subscriptions view, where you can also manage existing notifications:

Fill in the fields according to the kind of notification you want to receive :

  • Event : currently, Execution ended and Execution failed events are supported.
  • Gateway : select a the gateway your previously defined
  • Additional fields:
    • For E-Mail gateways, there will be a field named Mail Recipient where you can enter mail addresses.
    • For Webhook gateways, if (and only if) a Payload description was defined, a corresponding field will be shown.

Examples

E-Mail notification

Webhook notifications

Note: these examples show configuration screens for webhook gateways defined like in the examples above. As mentioned, the concrete labels of the displayed fields depend on the gateway configuration!

Use case: execution failed, no payload needed

Use case: execution succeeded, payload with plain-text message

Use case: execution succeeded, payload with list of mail addresses to inform

Notification subscriptions view

All notification subscriptions are listed in the Notification subscriptions view, accessible from the top level menu:

From this view, existing subscriptions can be modified or deleted, and new subscriptions can be defined.

Keyword “Notification_Send”

A LocalFunction keyword, pre-populated by default in the enterprise edition of step, allows you to send personalized notifications using the gateways you have set up previously:

The expected inputs are:

  • gatewayId : the name of the gateway your previously defined
  • sendTo : the destination of the notification
  • subject: the subject of your message
  • message: the body of your message
  • sendExecutionLink (optional): test it to false to remove the execution link from the message body. By default this link is added at the end of the message

Webhook invocations and payloads

Notifications via Webhooks follow a simple and standardized JSON format, and are sent to the URL defined in the notification gateway setup. Please ensure that the target endpoints are directly reachable from the machine where the step controller is running.

Messages are sent using the HTTP POST method, with a Content-Type of application/json. It is expected that the receiving end of the implementation returns an HTTP 200 OK Status Code on success. If any HTTP status code other than HTTP 200 OK is received in response to sending a webhook notification, the status code, and, if provided, the message body, are logged by the controller as warnings.

If you want to test your side of the webhook implementation, you can simulate a request using a curl command like the following (replace values as needed):

curl -H "Content-Type: application/json" -X POST http://localhost:9999/test/post/ended -d '{"secret":"secret", "eventType":"execution_ended", "payload":"the payload", "controllerUrl":"http://step.host/", "executionId":"executionId", "executionDescription":"step plan name", "executionParameters":{"env":"TEST"}, "status":"PASSED"}'

“Execution ended” message

{
  "secret":"The secret you defined for the gateway",
  "eventType":"execution_ended",
  "payload":"The payload you defined for the notification",
  "controllerUrl":"The URL you defined for the controller in step.properties",
  "executionId":"The execution ID",
  "executionDescription":"The name of the plan that was run",
  "executionParameters":{"env":"TEST"},
  "status":"PASSED"
}

The eventType is ALWAYS execution_ended.

The exhaustive list of all (theoretically) possible status values is: TECHNICAL_ERROR, FAILED, PASSED, INTERRUPTED, SKIPPED, NORUN, RUNNING.

“Execution failed” message

This message is similar to the above one, except for the “status” field being omitted (as it would always be “FAILED”):

{
  "secret":"The secret you defined for the gateway",
  "eventType":"execution_failed",
  "payload":"The payload you defined for the notification",
  "controllerUrl":"The URL you defined for the controller in step.properties",
  "executionId":"The execution ID",
  "executionDescription":"The name of the plan that was run",
  "executionParameters":{"env":"TEST"}
}

The eventType is ALWAYS execution_failed.

See Also