# Triggered Workflows

Triggered workflow tasks are the core execution unit of Veza Lifecycle Management. Each task represents a single workflow execution for an identity, created when a policy's source of identity detects a change (new hire, attribute change, termination, etc.).

These APIs correspond to the **Triggered Workflows** tab on the [Activity Log](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/getting-started/activity-log.md) page in the Veza UI.

**Triggered Workflow APIs** help you:

* Monitor real-time and historical workflow execution across all policies
* Investigate errored or blocked tasks with full state and message details
* Unblock tasks that are held by safety limit thresholds
* Restart previously failed tasks for reprocessing
* Export workflow task data for compliance reporting and auditing

## Endpoints

| Method | Endpoint                                                        | Description                                           |
| ------ | --------------------------------------------------------------- | ----------------------------------------------------- |
| GET    | [List Workflow Tasks](#list-workflow-tasks)                     | Retrieve a paginated list of triggered workflow tasks |
| GET    | [Get Workflow Task](#get-workflow-task)                         | Retrieve a single workflow task by ID                 |
| GET    | [List Workflow Tasks by Policy](#list-workflow-tasks-by-policy) | List workflow tasks scoped to a specific policy       |
| POST   | [Export Workflow Tasks](#export-workflow-tasks)                 | Export workflow tasks to a downloadable file          |
| POST   | [Unblock Workflow Tasks](#unblock-workflow-tasks)               | Run or abandon blocked workflow tasks                 |
| POST   | [Restart Workflow Task](#restart-workflow-task)                 | Restart a previously errored or completed task        |

## Key Concepts

### Task States

Each workflow task progresses through the following states:

| State       | Description                                 |
| ----------- | ------------------------------------------- |
| `INITIAL`   | Task created but not yet started            |
| `RUNNING`   | Task is currently executing actions         |
| `COMPLETED` | Task completed successfully                 |
| `ERRORED`   | Task failed (check `messages` for details)  |
| `SKIPPED`   | Task was skipped (conditions not met)       |
| `SCHEDULED` | Task is scheduled for future execution      |
| `PENDING`   | Task is waiting for a prerequisite          |
| `BLOCKED`   | Task is blocked by a safety limit threshold |
| `ABANDONED` | Task was manually abandoned                 |

### Identity Status (Trigger Reason)

The `identity_status` field indicates what change triggered the workflow:

| Value              | Description                                        |
| ------------------ | -------------------------------------------------- |
| `NONE`             | No specific identity change (e.g., manual trigger) |
| `NEW`              | New identity discovered in the source of identity  |
| `DELETED`          | Identity removed from the source of identity       |
| `CHANGED`          | One or more identity attributes changed            |
| `UNCHANGED_RESYNC` | Identity unchanged but re-synced                   |

### Priority Levels

| Value      | Description                               |
| ---------- | ----------------------------------------- |
| `UNSET`    | Default behavior                          |
| `LOW`      | Processed after all higher-priority tasks |
| `NORMAL`   | Standard priority                         |
| `MEDIUM`   | Elevated priority                         |
| `HIGH`     | Processed before normal and low           |
| `CRITICAL` | Processed immediately                     |

## List Workflow Tasks

### Endpoint

```sh
GET /api/private/lifecycle_management/workflow_tasks
```

### Description

Retrieve a paginated list of triggered workflow tasks across all policies. Supports SCIM-style filtering, ordering, and pagination.

### Filterable Fields

| Field                          | Operators              | Description                              |
| ------------------------------ | ---------------------- | ---------------------------------------- |
| `id`                           | eq                     | Workflow task ID                         |
| `policy_id`                    | eq                     | Policy that owns the task                |
| `state`                        | eq                     | Current execution state                  |
| `workflow`                     | eq, ne, co             | Workflow name (case-insensitive)         |
| `identity_id`                  | eq, co, sw, ew         | Identity ID                              |
| `identity_name`                | eq, co, sw, ew         | Identity display name (case-insensitive) |
| `identity_status`              | eq, ne                 | Change type that triggered the task      |
| `priority`                     | eq, ne, gt, ge, lt, le | Execution priority                       |
| `started_at`                   | gt, lt, ge, le         | Task start time                          |
| `completed_at`                 | gt, lt, ge, le         | Task completion time                     |
| `manually_triggered`           | eq                     | Whether task was manually triggered      |
| `dry_run`                      | eq                     | Whether task was a dry run               |
| `runtime_change_limit_reached` | eq                     | Whether blocked by safety limit          |

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/workflow\_tasks" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X GET "https://your-tenant.vezacloud.com/api/private/lifecycle_management/workflow_tasks?filter=state%20eq%20%22ERRORED%22&page_size=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Get Workflow Task

### Endpoint

```sh
GET /api/private/lifecycle_management/workflow_tasks/{id}
```

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/workflow\_tasks/{id}" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X GET "https://your-tenant.vezacloud.com/api/private/lifecycle_management/workflow_tasks/abc-123-def" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## List Workflow Tasks by Policy

### Endpoint

```sh
GET /api/private/lifecycle_management/policies/{policy_id}/workflow_tasks
```

### Description

Same parameters and response shape as the global List Workflow Tasks endpoint, but automatically scoped to the given `policy_id`.

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/policies/{policy\_id}/workflow\_tasks" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

## Export Workflow Tasks

### Endpoint

```sh
POST /api/private/lifecycle_management/workflow_tasks:export
```

### Description

Export triggered workflow tasks matching a filter to a downloadable CSV file. The request body wraps the same filter and ordering parameters used by the List endpoint.

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/workflow\_tasks:export" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X POST "https://your-tenant.vezacloud.com/api/private/lifecycle_management/workflow_tasks:export" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "filter": "state eq \"ERRORED\"",
      "order_by": "completed_at desc"
    },
    "format": "CSV"
  }'
```

## Unblock Workflow Tasks

### Endpoint

```sh
POST /api/private/lifecycle_management/workflow_tasks:unblock
```

### Description

Unblock workflow tasks that are in `BLOCKED` state because a safety limit threshold was reached. You can target tasks by a specific `id` or by a SCIM `filter` expression. Choose whether to `RUN` (resume processing) or `ABANDON` (skip without executing) the blocked tasks.

{% hint style="warning" %}
**Requires admin or operator role.** Unblocking tasks that exceeded safety limits may result in large-scale changes. Review the blocked tasks carefully before proceeding.
{% endhint %}

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/workflow\_tasks:unblock" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X POST "https://your-tenant.vezacloud.com/api/private/lifecycle_management/workflow_tasks:unblock" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": "policy_id eq \"abc-123\"",
    "action": "RUN"
  }'
```

## Restart Workflow Task

### Endpoint

```sh
POST /api/private/lifecycle_management/workflow_tasks/{id}:restart
```

### Description

Restart a previously errored or completed workflow task. Creates a new task execution linked to the original. Requires admin role.

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/workflow\_tasks/{id}:restart" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X POST "https://your-tenant.vezacloud.com/api/private/lifecycle_management/workflow_tasks/abc-123-def:restart" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Authentication

All Triggered Workflow API requests require authentication. See [API Authentication](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md) for details.

## Related Documentation

* [Activity Log](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/getting-started/activity-log.md)
* [Policies and Workflows](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows.md)
* [Workflow Actions](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/workflowactions.md)
* [Integration Jobs](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/integrationjobs.md)
* [Events](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/events.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/triggeredworkflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.