Skip to main content
Version: 2026.08

External workflow logs

External workflow logs record runs of work performed outside Istari — a verification script on your workstation, a CI job, a batch run on an HPC cluster — against the system the work targeted. Output files are uploaded back to the system as workflow outputs, and a workflow log entry ties the run together with a title, status, and, when applicable, configuration and branch provenance from the time of the run.

External workflows are distinct from Istari jobs, which run on Istari agents and are scheduled and tracked end-to-end by the platform. With external workflows, the work happens wherever you run it; Istari stores the record and the outputs.

A typical run​

A common pattern: pull a tracked file from a system, do some work locally, then upload the artifacts and a single log entry back to Istari.

Initialize the clients​

from istari_digital_client import Client, V3Client, Configuration

config = Configuration(
    registry_url="https://your-instance.istari.digital",
    registry_auth_token="your-personal-access-token",
)

client = Client(config)
v3 = V3Client(config)

Pull the source from the system​

file = client.get_file(file_id="<file_id>")
source_bytes = file.revisions[-1].read_bytes()

Upload your outputs​

Once your workflow has produced one or more files on disk, register each as a workflow output:

output_ids = []
for path in ["out/results.xml", "out/summary.json", "out/plot.png"]:
    output = v3.create_workflow_output(system_id="<system_id>", path=path)
    output_ids.append(output.id)

Create the log entry​

from istari_digital_client.v3.models import WorkflowLogEntryCreateDto

entry = v3.create_workflow_log_entry(
    system_id="<system_id>",
    workflow_log_entry_create_dto=WorkflowLogEntryCreateDto(
        title="Design verification — iter-1",
        status="FAILED",          # SUCCESS | FAILED | UNSPECIFIED
        configuration_id="<configuration_id>",
        branch_id="<branch_id>",   # omit for runs on the baseline branch
        workflow_output_ids=output_ids,
    ),
)

The entry now appears on the system's Workflow log tab.

Branch provenance​

branch_id records which branch the run was performed on. If you omit branch_id, Istari records the system's baseline (default) branch — see Branching. For a run on any non-baseline branch, pass branch_id explicitly.

Unless branchless=True, configuration_id is required, and it must be reachable in that branch's history. Istari validates branch history rather than only the branch's current head, so a workflow can still be recorded correctly if the branch advances before the workflow finishes.

For workflows that are not tied to one branch or configuration state, set branchless=True and omit both configuration_id and branch_id:

entry = v3.create_workflow_log_entry(
    system_id="<system_id>",
    workflow_log_entry_create_dto=WorkflowLogEntryCreateDto(
        title="Nightly compliance sweep",
        status="SUCCESS",
        branchless=True,
        workflow_output_ids=output_ids,
    ),
)

Workflow log responses include:

  • branch_id: the branch recorded for the run, or None for workflows not tied to a branch state.
  • branch_name: the stored branch name for display, or None for branchless entries.
  • branch_revision_id: the branch-history revision that links the workflow to the recorded configuration, or None when no branch revision is recorded.

status and workflow_type​

Use one of SUCCESS, FAILED, or UNSPECIFIED for status — these are the values the Workflow log tab renders with the appropriate icon and colour. UNSPECIFIED is the default if you omit the field.

workflow_type should be "external" for runs created by the SDK against an external workflow. It is also the default if you omit the field.

Outputs and entries​

A workflow log entry owns its outputs. Create the outputs first, then create one entry that references them — a single workflow run should map to a single entry that holds all of its outputs.

Listing and reading entries​

page = v3.list_workflow_log_entries(
    system_id="<system_id>",
    branch_id=["<branch_id>"],  # optional exact branch filter
)
for entry in page.items:
    print(entry.created, entry.status, entry.title, entry.branch_name)

detail = v3.get_workflow_log_entry(system_id="<system_id>", entry_id="<entry_id>")
print(detail.branch_id, detail.branch_revision_id)
for output in detail.workflow_outputs:
    print(output.name, output.size)

What's next​