spc.sample.getCreateByDefName(...)

Sepasoft MES Module Suite

getCreateByDefName(...)

Overview

Returns an existing SPC sample when sampleUUID is provided; otherwise creates a new sample from a sample definition name at the specified location. Use this helper when a workflow may resume an existing sample or start a new sample with the same call pattern.

Syntax

Copy Code

Python

# Current system.mes.spc.sample API
system.mes.spc.sample.getCreateByDefName(sampleUUID, defName, locationPath)

# Legacy SPC 2.0 API name
system.quality.sample.data.getCreateSampleByName(sampleUUID, defName, locationPath)

Parameters

Parameter	Type	Required	Description
sampleUUID	String	Optional	UUID of an existing sample to return. When this value is not blank, the function returns that sample and does not use defName or locationPath to create a new one.
defName	String	Required when sampleUUID is blank	Name of the sample definition to use when creating a new sample.
locationPath	String	Required when sampleUUID is blank	Equipment path for the MES location where the new sample is initialized.

Return Value

Type	Description
CommonSample / QualitySample	Existing sample matching sampleUUID, or a newly created sample based on defName and locationPath. Returns None when the current API is called without either a non-blank sampleUUID or both creation inputs.

Scope / Availability

Registered on the system.mes.spc.sample script module as getCreateByDefName.
The equivalent getCreateSampleByName method name is implemented by the legacy SPC 2.0 script class registered under system.quality.sample.data.
Gateway scripts execute locally on the gateway. Designer / Client calls use the quality RPC layer to perform the same sample lookup or creation on the gateway.

Behavior / Edge Cases

Existing sample path: A non-blank sampleUUID takes precedence. The function calls getSample() and ignores defName and locationPath for creation.
New sample path: A blank sampleUUID creates a new sample from defName at locationPath via getNewByDefName().
Blank creation inputs: The function returns None if sampleUUID is blank and either defName or locationPath is blank.
Unknown sample UUID: When sampleUUID is provided but no matching sample exists, the function returns None; it does not fall back to creating a sample from defName and locationPath.
Invalid definition or location: The sample definition name must exist, and locationPath must resolve to a valid MES location for the definition; otherwise sample creation fails or returns no sample depending on call context.

Example Usage

Minimal example

Copy Code

Python

sample = system.mes.spc.sample.getCreateByDefName(
	"",
	"Finished Good Weight",
	"Enterprise\\Site\\Area\\Line 1"
)

Complex example

Copy Code

Python

defName = "Finished Good Weight"
locationPath = "Enterprise\\Site\\Area\\Line 1"
sampleUUID = event.source.parent.getComponent("SampleUUID").text

sample = system.mes.spc.sample.getCreateByDefName(sampleUUID, defName, locationPath)

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

sample.setRefNo("WO-100145")
sample.setProductCode("FG-100")
sample.setSampleData(1, "Weight", 12.4)

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

Related Functions

system.mes.spc.sample.getCreateByDefUUID() — Returns an existing sample or creates one from a sample definition UUID.
system.mes.spc.sample.getNewByDefName() — Always creates a new sample from a sample definition name and location path.
system.mes.spc.sample.getSample() — Returns an existing sample by UUID.
system.mes.spc.sample.update() — Persists changes to a sample and optionally records values.

Sepasoft MES Module Suite