Refresh a Surface with an Orchestration

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

Open the task

In the Orchestration editor, open the task that produces the Surface data.

Choose Surface output

Set the task’s Output Mode to Surface.

Choose the target

Set a fixed Surface or choose a Surface input that the run will ask for.

Name the Surface part

Enter the section the task updates, such as Risk Register, Timeline, or Metrics.

Choose the update behavior

Select Replace snapshot, Merge object, or Append row/event.

Define the output

Click Define Output and create the structured fields the Surface expects.

Test the run

Run the Orchestration with realistic inputs. Confirm the right Surface part changed and review the Sources and Activity tabs.

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.

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.

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:

{
  "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:

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

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.

Ask Sofie to set up the workflow

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

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:

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.

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.

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 and Test Orchestrations.

Start here

Chat with Sofie

Search

Notifications and handoff

Connected apps

Workspaces

Surfaces

CoDrafts

CoMeetings

CoSheets

Templates

Sequences

Orchestrations

Personalize Sofie

Account

Administration

Life sciences workflows

Refresh a Surface with an Orchestration

Understand the connection

Choose a target strategy

Configure a Surface output

Choose an update behavior

Map one task to one part

Map one task to multiple parts

Save a snapshot after each run

Verify the update

Ask Sofie to set up the workflow

​Understand the connection

​Choose a target strategy

​Configure a Surface output

​Choose an update behavior

​Map one task to one part

​Map one task to multiple parts

​Save a snapshot after each run

​Verify the update

​Ask Sofie to set up the workflow

Understand the connection

Choose a target strategy

Configure a Surface output

Choose an update behavior

Map one task to one part

Map one task to multiple parts

Save a snapshot after each run

Verify the update

Ask Sofie to set up the workflow