Versions and Publishing
Every project holds two things: a draft you edit, and a numbered history of published versions. Production runs a published version, never the draft. Publishing is what moves your work from one to the other.
This one rule explains most questions about why a change did or did not take effect.
Draft, published, and what production runs
| What it is | What uses it | |
|---|---|---|
| Draft | The live, editable configuration. Every change you make (a field, a rule, the workflow, a setting) is saved here immediately. | The Playground, and nothing else. |
| Published versions | Frozen snapshots of the draft, numbered v1, v2, v3 and upward. They are immutable: they are created and deleted, never edited. | Production, which always runs the latest published version. |
Two consequences worth keeping in mind:
- A project that has never been published cannot process production documents at all. Publishing v1 is what turns a configured project into a live one. Until then you can still work in the Playground.
- Production always uses the highest-numbered version that exists. There is no setting that points production at an older one. That is why moving production backward is done by publishing again or by deleting newer versions, described below.
The Playground runs your draft, so it is the right place to try a change on real documents. A Playground result proves nothing about production until the draft is published.
Each production transaction also records the version it ran under and stays pinned to it. Old transactions keep opening with the fields and layout they were extracted with, even after the project has moved on. This is also why a version that has processed work cannot be deleted.
The version indicator
The project name in the page header is followed by the version state:
- Draft with a Publish button: there are unpublished changes. The tooltip is exact about the numbers, for example "Unpublished changes since v7. Publishing creates v8."
- Draft on a project that has never been published: publishing creates v1.
- Project v7 with a check mark: the draft matches what is published. Nothing is waiting.
Next to it, Review changes opens a summary of everything the draft adds, removes or changes compared with the last published version, grouped by document classes, extraction fields, workflow, business rules, views and settings. Read it before publishing, and read it before discarding a draft.
Publishing
- Open Review changes and confirm the changeset is what you intend to put live.
- Click Publish. The dialog validates the configuration first and shows the next version number.
- Write release notes saying what changed. They are the only history the next person has when looking at the version list.
- Publish.
The dialog can report two kinds of feedback:
- Errors block publishing. In practice these mean the project has no draft settings, or its versioning data is missing.
- Warnings do not block it. The common ones are an empty configuration (classification enabled with no document classes, extraction enabled with no fields) and, most importantly, auto-discovery still being switched on.
If "discover additional classes" or "discover additional fields" is on when you publish, live traffic keeps inventing new classes and fields in your production configuration. Auto-discovery is a design-time convenience. Switch both off before the version that real work will run on.
The publish dialog also carries a Keep learning in production switch. When it is on, the version you are about to publish keeps capturing new memory samples from the documents it processes. Turn it off to freeze memory at exactly the samples published with this version. See Memory for the full picture.
Discarding draft changes
If a set of edits turned out to be wrong, Manage Versions → Discard Draft Changes resets the draft to the latest published version.
Everything changed since that publish is lost, and there is no undo. Open Review changes first so you know exactly what you are dropping. If some of it is worth keeping, publish it as a version first, or duplicate the project, before discarding.
Managing versions
The Library page lists your projects. Each project card's menu has Manage Versions, which shows the published history with dates, authors and release notes, and offers three actions:
| Action | What it does |
|---|---|
| Discard Draft Changes | Resets the draft to a published version. Affects the draft only. |
| Delete a version | Permanently removes that version snapshot. If it was the latest, the previous version becomes the latest, and production falls back to it. |
| Copy from a version | Creates a new project whose draft is that version's configuration. The original is untouched. |
Moving production back to an earlier configuration
There are two ways, and the first is almost always the right one.
Option A: republish the older configuration (recommended)
- Manage Versions → Discard Draft Changes, choosing the version you want to return to (for example v3). Your draft is now v3's configuration.
- Publish it, with release notes such as "Reverting to the v3 configuration".
This creates v6, whose contents are identical to v3, and production immediately runs it. Nothing is deleted, the history stays intact, and transactions processed under v4 and v5 keep opening correctly.
Option B: delete the newer versions
Deleting the latest version makes the previous one latest again, so deleting v5 and then v4 puts production back on v3.
Use this only for versions that were published by mistake, and note the limit:
If even one production transaction ran under v5, deleting v5 is refused. Those transactions need their original configuration in order to display correctly. When that happens, use Option A instead. Never delete transactions in order to free up a version.
Deletion is permanent, and it also releases the memory samples pinned to that version.
Keeping an older version before you delete it
If you want v4 and v5 preserved somewhere first, use Manage Versions → Copy on each of them. Each copy becomes a separate project holding that exact configuration as its draft.
Duplicating the whole project is not a substitute: a duplicate carries only the latest published version, so it would preserve v5 and lose v4.
Duplicating a project
Library → project card menu → Duplicate creates an independent copy of a project. It is a single action, with nothing to paste afterward. Use it to experiment away from a live project, to fork a variant for another team or region, or to snapshot a configuration before a risky change.
A duplicate is not a full clone. It carries:
| Copied | Not copied |
|---|---|
| The draft configuration: document classes, extraction fields, business rules, workflow, table views | Production transactions. The copy starts with an empty production dataset. |
| Playground transactions | The version history. Only the most recent published version is carried over. |
| Memory samples for the draft and the latest version | Earlier processing history of individual transactions |
However many versions the original had, the copy begins with no published version and a draft flagged as changed. Publish it before it can process production documents.
To start from a shared template instead, use the Library tab of the Library page and choose Get on a template project.
Who can do what
| Capability | Permission | Built-in roles |
|---|---|---|
| Edit the draft (classes, fields, rules, workflow, settings) | Configure project | Admin, Designer |
| Publish the draft as a new version | Publish project version | Admin, Designer |
| Discard draft changes / roll back to a version | Roll back project version | Admin, Designer |
| Create a project, duplicate one, copy from a version | Create projects | Admin |
| Delete a project or a published version | Delete projects | Admin |
Custom roles can be given any combination of these. A common arrangement is a designer who can configure and publish, while creating and deleting projects stays with an administrator.
Common questions
I changed a setting and production behaves the same. The change is in the draft. Check the version indicator: if it says Draft, publish. This is by far the most frequent cause, and it applies to every kind of setting, including memory and business rules.
The Playground gives the right result but production does not. The Playground runs the draft and production runs the latest published version. They differ until you publish.
An old transaction opens with fields the project no longer has. That transaction is pinned to the version it was processed under, and is shown with that version's configuration. This is intentional.
Someone published while I was editing. Your draft edits are still in the draft. Open Review changes to see what is now unpublished relative to the new version.
Nothing shows in Review changes but the badge says Draft. Memory samples captured from production also move the draft, and they are already live. The Publish button only appears for changes a publish would actually put into production.
Related
- Projects for what a project contains and how to set one up
- Memory for how samples are versioned along with the project
- Data retention for how long production transactions are kept