Reprocessing an Activity

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

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.

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.