TIBCO Scribe® Online Connector For OData

The TIBCO Scribe® Online Connector for OData (Open Data Protocol) enables you to interact with data via REST interfaces and provides a uniform way to describe the data and the data model.

Connector Specifications

This Connector supports up to and including OData protocol version 4.0.

	Supported
Agent Types
Connect on-premise	X
Connect cloud	X
Data Replication Apps
Source
Target
On Schedule Apps
Source	X
Target	X
On Event Apps
Source
Target
Flows
Integration	X
Request-Reply
Message

OData Requirements

If the data source to which you are connecting requires basic authentication, you must provide that authentication when configuring the Connection in TIBCO Cloud™ Integration - Connect. If your OData service does not require authentication, the OData Connector configuration in TIBCO Cloud™ Integration - Connect does not require authentication either. For more information on authentication, contact your OData service administrator.

For more information on the OData protocol, see the OData website.

Selecting An Agent Type For OData

Refer to TIBCO Cloud™ Integration - Connect Agents for information on available agent types and how to select the best agent for your app.

Connecting To OData

1. Select Connections from the menu.
2. From the Connections page select Create to open the Create a connection dialog.
3. Select the Connector from the list to open the Connection dialog, and then enter the following information for this Connection:
   • Name — This can be any meaningful name, up to 25 characters.
   • Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
   • OData Service URL — Address of any acceptable URL where the OData service is located.
   • User — Name of the user with rights to access OData, if your OData service requires authentication.
   • Password — Password for User, if your OData service requires authentication.

     For more information on OData, see your endpoint provider.

4. Select Test to ensure that the agent can connect to your database. Be sure to test the Connection against all agents that use this Connection. See Testing Connections.
5. Select OK/Save to save the Connection.

Metadata Notes

OData Metadata

Only supported OData data types appear in TIBCO Cloud™ Integration - Connect. The following data types are not supported by this Connector:

• Edm.Geography
• Edm.GeographyPoint
• Edm.GeographyLineString
• Edm.GeographyPolygon
• Edm.GeographyMultiPoint
• Edm.GeographyMultiLineString
• Edm.GeographyMultiPolygon
• Edm.GeographyCollection
• Edm.Geometry
• Edm.GeometryPoint
• Edm.GeometryLineString
• Edm.GeometryPolygon
• Edm.GeometryMultiPoint
• Edm.GeometryMultiLineString
• Edm.GeometryMultiPolygon
• Edm.GeometryCollection
• Edm.Stream

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

Endpoint Support

• The Connector does not currently support the FunctionImport or ActionImport OData features.

Data Types

• The Connector converts DateTime data types on the OData protocol versions as follows:

  Data Type	Converted in TIBCO Cloud™ Integration - Connect
  	OData V3	OData V4
  Edm.DateTime	DateTime	N/A
  Edm.DateTimeOffset	String	DateTime (UTC)

Supported Blocks

This Connector supports the following Blocks:

• Query
• Create
• Delete
• Fetch
• Lookup
• Update Patch
• Update Patch Singleton
• Update Replace
• Update Replace Singleton
• Update Merge
• Update Insert
• Upsert Patch
• Upsert Replace

Singletons

A singleton represents a single entity in an entity model.

• The OData Connector supports the following Blocks for singletons:
  • Query
  • Update Patch Singleton
  • Update Replace Singleton

  The Update Patch Singleton and Update Replace Singleton Blocks only appear if a Singleton is defined in the Entity Data Model.

• Filtering and Lookups are not supported on singletons.
• Multiple singletons on an OData resource are supported.

Relationships

• Hierarchical relationships, such as grandparent, parent, grandchild relationships are not supported. See Hierarchical Data for examples.
• Self joins and outer joins are supported. In an OData relationship, only outer joins are supported. For more information about joins, see Joins.

OData Queries

• If you create a flow that queries a large number of fields, the URL that is generated may be very long. Some services, cannot process long URLs even though the URLs are valid. An error is returned when you attempt to run the flow. To work around this issue, create multiple flows with fewer fields in each flow.

Update Operations

• If you try to use an operation that is not implemented in your OData endpoint, you may see an error message.
• Update/Insert — If your OData service is implemented to support more than one Update operation, TIBCO Cloud™ Integration - Connect cannot anticipate which of these Update operations to use in a Block.
  Note: Best practice is to use separate Update and Insert Blocks, not the Update/Insert Block.
• TIBCO Cloud™ Integration - Connect supports the Update Merge, Update Patch, and Update Replace operations supported by OData. However, OData support for these operations varies by OData version.

Update Replace

• A replacement update issues a PUT request. The OData service replaces all property values with those specified in the request.
• Any properties not included in the request, or any unmapped fields, are either cleared or set to default values for the OData service. Any data in fields with unsupported data types is lost. See OData Metadata.

Update Patch And Update Merge

• These are different updates that issue a PATCH or a MERGE request. The OData service replaces exactly those property values that are specified in the request, or mapped fields.
  • Any properties not included in the request are not altered.
  • Any field containing a NULL value or an empty string overwrites any value previously in that field.
  Note: Update Merge is not supported in OData V4.

Upsert

• Upsert Blocks support the PATCH and PUT operations.

Filtering

When a datetime is configured on the Query block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Cloud™ Integration - Connect builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.

Some Connectors for TIBCO Cloud™ Integration - Connect only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

• The OData Connector supports the following filtering operations, based on the filtering operations supported by your OData service.
  • Like/Not Like
  • And/Or
• And/Or filter sequences are handled from top to bottom.
• OData associations support filtering.

Batch Processing

• The OData Connector supports Batch Processing for Create, Update, Upsert, and Delete operations if your OData service also supports Batch Processing for those operations. The number of records allowed per batch varies depending on the OData service.

Optimistic Concurrency

• The OData Protocol uses Entity Tags (ETag) to determine how to update or delete data. Rules for updating or deleting data are based on the ETag value and the concurrency behavior. There are three options for concurrency behavior: always overwrite, overwrite if ETag has not changed, or overwrite if Etag has changed.

  The OData Connector exposes these ETags as fields:

  • ETag — Available as a source and target field, contains the ETag value provided by the OData service.
  • ETagConcurrencyBehavior — Available as a target field, used to determine how data conflicts are handled. Possible values for this field are:
    • Always Overwrite
    • Overwrite If Match
    • Overwrite If Not Match

  If these fields are left blank and the entity provides ETag information, the default is to always overwrite the record.

• Delete operations always perform the default behavior. There is no way to map fields within a Delete Block. Therefore, if you attempt to use a Delete Block operation it always overwrites the existing data.
• Optimistic Concurrency is an optional OData feature supported in some OData services, but not all. This option is limited to specific entities. Contact your OData service administrator for additional information.

Conditional Success

When you Insert or Update a record, some services may indicate success but also return error information in the response. When this occurs, refer to your OData service documentation for further information, and review the record for accuracy.

For example, if a record is inserted without providing a required field, an OData service may return a successful status code but the response will have error information stating that the field is required. The OData service has committed the record but it could be inaccurate and possibly unusable. In this case, the TIBCO Cloud™ Integration - Connect app execution will yield a record error. However, the corresponding records in the actual application may still need values for the required fields.

TIBCO Cloud™ Integration - Connect API Considerations

You must define a Connection Name and Connection Alias for each OData endpoint.

Connector Name	OData
Connector ID	A2A3DE52-0A88-4E1F-8788-693CF6BEA505

TIBCO Cloud™ Integration - Connect Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

Name	Data Type	Required	Secured	Usage
ServiceUrl	string	Yes	No
User	string	No	No
Password	string	No	Yes
AuthenticationType	string	Yes	No	None,Basic

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.