Using the OData Service Broker (including Serialization and Deserialization)

This tutorial focuses on using the generic OData Service Broker, which is used to expose OData services as SmartObjects. In this tutorial, you will register a service instance against an OData service object, and you will learn how data can be serialized and deserialized. The following aspects are covered:

For the purposes of this exercise, we will be using a sample web service that exposes hypothetical product information for our Denallix organization. The sample service is intended for learning and demonstration purposes only. It is not intended for use in production environments and is not supported or guaranteed by K2.
Serialization is the process of converting one or more instances of an object into a text/string format (such as XML or another string type), which can then be easily transported and manipulated by other tools. The compliment of serialization is Deserialization, which converts the serialized data back to an object. Additional information on Serialization and Deserialization can be found on the K2 blackpearl Developer Reference site.
Additional information on the OData Service Broker is also available on the Developer Reference site.

Step 1 Tasks

  1. Register a new OData Service Instance. For the OData Service Url, enter
    http://k2learningodata.azurewebsites.net/K2LearningService.svc
  2. Leave the Authentication Mode as Impersonate, because for this service the credentials don’t matter.
  3. Change the Display Name to
    ODataSample
    4. If you see an error about the ServiceInstance name already existing, change the System Name to
    K2learningservice2
  4. After the new service instance has been created, briefly review the Entities that are returned.
  1. Launch the SmartObject Services Tester if it is not already open. Expand the ServiceObject Explorer node and locate the OData Service Object. Right-click the OData Service Object and select Register ServiceInstance.

  2. Copy and paste the following URL into the OData Service Url field:
    http://k2learningodata.azurewebsites.net/K2LearningService.svc
    then click Next. (The other settings are fine as is. You can leave the Authentication Mode as Impersonate, because for this service the credentials don’t matter.)

  3. Change the Display Name to
    ODataSample
    then click Add. Click OK when you see the success dialogue.
    4. If you see an error about the ServiceInstance name already existing, change the System Name to
    K2learningservice2

  4. Expand the Entities node and review the Service Objects that were discovered for the sample service. In the next step, you will generate a SmartObject from the Product entity.

Step 1 Review

In this step, you registered a new instance against an OData service. There were several entities discovered and exposed as Service Objects. In the next step, you will work with the Product entity.

In this step, you will create a new SmartObject from the Product entity.

Step 2 Tasks

  1. Using the Service Object Tester utility,. create a new SmartObject from the Product Entity. Name the new SmartObject
    OData Product
    and choose the OData category as the location to save it.
  2. Check that the name is unique, then Publish the SmartObject.
  1. Expand the ODataSample Service Instance, then the Entities node if it is not already. Right-click the Product entity and select Create SmartObject.

  2. Name the new SmartObject
    OData Product
    then select the OData category for the SmartObject location. Click Check Name to confirm the name is unique and meets the K2 SmartObject naming convention. Click OK for the confirmation dialogue (that the name is unique), then click Publish SmartObject. Click OK to the dialogue indicating the SmartObject was successfully published. Exit the Publish SmartObject screen.

Step 2 Review

In this step, you created a new SmartObject from the Product entity returned by the sample OData service. (We just generated a SmartObject using the Service Tester utility in this step to save time. In the real world, you would probably create the SmartObject in one of the K2 design tools like K2 Studio or K2 Designer). In the next two steps, you will test the new SmartObject and learn how K2 can serialize and deserialize data.

The first test you will run will execute the Product List method, and return an array of Products as a list of SmartObject records.

When using the OData service, K2 will attempt to generate SmartObjects with Properties that represent the complex OData objects. In other words, K2 will attempt to discover the objects in the targeted service and where possible, create logical Entities that match the properties and methods exposed by those objects. In this case, K2 is able to do this for the Product entity returned by the sample service, because the Product entity contains only properties of simple types (e.g. strings, numbers) and no "nested" complex types. This may not always be possible, in which case you may want to use the serialization and deserialization methods to work with more complex types as described in steps 4 and 5.

Step 3 Tasks

  1. Navigate to the OData Product SmartObject, then Execute the List method. Review the results that are returned.
  1. Expand the SmartObject Explorer, then expand the OData category. Because you selected the OData category when you created the new SmartObject, this is where K2 saved the SmartObject. Right-click the OData Product SmartObject and select Execute SmartObject.

  2. Change the Method to Execute to List, then click Execute. Review the records that are returned as part of the list. (Collapse the Input Properties pane if you need more room.)

Step 3 Review

In this step, you executed the list method for the OData Product SmartObject, showing that the OData broker was able to "convert" the Product entity to a straightforward SmartObject.

Now imagine having to pass all of the classes that make up a complex object. For example, perhaps our Product entity had within it more complex entities such as Product Specifications or Manufacturing Specifications. Since these are complex types nested within a complex type, K2 may not be able to create a straightforward SmartObject representation of the Product entity, because K2 does not know how to expose a Product Specificationscomplex type as a property of a SmartObject. One way of handling this is to use Serialization to format complex objects into a single string that can later be Deserialized.

In this step, you will execute the List to Serialized Item method to see how Serialization works.

Step 4 Tasks

  1. Still working with the OData Product SmartObject, Execute the List to Serialized Item method. Review the results returned.
  2. Copy one of the strings.
  1. Change the Method to Execute to List to Serialized Item and Execute the method. Notice now that each record is comprised of a string that contains all of the properties making up the complex object.

  2. Click to highlight one of the string values for one of the records, and then press <CTRL-C> to copy the string.

  3. Paste the copied text data for one of the records into something like Notepad. (We will be pasting this value into the Deserialize method in the next step)
    We will be using just the data value, not the heading, so you can delete the Product (Product) text, as shown below:
Step 4 Review

In this step, you executed the List to Serialized Item method. When data has been serialized, it is essentially reformatted into a string that can be persisted (stored), handled or transported across multiple data connections and consumers. In the next step, you will deserialize the data to return it to a complex object, to illustrate how data is serialized into text format and deserialized into object format.

The opposite of serialization is deserialization. When you deserialize a text value, the data is "converted" back into a complex object.

Step 5 Tasks

  1. Execute the Deserialize method. Use the string you copied in the previous step as the Serialized Item (String) Input Property. Review the results returned.
  1. In the SmartObject tester utility, change the Method to Execute to Deserialize. Click <CTRL-V> to paste the string you copied to Notepad in the preceding step, into the Serialized Item (String) Input Properties field. (If you collapsed the Input Properties pane, you will need to expand the pane once again to see the input field.)
    2. If you see the words Product (Product), you pasted more data than what you need. Remove the Product (Product) wording, then just copy over the actual serialized string for the input value; see the screenshot below for the specifics.

  2. Execute the Deserialize method. Review the object that is returned, and notice how K2 "converted" the text string into a SmartObject with Properties.

Step 5 Review

In this step, you executed the Deserialize method to convert a serialized string back to a complex object.