IS2 Or MS2 Connector Methods

IS2 Or MS2 Connector Overview

The following diagram details the interaction between the various methods, the Agent, and an IS2 or MS2 Connector. Review the methods listed below the diagram.

IS2/MS2 Methods

To develop a TIBCO Scribe® Integration Services Connector, implement each of these methods.

Use the IS2 methods to implement a Connector using either a standard login page or a REST Web Services Connection using OAuth protocols.

IConnector.Preconnect

Allow a Connector to define the user interface (UI) that users use to create Connections. There are two ways to implement Preconnect:

• As shown in the IS2 Sample Connector, use Preconnect to specify any fields, such as Username, Password, or Database Name, that require user input to connect to your technology.
• As shown in the REST Web Services Sample Connector, use OAuth to validate the connection. To support OAuth, implement a public PreConnect method that returns the OAuth REST URI as a string type.

Once a Connection has been created, Preconnect is only called again if a user re-opens the Connection UI to adjust the connection settings.

IConnector.Connect

Connect instructs the Connector to open communication with its datastore, if initialization of the Connection is required for your technology. If it is not required, this method is expected to test that the Connection is possible.

• For a non-OAuth Connection, the Connector can choose to maintain or drop this Connection as needed while the Connector is in use.  Even if your Connector does not use Connect to initialize a Connection and keep it open, use the Connect method to test that a connection can be made when it is called.
• To implement a Connection using OAuth, set the ConnectionUITypeName property equal to "ScribeOnline.Views.OAuthConnectionUI".
  
  

  This allows you to provide an OAuth interface that handles the correct routing and information transfer to generate the TIBCO Scribe® OAuth Connection interface.

  When logging in via OAuth, the Preconnect method will already have pushed the user to the client's login page to log in. Once the user is redirected back to TIBCO Scribe®, Connect captures their authorization code in the Connection properties. The first time Connect() runs:

  1. The Connector parses the code query string.
  2. Use this code to authenticate against the REST URI to get the user's access token.
  3. When the Connector receives the token, encrypt it and store it in memory.

  On successive Connect calls, the access token is available from memory to be passed to other REST calls.

IConnector.Disconnect

Disconnect is called to instruct the Connector to close communication from its datastore and free any resources that may be associated with the connection.

OAuth Connections for REST Web Services do not require a constant Connection. For an OAuth Connection, this method sets the IsConnected property to "false" and logs the event.

IConnector.ExecuteOperation

ExecuteOperation is called by TIBCO Scribe® to perform an operation, such as Create, CreateWith, Update, UpdateWith, or Delete, on a given data object type, for example, an Account. Implement as many of these operations as possible, as dictated by your data technology. These operations are passed with the OperationInput object, which describes the details of the operation, such as: matching criteria, fields to map, and other operation details.

IConnector.ExecuteOperation operations are:

• Create — A new record is inserted into the data source.
• CreateWith — An entire complex object is inserted into the data source.
• Delete — The record specified by the OperationInput LookupCondition is deleted.
• Update — The record specified by the OperationInput LookupCondition is updated with the specified values.
• UpdateWith — A complex object specified by the OperationInput LookupCondition is updated with the specified values.
• Upsert — A single-step Insert/Update operation. If a record exists that matches the OperationInput LookupCondition, it is updated. If a matching record is not found, a new record is inserted.

For IS2 or MS2, you should include the values of as many fields as possible in the target record of the OperationResult object that you return.

IConnector.ExecuteQuery

ExecuteQuery is called by TIBCO Scribe® as a request for specific data from the Connector. The query object received by this method may include constraint information as well as information about which object or objects are being queried.

An ExecuteQuery implementation must:

• Filter an Entity on the specified conditions, with multiple conditions AND’ed together. For IS2 or MS2, you must also support conditions linked with both AND’s and OR’s.

  Important: When possible, include any filters in the call to your datastore technology rather than requesting all records and filtering the data yourself.

• Return only the fields/properties that are requested in the property lists, including fields from related entities if they are specified in your metadata.
• Perform queries including linked entities as an outer join. You must also be able to support inner join.

For more information about queries, see Managing Filtered Queries.

IConnector.GetMetadataProvider

GetMetadataProvider is a required method called by TIBCO Scribe® to retrieve an active instance of the Object that inherits the IMetadataProvider interface. This allows TIBCO Scribe® to access the IMetadataProvider specific methods.

ISupportMessage.ProcessMessage

Allow a Connector to process a message, returning one or more DataEntity objects.

IMetadataProvider.RetrieveActionDefinitions

RetrieveActionDefinitions is a required method called by TIBCO Scribe® to ask the Connector which KnownActionTypes, along with certain attributes such as bulk operations, are supported in the Connector on a global level. Known action types include Create, Update, Upsert, Delete. In addition, if supported by your datastore technology, you can use this method to specify bulk operations.

RetrieveActionDefinitions should return a collection of IActionDefinitions describing your Connector's capabilities. At a minimum, this method should return a "Query" action to allow TIBCO Scribe® to retrieve data.

For example:

var action = new ActionDefinition

{

Name = "Query",

FullName = "Query",

SupportsMultipleRecordOperations = true,

SupportsLookupConditions = false,

SupportsBulk = false,

SupportsConstraints = true,

SupportsRelations = true,

SupportsSequences = true,

KnownActionType = KnownActions.Query

};

Unsupported Operations

If a Connector does not support an operation, then the ObjectDefinitions returned from the Connector cannot allow for the action, and IConnector.ExecuteOperation is not required.

Bulk Operations

If available for the Connector, you can specify bulk support for an operation by setting the SupportsBulk property on the corresponding ActionDefinition. If SupportsBulk is selected for an operation, TIBCO Scribe® sends an array of up to 10,000 records to the Connector in a single operation request. These records are sent in the form of DataEntity and LookupCondition objects stored in the OperationInput.Input parameter.

Each Expression stored in the OperationInput.LookupCondition array is related to each item in OperationInput.Input by the corresponding index. As the Connector developer, you need to ensure that all results of the operation are returned with the same index with which they were received.

IMetadataProvider.RetrieveObjectDefinitions

RetrieveObjectDefinitions is called as a part of any IS2 or MS2 job creation, requesting a complete list of metadata object definitions. For example, a SQL Connector would provide table information that includes all columns and attributes for each column, all child to parent foreign key relationships, and if the table allows for one/many or all CRUD operations.

Each ObjectDefinition requires one or more PropertyDefinitions that represent the fields associated with the object. By default, the entities are handed to TIBCO Scribe® without their fields. When a user drills into individual entities, TIBCO Scribe® calls back to the Connector and asks for the fields. To support complex hieracrchal data, ObjectDefinitions can be included as part of other ObjectDefinitions, allowing them to have no actions. The nesting of objects within objects can go beyond one level. For more information on hierarchical data, see Hierarchical Data — Sample Connector Code.

To create the PropertyDefinitions collection, either:

• Move it to a separate, private method as shown in the REST Web Services sample code.
• Create it inline with the rest of the RetrieveObjectDefinition method.

IMetadataProvider.RetrieveObjectDefinition

RetrieveObjectDefinition is a required method called by TIBCO Scribe® to ask the Connector for a single metadata object definition. For example, a SQL Connector must provide table information that includes all columns and properties for each column, all child to parent foreign key relationships, and if the table allows for one/many or all CRUD operations.

IMetadataProvider.ResetMetadata

ResetMetadata is a required method called by TIBCO Scribe® to inform the Connector that the user wants TIBCO Scribe® to be aware of any schema changes to the data source. If you are caching information about object or field names, you need to clear this cache so that schema changes are visible in TIBCO Scribe®.

See Also

Managing Filtered Queries

Testing A Connector

Using The IS2 Sample Connector

Using The REST Web Service Sample Connector

CDK Key Concepts