---
title: "Adding Sample Definitions via Scripting"
id: "adding-sample-definitions-via-scripting"
project: "MES User Manual"
url: "https://docs.sepasoft.com/articles/user-manual/adding-sample-definitions-via-scripting"
updated: 2026-07-31T14:59:08Z
---

# Adding Sample Definitions via Scripting

**Sepasoft MES Module Suite**
 ## Adding Sample Definitions with Scripting

The [SPC Sample Definition Manager](/articles/user-manual/spc-sample-definition-manager) is generally used to add Sample Definition Classes and Sample Definitions. However, there are situations where you may want to add these via scripting. The SPC module provides scripting functions to perform a variety of tasks, such as adding or modifying Sample Definition Classes and Sample Definitions.

A sample definition (SPC definition) defines what to measure, where samples may be taken, and which control limits and rules apply. You can create and update definitions from script using [system.mes.spc.definition](/articles/user-manual/system-mes-spc-definition), then persist the object with [system.mes.saveMESObject](/articles/user-manual/system-mes-savemesobject). Run these scripts on the Gateway (or from the client in contexts that execute on the gateway) with Production and Quality modules available.
![](/resources/Storage/user-manual/adding-sample-definitions-via-scripting/sampleDefViaScript.png)

#### Before you begin

* Use a unique definition name.
* **locationPath** must be a valid MES equipment path to a location (for example Enterprise/Site/Area/Line/Location).
* Sampling interval must match a configured interval name in your enterprise (for manual collection, Manual is typical).
* Control limit and SPC rule (signal) names must already exist. Use the list functions below to see valid names in your system.
 #### List valid limit and rule names

```python
limitNames = system.mes.spc.definition.getLimitNameList()
signalNames = system.mes.spc.definition.getSignalNameList()
```

#### Optional: list existing sample definitions
showDisabled=True includes disabled definitions; False returns only enabled definitions.


```python
defs = system.mes.spc.definition.getSampleDefinitionList(False, '*', '')
```


### Create a new sample definition

* [Before you begin](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4__1227129135)
* [List valid limit and rule names](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4_1848917144)
* [Optional: list existing sample definitions](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4__1183706791)
* [Create the definition object](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4_657216473)
* [Set name, interval, and optional fields.](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4_306098486)
* [Add one or more attributes](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4__64542072)
* [Add allowed location(s)](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4_855662076)
* [Add control limits (optional)](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4__324332925)
* [Add SPC rules / signals (optional)](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4__453805579)
* [Save](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4__1966746939)
* [Verify (optional)](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4_5586762)
* [Update an existing definition](/articles/user-manual/adding-sample-definitions-via-scripting/a/h4_385765892)

* #### Create the definition object

Call **getSampleDefinition** with an empty string for the name so the system creates a new definition. (Loading an existing definition uses the same function with a non-empty name.)

```python
sd = system.mes.spc.definition.getSampleDefinition('')
```

* #### Set name, interval, and optional fields.


```python
sd.setName('Scripted Width SPC')
sd.setInterval('Manual')
sd.setDescription('Width monitoring from script')
sd.setDefaultSampleSize(1)
sd.setAutoApprove(False)
sd.setAutoEvaluateSignals(True)

```


* #### Add one or more attributes

Use **addAttribute** with keyword arguments. **attributeName** is required; **dataType** defaults to **REAL** if omitted. Chart names (for example **Individual, XBar**) must match types configured in your system.


```python
system.mes.spc.definition.addAttribute(
    sampleDefinition=sd,
    attributeName='Width',
    dataType='REAL',
    defaultChart='Individual',
    measurementCount=1,
    units='mm'
)

```


Optional keywords also supported: **format, min, max**.
* #### Add allowed location(s)


```python
system.mes.spc.definition.addLocation(
    sampleDefinition=sd,
    locationPath='Enterprise/Site/Area/Line/Location',
    autoApprove=True
)

```

* #### Add control limits (optional)

Each name must appear in **getLimitNameList()**.


```python
system.mes.spc.definition.addLimit(sd, 'Individual LCL')
system.mes.spc.definition.addLimit(sd, 'Individual UCL')
```

* #### Add SPC rules / signals (optional)

Each name must appear in **getSignalNameList()**.


```python
system.mes.spc.definition.addRule(sd, 'Western Electric Rule 1')
```


* #### Save


```python
system.mes.saveMESObject(sd)
```


* #### Verify (optional)


```python
loaded = system.mes.spc.definition.getSampleDefinition('Scripted Width SPC')
```


* #### Update an existing definition

Load by name, change properties or add attributes, locations, limits, or rules, then save again.

```python
sd = system.mes.spc.definition.getSampleDefinition('Scripted Width SPC')
sd.setDescription('Updated from script')
system.mes.saveMESObject(sd)

```

## Complete Jython Code Example

Replace paths, interval, limits, and rules with values that exist in your environment.

```python
# Optional: inspect configured names
# limits = system.mes.spc.definition.getLimitNameList()
# signals = system.mes.spc.definition.getSignalNameList()

sd = system.mes.spc.definition.getSampleDefinition('')
sd.setName('Scripted Width SPC')
sd.setInterval('Manual')
sd.setDescription('Example sample definition created from script')
sd.setDefaultSampleSize(1)

system.mes.spc.definition.addAttribute(
    sampleDefinition=sd,
    attributeName='Width',
    dataType='REAL',
    defaultChart='Individual',
    measurementCount=1,
    units='mm'
)

system.mes.spc.definition.addLocation(
    sampleDefinition=sd,
    locationPath='Enterprise/Site/Area/Line/Location',
    autoApprove=True
)
# Optional — use names from getLimitNameList()
system.mes.spc.definition.addLimit(sd, 'Individual LCL')
system.mes.spc.definition.addLimit(sd, 'Individual UCL')

# Optional — use names from getSignalNameList()
# system.mes.spc.definition.addRule(sd, 'Western Electric Rule 1')

system.mes.saveMESObject(sd)


```


## Script functions used in this topic
| Function | Purpose |
| --- | --- |
| [system.mes.spc.definition.getSampleDefinition(name)](/articles/user-manual/system-mes-spc-definition-getsampledefinition-sampledefname) | New definition if name is blank; otherwise load by name. |
| [system.mes.spc.definition.addAttribute](/articles/user-manual/system-mes-spc-definition-addattribute-sampledefinition-attributename-datatype-format-measurementco)(...) | Add a measured attribute to the definition. |
| [system.mes.spc.definition.addLocation](/articles/user-manual/system-mes-spc-definition-addlocation-sampledefinition-locationpath-autoapprove-interval-intervalco)(...) | Tie the definition to a location path. |
| [system.mes.spc.definition.addLimit](/articles/user-manual/system-mes-spc-definition-addlimit-sampledefinition-limitname)(sd, limitName) | Add a control limit by name. |
| [system.mes.spc.definition.addRule](/articles/user-manual/system-mes-spc-definition-addrule-sampledefinition-rulename)(sd, ruleName) | Add an SPC rule by name. |
| [system.mes.spc.definition.getLimitNameList](/articles/user-manual/system-mes-spc-definition-getlimitnamelist)() | List configured control limit names. |
| [system.mes.spc.definition.getSignalNameList](/articles/user-manual/system-mes-spc-definition-getsignalnamelist)() | List configured signal/rule names. |
| [system.mes.spc.definition.getSampleDefinitionList](/articles/user-manual/system-mes-spc-definition-getsampledefinitionlist-showdisabled-namefilter-locationpathfilter)(showDisabled, nameFilter, locationPathFilter) | Query definitions as a dataset. |
| [system.mes.saveMESObject](/articles/user-manual/system-mes-savemesobject)(mesObject) | Persist the sample definition. |

## Related

* [system.mes.loadMESObject](/articles/user-manual/system-mes-loadmesobject) — Load MES objects by UUID or name and type when needed for other workflows.
* [system.mes.createMESObject](/articles/user-manual/system-mes-createmesobject) — Alternative way to create a new object by type name (for example sample definitions) where supported by your scripting context.
 
**Sepasoft MES Module Suite**