End of the line: dispose and dispatch as optional workflows

The basic sample workflow ends when the report is published. The material does not. It sits in a fridge for its retention period, goes to a reference laboratory for a test the lab does not run, or goes back to the client. Until now, SENAITE recorded only one of these endings, dispatch, and it was always on. Two changes merged into senaite.core for the upcoming 2.7 release give both endings a proper place in the workflow.

Dispose: recording that the material is gone

senaite.core#2970 adds a dispose transition and a Disposed state. It is off by default. Switch on Enable the Sample Dispose workflow on the Sampling tab of the setup, and Lab Managers get a Dispose action on samples in Received, To be verified, To be preserved, Verified, Published, Rejected, Invalid and Cancelled.

The list is long on purpose. Retention periods run out regardless of what happened to the results, and the cancelled sample that stood in the fridge for a year still has to be accounted for when it goes into the waste.

Dispose opens a form that requires a reason. It comes prefilled with “Sample disposed after the retention period”, which covers the routine case; anything else gets written in. The sample view then shows who disposed the sample, when, and why.

Dispatch: now optional

Dispatch has existed since SENAITE 2.0, for samples that leave the lab and may come back. senaite.core#2971 puts it behind its own switch, Enable the Sample Dispatch workflow, on the same tab. New installations start with it off. On an existing installation, the upgrade step switches it on only if the database already contains dispatched samples, so labs that use it keep it and labs that never did stop seeing the button.

Dispatch accepts the same states as Dispose except Cancelled, and it also refuses to run without a reason.

Both lock the analyses

The more important change is what happens to the results. Before 2.7, a dispatched sample was recognisable by its state, but its analyses were not protected: their permissions follow the state of the analysis, not of the sample, so a result could still be written through the JSON API.

Now both transitions move every analysis of the sample into a new read-only state, locked. Analyses that were already cancelled, retracted or rejected are left alone. Locking cannot be triggered by hand, and neither can the way back: an analysis is unlocked only when its sample leaves the dispatched or disposed state.

Technically, both states share a marker, ILockingState, and the analysis lock checks only for that marker. An add-on that introduces another state in which results must not change can reuse the mechanism without touching the analysis workflow.

Restore

Both states can be left again with Restore, also a Lab Manager action. The sample returns to the state it had before it was dispatched or disposed, and every locked analysis returns to the state it had before it was locked. A sample that comes back from the reference lab therefore continues exactly where it stopped. The samples listing has a Dispatched and a Disposed filter, and Restore there asks for confirmation.

Partitions and worksheets

Two rules keep the record consistent:

• Partitions follow their primary. Disposing or dispatching a primary sample does the same to its partitions. Disposing the last open partition (ignoring cancelled, rejected and retracted ones) disposes the primary as well. Restore works the same way in both directions.
• Nothing leaves while it is on a worksheet. Neither transition is offered while one of the sample’s analyses is assigned to a worksheet. Unassign first; otherwise a worksheet would wait for material that is no longer in the building.

What it does not do

SENAITE does not dispose of samples by itself. The sample type has a retention period, but core does not act on it: no reminder, no automatic transition. Someone has to select the samples and dispose them, which for most labs is a weekly or monthly routine over a filtered listing. For labs that track where each sample is stored, the storage add-on adds retention rules on top.

Deciding whether to enable them

Enable Dispose if an auditor may ask what happened to a sample’s material, which in accredited labs is the normal case. The reason field then becomes the disposal record.

Enable Dispatch if samples regularly leave the lab, to a subcontractor or back to the client. If they come back for further tests, Restore picks up where the sample left off.

If neither applies, leave both off. The day-to-day workflow does not change.