---
url: /en/build/internal-steps/tapd/status-update.md
---
`tapd:status-update`

\==Update the status of TAPD-associated items (story, task, or bug)==

When submitting code, you can add TAPD source code keywords in the **commit message** or **PR description**.
The cloud-native build system will automatically recognize and associate commits, PRs, and TAPD work items.

In pipelines triggered by code pushes, PRs, and tags,
you can update the information of TAPD-associated items through this task.

**Prerequisites**

* The TAPD feature must be enabled in the root organization.
* The pipeline triggerer must have a bound TAPD account.

**TAPD Association Item Filtering Rules**

The pipeline will filter associated TAPD work items based on the following rules:

**1. When the `fromFile` or `fromText` parameters are provided:**

Parse the commit IDs from the provided text file or text, and query the associated TAPD work items.

The `fromFile` parameter takes precedence over `fromText`.

**2. When neither the `fromFile` nor `fromText` parameters are provided:**

* **PR-related events:**

  Query the TAPD work items associated with the commits and PR description of the PR.

* **`commit.add` event:**

  Query the TAPD work items associated with the newly added commits.

* **`push` event for non-new branches:**

  Retrieve the associated TAPD work items from the commit logs of all commits in this push.

* **Other cases:**

  Query the TAPD work items associated with the latest commit.

**TAPD Association Item Types**

The type in the TAPD work item `source code keyword` is the work item type, such as: story, task, bug.

> Note: The source code keyword for TAPD tasks may be either story or task. Please distinguish carefully.

* [Applicable Events](#tapd-status-update-applicable-events)
* [Parameters](#tapd-status-update-parameters)
* [Configuration Examples](#tapd-status-update-configuration-examples)

## Applicable Events {#tapd-status-update-applicable-events}

[All Events](../../trigger-rule.md#trigger-event)

## Parameters {#tapd-status-update-parameters}

The list below gives an overview of all `tapd:status-update` parameters.

* [status](#tapd-status-update-parameters-status): Target status
* [when](#tapd-status-update-parameters-when): Update only items in a given status
* [type](#tapd-status-update-parameters-type): Update only items of a given type (story/task/bug)
* [fromText](#tapd-status-update-parameters-from-text): Parse commit ids from text to find linked items
* [fromFile](#tapd-status-update-parameters-from-file): Parse commit ids from a file to find linked items

Detailed descriptions for each parameter are provided below.

### status {#tapd-status-update-parameters-status}

* Type: `String`
* Required: `true`

Target status.

### when {#tapd-status-update-parameters-when}

* Type: `String` | `Array<String>`
* Required: `false`

Update work items with the specified status. No filtering is applied if left empty.

### type {#tapd-status-update-parameters-type}

* `Enum<String>`: story | task | bug
* Required: `false`

Update work items of the specified type. No filtering is applied if left empty.

### fromText {#tapd-status-update-parameters-from-text}

* Type: `String`
* Required: `false`

Parse commit IDs (up to 50) from the provided text and query their associated work items.

### fromFile {#tapd-status-update-parameters-from-file}

* Type: `String`
* Required: `false`

Parse commit IDs from the provided text file and query their associated work items.

## Configuration Examples {#tapd-status-update-configuration-examples}

1. Update the status of all TAPD-associated items:

```yaml title=".cnb.yml"  
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: developing
```

2. Update the status of TAPD-associated items that meet specific conditions:

```yaml title=".cnb.yml"  
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: Completed
            when:
              - developing
            type: story
```

3. Parse commit IDs from `fromText`, query TAPD-associated items, and update their status:

```yaml title=".cnb.yml"  
$:
  tag_push:
    - stages:
        - name: Generate changelog
          image: cnbcool/changelog
          settings:
            dryRun: true
            linkReferences: false
          exports:
            latestChangeLog: RELEASE_NOTES
        - name: tapd
          type: tapd:status-update
          options:
            status: published
            type: story
            fromText: $RELEASE_NOTES
```