Message Listener

The Message Listener Task in ReleaseOwl is designed to pause a pipeline until it receives a specific message event from an external ALM (Application Lifecycle Management) system. Once the expected message is received, the pipeline resumes execution.

Prerequisites

Before using the Message Listener Task, make sure that:

  • An ALM integration is already configured and attached to the project.

  • The project has an external User Story ID from an ALM system (e.g., Jira, ServiceNow).

How to Add a Message Listener Task

  • Go to your Project View in ReleaseOwl.

  • Click on Release Pipelines.

  • Select Create New Release Pipeline (or edit an existing pipeline).

  • Add an Approval Task if required.

  • Add the Message Listener Task.

  • Click Save to save the pipeline.

Assign Variables

In ReleaseOwl, the Assign Variables feature allows you to capture dynamic data during pipeline execution and store it in named variables. These variables can later be reused in different stages, such as scheduling a deployment at a specific date and time. In the case of a Message Listener, values can be assigned to these variables by parsing the JSON payload received by the listener.

How to Use "Assign Variables" in ReleaseOwl

When you click Assign Variables in the Message Listener task configuration screen, a pop-up window appears. This feature allows you to define pipeline variables that will be dynamically populated with data received from the external message.

The Assign Variables screen contains a table with two columns:

  • Name : Specify the name of the pipeline variable you want to create. This is the variable that will hold the extracted data. (Note: Special characters and spaces are not allowed in the variable name.)

  • Value : Provide the mapping expression that extracts data from the incoming message. The syntax depends on the structure and format of the message.

Mapping Syntax

Use the following format to map variables to event message properties:

${resp.<message-object>.<property>}

Where:

  • resp → Represents the entire response message.

  • <message-object> → The key or object name inside the message (as defined in the Message Listener configuration).

  • <property> → The field within the <message-object> whose value you want to extract.

User Story Promotion

  • Promote the User Story directly in ReleaseOwl.

  • Open the Pipeline Activity view.

  • Locate the Message Listener task.

  • Click Send Message to open the message form and view the event payload details.

  • Click Save. Once the correct message is received, the pipeline proceeds to the next stage.

  • Optionally, click View Message to inspect the event details and confirm what was received.

Triggering the Message from an External Tool (e.g., Postman)

The Message Listener can be triggered from any external application, such as ALM Rules, ALM Webhooks, or even tools like Postman.

Step 1: Set the Request Type to POST

  • In the Postman interface, locate the dropdown menu to the left of the URL input field.

  • Click on it and select POST. This is a crucial step because you are sending data to the server to trigger an action, which is the standard use case for a POST request.

Step 2: Enter the API Endpoint URL

https://<domain>/webhook/tenant/{tenant}/project/{ProjectID}?secretkey=<secretkey>
  • <Domain> → This will be provided during the ReleaseOwl solution implementation.

  • {Tenant} → Replace with your tenant ID.

  • {ProjectID} → Replace with your project ID.

  • <Secret Key> → This will be provided during ReleaseOwl Solution implementation

Step 3: Configure the Request Body

This is the most critical part, as the data you send in the body is what ReleaseOwl's Message Listener will read and act upon.

Request Body (JSON format)

{
  "UserStoryId": "<external-user-story-id>",
  "EventName": "Pipelinemessage",
  "message": {
    "<messageName>": {
    }
  }
}

Field Descriptions

  • UserStoryId → This value links the external message to the specific User Story in ReleaseOwl that has an active pipeline running. The pipeline will only proceed if the userStoryId in the request body matches the one associated with the waiting pipeline activity.

  • EventName → A mandatory field that must have the value "Pipelinemessage". This is the non-negotiable field. The Message Listener task is specifically configured to wait for an event with this exact name. Sending any other value will cause the event to be ignored.

  • Message → An optional object to pass additional details.

    • MessageName→ Must match the message name configured in the Message Listener task (in the “Wait for Message” step).

Important Note

When you configure a Message Listener task in your pipeline, you specify a Message Name in the “Wait for Message” step.

  • In the JSON payload, replace <messageName> with the exact, case-sensitive name you configured in the task.

  • This value becomes the key inside the message object.

  • If the names do not match, the pipeline will continue waiting because the event will not be recognized.

Step 4: Send the Request and Verify

  • Once the URL and the JSON body are correctly configured, click the blue Send button in the top right corner of the Postman interface.

  • Postman will send the request, and you will see the response in the bottom panel.

  • Verification:

    • The expected response is a 200 OK status code, as shown in the image. This indicates that ReleaseOwl successfully received and processed the request.

  • You can then check the ReleaseOwl Pipeline Activity view for the corresponding User Story. The Message Listener task should have completed, and the pipeline should have moved on to the next step.

Last updated