Transition guide to the multi-step workflow
This guide will help you adapt your SDK scripts to support the new multi-step workflow (Workflow V2), while maintaining compatibility with existing V1 projects. The new workflow is only applied to newly created projects your existing projects will continue using the previous logic, so no project migration is required.
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 as
Label
,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 upDoing
: the asset is currently being worked onDone
: the step has been completed for this assetRedo
: the asset has been sent back and is being reworkedPartially done
: used in consensus workflows when some, but not all, reviewers have completed their taskSkipped
: 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.
Workflow V1 status_in | Workflow V2 step_name_in | Workflow V2 step_status_in |
---|---|---|
TODO | Label (or custom labeling step name) | TO_DO |
ONGOING | Label (or custom labeling step name) | PARTIALLY_DONE |
LABELED | Label (or custom labeling step name) | DONE |
TO_REVIEW | Review 1 , Review 2 , etc. (or custom step name) | TO_DO |
REVIEWED | Review 1 , Review 2 , etc. (or custom step name) | DONE |
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 stepsIf 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.
Updated about 23 hours ago