> ## Documentation Index
> Fetch the complete documentation index at: https://sofiedocs.usetransfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh a Surface with an Orchestration

> Send structured Orchestration output to a Surface, map output to parts, choose update behavior, and save snapshots after runs.

An Orchestration can refresh a Surface after a task completes. The task returns a structured payload once, then Sofie updates the target Surface, records where the update came from, and refreshes the open Surface.

Use this pattern for recurring metrics, program status, review packs, operational trackers, and other Surfaces that should stay connected to a repeatable workflow.

## Understand the connection

| Term     | Meaning                                                                                                                 |
| -------- | ----------------------------------------------------------------------------------------------------------------------- |
| Source   | The Orchestration run and task that supplied an update. Sofie keeps the run reference as provenance.                    |
| Part     | The named Surface section a task targets, such as `Metrics` or `Risk Register`.                                         |
| Feed     | The named structured update stream the Surface reads for that part.                                                     |
| Snapshot | A saved Surface version and point in each feed's history. It is separate from the **Replace snapshot** update behavior. |

## Choose a target strategy

| Strategy      | Use it when                                                                  |
| ------------- | ---------------------------------------------------------------------------- |
| Fixed Surface | Every run should update the same reusable Surface.                           |
| Surface input | The person starting the run should choose which Surface receives the output. |

A fixed target is safer for a workflow built specifically for one dashboard or report. A Surface input is useful for a reusable Orchestration that operates on different projects.

## Configure a Surface output

<Steps>
  <Step title="Open the task">
    In the Orchestration editor, open the task that produces the Surface data.
  </Step>

  <Step title="Choose Surface output">
    Set the task's **Output Mode** to **Surface**.
  </Step>

  <Step title="Choose the target">
    Set a fixed Surface or choose a Surface input that the run will ask for.
  </Step>

  <Step title="Name the Surface part">
    Enter the section the task updates, such as `Risk Register`, `Timeline`, or `Metrics`.
  </Step>

  <Step title="Choose the update behavior">
    Select **Replace snapshot**, **Merge object**, or **Append row/event**.
  </Step>

  <Step title="Define the output">
    Click **Define Output** and create the structured fields the Surface expects.
  </Step>

  <Step title="Test the run">
    Run the Orchestration with realistic inputs. Confirm the right Surface part changed and review the **Sources** and **Activity** tabs.
  </Step>
</Steps>

## Choose an update behavior

| Operation | Use it for                   | Example                                                           |
| --------- | ---------------------------- | ----------------------------------------------------------------- |
| Replace   | A complete current snapshot. | Replace the full monthly metrics summary.                         |
| Merge     | A partial object update.     | Update risk counts while keeping the rest of the dashboard input. |
| Append    | A new row or event.          | Add one monitoring visit or one run event to a feed.              |

Choose the behavior deliberately. Replacing an event log can remove earlier entries from the rendered feed. Appending a full snapshot can create duplicates.

<Note>
  **Replace snapshot** replaces the current payload in one feed. It does not create a named Surface snapshot. Use **Snapshot After Each Run** when you also want to retain the Surface version and feed state after the run.
</Note>

## Map one task to one part

When the structured output has a top-level field with the same meaning as the Surface part, Sofie sends that field. Otherwise, Sofie sends the complete task output.

For predictable mapping, align the field and part names.

Example output shape:

```json theme={null}
{
  "metrics": {
    "openDeviations": 12,
    "overdueCapas": 3,
    "closureRate": 0.91
  }
}
```

Target the `Metrics` part so Sofie can map the `metrics` field without extra configuration.

## Map one task to multiple parts

Use **Advanced multi-part mapping** only when one task intentionally updates several Surface parts.

For each mapping, define:

* The part or feed.
* An optional output field or path.
* Replace, merge, or append behavior.

Keep mappings small and test each one. Separate tasks are often easier to review when different sources or validation rules drive each Surface section.

## Save a snapshot after each run

Turn on **Snapshot After Each Run** for recurring formal outputs. Name patterns can include the run date, date and time, run reference, or timestamp.

Good uses:

* Weekly business reviews.
* Monthly PPQ summaries.
* Client status packs.
* Periodic governance reports.

Skip automatic snapshots for high-frequency or exploratory updates because they can create a noisy snapshot library.

Snapshots save the Surface version and feed history selected at that run. They do not freeze collection records used by the Surface.

## Verify the update

After the run:

1. Open the Surface and confirm the intended visual or records changed.
2. Open **Data** > **Sources** and confirm the Orchestration, affected collections, fields, and record counts.
3. Open **Activity** and filter to **Orchestrations** or **Sources**.
4. Check for a **Needs attention** feed status.
5. If the run created a snapshot, open it and verify the saved version and feed state.

<Warning>
  A successful run confirms that Sofie delivered a payload. It does not prove that the source data, calculations, mapping, or resulting visual is correct. Review the Surface after changes to the Orchestration output schema or Surface structure.
</Warning>

## Ask Sofie to set up the workflow

You can describe the connection in chat before editing it directly.

```text theme={null}
Update this Orchestration so the final metrics task refreshes the Metrics part of the Monthly Quality Review Surface. Replace the complete metrics snapshot on each run. Define a structured output that matches the Surface and save a dated snapshot after successful runs. Keep the Orchestration in draft and ask me before publishing it.
```

Use focused prompts to review or diagnose an existing connection:

```text theme={null}
Inspect this Surface and Orchestration without changing them. Map each Surface part to its feed, producing task, output field or path, update behavior, and validation status. Flag mismatches and stale sources.
```

```text theme={null}
The last run succeeded but the Surface did not visibly change. Trace the run reference through Sources and Activity, compare the delivered payload with the target feed schema, and explain the most likely cause before fixing anything.
```

```text theme={null}
Review whether Snapshot After Each Run is useful here. Estimate how often snapshots will be created, name what the snapshot preserves, and call out any collection records it will not freeze.
```

For general workflow design and testing, see [Build and edit an Orchestration](/orchestrate/build-orchestrations) and [Test Orchestrations](/orchestrate/test-orchestrations).