Categories: USER GUIDE NOTIFICATIONS ENTERPRISE

Notifications (legacy)

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 single Plan executions or Scheduler tasks assertions.

Currently, Step supports two notification mechanisms: email and webhooks.

  • Email: Notifications are delivered by sending emails to specific email addresses. This is a simple and proven procedure, the message can be customized using html template.
  • Webhooks: Notifications are delivered by performing HTTP requests to an external URL. In this case, an HTTP server is required on the receiving end, and the actual data processing is the responsibility of the remote server. You can choose to have webhooks delivered in a standard format defined by Step (deprecated) or in a specified format according to your implementation.

Setting up notifications is a two-step procedure:

Define notification gateway

To create a notification gateway, navigate to Admin > Settings > Notification gateways and click the New button.

E-mail notification gateway

The following screenshot highlights how to create a new notification gateway of type “email”, and fill in the fields according to the settings you want to use:

  • Name : the name of your gateway
  • Type : the gateway type (Email)
  • From Address : the email address that is set as the email sender
  • From Name : the display name of the email 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

This example shows how to set up email notification gateway using a Gmail account. See more information about Google SMTP servers configuration.

Email content templating

You can optionally customize the subject and content of the email using the advanced templating feature which support HTML tags and placeholders to generate dynamically the content based on the executions results. See variable substitution for more details.

Webhook notification gateway - Custom format

If you require a more flexible webhook format, Step can be configured to send webhook messages using any textual format that you provide. In other words, “You define the rules, and Step adheres to them”. This setup requires more configuration.

To create a new notification gateway using a custom message format, fill the following fields according to the settings you want to use:

  • Name : the name of your gateway
  • Type : Webhook (Custom)
  • HTTP(S) Endpoint : the URL where notifications are sent to. HTTPS is strongly recommended, but not required.
  • HTTP Method : GET or POST.
  • HTTP Headers : An arbitrary number of HTTP headers to send in standard HTTP format.
  • Message Body: The raw HTTP message body to be sent to the remote server.

Variable substitution for Email and custom webhook

The endpoint, headers, and body will be used exactly as defined by you in the gateway configuration screen. However, sending exactly the same message is generally not so useful as one will usually require at least some dynamic information. Therefore, the following substitutions will be performed before sending the message:

  • Common to all event types:
    • ${executionId}: The identifier of the execution that has triggered the notification, in hexadecimal format (e.g. 63dbcb222e9efd3a01b09c4f).
    • ${status}: The status of the execution, for instance PASSED or FAILED.
    • ${eventType}: one of execution_ended or execution_failed. This is determined by the subscription which triggered the notification.
    • ${tenant}: The name of the project in which the execution took place.
    • ${executionDescription}: The name of the plan that was executed.
    • ${executionUrl}: The complete URL of the execution, suitable for opening in a web browser.
    • ${controllerUrl}: The base URL of the controller where the execution took place.
    • ${executionParameters}: A JSON representation of all parameters of the execution.
    • ${executionParameters[XY]}: The value of the execution parameter XY, if and only if such a parameter is present. For example, if the execution contains a parameter named env with value TEST, then ${executionParameters[env]} will be replaced by TEST. However, if no such parameter is present, the string ${executionParameters[env]} remains unchanged..
  • Failed event types:
    • ${errorSummary}: A string representing the errors causing the plan execution or task assertion to fail.
    • ${errorCodes}: The error code causing the plan execution or task assertion to fail.
  • Failed event for task assertion
    • ${taskId}: The id of the related scheduled task
    • ${taskName}: The name of the related scheduled task
    • ${assertionPlanStatus}: the status of the assertion plan execution
    • ${assertionPlanExecutionUrl}: the complete URL of the assertion plan execution triggering this event

Notes:

  • Variable substitution is performed in the message body as well as the headers and the endpoint URL. In the next screenshot, the result of the substitution is URL-encoded.
  • Only a textual substitution is performed, there is no full-blown expression evaluation. In other words, substitution will only be performed on the exact strings as shown above. For example, the string ${ status } with added spaces will not result in a substitution.

Example

The definition for a custom webhook and the resulting payload, when sent with the actual values, will depend on the environment. See the following example screenshot and payload:

{
	"step_server": "http://localhost:8080",
	"project" : "Common",
	"plan" : "Test Plan",
	"parameters": {"xray_reporting":"true","env":"TEST"},
	"id" : "63dd054ec9615c57fdbe64a9",
	"status" : "PASSED"
}

Configure notification triggers

Notification subscriptions view

All notification subscriptions are listed in the Notifications view, accessible from the Alerting section. From this view, existing subscriptions can be modified or deleted, and new subscriptions can be defined.

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

  • Plan : the plan for which the subscription is made
  • Event : currently, Plan: Execution ended, Plan: Execution failed and Scheduler: Assertion of task failed events are supported
  • Gateway : select a previously defined gateway
  • Additional fields:
    • For email gateways, there will be a field named Mail Recipient where you can enter one or multiple comma-separated email addresses.
    • For Step webhook gateways, if only a Payload description is defined, a corresponding field will be shown.

Examples

The following screenshots are examples of how to configure email notifications and webhooks from the notifications view. As mentioned, the concrete labels of the displayed fields depend on the gateway configuration.

E-Mail notification

Webhook, Step format, payload with plain-text message

Webhook, custom format

Keyword “Notification_Send”

Notification_Send is a local function Keyword pre-populated by default in the enterprise edition of Step, that lets you send personalized notifications withing a plan using the gateways you have set up:

 

The expected inputs are:

  • gatewayId : name of the gateway your previously defined
  • sendTo : destination of the notification
  • subject: subject of your message
  • message: body of your message
  • sendExecutionLink: An optional boolean input for sending execution link. By default, the link is added at the end of the message. Set it to false to remove the execution link from the message body.

Webhook Step message format (deprecated)

Webhook notification gateway in Step message format

For this notification mechanism to work, the receiving endpoint must be able to handle messages in the specific JSON format that Step uses. In other words, “Step defines the rules, and you adhere to them”.

To create a new notification gateway using Step message format, fill in the fields according to the settings you want to use:

  • Name : the name of your gateway
  • Type : Webhook (Step format)
  • HTTP(S) Endpoint : the URL where notifications are sent. 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 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 that 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: endpoint for “execution failed” events, no payload

Use case: endpoint for “execution ended” events, payload is an informational message

Use case: endpoint for “execution ended” events, payload is a list of mail addresses to inform

Webhook endpoint implementation

This section only applies to webhooks in Step format and provides the information required for implementing a compatible endpoint. Notifications via webhooks follow a simple and standardized JSON format and are sent to the URL defined in the notification gateway setup.

Note: 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 the message body (if provided), 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 list of all possible status values is as follows: TECHNICAL_ERROR, FAILED, PASSED, INTERRUPTED, SKIPPED, NORUN, RUNNING.

“Execution failed” message

This message is similar to the “Execution ended” message, 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