> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Reprocessing an Activity
> Run part of an Activity again: retry the failures to resume after an error, or reprocess from a chosen step to deliberately redo completed work.
An Activity can be run again in part. There are two operations, and the difference between them is how much already-completed work is redone:
* **Retry failures** resumes an Activity that stopped on an error. It is the safe option: successful work at the failed step is kept.
* **Reprocess from step** deliberately re-runs a step you choose, including work that had already completed there, and rewinds what the steps after it produced.
Both are exposed on `POST /api/activities/{id}/retry` and both require the `activity:retry` permission on the Activity.
## Choosing Between Them
| | Retry failures | Reprocess from step |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| How you invoke it | `POST /api/activities/{id}/retry` with no body | `POST /api/activities/{id}/retry` with `{"stepId": "..."}`, or **Reprocess** on a step in the Activity view |
| Which steps are reset | Every `FAILED` and `CANCELLED` step | The step you selected |
| Downstream steps | Reset and re-run, even where they had completed | Reset and re-run, even where they had completed |
| Completed per-document work at that step | Kept | Re-run |
| Content produced downstream | Rolled back | Rolled back |
| Downstream review tasks | Deleted and recreated | Deleted and recreated |
| Use it when | The Activity failed, the underlying problem is fixed, and you want to pick up where it stopped | The step's logic, module, prompt, or configuration changed and its earlier output is no longer the answer you want |
Reprocess from step is destructive by design. Content produced after the selected step is deleted, and review tasks downstream of it are deleted along with the work recorded on them. Reach for **Retry failures** when the goal is only to resume after an error.
## Retry Failures
Sending `POST /api/activities/{id}/retry` with no body resets every step in `FAILED` or `CANCELLED` state, plus everything transitively downstream of those steps.
* **Cancelled steps are included.** When an Activity deadlocks on a failure, its still-pending steps are cancelled; a retry has to revive those too, or the plan cannot finish.
* **The failed step keeps its successful documents.** On a per-document step, only the `FAILED`, `CANCELLED`, and in-flight document rows are reset. Documents that already completed there are left alone, so a retry does not redo work that succeeded.
* **Downstream work re-runs regardless.** Anything after a reset step is re-run even where it had completed, because its input may now be different.
* **The Activity resumes immediately.** It returns to `RUNNING`, its completion time and error details are cleared, its version is bumped, and the plan is advanced in the same transaction. The response reports the Activity's real state afterwards, which can already be terminal again if a reset step fails on its first attempt.
* **A retry with nothing to revive is a no-op.** If no step is `FAILED` or `CANCELLED`, the Activity is left exactly as it is — a completed Activity is never restarted, and its completion is never re-announced.
## Reprocess From Step
Select a step in the Activity view and choose **Reprocess**, or send the step's ID as `{"stepId": "..."}`. The option applies to a step in `COMPLETED`, `FAILED`, or `CANCELLED` state.
Targeting a step explicitly means "run this again", so the contract is stronger than a retry:
1. **The selected step re-runs in full.** Its own per-document rows are reset even where they had `COMPLETED`, so the step actually executes instead of settling straight back to completed.
2. **Every step downstream re-runs**, transitively, following the plan's dependency graph.
3. **Downstream content is rolled back.** For each document in scope, Kodexa finds the content the rewound work started from and deletes every version derived from it, so the re-run reads the same input the first run did instead of consuming its own earlier output. The starting version itself is kept.
4. **Downstream review tasks are recreated.** A `CREATE_TASK` step after the selected step has its task deleted, and creates a fresh one when it runs again.
5. **Superseded runs are marked, not erased.** Executions the reprocess replaced are recorded with status `REPROCESSED`, so the history stays readable, and the workspace stops following them instead of waiting for results that will never arrive.
```mermaid theme={null}
flowchart LR
Extract["EXECUTION: extract
untouched"] --> Score["SCRIPT: score
re-runs (selected)"]
Score --> Review["CREATE_TASK: review
task recreated"]
Review --> Post["BRIDGE_CALL: post
re-runs"]
```
Reprocessing from `score` re-runs `score`, rolls back what `review` and `post` produced, deletes and recreates the review task, and leaves `extract` and its output untouched.
### Documents That Are Not Rolled Back
The rollback is attributed per document, so it only touches documents the rewound steps actually ran over:
* A document that none of the rewound runs processed keeps all of its content. Kodexa would rather leave such a document alone than rewind it to its original upload.
* A document that a routing step sent down a different branch is not revived by reprocessing. Routing owns that decision, and it is re-evaluated when the step runs again.
### Routing on the Re-Run
A routing step can reach a different decision on the re-run — for example when its condition reads document status or metadata that has since changed. Kodexa keeps the document rows honest in both directions:
* A document that is now routed away is flipped to `NOT_TAKEN`, and its execution reference, error details, completed action, and content references are cleared. A not-taken document therefore shows no stale run, and its superseded output cannot be mistaken for a current result or used as the source of a later rollback.
* A document that is eligible again — where the previous run had recorded `NOT_TAKEN` — is returned to `PENDING` with those same references cleared, so it is picked up by the launch path and starts from a clean state.
## After Reprocessing
* Check the step's logs and result on the re-run rather than the values you saw before it; the earlier execution is now marked `REPROCESSED`.
* A recreated review task is a new Task. Anything a reviewer had entered on the deleted one is gone, so tell reviewers before reprocessing a step whose downstream work is already in a queue.
* If the Activity fails again at the same step, the cause is usually upstream of it: fix the input or the step configuration, then retry the failures rather than reprocessing further back.
Step types, dependencies, routing, and per-document plans.
How review tasks are created, and which documents they carry.