AbstractMESObject | Artifact Functions

Sepasoft MES Module Suite

Artifact Object Functions

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


Artifact Names

Success 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

Copy Code
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

Copy Code
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 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
Copy Code
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


Copy Code
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