OData

The OData Service Type enables you to call methods from OData-compliant service endpoints by exposing these methods as SmartObjects.

OData is the protocol that enables the creation and consumption of REST APIs. These APIs allow URL-based resources (defined by a data model) to be accessed and used via HTTP messages. It shares some similarity with JDBC and ODBC, but OData is not limited to relational databases. The following resources contain additional background information on the OData protocol. This topic assumes that you are familiar with OData, so it might be worthwhile to read the links below before attempting to use the broker.

The K2 OData endpoint broker is similar to the other endpoint brokers in that it exposes entities, objects and system types based on an OData endpoint.

Service Authentication

The following Authentication Modes may be used with the OData Service Type:

  • Impersonate
  • OAuth
  • ServiceAccount
  • Single Sign-on
  • Static

Service Keys (Service Instance Configuration Settings)

Service Key

Default value

Description

OData Service Url

The URL to the OData Service.

Add HTTP Response Header Property To Methods

False

Adds an optional property to each method to allow for a list of HTTP Response headers to be returned from the service.

Ignore Error When Record Is Not Found

False

Tells the service broker whether it should throw an error when it fails to find a record.

Metadata Url Or File Path

null

Some OData services may restrict who has access to its metadata or choose to store its metadata in another location. To accommodate this, this config setting takes an alternative local file path or external url pointing to the service’s metadata.

Add Query Options Property To Methods

False

This setting adds the Query Options input property to the Entity and Service Operation smart objects. The Query Options field is used to supply advanced query parameters that the SmartObject framework filter does not handle such as $Skip, $Take, etc.

Authorization Header Format

Basic {0}

This setting adds an authentication string to the OData URL. Use Basic {0} for Static authentication, and Bearer {0} for OAuth.

Names: Append Property Types

True

Includes the property type in parentheses after the complex property name.

Debugging Enabled

False

Displays stack trace information in dialog and error information.

Default Http Request Headers

null

This is used to supply default HTTP headers that should be added onto every HTTP request. The non-default value expected can be created using the HttpHeader SmartObject found in the ObjectTypes folder of this service broker.

Serialization: Compress

False

Compress the serialization data for complex types.

Add HTTP Response Header Property To Methods

False

Adds an optional property to each method to allow for a list of HTTP Response headers to be returned from the service.

Add Navigation Properties to List Methods

false

This config setting toggles navigation input properties on or off. These navigationproperties show up on the brokers list method’s to allow additional filtering capabilities.

Timeout (Seconds)

100

The default time out is 100 seconds. Use this setting to increase or decrease the timeout . This is useful when a list method returns a large number of items.

Add Return Properties as Inputs

false

This config setting toggles setting the returned properties as inputs.

Certificate Search Method

FindBySubjectName

This config setting is only used when the Certificate Search Value config setting is not set to null.

The method with which to search the opened certificate store for the client certificate. There are a number of search options available including searching by name or thumbprint.

Please refer to: http://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509findtype.aspx for a complete list of all valid config values.

Handle Service Operation Filters

False

Not all OData services allow clients to query the results of Service Operations. When this setting is set to false, filters will be handled in the SmartObject framework. Setting this value to true will cause the filter to be added into the service query.

Names: Use Method FullName

True

Uses the full name of the method including the property names and types.

Ignore Unmappable Properties

False

Tells the service broker whether it should throw an error when an entity has unserializable properties on execution.

Use POST Tunneling

False

Some OData services only allow GET and POST operations. This value tells the broker whether it is allowed to use other HTTP verbs such as PUT and DELETE.

Default Http Method For Service Operations

POST

Tells the service broker whether it should default Service Operation executions to either an HTTP GET or POST.

Serialization: Include All Assembly types

True

Includes all available serialization objects regardless of usage in public methods.

Include non Serialized Properties False If the value of this Key is set to True it will add non-Serializable properties on the Serialize method Input values.

Certificate Search Value

null

The search value to use when looking for a client certificate. Filling in this config setting will cause the broker to expect to find a valid certificate at the specified location. An error will be thrown if a valid certificate is not found (this includes the case where a certificate is found, but the certificate is invalid due to expiration or lack of trust). Used in conjunction with the Certificate Search Method.

Typically the certificate should be installed under the K2 Service Account user's CurrentUser\My store (CurrentUser\Personal), but when Kerberos and Windows Authentication are used, the service instance should either be set to the Service Account authentication method, or the certificate should be installed for every user connecting to the endpoint.

Exclude query parameters

empty

Microsoft CRM and Microsoft NAV do not support all the parameters of OData. With this Key you can enter parameter values that should be excluded. If you make use of any of these parameters on your environment, you need to enter the values: $top, $skip, $orderby, and $inlinecount.

This service key was added with 4.7 May 2017 Cumulative Update FixPack 5.

Service Objects

The broker will create Service Objects for the entities, objects and system types in the targeted service endpoint. See the sections below for more information on how the Broker creates and manages Service Objects.

SmartObjects

K2 does not automatically create SmartObjects for the Service Objects in this service. SmartObjects can be automatically created by selecting the Generate SmartObjects for this Service Instance check box when creating a new Service Instance. Designers can use the SmartObject design tools to build advanced SmartObjects that leverage the Service Objects in this service. It is recommended to use the SmartObject design tools to create SmartObjects rather than generating SmartObjects, since this allows better control over the naming, behavior and design of the SmartObject and its methods and properties.

Considerations

  • At the time of release, the OData service broker was tested up to Version 3.0 of the OData standard. See the topic Determine if a Service is OData compliant for guidance on testing whether a service is compliant with the OData standard. If you are working with an unfamiliar service or experience trouble when registering an instance of the broker, we recommend that you follow the steps in that topic to determine whether the service is OData compliant.
  • You can use a sample OData service to test the OData service broker. Using a web browser, navigate to
    http://services.odata.org/V3/(S(readwrite))/OData/OData.svc/
    This will generate a unique “read-write” OData service with a unique URL to test with. Use the URL generated for your test service, and register an Instance of the OData Service using that unique URL. You will see several Service Objects discovered, which you can then generate or create SmartObjects for.

Known Issues