spc.sample.update

Sepasoft MES Module Suite

system.mes.spc.sample.update(...)

Overview

Persists changes to an existing or newly created SPC sample.

Use this function after loading or creating a sample and modifying its fields (reference number, product code, measurements, additional factors, and so on). When valuesRecorded is True, the gateway records measurement values along with sample timestamps, shift, product code, and location additional factors; when False, the sample can be updated without treating measurements as recorded (entry and taken timestamps are cleared).

Syntax

Copy Code

Python

# Current system.mes.spc.sample API
system.mes.spc.sample.update(sample, valuesRecorded)
system.mes.spc.sample.update(locationPath, sample, valuesRecorded)

# Legacy SPC 2.0 API name
system.quality.sample.data.updateSample(sample, valuesRecorded)
system.quality.sample.data.updateSample(locationPath, sample, valuesRecorded)
system.quality.sample.data.updateSample(projectName, locationPath, sample, valuesRecorded)

Parameters

Parameter	Type	Required	Description
sample	CommonSample / QualitySample	Required	The sample object to persist. Typically obtained from getSample(), getNewByDefName(), getNewByDefUUID(), or getCreateByDefName() / getCreateByDefUUID().
valuesRecorded	Boolean	Required	When True, records measurement values and related sample information (timestamps, shift, product code, location additional factors). When False, updates the sample without recording values; entry and sample-taken timestamps are cleared.
locationPath	String	Optional	Equipment path for the MES location where the sample is collected. Required only when the sample object does not already have a valid locationPath. If omitted in the two-argument overload, the sample’s getLocationPath() is used.

Return Value

Type	Description
None	The function does not return a value. On success it completes with no return value.

Scope / Availability

Registered on the system.mes.spc.sample script module as update.
The equivalent updateSample method is implemented by the legacy SPC 2.0 script class registered under system.quality.sample.data (including optional locationPath and projectName overloads).
Gateway scripts execute the update locally on the gateway. Designer / Client calls use the Quality RPC layer to run the update on the gateway.

Behavior / Edge Cases

Modified data only: Database writes and SPC before/after events run only when the sample reports changes via isModified(), isDataModified(), or isFactorModified(). Location sample caches are still invalidated and listeners notified after every call.
valuesRecorded=True: Sets entry and sample-taken timestamps when missing, copies additional factors from the MES location, and may auto-approve the sample when the sample definition’s location property has auto-approve enabled.
valuesRecorded=False: Clears entryDateTime and sampleTakenDateTime. Persisted measurement attribute values are not recorded in the same way as a full sample entry (see tests for attribute value behavior).
Location resolution: If locationPath is blank and the sample has no location path, the function raises IllegalArgumentException (“Could not determine sample location.”). The path must resolve to an MESLocation.
Invalid location for definition: When valuesRecorded is True and the location is not allowed on the sample definition, the function fails with an error message (thrown as Exception in script contexts).
Licensing: The target location must be licensed for the Quality module; otherwise a licensing exception is raised.
Before Sample Updated event: Location Before Sample Updated scripts can cancel the update by setting cancelUpdate on the event; this yields “Sample update prevented by user script”.
After Sample Updated event: Runs after a successful persist when sample data changed.
One-shot collect: collect() creates a sample, applies keyword arguments, and calls update(sample, True) internally.

When valuesRecorded is True, the sampleTakenDateTime is set to the current time. SampleTakenDateTime is required to record attribute values, notes on samples or attributes, or the sample 'tag'.

sampleTakenDateTIme is not required for Additional Factors, Reference Number, Product Code

system.mes.spc.sample.update(sample, valuesRecorded)

system.mes.spc.sample.update(locationPath, sample, valuesRecorded)

Example Usage

Minimal example

Copy Code

Python

sample = system.mes.spc.sample.getSample("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
sample.setRefNo("WO-100145")
system.mes.spc.sample.update(sample, False)

Complex example

Copy Code

Python

defName = "Finished Good Weight"
locationPath = "Enterprise\\Site\\Area\\Line 1"

sample = system.mes.spc.sample.getNewByDefName(defName, locationPath)

if sample is None:
	raise ValueError("Unable to create the requested SPC sample.")

sample.setRefNo("WO-100145")
sample.setProductCode("FG-100")
sample.setSampleTakenBy(system.security.getUsername())
sample.getSampleData(1, "Weight").setAttrValue(12.4)
sample.addAddlFactor("Lot", "LOT-8842", system.date.now())

system.mes.spc.sample.update(sample, True)

Related Functions

system.mes.spc.sample.getSample() — Loads an existing sample by UUID for editing before update().
system.mes.spc.sample.getNewByDefName() — Creates a new sample from a definition name and location path.
system.mes.spc.sample.getNewByDefUUID() — Creates a new sample from a definition UUID and location path.
system.mes.spc.sample.getCreateByDefName() — Returns an existing sample or creates one from a definition name.
system.mes.spc.sample.getCreateByDefUUID() — Returns an existing sample or creates one from a definition UUID.
system.mes.spc.sample.collect() — Creates and records a sample in one call (uses update() with valuesRecorded=True).
system.mes.spc.sample.approve() — Approves a sample when auto-approve is not used or additional approval is required.
system.mes.spc.sample.remove() — Permanently removes a sample from the database.

Sepasoft MES Module Suite