Introducing the new workflow

The new workflow brings more flexibility and control to how you structure labeling and review processes. You can now define multiple steps, assign different team members at each stage, and track progress more precisely across the entire pipeline.

Key concepts in the new workflow: what’s changed?

To support a more flexible and customizable review process, we’ve introduced new concepts that replace and extend the previous Asset status model.

In the previous workflow, each asset had a single Asset status value that reflected both the process step and its progress (e.g., “Labeled”, “Reviewed”).

In the new workflow, we’ve separated these ideas into two distinct attributes:

• Step: This represents the current step in the process, such asLabel , Review 1, ...or any custom steps you define
• Status in Step: This indicates the asset’s current status within the step, and can take the following values:
  • To do: the asset is waiting to be picked up
  • Doing: the asset is currently being worked on
  • Done: the step has been completed for this asset
  • Redo: the asset has been sent back and is being reworked
  • Partially done: used in consensus workflows when some, but not all, reviewers have completed their task
  • Skipped: the asset was excluded from this step (e.g., based on sampling rules)

This separation makes the workflow more transparent, easier to track, and scalable for complex projects with multiple quality control stages.

👉 Learn more about steps and status in our documentation

Script migration guide

What will change for you

With the new workflow activated for your organization, your existing projects will continue to operate using the previous workflow—no action is required on them.

The new workflow will only apply to newly created projects, giving you access to enhanced customization and visibility from the start.

• In the Kili App

You can fully customize your project workflow directly in the Kili interface. Define multiple steps, assign team members to each step, and configure sampling rules to control the flow of assets.

👉 See how to set up and monitor your workflow in Kili app

• In the Kili SDK

If you use the Kili SDK to automate project creation or asset handling, you will need to update your scripts to ensure compatibility with both workflows. This includes handling the new structure for steps and statuses.

Let’s walk you through the key changes and how to write scripts that work seamlessly with both the old and new workflows.

Determining whether a project uses workflow V1 or V2

To check which workflow version a project is using, you can look at the number of defined steps. Projects using the new workflow (V2) will have at least one step configured, while older projects (V1) will have none.

projects = kili.projects(project_id=project_id, fields=["steps {type}"])

steps = projects[0]['steps']
if len(steps) > 0:
    print("This project is using workflow V2")
else:
    print("This project is using workflow V1")

This check allows you to conditionally adapt your script logic depending on the workflow version, which is especially useful when working with both legacy and new projects in the same organization.

Querying data with the new workflow (V2)

In Workflow V2, asset progress is tracked using two distinct fields:

• step_name (e.g., "Label", "Review 1")
• step_status (e.g., "TO_DO", "DOING", "DONE")

To query assets or asset labels with the new workflow, you must explicitly provide both step_name_in and step_status_in parameters.

Example: Query assets that are in the “Label” step and still “To do”

kili.assets(
    project_id=project_id,
    step_name_in=["Label"],
    step_status_in=["TO_DO"]
)

This allows for more precise filtering and tracking, especially in workflows involving multiple review stages.

Mapping V1 status_in to V2 step_name_is and step_status_in

To ease the transition, you can map the legacy status_in values from Workflow V1 to the new combination of step_name_in and step_status_in used in Workflow V2.

This table can help you maintain compatibility with V1 behavior while leveraging the flexibility of V2.

ℹ️

In Workflow V2, step names are fully customizable. Make sure your mapping logic accounts for project-specific step names if you’re working across multiple projects.

Appending labels in workflow V2

Appending labels in Workflow V2 works similarly to the previous workflow (V1), with one key difference: If the asset is already marked as DONE in its current step, you must explicitly specify which step the new label should apply to.

Depending on the step_name you provide, two behaviors are possible:

Case 1: Updating the label in the same step

If you specify the same step the asset is already marked as DONE in, the new label will correct the existing one, and the asset will remain in the same step and status.

kili.append_labels(
    project_id=project_id,
    asset_external_id_array=asset_external_id_array,
    json_response_array=[jsonResponse],
    label_type="DEFAULT",         # Use "DEFAULT" for labeling steps
    step_name="Label"             # Same step the asset is already in
)

➡️ The asset remains in the Label step with status DONE.

Case 2: Appending a label in the next step

If you specify the next step defined in the project workflow, the label will be attached to that new step, and the asset will move to the next step and be marked as DONE there.

kili.append_labels(
    project_id=project_id,
    asset_external_id_array=asset_external_id_array,
    json_response_array=[jsonResponse],
    label_type="REVIEW",          # Use "REVIEW" for review steps
    step_name="Review"            # The next step in the workflow
)

➡️ The asset is moved to the Review step with status DONE.

📘

Make sure the label_type is consistent with the step type:

• Use DEFAULT for labeling steps
• Use REVIEW for review steps

If step separation enforcement is activated, the same user will not be allowed to label or review an asset in a step if they already authored a label in a previous step.