Working with Endpoint SmartObjects: Serialization and Deserialization

The Generic or "EndPoint" Service Brokers make extensive use of .NET Serialization and Deserialization to deal with complex types. While this topic explains how these functions are used by the generic service brokers, understanding Serialization and Deserialization requires some knowledge of how .NET stores and transfers data. (For more information on Serialization in .NET, see https://msdn.microsoft.com/en-us/library/7ay27kt9(v=vs.110).aspx.). In practice, you may find yourself combining serialization and deserialization methods in advanced SmartObject methods to pass values between methods.

The main methods that you use with the endpoint brokers are serialization and deserialization. Simply put, these methods are used to send and store complex data. To serialize the results of a service call means to represent it in a state that can be transferred and/or stored, such as in a database. To deserialize that data is to turn it back into a state that can be consumed by code or an application. These methods (while based on the .NET Framework for the purposes of the Endpoint Service Brokers), represent a device-independent, cross-platform method of representing complex, relational data. For more information, see http://en.wikipedia.org/wiki/Serialization.

For entities with complex types or nested objects, the complex type or nested object will be returned as serialized items. The serialized item will need to be deserialized before being displayed and in a case where data is being captured, the item should be serialized then passed to the SmartObject as a serialized item. (It is also possible to chain SmartObject methods to execute more than one method. This is useful for deserializing nested or complex typed items in one method execution.)

Serialization converts an object into a form that can be persisted or transported. Most commonly, this means converting an object to a string format.
Deserialization is the process of taking a string and converting it back into an object so the underlying system can work with it.

Serializing an object to string

The opposite of serialization is deserialization, which converts a string to an object.

The product will create the serialization and deserialization Service Object methods for you, but you may need to “chain” them in the correct way for the underlying provider to understand. The key to using the brokers is to understand what you are trying to do. Ask yourself the following questions:

  1. Am I submitting data?
  2. Am I retrieving data?
  3. Do I have the data I need?
  4. Is the data in the right structure?
  5. Does the main structure have any nested types?
  6. If it has nested types, do I need to serialize those before submitting? Or deserialize them after retrieving?

It is important to know what your multiple levels of serialization are, and then keep deserializing things until you get to simple types. The exact sequence of number of calls you need to make will depend on the service.

Use the Properties, Methods, and the ability to Chain Methods to process the data through the Serialization/Deserialization steps.

The following are the property names for the different types of Serialization Service Objects.

To help determine what types are used in what properties, the property names include the expected type for that property as part of the name.

Simple Type

Complex Type

Enum

The following basic methods are created for most Endpoint service brokers.

Serialize

Serializes an object to text.

  • Input properties: All properties that makes up the object.
  • Return properties: Serialized object as text.

Deserialize

Deserializes text to an object.

  • Input properties: Serialized object as text.
  • Return properties: All properties that make up the object, returned as simple types and nested serialized objects.

Deserialize Array

Deserializes an array to serialized items. If the items are complex, they are returned as serialized values. In some cases this could save a serialize method call.

  • Input properties: Serialized array as text.
  • Return properties: All items in the array as serialized text.

Deserialize Typed Array

Deserializes an array to deserialized items. If the items are complex, they are deserialized to the properties that make them up. In some cases this could save a deserialize method call.

  • Input properties: Serialized array as text.
  • Return properties: All items in the array deserialized to the properties that makes them up.

Serialize Item to Array

Creates a one item array with the item in it and returns the array as serialized text.

  • Input properties: All properties that makes up the object.
  • Return properties: Serialized array as text

Serialize List to Array

Takes a generic list and converts it to an array.

  • Input properties: Serialized list as text.
  • Return properties: Serialized array as text.

Serialize Add Item to Array

Adds an item to an existing array.

  • Input properties: Serialized array as text. All properties that makes up the object.
  • Return properties: Serialized array as text

You may find that it’s helpful to chain multiple methods together to wrap all serialization/deserialization calls into a single SmartObject method.

The following figure illustrates how this could be configured. Keep in mind that primary/detail records, or having an array of nested complex objects, cannot be represented in a single SmartObject. However, deserialized simple types and non-array can be represented by various SmartObject properties.

The Serialization of the SoapHttpClientProtocol is done with a ServiceObject and not XML or a comma delimited structure. The ServiceObject will be created in a new folder, SoapHttpClientProtocol.

When the Add SoapHttpClientProtocol Parameter To Methods Service Key is set to True, a SoapHttpClientProtocol parameter will be added to all methods.

The Default SoapHttpClientProtocol Value must be created with the generated Serialization object. If you provide a value for the parameter at runtime, the default value will not be used.