Understanding Pipeline States

A Pipeline moves through a series of states from the moment you create it. The Pipeline is first set up, then begins replicating data, and may later be disabled, resynced, or deleted. Every action that you request moves it from one state to the next.

The state controls what you can do with a Pipeline, and reports the outcome of what you have already done:

• An action is accepted only from certain states, so the state tells you whether the Pipeline can accept the request you want to send.
• An action does not finish while Hevo is answering your request, so you read the state to find out whether the work completed.

Every Pipeline reports its current condition through the following three fields:

Read these fields together to find out whether a Pipeline is replicating data, whether it has failed, and whether an action that you requested has finished.

Refer to the following sections to understand the condition of a Pipeline:

• Pipeline States: Every state a Pipeline can be in.
• Pipeline Health: The condition of the Pipeline's runs.
• Checking a Pipeline after an Action: Find out when an action has finished.
• Actions Allowed in Each State: Understand which actions a state accepts.
• Pipeline Behavior when a Change is in Progress: Understand why a request is rejected while an earlier change is still being applied.

Pipeline States

A Pipeline is always in one of the following states, which are divided into five groups:

• Setup: The Pipeline is being created.
• Running: The Pipeline has been created, and is replicating data or disabled.
• Transitional: An action that you requested is in progress.
• Failed: An action did not succeed.
• Deleted: The Pipeline has been removed.

Setup

A Pipeline passes through these states while it is being created.

Running

A Pipeline remains in one of these states once it has been created.

Transitional

A Pipeline is in one of these states while an action that you requested is in progress.

Failed

A Pipeline reports one of these states when an action that you requested did not succeed. The API does not return these names. Every one of them is returned as the single value Failed, so the response does not say which action failed. Read the Pipeline’s recent jobs, or the Hevo UI, to find out. The names below are the internal ones.

You can resync a Pipeline from the Initialized state, and from the Failed state, unless the failure was a failed deletion. Read Actions Allowed in Each State for the actions that each state accepts.

Deleted

The API never returns Deleted. The Pipeline is no longer returned by the API, and every request for it answers with a 404.

Pipeline Health

The health object reports how the Pipeline's runs are going, as the Pipeline Overview in the Hevo UI shows it. Read the state field to find out whether an action that you requested has finished, and the health object to check the condition of its runs.

Hevo returns the health object for a single Pipeline only, in the response of the Get Details of a Pipeline endpoint and in the response of an action. It is not returned in a list of Pipelines, or when the job monitoring service is unavailable.

The health object contains the following fields:

Checking a Pipeline after an Action

An action does not finish while Hevo is answering your request. The response returns a 202 with the Pipeline in a transitional state, which tells you that Hevo accepted the request and started the work.

To find out whether the work succeeded, send a request to the Get Details of a Pipeline endpoint and check its state. Repeat this at regular intervals until the state changes to one that is not transitional.

For example, enabling a Pipeline produces the following sequence:

A Pipeline usually reaches its final state within a few seconds. If the state changes to Failed, the action did not succeed. Do not wait for a value that ends with _FAILED, because the API never returns such a value.

Actions Allowed in Each State

An action is accepted only from certain states. The following table lists the states that each action can be performed from:

An action that cannot be performed in the Pipeline's current state returns a 400, and the response names that state. This applies only when the Pipeline is not in a transitional state.

From a transitional state (Initializing, Enabling, Disabling or Restarting), a rejected action returns a 409 instead.

Every configuration change and object-selection change moves a replicating Pipeline to Initializing, so a request sent straight after such a change returns a 409.

Pipeline Behavior when a Change is in Progress

Hevo applies one change to a Pipeline at a time. A change is an action that you requested, such as enabling or disabling the Pipeline, or an edit to its configuration. If you send a request while another change is still being applied, Hevo does not apply your request and returns a 409 error.

A change is already in progress in the following cases:

• The Pipeline is in a transitional state, such as Enabling or Disabling, because an action that you requested earlier has not finished. Wait until the Pipeline reaches its final state, and then send the same request again.
• An edit that was started in the Hevo UI is still open. Submit or cancel that edit in the Hevo UI, and then send the request again. Only some requests check for an open edit. These are modifying the Pipeline, modifying its Source, managing its objects and triggering a manual sync. Enabling, disabling, resyncing and deleting do not check, and run as usual.

A 409 error and a 400 error require different responses from you:

• A 409 error means that your request is valid, but Hevo cannot apply it yet. Send the same request again, without changing it, once the Pipeline is free.
• A 400 error means that Hevo did not apply the request. This happens when something in the request is incorrect, or when the current state of the Pipeline does not allow the action. Correct the request, or wait until the Pipeline is in a state that allows the action, and then send the request again.