The
workflow_v3 interface is in BETA and may change before it becomes stable. It requires version 0.2.0 or later of the encord SDK, and is imported from encord.beta.workflow_v3.project.workflow_v3 gives you read access to a Project’s complete Workflow graph, including its stages, pathways, and selected settings. It also lets you list tasks, assign and release manual work, and submit Annotation, Review, and External tasks.
workflow_v3 is not available for every Project. Before you use it, check project.has_workflow_v3. Accessing project.workflow_v3 on a Project that does not support it raises EncordException.
Key Concepts
Inspect a Workflow
The following example lists every stage in a Project’s Workflow, and where each stage’s pathways lead.get_stage() accepts either a name or an id, but not both. Names must match exactly. If two stages have the same name, use the stage ID. Pass type_ to check the stage’s class, for example type_=ExternalStage.
Inspect a Workflow
workflow.pathways holds every pathway in the Workflow, and stage.pathways holds a stage’s outgoing pathways. Each pathway has a source_stage_id, a destination_stage_id, a verdict, and an optional name. Pathway names do not have to be unique.
To read the latest Workflow, call project.refetch_data() and read project.workflow_v3 again. Objects you read earlier keep their original values.
Read Stage Settings
Each stage has asettings object. Settings classes are in encord.beta.workflow_v3.settings, and each class name ends with its version, for example ReviewStageSettingsV1. Currently, only Percentage Router stages expose settings: pathway_probabilities maps each pathway ID to the fraction of tasks sent down that pathway (0.25 means 25%). Worker restrictions and Collaborator Router rules are not available.
Read Percentage Router settings
Unfamiliar Stages and Values
If the Workflow contains a stage or target type that your version of the SDK does not recognize, it loads asUnknownStage or UnknownTarget, with the original type in raw_stage_type or raw_target_type. Unfamiliar settings versions load as UnknownStageSettings. Use to_dict() to inspect their configuration. Unrecognized enum values become UNKNOWN. Upgrade the encord package to use these capabilities.
List Tasks
stage.get_tasks() returns the current tasks at a stage that you can see. Historical tasks are not returned. Each task has an id, a target, a status, a priority, timestamps, and an optional assignment.
- By default, tasks are sorted by descending priority, then by creation time. Pass
sort=TaskSort.CREATED_ATto list the oldest tasks first. - Pass
statusesto list only tasks with specific statuses. - Terminal stages, such as Complete, list the newest tasks first, and do not accept
statusesorsort. - Tasks load page by page as you iterate, so errors can occur during iteration. The queue can change between pages.
DataUnitTarget, which has a data_hash and a dataset_hash. Other targets represent data unit slices, Datasets, Data Group subsets, or Dataset subsets, and do not all have a data_hash.
List tasks at a stage
Assign and Release Tasks
You can assign and release tasks at Annotation and Review stages.task.assign()assigns the task to an eligible user, by email.task.release()releases the task’s current assignment. Releasing requires Admin or Team Manager access to the Project. Releasing an unassigned task succeeds.workflow.release_tasks()releases up to 1,000 tasks in one request. If any task is unavailable, no tasks are released.
workflow.get_task(id=task.id). If a task has changed since you read it, the SDK raises StaleTaskError.
Assign and release tasks
Submit Annotation and Review Tasks
submit() moves a task down one of its stage’s outgoing pathways. Select the pathway with pathway_id or pathway_name (an exact, case-sensitive match), but not both. If the stage has only one outgoing pathway, you can leave out both.
- Submitting does not save labels. Save the task’s labels first, by finding its label row with
project.list_label_rows_v2(data_hashes=[task.target.data_hash]), and calling the label row’ssave(). - Annotators and reviewers must be assigned the task before they submit it. Project Admins and Team Managers can submit without assigning themselves.
- You can add a
commentof up to 50,000 characters, for data unit targets only. - Submitting a Review task routes the task, but does not change the decisions on individual labels. The pathway’s rules decide whether pending, rejected, or missing labels prevent submission.
stage.submit_tasks()submits up to 100 tasks at the same stage down one pathway. If any task fails, none are submitted. To send tasks down different pathways, submit one batch per pathway.
Submit Review tasks
AnnotationStage, AnnotationTask.submit(), and AnnotationStage.submit_tasks().
Process External Tasks
Use an External stage to process data outside Encord, and then submit each task to move it on. Only tasks with the statusENTERED can be submitted. You need the Admin or Team Manager role on the Project.
Replace process_data() in the following example with your own processing.
Process External tasks
task.submit(pathway_name=PATHWAY_NAME). Submitting completes the task and routes it in one step.
Errors and Retries
The SDK never automatically retries a request that changes a task. If a request fails because of a network or gateway error, the change may or may not have been applied. Get the task again with
workflow.get_task() before you retry.
