Using the WITSML Operators

Contents

Introduction
Properties View Settings
Input Ports
Output Ports
Log Data Converter
Related Topics

This document describes how to use the suite of Wellsite Information Transfer Standard Markup Language (WITSML) operators.

Introduction

The TIBCO WITSML adapter connectivity solution is implemented as a suite of fourteen global Java operators that allow a StreamBase application to connect to a WITSML data store, and to allow read, write, and delete operations on the log, well, wellbore, and trajectory data types.

The TIBCO WITSML connectivity solution is intended for the oil and gas industry to retrieve and send well data between well operators, service companies, and regulatory agencies.

The operators are designed to work with the client-server API WMLS STORE interface; the WMLP PUBLISH interface has not been implemented.

The list of supported operations and operators is described below.

Placing WITSML Operators on the Canvas

The WITSML operators are members of the Java Operator group in the Palette view in StreamBase Studio. Select the operators from the Insert an Operator or Adapter dialog. Invoke the dialog with one of the following methods:

  • Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.

  • Click in the canvas where you want to place the operator, and invoke the keyboard shortcut O V

  • From the top-level menu, invoke Insert>Operator>Java.

From the Insert an Operator or Adapter dialog, enter witsml to narrow the list of operators. Then select one of the following WITSML operators, and double-click or press OK:

  • TIBCO StreamBase® Adapter For WITSML STORE Server Capabilities, which reads server capabilities.

  • TIBCO StreamBase® Adapter For WITSML STORE Read, which reads data based on given options.

  • TIBCO StreamBase® Adapter For WITSML STORE Read Log, which reads log data.

  • TIBCO StreamBase® Adapter For WITSML STORE Read Well, which reads well data.

  • TIBCO StreamBase® Adapter For WITSML STORE Read Wellbore, which reads wellbore data.

  • TIBCO StreamBase® Adapter For WITSML STORE Read Trajectory, which reads trajectory data.

  • TIBCO StreamBase® Adapter For WITSML STORE Delete, which deletes records based on given options.

  • TIBCO StreamBase® Adapter For WITSML STORE Delete Log, which deletes log records.

  • TIBCO StreamBase® Adapter For WITSML STORE Delete Well, which deletes well records.

  • TIBCO StreamBase® Adapter For WITSML STORE Delete Wellbore, which deletes wellbore records.

  • TIBCO StreamBase® Adapter For WITSML STORE Delete Trajectory, which deletes trajectory records.

  • TIBCO StreamBase® Adapter For WITSML STORE Write, which writes records based on given options.

  • TIBCO StreamBase® Adapter For WITSML STORE Write Log, which writes log records.

  • TIBCO StreamBase® Adapter For WITSML STORE Write Well, which writes well records.

  • TIBCO StreamBase® Adapter For WITSML STORE Write Wellbore, which writes wellbore records.

  • TIBCO StreamBase® Adapter For WITSML STORE Write Trajectory, which writes trajectory records.

  • TIBCO StreamBase® Adapter For WITSML Log Data Convert, which takes in data read from the Read Log adapter and converts the comma separated strings to data tuples.

Properties View Settings

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

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

Operator: A read-only field that shows the formal name of the operator.

Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.

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 Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Operator Properties Tab

This section describes the properties on the Operator Properties tab in the Properties view for the WITSML operators. Enter all text fields as string literals, not as expressions.

Common Properties

All WITSML operators have a common set of properties:

Property Type Description
Service URI string The URI that points to the WITSML service endpoint. This value can be overridden at Runtime by using the input tuple with a field named connection.serviceURL.
Enable Authentication check box When enabled, the adapter uses the given user name and password to authenticate with the server.This value can be overridden at Runtime by using the input tuple with a field named connection.useAuth.
Username string When authentication is enabled, this user name is sent as part of the credentials.This value can be overridden at Runtime by using the input tuple with a field named connection.username.
Password string When authentication is enabled, this password is sent as part of the credentials.This value can be overridden at Runtime by using the input tuple with a field named connection.password.
Witsml Version combo Specifies which WITSML version will be used when performing the operation against the server. Depends on the version selected the input schema to the operator should match the WITSML specification for that version. Currently the operators proposed schemas will generate 1.3.1.1 schemas, if 1.4.1.1 is required the generated schema by the adapter can be used as a guidelines and modified to conform to the 1.4.1.1 specification.This value can be overridden at Runtime by using the input tuple with a field named connection.witsmlVersion.
Read Timeout (ms) int Specifies the number of milliseconds to allow to pass before failing on a read. Default: 30000. This value can be overridden at Runtime by using the input tuple with a field named connection.readTimeout.
Connect Timeout (ms) int Specifies the number of milliseconds to allow to pass before failing on a connection. Default: 15000. This value can be overridden at Runtime by using the input tuple with a field named connection.connectTimeout.
WITSML Date Format string The date format used by the WITSML server. The date format supplied must be a valid pattern for SimpleDateFormat. This value can be overridden at Runtime by using the input tuple with a field named settings.datetimeFormat.
Add Passthrough Field check box When enabled, a field named passthrough will be added to output tuples to contain the input tuple that triggered them.

Note

This property is only available on the Reader adapter variants and the Server Capabilities adapter.

Enable Status Port check box When enabled, a status port is available to emit status tuples for various events of this operator.
Include Input Tuple In Status And Traces check box When enabled, status tuples (as well as console log messages, when applicable) will contain a copy of the input tuple that triggered them.
Log Level INFO Controls the level of verbosity the adapter uses to issue informational traces to the console. This setting is independent of the containing application's overall log level. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Generic Operator Properties

Generic WITSML operators Read/Write/Delete have 2 additional properties to specify the main and child objects to query:

Property Type Description
Main Object string The main object to query against. For instance if you want to query for log data this value would be 'logs' or for rig data this value would be 'rigs'.
Child Object string The main object to query against. For instance if you want to query for log data this value would be 'log' or for rig data this value would be 'rig'. When using the operator input schema with this field as a tuple will be used as the field schema to run a query with.

Proxy Properties

All WITSML operators have a common set of proxy properties:

Property Type Description
Use Proxy check box Use a proxy server to access the URL. This value can be overridden at Runtime by using the input tuple with a field named connection.useProxy.
Proxy Host string The proxy server host name or IP address. This value can be overridden at Runtime by using the input tuple with a field named connection.ProxyServer.
Proxy Port string The proxy server port number. This value can be overridden at Runtime by using the input tuple with a field named connection.proxyPort.
Proxy User string The username to use with the proxy if required. This value can be overridden at Runtime by using the input tuple with a field named connection.proxyUsername.
Proxy Pass string The password to use with the proxy if required. This value can be overridden at Runtime by using the input tuple with a field named connection.proxyPassword.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

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

Input Ports

Each operator has only one input port, which is used to start a data operation to the WITSML store.

Each WITSML operator embeds a set of proposed full 1.3.1.1 schemas for each operation type that you can use as a starting point when defining the schemas for the witsml field.

The best way to start is to import the proposed schemas for each operator by selecting the Import Proposed Schemas hyper link in the top right corner of the Operator Properties tab of the Properties view for each operator. Specify the name of an EventFlow module file, and the selected schemas are imported as Named Schemas into the Definitions tab of that module.

All Operators

Field Name Field Type Description
witsml list(tuple(witsml fields)) This is the main witsml field. If this field is missing or empty, the least amount of schema for the data type is used when querying the data store. For example, if this is a read well operator and the witsml field is missing, it is assumed that you are requesting only the UID field from the server. This list of tuples can be as few or as many fields as required. For example, you can provide the following to request only the UID for a well. 
Schema - list<tuple<uid string>>>
Example usage - list(tuple('abc123' as uid)) as witsml
Another example for a read operation to query for any well with a state of fl or oh but return country, state, and county would be: 
Schema - list<tuple<country string, state string, county string>>>
Example usage - list(
   tuple(string() as country, 'fl' as state, string() as county), 
   tuple(string() as country, 'oh' as state, string() as county)
) as witsml
settings.datetimeFormat string This optional field can be used to set the adapters data time format for each tuple that is sent in. If this field is missing, null, or empty the date time format from the adapters properties will be used.
connection.serviceURI string The URI that points to the WITSML service endpoint.(optional)
connection.username string When authentication is enabled, this user name is sent as part of the credentials.(optional)
connection.password string When authentication is enabled, this password is sent as part of the credentials.(optional). This value may be encrypted using the epadmin encrypt console command.
connection.connectTimeout int Specifies the number of milliseconds to allow to pass before failing on a connection. Default: 15000 MS.(optional)
connection.readTimeout int Specifies the number of milliseconds to allow to pass before failing on a read. Default: 30000 MS.(optional)
connection.witsmlVersion combo Specifies which WITSML version will be used when performing the operation against the server. Depends on the version selected the input schema to the operator should match the WITSML specification for that version. Currently the operators proposed schemas will generate 1.3.1.1 schemas, if 1.4.1.1 is required the generated schema by the adapter can be used as a guidelines and modified to conform to the 1.4.1.1 specification.(optional)
connection.witsmlDateFormat string The date format used by the WITSML server. The date format supplied must be a valid pattern for SimpleDateFormat.(optional)
connection.useAuth boolean When enabled, the adapter uses the given user name and password to authenticate with the server.(optional)
connection.useProxy boolean When enabled, the adapter uses proxy server to access the URL.(optional)
connection.proxyServer string The proxy server host name or IP address.(optional)
connection.proxyPort int The proxy server port number.(optional)
connection.proxyUsername string The username to use with the proxy if required.(optional)
connection.proxyPassword string The password to use with the proxy if required.(optional) This value may be encrypted using the epadmin encrypt console command.

Write Operators

Field Name Field Type Description
addToStore boolean This optional value determines whether the current request should be an add-to-store request or an update-in-store request. If this value is missing or null, it is assumed the request is an add-to-store request.

Output Ports

Each WITSML operator has only one fixed output port. The port delivers the results of executing operator commands. There also is one optional Status output port if the operator's Enable Status Port option on the Operator Properties tab is selected.

Results Port

The Results Port differs for each WITSML read operator.

Read Log Operator And Log Data Convert Operator

Field Name Field Type Description
logs tuple Contains the logs retrieved from the WITSML store as a result of a query received on the input port. This port's schema is determined by the input ports schema. The fields from the input schema's witsml field element data type (the tuple schema in the list) is used to create the schema in this output.
passThrough tuple The input tuple is passed through to the output using this field.

Read Well Operator

Field Name Field Type Description
wells tuple Contains the wells retrieved from the WITSML store as a result of a query received on the input port. This port's schema is determined by the input port's schema. The fields from the input schema's witsml field element data type (the tuple schema in the list) is used to create the schema in this output.
passThrough tuple The input tuple is passed through to the output using this field.

Read Wellbore Operator

Field Name Field Type Description
wellbores tuple Contains the wellbores retrieved from the WITSML store as a result of a query received on the input port. This port's schema is determined by the input port's schema. The fields from the input schema's witsml field element data type (the tuple schema in the list) are used to create the schema in this output.
passThrough tuple The input tuple is passed through to the output using this field.

Read Trajectory Operator

Field Name Field Type Description
trajectorys tuple Contains the trajectorys retrieved from the WITSML store as a result of a query received on the input port. This port's schema is determined by the input port's schema. The fields from the input schema's witsml field element data type (the tuple schema in the list) are used to create the schema in this output.
passThrough tuple The input tuple is passed through to the output using this field.

Status Port

The Status Port, when enabled, is the same for all WITSML operators.

Field Name Field Type Description
type string Describes the type of status message: INFO, WARN, ERROR.
action string The type of action this status message is about.
object string A formatted string with any object data associated with this status message.
message string A human readable message that describes the status.
time timestamp The time of the status message.
inputTuple tuple A copy of the tuple that started the operation that this message is associated with.

Log Data Converter

The Log Data Converter operator is a special case operator that takes in the output from the Read Log operator and converts the string data in the logs.log.logData.data field into actual tuples.

The operator works by matching the logCurveIndex mnemonic field to a data schema field, if a field is present with the name the value will be set. Optionally you can also do mapping of mnemonic values to a schema field using the Data Mapping property.

The input to this operator must match the output schema of the Read Log operator, the operator will convert the logs.log.logData.data field from a list(string) to a list(tuple) using the provided data schema.

The input to this operator may also optionally contain the settings.datetimeFormat field to override the default date time format for each tuple to be processed.

Parameters

The Log Data Converter requires the following parameters across the Operator Properties, Edit Schema, and Mapping tabs:

Field Name Field Type Description
Data Schema Schema This is the schema that will be used as the log data conversion output.
Data Mapping Map This property specifies which log curve info mnemonic values will be converted to which data schema field. If a field in the data schema does not match any from this map, then the system tries to match the mnemonic directly to a data schema field.
Output Type drop down The type of output to convert the log data into.

  • Schema — The user defined schema will be used to match log mnemonics to each field of the schema.

  • Key Value — The output will be a list(tuple(key string, value string)) for each data point.

  • JSON — The output be a JSON string with a mnemonic to value data point entries.

Output Tuple Per Row check box If enabled, a tuple will be output per log data row instead of one tuple with a list of data rows.
Missing Data Value string An optional value to set for fields that have no value.
Include Missing Fields check box If enabled, then fields in the schema that cannot be matched to a Log Curve also receive the missing data value.
WITSML Date Format string WITSML server's data format. The date format supplied must be a valid pattern for SimpleDateFormat. This value can be overridden at runtime by using the input tuple with a field named 'settings.datetimeFormat'.
Enable Status Port check box If enabled, a status port will be available which will emit status tuples for various events of this operator.

Related Topics

Back to Top ^