ScenarioBuilder

Builds a local scenario from an already-downloaded ScenarioExportPackage and a mapping of resource zip file paths.

The class is responsible for:

Creating ResourceDtoBuilder instances for all resources (shell models)
Running ScenarioLoader to prepare the scenario and protocol model
Persisting the scenario, protocol, shell resource models, tags, and shared-entity records to the DB inside a single transaction
After the transaction, filling zip-backed resources with their actual content via ResourceZipBuilder

This separation from ScenarioDownloader (which handles the HTTP/download phase) allows the build logic to be tested independently — e.g. to exercise "Skip if exists" without making any HTTP calls.

Build flow — phase 1 (transaction):

_load_scenario — parse the export package via ScenarioLoader.
_load_resource_dtos — create a ResourceDtoBuilder for every resource (both zip-backed and metadata-only).
_build_scenario (in transaction) — remap IDs, save shell resource models, persist the scenario and protocol (save_full), save remaining shell resources in execution order, then record tags and shared-entity origin.

Build flow — phase 2 (after transaction):

_fill_zip_resources — for each resource with a zip file, create a ResourceZipBuilder and fill the shell resource with actual content.

Update mode (KEEP_ID and a scenario with the same ID already exists):

Steps 1–2 are identical. Inside _build_scenario:

3a. _update_scenario — copy metadata onto the existing scenario, then call _sync_existing_processes to diff the old and new protocols (delete removed processes, reset rerun ones). 3b. After saving the scenario, call _merge_protocol_into_db to reconcile the DB protocol: update existing processes, add new ones, reload the graph, and copy the new graph structure (connectors, interfaces, outerfaces, layout). 3c. Save remaining shell resources, tags, and shared-entity origin as in creation mode. 3d. Phase 2 then fills zip-backed resources as usual.

Usage::

builder = ScenarioBuilder(
    scenario_info=package,
    origin=external_lab_info,
)
scenario = builder.build()
builder.fill_zip_resources({resource_id: "/tmp/resource_abc.zip"})

Functions

__init__

Initialize self. See help(type(self)) for accurate signature.

scenario_info : ScenarioExportPackage

origin : ExternalLabWithUserInfo

create_mode : ShareEntityCreateMode

message_dispatcher : gws_core.core.classes.observer.message_dispatcher.MessageDispatcher | None

skip_resource_tags : bool - False

skip_scenario_tags : bool - False

build

Build (or update) the scenario in the DB inside a transaction.

Creates shell resource models (ResourceDtoBuilder) for every resource and persists the scenario, protocol, and shell resources atomically. Call fill_zip_resources() afterwards to fill zip-backed resources with their actual content.

In KEEP_ID mode, if a scenario with the same ID already exists in the database the builder automatically switches to update mode: scenario metadata is copied over, unused processes are deleted, rerun processes are reset, and the new protocol is saved on top of the existing one.

Return type : Scenario

fill_zip_resources

Fill shell resources that have zip content with their actual data.

Should be called after build() completes. For each resource that has a corresponding zip file, creates a ResourceZipBuilder and saves the content into the existing shell resource model.

resource_zip_paths : dict

Have you developed a brick?