Product Versioning — User Guide

What is a version?

Every product, raw material, packaging type, and environmental monitoring point in the system can have multiple versions. A version is a permanent, uneditable record of what that item looked like at a specific point in time — its field values and, for products, the list of raw materials and packaging it was composed of.

You can think of it like a photograph. Once taken, the photograph does not change even if the original subject changes. Older photographs (versions) remain accessible forever so you can always look back and see exactly what something was at any given time.

Recipes version differently. A production Recipe's formula versions follow their own, simpler lifecycle (Draft → Approved → Obsolete) rather than the one below — see the Manufacturing Guide.

Why versions matter

In a quality control and compliance context, you need to be able to answer questions like:

• What exactly did batch 2024-07-B of Whole Milk Yogurt contain when we submitted it to the lab?
• Was Raw Material A at pH 6.5 or 6.7 when we published Product X version 2?
• Did we test this formulation before publishing it, or did we publish it directly?

Versions answer all of these questions permanently and reliably.

The version lifecycle

A version moves through a series of stages:

DRAFT  →  IN TESTING  →  TESTED  →  PUBLISHED
  └─────────────────────────────────────┘
            (skip lab, with reason)

Draft

You create a new draft when you are ready to record a new state of the product. While a version is in draft you can still edit the product's field values and composition. The draft is your working copy — it is not yet official.

Only one draft is allowed per product at a time.

In testing

When you click Send to lab, the version is submitted to the laboratory. At this exact moment the system takes a snapshot — a permanent record of every field value and every component of the product at that instant. The version is now locked. No changes to the product's fields or composition will affect this version.

If you realise something needs changing after sending to the lab, you cannot edit this version. Instead you would abandon it and create a new draft with the corrections.

Tested

Once the lab has completed its work, the version is marked as Tested. This means the lab results are in and the version is ready for a decision.

Published

A published version is the official record. When you publish a version:

• It becomes the version shown on the main product page
• The previous published version is automatically moved to the archive
• The published version is permanently locked

Once something is published it cannot be changed. If anything needs to change, you create a new draft version.

Skipping lab testing

In some situations you may want to publish a version without sending it to the lab first — for example, if the change is minor and testing has been waived by a responsible person.

To do this, click Publish (skip lab) on a draft version. The system will ask you to provide a written reason. This reason is stored permanently with the version so there is always a record of why lab testing was skipped.

Use this option carefully. It is designed for genuinely low-risk situations. The reason you provide will be visible in the version history to anyone reviewing the record.

Abandoning a version

If a version was sent to the lab but the testing did not go as expected — or if a decision is made not to proceed — you can Abandon the version. Abandoned versions are not shown in the normal version history, but they are not deleted. Anyone with access can retrieve them by switching on the "show abandoned" filter.

Creating a new version

1. Open the product (or raw material, packaging, environmental point) from the catalog.
2. On the Versions tab, click New version.
3. Enter a note describing what changed and why. This note is required when publishing.
4. The new draft is created. You can now update field values on the Field Values tab and modify composition on the Raw Materials or Packaging tab.
5. When ready, send to lab or publish directly.

Products and their components

A product is made up of raw materials and packaging. When you publish a product version, the snapshot records:

• The product's own field values (e.g. pH, fat %)
• The complete list of raw materials and packaging at that moment
• The field values of each raw material and packaging item at that moment
• Which version of each raw material and packaging was active at that moment

This means the product snapshot is completely self-contained. Even if a raw material is later modified or deleted, the product's historical versions remain accurate.

When a component changes

If a raw material you use in a product is updated to a new version, the system will show a warning on the product page indicating that one or more components have changed since the product was last published.

This warning does not force you to do anything — it is a prompt to review whether the change to the raw material is significant enough to require a new product version. If the change is minor and does not affect the product, you can publish a new product version with a note saying so. If the change is significant, you update the product and go through the full testing cycle.

Shared raw materials

The same raw material can be used in multiple products. Each product's published version captures the raw material at its own snapshot time — independently. Updating the raw material does not retroactively change any published product version.

Environmental monitoring points

Environmental versions work slightly differently. An environmental monitoring point (a kitchen surface, a water inlet, an air sampling location) does not change in the same way a product does — the point itself stays the same, but it is tested periodically.

For environmental points, each version represents one test event. Version 1 might be the January swipe, version 2 the February swipe, and so on. The field values (temperature, sampler name, location notes) describe the conditions of that specific test. Publishing confirms the results are accepted.

Version history

The Versions tab on any product or subject page shows the complete version history, from the most recent to the oldest:

Archived versions (older published versions superseded by a newer one) are shown in the list so you can always go back and read what was recorded at any earlier point.

Frequently asked questions

Can I edit a published version? No. Published versions are permanent records. To make changes, create a new draft version.

Can I have two drafts at the same time? No. Only one draft is allowed per subject at a time. Finish or abandon the current draft before creating a new one.

What happens to my old published version when I publish a new one? It moves to the archive automatically. It remains fully readable in the version history.

Does a component need to be published before I send a product to the lab? No. You can send a product to the lab even if its raw materials or packaging are still in draft. The snapshot records the exact state of each component at the time of submission, including its version status, so there is a clear record.

Can I see what was in a version from years ago? Yes. Click on any version in the history to see its full snapshot — field values, components, and component states — exactly as they were at the time.

What is the "skip lab testing" option for? It is for situations where a responsible person has determined that lab testing is not required for a particular change. It requires a written reason and creates a permanent record of that decision.