Using the TIBCO ActiveMatrix BPM Operator

This topic describes how to use the TIBCO ActiveMatrix BPM® operator to interact with an ActiveMatrix BPM Server, and explains how to configure the operator's Properties view.

Introduction

The TIBCO ActiveMatrix BPM operator wraps ActiveMatrix BPM REST APIs to allow for any of the REST methods to be easily called from within a StreamBase application.

Placing the ActiveMatrix BPM Operators on the Canvas

The ActiveMatrix BPM operator is a member 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, select the following related operator and double-click or press OK:

  • TIBCO ActiveMatrix BPM, which wraps access to the ActiveMatrix BPM REST API.

Properties View Settings

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

General Tab

Name: Use this required field to specify or change the component's name, which must be unique in the current 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: 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 with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this operator starts as part of the JVM engine that runs this EventFlow fragment. If this field is set to No or to a module parameter that evaluates to false, the operator instance is loaded with the engine, but does not start until you send an epadmin container resume command (or its sbadmin equivalent), 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.

Operator Properties Tab

Property Description
URL The URL endpoint with variables denoted with '<variable>' which will be replaced with the pathParameters field data passed in, these values will match on the key field and replace with the value field.
HTTP Request Type The type of HTTP operation to use with this service call.
Enable Pass-Through Fields Enable the pass-through fields to allow all fields of the incoming control tuple to be copied to the outgoing data tuple.
Enable Status Port Enable the status port.
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.

Edit Schema Tab

For general instructions on using the Edit Schema tab, see the Properties: Edit Schema Tab section of the Defining Input Streams page.

Note

Please note that every request sent has the query parameter of responsetype=json applied to ensure the result is returned in JSON format.

Use this tab to specify the schema to use when receiving results from the REST API call. Characters in field names from AciveMatrix BPM that would be subject to the StreamBase escaped identifier rules such as "@" and "-" are automatically removed. If the result is wrapped in an xml-fragment object, that is also automatically removed. Specify your schema starting with the first underlying data set.

For Example:  

{
  "xml-fragment": {
    "start-Position": 0,
    "end-Position": 2,
    "total-Items": 2,
    "businessCategory": [
      {
        "@name": "WelcomeUsersImplementSolution",
        "ChildBusinessCategory": {
          "@name": "ProcessPackage",
          "BusinessServiceTemplate": {
            "@moduleName": 
              "/WelcomeUsersImplementSolution/Process Packages/ProcessPackage.xpdl",
            "@version": "1.0.0.201301021250",
            "@processName": "RequestCall",
            "@hasFormalParameters": "false"
          }
        }
      }
    ]
  }
}

Converts to the following before matching the schema:

{
  "startPosition": 0,
  "endPosition": 2,
  "totalItems": 2,
  "businessCategory": [
    {
      "name": "WelcomeUsersImplementSolution",
      "ChildBusinessCategory": {
        "name": "ProcessPackage",
        "BusinessServiceTemplate": {
          "moduleName": 
            "/WelcomeUsersImplementSolution/Process Packages/ProcessPackage.xpdl",
          "version": "1.0.0.201301021250",
          "processName": "RequestCall",
          "hasFormalParameters": "false"
        }
      }
    }
  ]
}

Connection Tab

Property Description
Connect timeout Sets a specified timeout value, in milliseconds, to be used when opening. A timeout of zero is interpreted as an unlimited timeout.
Read timeout Sets a specified timeout value, in milliseconds, to be used when reading. A timeout of zero is interpreted as an unlimited timeout.
Use Proxy Use a proxy server in processing the HTTP GET request.
Proxy Host The proxy server host name or IP address.
Proxy Port The proxy server TCP port number.
Ignore certificate errors 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.
Authentication The type of authentication used when doing a request to the service.
Username When basic authentication is enabled this is the username that will be sent to the server.
Password When basic authentication is enabled this is the password that will be sent to the server.
Poll Interval The number of milliseconds to wait between calling the services. The adapter will use the last input tuple as the values when calling the service. A value of 0 will disable polling.

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 Schema Fields

The input schema may contain various fields to push data into the BPM Operator (case sensitive). The fields listed below are all optional.

Field Name (case sensitive) Description
pathParameters The field that contains the list<tuple<string key, string value>> data for replacing any templated items in the URL. Leave blank to ignore this field.

Note

The key value will be matched against any '<variable>' in the URL and replace it with the 'value' field.

queryParameters The field in the input schema that contains the list<tuple<string key, string value>> data used to add any query parameters to the REST request. Leave blank to ignore this field.

Note

A query parameter of 'responsetype=json' is always applied to enforce the results return in JSON format.

body The field in the input schema that contains the information to be sent as the body (expected to be in JSON format). Leave blank to ignore this field.

Note

The body field is always wrapped in the following format before sending to the server '<payload payloadMode="JSON"><serializedPayload>{BODY}</serializedPayload></payload>'

pollInterval The field in the input schema that determines the polling interval in milliseconds to set for this service request. This value must be 0 or greater, any value less than 0 will be considered 0. If the value is 0 then current polling will be disabled.

ActiveMatrix BPM Operator Sample

The StreamBase installation comes with a sample demonstrating the use of this operator. To load the sample in StreamBase Studio, select File>Load StreamBase Sample and look under the Extending StreamBase section for an entry called ActiveMatrix BPM Operator.