epadmin-artifact

epadmin artifact target — Manages Artifact Distribution Service features.

SYNOPSIS

epadmin [globalparameters] command artifact [commandparameters]

DESCRIPTION

Disclaimer

Artifact Management Server (AMS) is removed in Spotfire® Streaming 11.1.x.

Use the artifact target to manage files and artifacts controlled by the Artifact Distribution Service (ADS). ADS is a service associated with a node that acts as a bridge between certain EventFlow operators and the TIBCO Artifact Management Server (AMS). AMS is a separate server product with a separate installation from the Spotfire Streaming installation. AMS uses ADS to load and activate artifacts requested by StreamBase operators at runtime.

You can also use an ADS configuration file to package one or more artifacts with your fragment or application archive instead of retrieving the artifact from AMS. In both cases, the epadmin artifact commands can be used to administer the packaged artifacts. artifact commands always make sure that the cluster-wide states of the managed artifacts are consistent, whether a command is sent to a single node, multiple nodes, or all nodes in a cluster.

ADS allows StreamBase operators to define a default artifact that is loaded in the operator at startup. Default artifacts are packaged with your fragment or application archive but do not have to be defined in an ADS configuration file. Default artifacts are not added to the cluster-wide artifact cache, which improves startup times, but cannot be administered with the activate, deactivate, register, and remove artifact commands. Default artifacts can optionally be associated with an artifact from AMS so that when the artifact from AMS is loaded and activated it replaces the default artifact.

The artifact target has eight commands:

The designation [sn|ad] in syntax examples is a reminder that this command requires either the global parameter ‑‑servicename or the ‑‑adminport and ‑‑hostname combination to identify the node or cluster of interest.

epadmin activate artifact

Activates a previously loaded artifact on all the nodes within the cluster.

The artifact commands function at the cluster level, rather than on individual nodes. When a node receives the activate command, it initiates the activation process for the artifact across all the nodes within the cluster.

For example, if you have a cluster with three nodes, and you run the activate command, each of the three nodes receives the activate command: 

epadmin adminport=port-num activate artifact --type=XLS --name=arty --version=1.0.1

The first node that receives the command on the specific artifact and proceeds to activate it across the entire cluster. When it is done, the subsequent execution on the remaining two nodes results in a no-op, as the artifact has already been activated. 

epadmin [sn|ad] activate artifact --type=XLS --name=arty --version=1.0.1
epadmin [sn|ad] activate artifact --type=XLS --name=arty --version=1.0.1 --latest
Command Parameter Description Required
type Artifact type. Yes.
name Artifact name. Yes.
version Artifact version. Yes.
latest A boolean value indicating whether this artifact should be marked as the latest version, possibly replacing another artifact marked latest. true tags the artifact version as latest, false does not. No. The default is false.

epadmin deactivate artifact

Deactivates a previously activated artifact. 

epadmin [sn|ad] deactivate artifact --type=XLS --name=arty --version=1.0.1
Command Parameter Description Required
type Artifact type. Yes.
name Artifact name. Yes.
version Artifact version. Yes.

epadmin display artifact

Displays artifact information. The type, name, and version parameters are used as filters to control which artifacts are displayed. The parameters have the following precedence: type, name, version. To specify a lower precedence parameter, all higher precedence parameters must be specified. For example, if you specify a name, you must also specify a type. 

epadmin [sn|ad] display artifact
epadmin [sn|ad] display artifact --filter=required
epadmin [sn|ad] display artifact --filter=operator
epadmin [sn|ad] display artifact --filter=default_artifact
epadmin [sn|ad] display artifact --filter=cluster_artifact 
epadmin [sn|ad] display artifact --type=artytype
epadmin [sn|ad] display artifact --type=artytype --name=arty
epadmin [sn|ad] display artifact --type=artytype --name=arty \
  --version=1.0.0 --verbose
Command Parameter Description Required
filter An enumeration value controlling the type of information to display. Valid values are loaded, required,operator,default_artifact, and cluster_artifact. No. The default value is loaded.
name Artifact name. Cannot be specified if the filter value is operator. No. The default display is all artifact names.
type Artifact type. No. The default display is all artifact types.
version Artifact version. Can only be specified if the filter value is loaded. No. The default display is all artifact versions.
verbose A boolean controlling detailed output. true enables detailed output. No. The default value is false.

epadmin export artifact

Exports artifacts. Exported data is written to standard output by default. 

epadmin [sn|ad] export artifact --type=artytype --name=arty --version=1.0.0 \
    --file=arty.extension
epadmin [sn|ad] export artifact --type=artytype --name=arty --version=1.0.0 \
    --metadata --file=artymeta.extension
epadmin [sn|ad] export artifact --type=artytype --name=arty --version=default-decision-table  
 --engine=engine1 --operator=DecisionTable --file=arty.extension
Command Parameter Description Required
file Export the file name. If this file exists, it is overwritten. Append the appropriate file name extension for the expected artifact file type. Yes.
metadata A boolean controlling whether to export artifact data or metadata. true exports metadata, false exports artifact data. No. The default value is false.
name Artifact name. Yes.
type Artifact type. Yes.
version Artifact version. Yes.
operator If exporting a default artifact, the name of the operator that defined the default artifact. This parameter is optional and can be used when the type, name, and version parameters do not uniquely identify the default artifact. No.
engine If exporting a default artifact, the name of the engine containing the operator that defined the default artifact. This parameter is optional and can be used when the type, name, and version parameters do not uniquely identify the default artifact. No.

epadmin load artifact

Loads artifacts. Loading an already loaded artifact (that is, having the same type, name, and version) follows these rules:

  1. If the artifact data, metadata, and encoding are the same, no action is taken.

  2. If the artifact data, metadata, or encoding is different, and force=false, the load fails.

  3. If the artifact data, metadata, or encoding is different, and force=true, the artifact is reloaded. 

epadmin [sn|ad] load artifact --type=artytype --name=arty --version=1.0.0 \
    --source="xxx" --metadata="yyy"
epadmin [sn|ad] load artifact --type=artytype --name=arty --version=1.0.0 \
    --source="xxx" --encoding="UTF-8"
epadmin [sn|ad] load artifact --type=artytype --name=arty --version=1.0.0 \
    --sourcefile=arty.txt --metadatafile=artymeta.file
epadmin [sn|ad] load artifact --type=artytype --name=arty --version=1.0.0 \
    --source="zzz" --force
Command Parameter Description Required
encoding Artifact encoding specifier. No. No default.
force A boolean controlling whether a load should succeed if an artifact with the same type, name, and version is already loaded with different data, metadata, or encoding. true reloads the artifact if the data, metadata, or encoding is different, false causes the load to fail if the data, metadata, or encoding is different. No. The default is false.
metadata Artifact metadata. Only one of the metadata or metadatafile parameters can be specified. No. No default.
metadatafile Artifact metadata file. Only one of the metadata or metadatafile parameters can be specified. No. No default.
name Artifact name. Yes.
source Artifact data. One of the source or sourcefile parameters must be specified. No. No default.
sourcefile Artifact data file. One of the source or sourcefile parameters must be specified. No. No default.
type Artifact type. Yes.
version Artifact version. Yes.

epadmin notify artifact

Sends a message notification to operators registered to be using a certain artifact. 

epadmin [sn|ad] notify artifact --type=artytype --name=arty --severity=INFO 
    --message=hello
epadmin [sn|ad] notify artifact --type=artytype --name=arty --version=1.0.0 \
    --severity=ERROR --source=an-administrator \
    --messagecode="ERROR-10" --message="something bad"
Command Parameter Description Required
message Message text. Yes.
messagecode Message code. No. No default.
name Artifact name. Yes.
severity An enumeration value indicating the severity of the notification. Valid values are ERROR, WARN, INFO, DEBUG, and TRACE. Yes.
source Notification source. No. No default.
type Artifact type. Yes.
version Artifact version. No. The default is the latest version.

epadmin register artifact

Updates or creates an operator's artifact registration. 

epadmin [sn|ad] register artifact --operator=default.myModule.myOperator \
    --type=artytype --name=arty
epadmin [sn|ad] register artifact --operator=default.myModule.myOperator \
    --type=artytype --name=arty --version=1.0.0
epadmin [sn|ad] register artifact --engine=my-engine \
    --operator=default.myModule.myOperator --type=artytype
epadmin [sn|ad] register artifact --operator=default.myModule.myOperator \
    --type=artytype --action=restore
epadmin [sn|ad] register artifact --engine=my-engine \
    --operator=default.myModule.myOperator --type=artytype --action=restore
Command Parameter Description Required
action Enumeration controlling registration action. Valid values are register and restore. The register action updates or creates a registration for the operator. The restore action resets the operator's registration to any initial value (including no registration). No. The default is register.
engine The engine containing the target operator. No. All engines containing the target operator.
name Artifact name. Required if action is register. Cannot be specified if action is restore. No. No default.
operator Fully qualified StreamBase path to the target operator. Yes.
type Artifact type. Yes.
version Artifact version. Cannot be specified if action is restore. No. The default is the latest version.

epadmin remove artifact

Removes a loaded artifact. The artifact must be already deactivated. 

remove [sn|ad] artifact --type=artytype --name=arty --version=1.0.0
Command Parameter Description Required
name Artifact name. Yes.
type Artifact type. Yes.
version Artifact version. Yes.

SEE ALSO

Help System for epadmin
epadmin(1)
epadmin-globals(1)