Skip to content

Commit de1093e

Browse files
josephjclarkjosephjclark
authored
Sandbox docs (#712)
* draft sandbox docs * fix nav * update changing env * feedback * fixes
1 parent 02c0aab commit de1093e

2 files changed

Lines changed: 195 additions & 0 deletions

File tree

‎docs/build/sandboxes.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Sandboxes
3+
sidebar_label: Sandboxes
4+
---
5+
6+
Sandboxes are a way to develop fixes and new features on workflows without
7+
affecting live, or "in production", runs.
8+
9+
:::info Sandboxes are new to OpenFn since October 2025.
10+
11+
At the time of writing sandboxes are under active development and testing. We
12+
expect to be in full working order by the end of November 2025, but until then
13+
we recommend not using them with live workflows.
14+
15+
To access sandboxes, you'll need to enable the Experimental Features option in
16+
your user settings.
17+
18+
:::
19+
20+
A sandbox is essentially a clone of a project, with its own private history,
21+
webhooks, cron triggers credentials and access rights. It also has its own
22+
billing rules - so sandbox runs and AI tokens don't affect your main project.
23+
Unlike most sandbox settings, the billing rules derive from the original
24+
project, rather than duplicate them.
25+
26+
The idea is that you can develop the workflow in total isolation from the main
27+
project, and once you're done, merge (read as "push" or "promote") changes back.
28+
29+
:::tip Short-lived sandboxes
30+
31+
sandboxes work best when they're short-lived, so right now they are destroyed
32+
after merging. While you can create as many sandboxes as you like (subject to
33+
your usage allowance), we recommend keeping the number low to reduce the risk of
34+
merge conflicts.
35+
36+
:::
37+
38+
## Isolated Context
39+
40+
A sandbox is an isolated copy of your original project with its own context. As
41+
such, your sandbox has its own "private" copies of the following artefacts and
42+
features:
43+
44+
- Workflows
45+
- Dataclips
46+
- Run History
47+
- Subscription (run limits, AI credits and collection memory)
48+
- Collections
49+
- Settings
50+
51+
By "private copy", what we mean is that changing a Workflow in a sandbox will
52+
not affect the same-named Workflow in any other project or sandbox, or that a
53+
Run in a sandbox will contribute to your usage in any other sandbox or project,
54+
and so on.
55+
56+
## Creating sandboxes
57+
58+
When you create a new sandbox, we basically create a total copy of your project.
59+
Any changes made to the sandbox will not affect your main project workflows - so
60+
you can experiment freely without breaking anything.
61+
62+
To create a sandbox, enter a Project, click on sandboxes, and click on the
63+
Create sandbox button.
64+
65+
You'll need to set a name for the sandbox. This is unique within your project
66+
and its sandboxes. If you're familiar with git, treat it like a branch name.
67+
Otherwise, you can either give it a general name like `testing`, or name it for
68+
a specific feature, like `new-patient-workflow`.
69+
70+
You'll also need to set an Environment (see below). This configures all
71+
credentials within the sandbox to use that environment variant. If you're not
72+
sure, set the environment to `dev` (you can change this at any time from the
73+
Setup tab of the sandbox Settings page).
74+
75+
A color will be randomly selected to associate with the sandbox. You'll see this
76+
color in the app UI while you're using the sandbox. You can select a different
77+
color if you like.
78+
79+
Click Create sandbox when you're ready. You'll automatically enter the sandbox.
80+
81+
## Viewing a sandbox
82+
83+
To develop and test a sandbox, you need to enter it in the app from the
84+
sandboxes menu.
85+
86+
When sandbox is active, the app will change color to help you understand what
87+
you're looking at. [TODO] We also list the active sandbox in the breadcrumbs at
88+
the top of the page, and in a banner on the Inspector.
89+
90+
Each sandbox has its own isolated Workflows, Subscription, History and settings.
91+
As you click through the pages, you'll notice that your original project's
92+
details are excluded. This is because your sandbox is an independent clone of
93+
the original project.
94+
95+
## Environments
96+
97+
Environments allow you to run a Workflow with a special set of credentials. This
98+
lets you use development servers, modes and databases while building your
99+
sandbox, without interfering with live production services.
100+
101+
Each sandbox has an associated environment. By default it's `main`, which
102+
implies that this is your live production environment. But you can create an
103+
environment like `dev` or `staging`.
104+
105+
The environment is just a label, and each credential used in your workflow has a
106+
set of values associated with that label. For example, when connecting to DHIS2,
107+
your main credential will contain private login details. But your `dev`
108+
environment might use the public sandbox and so contain a different username and
109+
password.
110+
111+
All environments are securely stored and encrypted within our database, so it's
112+
perfectly safe to duplicate production credentials across multiple environments.
113+
114+
For each Credential used in your workflow, you must ensure there is a value set
115+
to match your sandbox environment. If you do not configure your credentials, the
116+
Workflow will fail with clear instructions on how to correct it.
117+
118+
To change a the environment used by a Sandbox, first enter the Sandbox from the
119+
Sandboxes page, then go to the Settings page. The environment can be edited
120+
under the Identity section of the Setup tab (right at the top of the page).
121+
122+
## Merging sandboxes
123+
124+
Once you've finished making changes to your workflows, it's time to merge them
125+
back into your main project.
126+
127+
This is easy in the app: simply head to the Sandboxes page, find the Sandbox you
128+
want to merge in the list, and click the Merge icon on the right-hand side.
129+
130+
You'll be prompted to select the target project or sandbox to merge into: pick
131+
from the list and click Merge. Usually you'll want to merge into the original
132+
project, which is selected by default.
133+
134+
When merging, we replace the contents of workflows in your project with those in
135+
your sandbox. Any workflows which are not in the sandbox will be ignored. If you
136+
rename a workflow in the sandbox, you'll see the new workflow appear in your
137+
main project, and the original workflow will be left alone (you'll probably want
138+
to delete that manually).
139+
140+
Note that settings and options, like concurrency and data retention rules, are
141+
not transferred in the merge, nor are historical runs or dataclips. Just the
142+
Workflow contents.
143+
144+
After merging, the sandbox will be destroyed, along with its history and
145+
dataclips. Any environments and credentials assocaited with the project will be
146+
unaffected.
147+
148+
:::tip
149+
150+
You can also use the CLI to merge your changes locally, give them one final
151+
test, and then deploy them to your main project.
152+
153+
::::
154+
155+
## Conflicts
156+
157+
If you've ever worked with a source version control system - like git or
158+
Subversion - you'll be familiar with the idea of conflicts.
159+
160+
A conflict occurs when you're trying to merge a Sandbox into your original
161+
project (or another sandbox), and there are incompatible changes between them.
162+
163+
Say you create a Sandbox from your main project and in the sandbox, you change
164+
the adaptor of one step from `common` to `http`. And while you're making this
165+
change, a colleague goes to the main project and sets the adaptor of the same
166+
step to `salesforce`.
167+
168+
What happens when you try and merge the sandbox? Should we preserve the original
169+
change? Or accept the change in the sandbox? Or something else?
170+
171+
Occasionally these conflicts are trivial to resolve and you might wonder what
172+
all the fuss is about. But often they are complex, and it can be difficult or
173+
impossible to automate a solution.
174+
175+
[TODO not implemented yet] When we detect a conflict like this, we'll show a
176+
warning when you try and merge the Sandbox. You can choose to "force push" the
177+
Sandbox and overwrite whatever changes happened on the target Project, or you
178+
can cancel and resolve the conflict yourself.
179+
180+
For now, the only way to resolve conflicts manually is to use the CLI to edit
181+
your project locally, and pushed the resolved, final version up to the app.
182+
183+
:::tip
184+
185+
We'll be adding better support for resolving conflicts soon.
186+
187+
:::
188+
189+
## Editing sandboxes Locally
190+
191+
Sandboxes are fully compatible with the CLI.
192+
193+
We're still working on docs and features for that - check back soon for more
194+
details!

‎sidebars-main.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ module.exports = {
6666
'build/credentials',
6767
'build/collections',
6868
'build/limits',
69+
'build/sandboxes',
6970
'build/editing-locally',
7071
'build/working-with-branches',
7172
'build/troubleshooting',

0 commit comments

Comments
 (0)