Using the TIBCO AMS Operator

Introduction

The TIBCO AMS operator is an intermediary through which data files can be loaded (pulled) from a TIBCO Artifact Management Server to a TIBCO model operator within an EventFlow module, or deployed (pushed) from the Artifact Management Server to a running EventFlow module configured with a model operator. To do this, the TIBCO AMS operator:

Receives control information internally and exposes it on its output port.
Takes in status information through its status port and reports the status to the Artifact Management Server.
Provides the initial connection to Artifact Management Server and receives any version of a given set of data files.

Running the TIBCO AMS operator by itself provides no service and is not recommended.

The TIBCO Artifact Management Server, hereafter, AMS, is a separately installed product from TIBCO StreamBase. AMS supports and can store a variety of file types in its repository. From an AMS perspective, a data file is considered an artifact (and bears no relation to the concept of Apache Maven artifacts). For more information about AMS, see its product documentation.

The following operators support loading data files using the TIBCO AMS operator:

TIBCO StreamBase® Operator For H2O Model Evaluator
TIBCO StreamBase® Operator for JPMML Model Evaluator
TIBCO StreamBase® Operator for Spark/MLlib Model Evaluator
TIBCO StreamBase® TERR operator for TIBCO Enterprise Runtime for R (TERR)

Properties: General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: TIBCO AMS Settings Tab

Use the TIBCO AMS Settings tab to configure whether and which data file loads when a connected EventFlow module starts. This tab also configures the operator's logging level.

Field Name	Field Description
Load at Startup	Select this check box to set whether the data file is loaded from an Artifact Management Server upon startup of the EventFlow module to which this TIBCO AMS operator is configured.
Host Name	AMS host name.
Port Number	AMS port number.
Secure Channel	Check this box if your communications channel to AMS is enabled for SSL.
Username	AMS username.
Password	AMS password for the username.
Project Name	Project folder in AMS where the data file is located.
Artifact Path	Fully qualified directory path of the data file.
Artifact Version	Int. Version of the data file. Leaving the field blank or entering `-1` equates to "latest artifact version". Otherwise, enter the version number, which must match the version number for the artifact as stored in AMS.
Report Downstream Status	When checked (recommended), the TIBCO AMS operator receives a status tuple from the connected downstream operator to indicate whether the model file was successfully received by the downstream operator.
Log Level	Controls the level of verbosity the operator uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO (Default), DEBUG, TRACE, and ALL.

Properties: Concurrency Tab

Use the Concurrency tab to specify the use of parallel regions for this instance of this component. Consider selecting the parallel regions check box if this component instance is long-running or compute-intensive, can run without data dependencies on other StreamBase components, and would not cause the containing module to block while waiting for a thread to return. In this case, you may be able to improve performance by selecting this option. This option directs StreamBase Server to process this component concurrently with other processing in the application. The operating systems supported by StreamBase automatically distribute the processing of threads across multiple processors.

Caution

The parallel regions setting is not suitable for every application, and using this setting requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Ports

The TIBCO AMS operator contains the following ports.

Input Port

The TIBCO AMS operator contains one user-visible input port, which is used to relay the artifact load status from the downstream operator to the AMS. If the Report Downstream Status check box is unchecked, tuples received on this port are ignored, and the TIBCO AMS operator emits its own internally generated status tuples on its status port in response to artifact load operations:

Field Name	Field Type	Field Description
command	string	The only valid command value is `ReportStatus`.
artifactPath	tuple	The fully qualified path of the loaded artifact.
status	tuple	The output of the downstream operator's status port. This port must have the following fields:
		Field Name	Field Type	Field Description
		command	string	Ignored.
		tag	string	Must contain the tag used by the AMS in loading the artifact.
		type	string	Must contain "error" if the downstream operator failed to load the artifact.
		action	string	Ignored.
		object	string	Ignored.
		message	string	A human-readable string describing the results of the artifact load operation.
		time	timestamp	Ignored.

Output Ports

The TIBCO AMS operator contains two user-visible output ports, one (AMSData) to send received artifacts to the downstream operator, and a second (AMSStatus) to emit tuples that convey the status of artifact load operations:

AMSData Output Port

Field Name	Field Type	Field Description
command	string	The command used to load the artifact from the AMS.
tag	string	The tag specified by the AMS in uploading artifacts used to correlate upload requests with status tuples.
projectName	string	The name of the artifact's AMS project.
artifactPath	string	The fully qualified artifact path.
artifactVersion	int	The artifact version.
artifactContents	blob	The binary content of the artifact. Binary artifacts are base64-encoded within the AMS. The TIBCO AMS operator base64-decodes the artifact content before emitting it in an AMSData tuple.
artifactMetadata	string	Artifact metadata, such as model-specific schema information. Must be in a JSON-compliant format.

AMSStatus Output Port

Field Name	Field Type	Field Description
command	string	The original command used in loading the artifact from the AMS.
tag	string	The tag specified by the AMS in uploading artifacts.
status	boolean	True if the artifact load was successful and false otherwise.
message	string	A human-readable string describing the results of the artifact load operation.