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.
Views, the saved tabs above the transaction tables, are not part of the draft or of any version. A view takes effect for everyone in its audience as soon as it is saved, including on My Work Queue. Publishing, discarding the draft, or deleting a version never changes the views.
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. Re-running it after a step, or re-running one of its documents, uses that same version; only a re-run from the beginning moves it to the latest version (see Which configuration a re-run uses). This is also why a version that has processed work cannot be deleted.
A transaction you copy into Playground, Evaluation or Memory is no longer production work: it runs on the current draft, whichever version it ran under before. Re-running it, from the beginning or from a step, uses your draft settings.
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 and settings. Views are not listed, because they are not part of a version. Read it before publishing, and read it before discarding a draft.
Before the first publish, Review changes compares the draft with the configuration the project was created with, so the defaults a new project starts with are not listed. It appears once you change something. Publish is there from the start, because a project cannot process production documents until v1 exists.
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. The workflow must be valid, so an error appears when, for example, there is no Export step, a step depends on one that no longer exists, or a step's settings are not valid. These errors start with "Workflow:", and the dialog links to the Workflow page where you fix them. Errors also appear when the project has no draft settings, or its versioning data is missing.
- Warnings do not block it. They include the workflow's warnings, such as a step that can never run because the workflow does not lead to it. The common one is an empty configuration: classification enabled with no document classes, or extraction enabled with no fields. A published version never discovers classes or fields, so it skips classification or extracts nothing. Publishing also warns about a step that is turned off, since it does nothing in the published version, and about a class or field that no step uses: a class that no Classify step offers, because each one handles only its own list of classes, or a field that no Extract step extracts and that is not marked not extracted.
"Discover additional classes" and "Discover additional fields" work on the draft only. When you publish, both are switched off, in the draft and in the new version, and the dialog tells you when that is about to happen. A published version cannot change, so production never adds classes or fields, whatever the switches say. This includes versions published before this rule existed.
To keep discovering while you design the next version, turn the switches back on in the draft and process samples in the Playground. The next publish switches them off again.
The publish dialog also asks what the new version collects in production: after a person's review (the default), every correction, an agent's included, or nothing. Choose Nothing to freeze memory at exactly the samples published with this version. See What Memory collects 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. Views are not part of a version, so the new project gets the original's shared views as they are now. Its import connectors are switched off. |
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), the project's shared views, and each user's personal 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 has one: the original's latest published version, under the same number, and the same draft. If the original had unpublished changes, so does the copy. The copy's next publish takes the following number. An original that was never published gives a copy that is not published either.
Import connectors in a copy
A copy never takes the original's incoming documents. Its import connectors are all there, but switched off, and a managed hotfolder has no folder of its own yet. Otherwise two projects would watch the same folder or mailbox, and each document would go to whichever project picked it up first.
To use one in the copy, open the Import activity on the Workflow tab, point the connector at its own source (a managed hotfolder gets a new folder when you save), switch it on and publish. An email connector keeps its sign-in when you duplicate within your organization, so there is nothing to re-enter.
The same applies to a project you Get from the Library, import from an export file, or Copy from a version.
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. So does a transaction added to Memory from My Work Queue that went straight into production memory (see Adding transactions by hand). 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