---
title: "AbstractMESObject | Artifact Functions"
id: "abstractmesobject-artifact-functions"
project: "MES User Manual"
url: "https://docs.sepasoft.com/articles/user-manual/abstractmesobject-artifact-functions"
updated: 2026-09-18T22:12:10Z
---

# AbstractMESObject \| Artifact Functions

**Sepasoft MES Module Suite**

### Artifact Object Functions

MES objects inherit these functions. Use these functions to add artifacts to objects.

* [createArtifact(artifactName, serializableValue)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__1433897054)
* [createArtifact(artifactName, serializableValue, versioned)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4_1760547043)
* [getArtifactCount()](/articles/user-manual/abstractmesobject-artifact-functions/a/h4_255089624)
* [getAllArtifactNames()](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__414612802)
* [getArtifactNames()](/articles/user-manual/abstractmesobject-artifact-functions/a/h4_562820385)
* [getArtifactProperty(artifactName)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__1518401961)
* [getArtifactProperties()](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__1634680742)
* [getArtifactValueByName(name, versionNumber)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4_1027941177)
* [Version Numbers](/articles/user-manual/abstractmesobject-artifact-functions/a/h3_584366608)
* [Latest (name only, or versionNumber = 0)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__527675410)
* [Historical (versionNumber ≠ 0)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__298484266)
* [getArtifactValueByUUID(artifactUUID)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4_95373967)
* [setArtifactValue(artifactName, serializableValue)](/articles/user-manual/abstractmesobject-artifact-functions/a/h4__1987725039)

**Artifact Names**

| ![Success](/resources/Storage/user-manual/Success.png) | Artifact names are always set to lowercase to be case insensitive, when you call any of the artifact methods for get/set/create artifact the name is lowercased first. |
| --- | --- |

####  createArtifact(artifactName, serializableValue) 
 **Description**
 Create a new MES Artifact property named by **artifactName** on an existing MES Object, with a provided primitive, Pythonic or Java serializable object as the **serializableValue** (including strings, integer/real/float/double numbers and Boolean). The new MES Artifact is 'versioned' so each save creates a new version of the artifact (one additional row in the DB per version saved).
 
Files are also 'serializable' (Artifacts serialize the file as an array of bytes. Add "***from java.io import File***" to script and use ***File (fileName)*** where ***fileName***contains the path to the file, with filename and extension. Refer to the Java Class File page).
 **Syntax**
 **createArtifact(artifactName, serializableValue)**

* Parameters

String artifactName - the name of the 'versioned' MES Artifact to create. Name will be stored using lower-case letters.
 
Serializable serializableValue - Any primitive, Pythonic or Java serializable object (including strings, integer/real/float/double numbers and Boolean). Files are also 'serializable'.

* Returns

MESArtifactProperty - A reference to the newly-created Artifact property.

* Scope

All
 
```python
# Create a new 'versioned' MES Artifact object called 'my artifact'
#    on the Material Definition 'Test Material' and set the value
#    of the new Artifact to the string "Hello World".
obj = system.mes.loadMESObject('Test Material', 'MaterialDef')
obj.createArtifact('my artifact', 'Hello World')
system.mes.saveMESObject(obj)
```

#### createArtifact(artifactName, serializableValue, versioned) 
 **Description**
 Create a new MES Artifact property named by **artifactName** on an existing MES Object, with a provided primitive, Pythonic or Java serializable object as the **serializableValue** (including strings, integer/real/float/double numbers and Boolean).
 
Files are also 'serializable' (Artifacts serialize the file as an array of bytes. Add "***from java.io import File***" to script and use ***File (fileName)*** where ***fileName***contains the path to the file, with filename and extension. Refer to the Java Class File page).
 
If **versioned=FALSE**, only one artifact with the version 0 is created and each save overwrites the previous value. If **versioned=TRUE**, then the artifact is saved with its timestamp, such that each save creates a new version of the artifact (one additional row in the DB per version saved).
 **Syntax**
 **createArtifact(artifactName, serializableValue, versioned)**

* Parameters

String artifactName - the name of the Artifact to create. Name will be stored using lower-case letters.
 
Serializable serializableValue - Any primitive, Pythonic or Java serializable object (including strings, integer/real/float/double numbers and Boolean. Files are also 'serializable'.

Boolean versioned - FALSE means only one artifact is stored and is overwritten on each save. TRUE keeps a versioned copy with timestamp as an additional row in the database on each save.

* Returns

MESArtifactProperty - A reference to the newly-created Artifact property.

* Scope

All


```python
# Create a new 'unversioned' MES Artifact object called 'unversioned artifact'
#    on the Material Definition 'Test Material' and set the value
#    of the new Artifact to the string "Hello World".
obj = system.mes.loadMESObject('Test Material', 'MaterialDef')
obj.createArtifact('unversioned artifact', 'Hello World', False)
system.mes.saveMESObject(obj)
```
 
#### getArtifactCount() 
 **Description**
 Returns the number of artifacts that exist for this MES Object.
 **Syntax**
 **getArtifactCount()**

* Parameters

None

* Returns

Integer - The number of artifacts that exist for this MES Object.

* Scope

All

#### getAllArtifactNames() 
 **Description**
 Returns a list with the Name property for all artifacts that exist for this MES Object, as well as for all parent objects.
 **Syntax**
 **getAllArtifactNames()**

* Parameters

None

* Returns

List - A Pythonic list with the Name property for all artifacts that exist for this MES Object, as well as for all parent objects. Names have all been previously created with lower-case letters.

* Scope

All

#### getArtifactNames() 
 **Description**
 Returns a list with the Name property for all artifacts that exist for this MES Object.
 **Syntax**
 **getArtifactNames()**

* Parameters

None

* Returns

List - A Pythonic list with the Name property for all artifacts that exist for this MES Object. Names have all been previously created with lower-case letters.

* Scope

All

#### getArtifactProperty(artifactName) 
 **Description**
 Returns the MES Artifact Property of the specified Artifact on the MES Object.
 **Syntax**
 **getArtifactProperty(artifactName)**

* Parameters

String artifactName - The Name of the Artifact on the MES Object. Names have all been previously created with lower-case letters.

* Returns

MESArtifactProperty - The MES Artifact Property of the specified Artifact on the MES Object.

* Scope

All

#### getArtifactProperties() 
 **Description**
 Returns all of the MES Artifact Properties of the specified Artifact on the MES Object.
 **Syntax**
 **getArtifactProperties()**

* Parameters

None

* Returns

MESPropertyCollection - All of the MES Artifact Properties of the specified Artifact on the MES Object.

* Scope

All

#### getArtifactValueByName(name, versionNumber)
 
#### 
 **Description**
 | ![Note](/resources/Storage/user-manual/Note.png) | Version Specific: Available in MES 3.81.13 SP2, MES 4.83.3 SP2 and later. **versionNumber** added as an optional parameter. |
| --- | --- |

The **getArtifactValueByName** method returns the value of a named artifact on an MES object. Use it to read document HTML, script source, files, and other artifact payloads from recipes, phases, material definitions, and similar objects. Artifact names are matched case-insensitively.

Call with a name alone to get the latest value (including unsaved local changes and parent inheritance). Pass an optional versionNumber to read a historical value from the artifact change-log — useful for batch history scripts that need past documentText (or any other versioned artifact) without only getting the latest.
 **Syntax**
 
```python
mesObject.getArtifactValueByName(name)
mesObject.getArtifactValueByName(name, versionNumber)
```

###  Parameters

##### Required Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| name | String | Artifact name to retrieve (for example, documentText or script). Matching is case-insensitive. Must not be null. |
##### Optional Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| versionNumber | Integer | (latest) | Selects which change-log revision to return. Omit (or use 0) for the latest value. |

### Returns 

 | Type | Description |
| --- | --- |
| Serializable | The artifact value. Common types are String (documents, scripts) and byte[] (binary/file content). |

#### Version Numbers

Artifact versions are the ordered set of MES object versions where the artifact value changed (the change-log). Absolute ranks run from 1 (oldest change) to N (newest change). Relative numbers count back from the latest.

| Call | Returns |
| --- | --- |
| getArtifactValueByName(name) | Latest (includes unsaved local values and parent inheritance) |
| getArtifactValueByName(name, 0) | Latest — same as the one-argument call |
| getArtifactValueByName(name, 1) | Oldest change-log revision |
| getArtifactValueByName(name, 2) | Absolute revision 2 (newest absolute rank is N) |
| getArtifactValueByName(name, -1) | Second-to-latest |
| getArtifactValueByName(name, -2) | Third-to-latest |
| getArtifactValueByName(name, -k) | (k + 1)-th newest |

Out-of-range values (including requesting a historical version when the change-log is empty) throw a RuntimeException that includes the artifact name.

### Behavior

#### Latest (name only, or versionNumber = 0)

1. Returns any unsaved local artifact value set on the object (not yet persisted).
2. Otherwise loads the artifact value for the object's current version from the gateway.
3. If the artifact is not found on this object, searches parent MES objects and returns the first inherited value.
4. Throws a RuntimeException if the name is null, or if no local or inherited artifact value is found.

#### Historical (versionNumber ≠ 0)

1. Resolves the artifact on this object or a parent (inherited artifacts use the owning parent's change-log).
2. Loads the artifact change-log and selects the MES object version for the requested versionNumber.
3. Returns the artifact value at that version.
4. Throws a RuntimeException if the name is null, the artifact is not found, or versionNumber is out of range.

Historical reads do not replace the object's in-memory latest artifact value.

Do not read artifact content through the artifact property's getValue() method. That property returns a guidance message; always use getArtifactValueByName() or getArtifactValueByUUID().

### Scope
| Context | Availability |
| --- | --- |
| Gateway scripts | Available on any loaded MESObject instance |
| Client / Designer scripts | Available on any loaded MESObject instance |
| Perspective / Vision | Available where script access to MES objects is allowed |


```python
# Minimal — read the latest artifact value
docHtml = mesObject.getArtifactValueByName('documentText')

# Latest via explicit versionNumber (same result as one-argument call)
docHtml = mesObject.getArtifactValueByName('documentText', 0)

# Historical — oldest, second-to-latest, and absolute revision 2
oldest = mesObject.getArtifactValueByName('documentText', 1)
previous = mesObject.getArtifactValueByName('documentText', -1)
revision2 = mesObject.getArtifactValueByName('documentText', 2)

# Realistic — load a batch phase and compare current vs previous document
phase = system.mes.loadMESObject('Mix Phase', 'BatchPhase')
currentDoc = phase.getArtifactValueByName('documentText')
previousDoc = phase.getArtifactValueByName('documentText', -1)
print currentDoc
print previousDoc

# List names first, then read a known artifact
obj = system.mes.loadMESObject('My Material', 'MaterialDef')
for artifactName in obj.getArtifactNames():
	print artifactName

notes = obj.getArtifactValueByName('notes')

```
 
#### getArtifactValueByUUID(artifactUUID) 
 **Description**
 Returns the value of the Artifact on the MES Object specified by the Artifact's UUID.
 **Syntax**
 **getArtifactValueByUUID(artifactName)**

* Parameters

String artifactUUID - The UUID of the Artifact on the MES Object.

* Returns

Serializable - The primitive, Pythonic or Java serializable object value stored for the Artifact on the MES Object. Files are also 'serializable', so file contents are returned as an array of bytes.

* Scope

All

#### setArtifactValue(artifactName, serializableValue) 
 **Description**
 Updates an existing MES Artifact property named by **artifactName** on an existing MES Object, with a provided primitive, Pythonic or Java serializable object as the **serializableValue** (including strings, integer/real/float/double numbers and Boolean).
 
Files are also 'serializable' (Artifacts serialize the file as an array of bytes. Add "***from java.io import File***" to script and use ***File (fileName)*** where ***fileName***contains the path to the file, with filename and extension. Refer to the Java Class File page).
 **Syntax**
 **setArtifactValue(artifactName, serializableValue)**

* Parameters

String artifactName - the name of the Artifact to update. Names have all been previously created with lower-case letters.
 
Serializable serializableValue - Any primitive, Pythonic or Java serializable object (including strings, integer/real/float/double numbers and Boolean). Files are also 'serializable'.

* Returns

Nothing

* Scope

All
 
**Sepasoft MES Module Suite**