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:

Service Keys (Service Instance Configuration Settings)

Service Key

Default value

Description

OData Service Url

The URL to the OData Service.

Serialization: Compress

False

Compress the serialization data for complex types.

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.

Names: Append Property Types

True

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

Names: Use Method FullName

True

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

Debugging Enabled

False

Displays stack trace information in dialog and error information.

Add HTTP Request Header Property To Methods

False

Adds an optional property to each method to allow for a list of HTTP Request Headers to be sent to the 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.

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.

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.

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.

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.

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

Certificate Store Name

My

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

The name of the certificate store under which the client certificate is installed. The valid values for this config setting are: AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, and Trusted Publisher.

Please refer to: http://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storename.aspx for more information.

Certificate Store Location

CurrentUser

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

The location of the certificate store to open. The valid config values are CurrentUser and LocalMachine.

Please refer to: http://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.storelocation.aspx for more information.

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.

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).

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

Known Issues