Spotfire Automation Services Output Adapter

Introduction

The TIBCO StreamBase® Output Adapter for TIBCO Spotfire® Automation Services is used to post job execution, launch, and status requests to a TIBCO Spotfire® Automation Services server. The adapter posts a SOAP 1.1 request to the automation service for each tuple that is received.

The adapter has multiple samples, which are described in TIBCO Spotfire® Automation Services Adapter Samples.

Adapter Properties

This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. 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.

Adapter: A read-only field that shows the formal name of the adapter.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this adapter starts as part of the JVM engine that runs this EventFlow module. If this field is set to No or to a module parameter that evaluates to false, the adapter instance is loaded with the engine, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager.

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 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.

Adapter Properties Tab

Property Description
Log Level Controls the level of verbosity the adapter 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 is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.
API Version (drop-down list) Sets the version of the Spotfire Automation API to use.
  • 0.1 works with Spotfire 7.4 and below.

  • 0.2 works with 7.5 to 7.12.

  • 1.0 work with 7.13 and up.

Connection Tab

Property Description
Spotfire URL (string) The base URL of the Spotfire automation service. This URL should be the full URL to the automation services. For example: http://localhost:81/spotfireautomation/
Ignore certificate errors (check box) If enabled any errors produced by invalid SSL certificates will be ignored and the website will be processed as normal. Warning! This can lead to man-in-the-middle attacks.
Connection Timeout (int) The timeout value in milliseconds to wait until the adapter stops waiting for a response from the Spotfire automation service. Set this value to 0 to disable the timeout.
Client Id (string) When using V1.0 of the API you must specify the OAuth client Id that will be used to authenticate with the server.
Client Secret (string) When using V1.0 of the API you must specify the OAuth client secret that will be used to authenticate with the server.
Authentication (radio) Controls whether authentication is used when communicating with the Spotfire automation service.
Username (string) The user name to send when authentication is required.
Password (string) The password to send when authentication is required.
Use Proxy (check box) Controls whether a proxy will be used to connect.
Proxy Host (string) The host to use when connecting via a proxy.
Proxy Port (int) The port to use when connecting via a proxy.

Spotfire Service Tab

Property Description
Service Type (drop-down list) Controls which service request will be sent to the Spotfire automation service. The service types are:
  • Abort Job available with API v1.0, This method aborts an ongoing Automation Services job based on its job ID.

  • Execute Job available with API v0.1 and v0.2, This method starts an Automation Services job from its XML definition and wait for completion.

  • Launch Job This method starts an Automation Services job from its XML definition.

  • Launch Library Job available with API v1.0, This method starts an Automation Services job from a library file. The identity of the file can be provided using either library path or library ID (GUID). Note that the API client must have sufficient library permissions to access the library item.

  • Job Status This method returns the status of an Automation Services job.

Execute Timeout MS (int) The time in MS to wait for a job execution to finish. This option is available when the service type is Execute Job.
Execute Finished Status (string) The status result that will determine if an execution job has finished. This option is available when the service type is Execute Job.
Library Source (radio button) Indicates the type of value that will be given as the source for the library job load. Note that the API client must have sufficient library permissions to access the library item.
  • Library Id loads a library job by ID.

  • Library Path loads a library job by path.

Library Source Value (string) The value of the library item to load
Job Source (radio button) This option specifies how the Job XML data will be loaded into the adapter. If File is selected, the Job File Name field is enabled to select which file is sent. If Job XML is enabled, paste the Job XML data directly into the Job XML parameter field.
Job File Name (string) The full path to the file that contains the Job XML data to send to the Spotfire automation service. This option is enabled when Job Source is set to File.
Job XML (string) The full Job XML data to send to the Spotfire automation service. This option is enabled when Job Source is set to Job XML.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Description of This Adapter's Ports

The Spotfire Automation Services adapter's ports are used as follows:

  • Control (input): Tuples enqueued on this port cause the adapter to send a request to the Spotfire automation service. The schema for this port contains the following fields:

    • (Optional) ReplacementFields, tuple. A tuple containing zero-to-many subfields that will be matched to parameters in the Job XML.

    • (Optional) SpotfireURL, string. The base Spotfire URL to which to send requests. If null, the URL is taken from the adapter's Spotfire URL property.

    • (Optional) JobId, string. The Job Id for which to request status from the automation service. If null, the JobId is taken from the adapter's JobId property. This parameter is used only when the Service Type is set to Job Status.

    • (Optional) JobXML, string. The complete Job XML data to send to the Spotfire automation service. If null, the JobXML is loaded depending on the Job Source property. This parameter is used only when the Service Type is set to Launch Job or Execute Job.

    • (Optional) JobFileName, string. The complete path to the file to load the job XML data, which is then sent to the Spotfire automation service. If null, the JobXML is loaded depending on the Job Source property. This parameter is used only when the Service Type is set to Launch Job or Execute Job

    • (Optional) ConnectionTimeout, int. The timeout value to use for this connection.

  • Data (output): Tuples are emitted on this port when a service request is completed. The schema for this port contains the following fields:

    • Status, string, The status received back from the Spotfire automation service.

    • Message, string, The message received back from the Spotfire automation service.

    • JobId, string, The Job Id associated with the request.

    • InputTuple, tuple, A copy of the tuple inputted on the control port.

  • Status (output): The adapter emits tuples from this port when significant events occur, such as when an attempt to read a Spotfire automation service page fails. The schema for this port contains the following fields:

    • Type, string: returns one of the following values to convey the event type:

      • Read

      • UserInput

    • Action, string: returns an action associated with the event type:

      • Failed

      • Rejected

    • Object, string: returns an event type-specific value, such as the Spotfire URL for which a read failed or the control input tuple that was rejected.

    • Message, string: Returns a human-readable description of the event.

Using Replacement Fields

The Spotfire Automation Services adapter allows you to add parameterized fields into your Job XML, which are replaced during runtime with the incoming tuple's values.

To use replacement fields you must edit your Job XML and include any parameters you need in the format $[ParamName]. You must also then edit your input schema and add subfields to the ReplacementFields field with the same name as your ParamName. You can add as many fields to ReplacementFields as needed; each parameter found in the Job XML will be matched to a subfield in the ReplacementFields and that value is used to replace the parameter.

Typechecking and Error Handling

The Spotfire Automation Services adapter uses typecheck messages to help you configure the adapter within your StreamBase application. In particular, the adapter generates typecheck messages for the following reasons:

  • The input schema does not contain a field named ReplacementFields of type tuple on the input schema.

  • The Spotfire URL is empty. No SpotfireURL value is provided on the input schema.

  • The service type is set as Job Status and the Job Id is empty. No JobId field is provided on the input schema.

  • The service type is set as Execute Job, or Launch Job, and the Job Source is set to File; the Job File is empty or invalid and no JobFile field is provided on the input schema.

  • The service type is set as Execute Job, or Launch Job, and the Job Source is set to Job XML; the Job XML is empty and no JobXML field was provided on the input schema.

The adapter generates warning messages during runtime under various conditions, including:

  • A control tuple is received with a null value in its SpotfireURL field and a value for the adapter's Spotfire URL property was not specified.

  • A control tuple is received with a null value in its JobXML field and the JobFileName field and a value for the adapter's Job XML property, along with the Job File Name, was not specified. This message means no Job XML can be loaded from any source.

  • A control tuple is received with no field named ReplacementFields.

  • A control tuple is received and the adapter is unable to connect to the SpotfireURL, or process the job.

Related Topics