> For the complete documentation index, see [llms.txt](https://releaseowl.gitbook.io/releaseowl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://releaseowl.gitbook.io/releaseowl-docs/releaseowl-user-guide/working-with-release-pipelines/use-cases/abortion-and-promotion-via-external-tools.md).

# Abortion and Promotion via External Tools

This section explains how to perform **User Story Abortion** and **User Story Promotion** in ReleaseOwl using external tools such as **Postman or Jira**. These API-based operations enable external systems like **Jira** or other CI/CD tools to trigger user story lifecycle events in ReleaseOwl automatically.

#### Prerequisites

Before triggering user story abortion or promotion from external systems, ensure the following:

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

<figure><img src="/files/O3FuhDmfBSZCqckiCAkI" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/4F2075jbbhPNmiZ0bVrf" alt=""><figcaption></figcaption></figure>

3. The **user story** is attached to a **valid release pipeline** within ReleaseOwl.

<figure><img src="/files/1wDI6KFmyIsN0wpMtGhf" alt=""><figcaption></figcaption></figure>

#### User Story Abortion&#x20;

The **User Story Abortion** event is used to abort a specific user story from an external system. This can be triggered through a webhook or API request.

#### Triggering the Message from an External Tool <a href="#triggering-the-message-from-an-external-tool-e.g.-postman" id="triggering-the-message-from-an-external-tool-e.g.-postman"></a>

The User Story Abortion 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 included in the request body is what ReleaseOwl reads and processes to perform the corresponding user story action.

<figure><img src="/files/LH7mv9G9stmRXJxwCot9" alt=""><figcaption></figcaption></figure>

**Request Body (JSON format)**

```
  {
  userStoryId: <external-user-story-id>,
  eventName: usAbort,
  initiatedBy: <user-email-id>,
  abortMsg: Aborted due to failed validation or manual interruption 
  }
    
```

**Key Fields**

* `userStoryId`: Identifier of the linked user story.
* `eventName`: Must be `"usAbort"`.
* `initiatedBy`: Email of the user performing the abortion.
* `abortMsg`:  Reason for abortion.

**System Action:**\
The user story pipeline stops execution, and the status updates to *Aborted* in ReleaseOwl.

<figure><img src="/files/ONtoWU9ZkQrGmgBKB8Hh" alt=""><figcaption></figcaption></figure>

### User Story Promotion

The **User Story Promotion** event is used to promote a user story to the next stage in the pipeline through an external system. This ensures automation continuity between ALM tools and ReleaseOwl pipelines.

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

User Story Promotion can also be triggered from tools such as **ALM Rules**, **ALM Webhooks**, or **Postman**.

**Step 1: Set the Request Type to POST**

In Postman, click the dropdown beside the request URL and select **POST**. This allows the system to send the promotion request to ReleaseOwl.

**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**

```json
{
  "userStoryId": "<external-user-story-id>",
  "eventName": "usPromotion",
  "initiatedBy": "<user-email-id>"
}
```

**Field Descriptions:**

* **userStoryId** → External user story identifier (e.g., from Jira).
* **eventName** → Must be `"usPromotion"` to trigger the promotion event.
* **initiatedBy** → Email ID of the user initiating the promotion.

<figure><img src="/files/z74Tr9nDzCQUOZhTtzWe" alt=""><figcaption></figcaption></figure>

**System Action:**\
The user story pipeline advances to the next stage as defined in the release pipeline, and the user story status is updated accordingly in ReleaseOwl.

<figure><img src="/files/setTWJxsDmEt5vnRNyzO" alt=""><figcaption></figcaption></figure>