# Synchronization job states

## Synchronization job states

A synchronization job state tells you where a background synchronization run is in its lifecycle.
The lifecycle uses five states: Pending, Running, Completed, Failed, and Cancelled. A job can
start in Pending, move into Running, and finish in Completed or Failed. Cancelling a pending job
moves it to Cancelled.

| If you need to… | Go to |
|---|---|
| Prepare the project context before checking a run | [Before you start](#before-you-start) |
| Reach the project's job history | [Find a synchronization job](#find-a-synchronization-job) |
| Interpret the information on a job row | [Read the job history](#read-the-job-history) |
| Use a state-dependent control | [Act on an available job state](#act-on-an-available-job-state) |
| Compare active, completed, failed, cancelled, and empty outcomes | [Handle different job outcomes](#handle-different-job-outcomes) |
| Resolve a load or completion problem | [When a job does not load or finish](#when-a-job-does-not-load-or-finish) |
| Continue after the current state | [Know what comes next](#know-what-comes-next) |
| Read the wider status reference | Documentation job status reference |
| Follow the generation flow | Documentation generation lifecycle |
| Review the broader operations area | Operations overview |

## Before you start

The job history is the list of runs belonging to a project, so you need the project context before
you inspect a run.
The page uses the project context, and the controls available for a job depend on that job's
current state.

**Prerequisites**

- Know which project contains the synchronization job.
- Open the project job route with the project's identifier.
- For an active job, expect the progress area and a cancellation control only when cancellation
  is available for that job.

With the project identified, find its job history.

## Find a synchronization job

Use the project's job history to reach saved runs and refresh the list before inspecting a run.

**Prerequisites**

- Know the project whose jobs you need to inspect.

**Steps**

1. Open the project's jobs page.
2. Select **Refresh**, then wait for the job list to reload.

**Result:** The project's **Activity & Jobs** page shows the most recent job information returned for
that project.

Use this list to read the job history.

## Read the job history

A job row summarizes the run's current state, timing, progress, document count, stage, and any
error information so you can decide what to do next.

**Prerequisites**

- Open the project's job history.

**Steps**

1. Read the status badge to identify whether the job is **Pending**, **Running**, **Completed**,
   **Failed**, or **Cancelled**.
2. Read the created time, duration, document count, progress, current stage, and error information
   shown for the row.
3. Select a completed or failed job row to open its details.

**Result:** You can identify the job's lifecycle state and read the progress or outcome details
available for that state.

| Information | What it tells you | When it appears |
|---|---|---|
| **Pending**, **Running**, **Completed**, **Failed**, or **Cancelled** | The job's lifecycle state | On the job status badge |
| Created time | When the run was created | On every job row |
| Duration | How long the run took | When the recorded duration is greater than zero |
| Documents | The number of created and updated documents | When the total is greater than zero |
| Progress | The run's percentage and progress bar | While the job is **Running** or **Pending** |
| Current stage | The stage currently being processed | While the job is active |
| Error | The recorded error text | On a failed job when an error is present |

Select a completed or failed job row to expand it. A completed job opens its completion summary.
A failed job opens **Job Failed**, followed by the error stage and error text when those values are
present.

When you know the job's state, choose the control for that state.

## Act on an available job state

State-dependent controls let you refresh the list, request cancellation for an active job, or
remove documents associated with a finished job.

**Prerequisites**

- Open a project's job history.
- Use an active job when **Cancel** is available.

**Steps**

1. Select the action that matches the job's state:

   | If you need to… | Select… |
   |---|---|
   | Refresh the job list | **Refresh** |
   | Cancel an active job | **Cancel**, then **Are you sure?** |
   | Delete a finished job with no created documents | **Delete Job**, then **Confirm Delete?** |
   | Delete a finished job with created documents | **Delete <n> Docs**, then **Confirm Delete?** |

   While cancellation is in progress, the control reads **Cancelling...**.

**Result:** The selected state-dependent request is issued from the job row, subject to the job's
lifecycle state and available action.

After the action, handle the outcome shown for the job.

## Handle different job outcomes

The job outcome determines which information you can open and which action belongs next.

**Prerequisites**

- Have the project's job history open.

**Steps**

1. Use the job's status to choose one path:

   | If the job is… | Read or select… |
   |---|---|
   | **Pending** | Read its basic progress information while it waits to start. |
   | **Running** | Read its current stage and progress while it is active. |
   | **Completed** | Open the row to read its completion summary. |
   | **Failed** | Open the row to read **Job Failed**, the error stage, and the error text. |
   | **Cancelled** | Read the final cancelled status. |
   | Empty | Select **Configure & run documentation generation →** to reach the configuration route. |
   | Unavailable | Read the load message and follow the recovery direction in [When a job does not load or finish](#when-a-job-does-not-load-or-finish). |

**Result:** You use the information and controls that belong to the job's current outcome.

If the page shows a load, failure, empty, or stalled message, use the matching response below.

## When a job does not load or finish

Use the message on screen to identify whether the page is loading, empty, unavailable, failed, or
stalled.

**Prerequisites**

- Have the project job history open.

**Steps**

1. Read the message in the first column, then follow the matching instruction in the **What to do** column.

| What you see | What it means | What to do |
|---|---|---|
| `Loading runs…` | The job list is loading. | Wait for the list to finish loading. |
| `No generation runs yet` | No generation runs are listed for the project. | Select **Configure & run documentation generation →**. |
| `Every documentation generation run for this project lands here.` | The empty state explains where future runs appear. | Start from the configuration route. |
| `Jobs failed to load.` followed by the error message | The page has no job list to show because loading failed. | Refresh the page or use **Refresh** when it is available. |
| `Job Failed` followed by the error stage and error when present | The selected job finished with a failure. | Read the error stage and error text shown below the message. |
| `Stalled runs are automatically reconciled to “Failed” once their progress goes quiet past the inactivity threshold, so a run can never sit “in progress” indefinitely.` | A stalled run is reconciled to **Failed**. | Treat the run as failed and read its failure details. |

**Result:** You have a response for the message shown on the job history page.

Once the message is resolved, continue from the job's current state.

## Know what comes next

The next action depends on the state the job reaches: continue monitoring an active run, inspect a
completion summary after **Completed**, or read the failure details after **Failed**.

| Current state or event | Next place to continue |
|---|---|
| **Pending** | Continue monitoring until the job starts, completes, fails, or is cancelled. |
| **Running** | Continue monitoring its stage and progress. |
| **Completed** | Open the completion summary or review the [Documentation job status reference](doc:documentation-job-status-reference). |
| **Failed** | Read the failure details, then follow the [Documentation generation lifecycle](doc:documentation-generation-lifecycle). |
| **Cancelled** | Review the job history for the next run. |
| Operational aggregate needed | Open [Operations overview](doc:operations-overview). |