OData Service Broker

OData is the protocol that enables the creation and consumption of REST APIs, which allow resources, identified using URLs and defined in a data model, to be published and edited by Web clients using simple HTTP messages. It shares some similarity with JDBC and ODBC but OData is not limited to relational databases.

The following resources: have additional background information on the OData protocol. This topic assumes that you are familiar with OData, so take a moment to go through this content before attempting to use the broker.

• http://en.wikipedia.org/wiki/Open_Data_Protocol
• http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol

The K2 OData service broker enables OData-compliant services to be exposed by the K2 Service Broker as SmartObjects. Once the SmartObjects are available, the OData compliant service can be used by the K2 product stack which includes Workflows, Forms etc.

The K2 OData endpoint broker is similar to the REST broker and all other endpoint brokers in that it exposes entities, objects and system types based on an OData endpoint. However, it does not require a descriptor file like the REST broker.

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.

Registering the Service Type

Using the SmartObject Service Tester utility: The smartobject tester tool can be found in the installation directory for K2 blackpearl. [Program Files (x86)]\K2 blackpearl\Bin\SmartObject Service Tester.exe

1. Navigate to the location of the utility and launch it.
   

2. Click Register Service Type
   

3. Select the ODataBroker from the service types dropdown
   

   If you have installed previous versions of the OData broker, the name of the broker assembly file has changed. Delete the old assembly (SourceCode.SmartObjects.Services.Endpoints.ODataService.dll) from the ServiceBroker folder or you will still see it as in the above figure.You should also delete the previously-registered service instances and then delete the OData service type by clicking on the folder in SmartObject Services Tester and selecting Delete Service Type.

4. Add a Display Name and click Add
   

Register a Service Instance

Once you have registered the service type you can create service instances.

1. Click Register ServiceInstance
   

2. Select Service Type and click Next
   

   Select the appropriate Authentication Mode for the target service. If the target service uses OAuth, you will need to register the necessary OAuth resources before continuing. See the K2 KB article KB001702 - How to configure OAuth in K2 for more information on configuring OAuth resources.

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

3. Check details are clear and click Add
   

   K2 will now discover the target service and generate Service Objects for the operations and entities.