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

When connecting to on-premises systems from your K2 Cloud environment, you must use static credentials. See KB002939: Connecting to On-Premises Data from K2 Cloud for more information about how to do this for supported systems.

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).In a K2 Cloud environment, you can log a support ticket request to add your client certificate under the CurrentUser\My certificate location, where CurrentUser is the K2Service account (the account that K2 Server is running under
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.

Service Operations and Service Objects

The OData service broker supports OData’s Service Operations (Service Operations should not be confused with Actions and Functions, which are similar in nature. The broker does not expose Actions and Functions). Service Operations appear in the Operations folder. Each Service Operation is represented by a Service Object. A Service Operation Service Object exposes either a Load or an Execute method, or the three list methods (List, List To Serialized Item, and Read To Serialized Item).

Service Operation Service Objects discover all of the input properties, the return type, the function name, and required properties. They also handle all of the query string or body parameter construction.

A Service Operation can be bound to a particular entity or entity set. If a Service Operation is bound to a particular entity, the Service Operation allows you to specify that entity by exposing the primary keys of the entity as input properties.

The default HTTP method type for a Service Operation is POST. This default is used when the service does not specify a method type for a Service Operation. To override this default, the Default Http Method For Operations service key setting is provided in the service instance configuration. The two valid values are GET and POST. Any other values will cause the broker to default back to POST.

Service Operations have a naming convention consisting of:
MethodName (dataType + parameter , dataType + parameter)
So a service operation called MyServiceOperation with a text parameter of myString and a number parameter of myNumber would have the service object name:
MyServiceOperation(String myString, Int32 myNumber)

Due to ambiguity issues that can be present in OData implementations, filtering will work, but it will not be executed in the OData service by default. All filtering on service operations is done in the SmartObject framework unless the HandleServiceOperationsFilters config setting is set to True:

The screenshot below is a sample of the Service Object representation of OData.Org’s sample service operations:

The GetProductsByRating service operation’s List method on the OData.Org sample service:

Filtering

The OData broker handles complex SmartObject filtering. The SmartObject filter is translated to the corresponding URL to improve performance. For example, if you wanted to get all the Products where the Name starts with B and the Rating is greater than 1 you would use the following filter:

The corresponding URL looks like this:
http://services.odata.org/V3/(S(omdt3ebrzqrvcyfv1gsi5noq))/OData/OData.svc/Products()?$expand=Supplier,ProductDetail&$filter=startswith(Name, 'B') eq true and Rating gt 1

If the SmartObject framework filter does not expose the functionality necessary for your query, an additional parameter can be used to create custom queries. To turn this input parameter on, the set the Add Query Options Property To Methods service key to True. Once you to, the parameter appears on the Load, List, ListToSerializedItem, and ReadToSerializedItem methods.

Then custom queries like this one becomes possible:
http://services.odata.org/OData/OData.svc/Products?$top=5&$skip=2

This would be constructed in the SmartObject Service Tester like the following example:

The Query Options input property can be used in conjunction with the SmartObject filter safely. The OData service broker handles combining the two parameter groups together.

The Query Options supported are

$filter
$skip
$top
$take
$orderby
$select

Query options which return values other than those described on the service object method will not work.

The Query Options input property is provided for power users who need to leverage custom queries and understand the technical implications. The only processing done on the Query Options value is to resolve any instances of the same query option between the SmartObject filter and the Query Options value passed in. (If the SmartObjectfilter constructed a query with a $filter in it, and the Query Options had an additional $filter, the two would be combined). Due to this, it’s possible to construct any number of queries which will fail with error messages or produce strange results when executed in the broker. It is up to you to determine which parameters and filter options work for your scenario

Media Resource and Named Resource Streams

OData Services have the option to expose files through resource streams. Media resources are exposed through the /$value route on the end of an entity’s URL. The URL to retrieve a media resource from an entity called ‘MediaEntity’ would be: http://myservice.com/OData/OData.svc/MediaEntity(1)/$value.

Named resources are exposed in a similar fashion but specify the property they apply to. The URL to reach the named resource on an entity with a property named ‘Photo’ would be: http://myservice.com/OData/OData.svc/NamedResourceExample(1)/Photo/$value.

If an entity exposes a media or named resource, then it also exposes two methods: Load Without Content and List Without Content. These methods only return the basic properties and the URL pointing to the media or named resource. The standard Load and List methods return URLs and the full media or named resource files.

Example of the Hyperlinks on a media resource stream’s List Without Content method:

Media and Named Resource Streams are supported in the OData Broker through FileProperties. The FileProperties are only exposed on the basic CRUD methods. List methods do not retrieve resource streams. Instead, list methods expose the hyperlinks to the URLs of the resource streams that can be used in your applications or forms.

Media and Named Resource Streams also expose additional properties to support the main file property. These properties are the Media/Named Resource Stream Path and the Resource Stream MIME Type properties.

The MIME Type property is used to indicate the MIMEType of the file being saved through the ContentType header on the HTTP request to the service. If the MIMEType property is populated, its value overrides the file’s extension and any other internal processing the broker might use to figure out the MIMEType.

The Path property is used to set the Slug header on the HTTP request. If this header is left empty, the Slug header is not added to the HTTP request. The Slug header is often used in OData services to indicate where the resource stream should be saved on the server. There is no processing on the value in this property so if the service requires the Slug header to be populated for reasons other than path specification, this property can be used.

An example of a Media Resource Stream being retrieved:

An example of the Media Resource properties on an update method:

An example of a Named Resource Stream for a Photo property being retrieved:

An example of the Named Resource properties for the Photo property on the Create method:

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.