ENDPOINT BROKER DEEP DIVE

ENDPOINT BROKER DEEP DIVE PRESENTED BY: ERIC SCHAFFER PRODUCT MANAGER [email protected]

K2.COM

AGENDA    

    

Goals Non-Goals How does it work? Dealing with Complex Types Registering Instances Serialization Custom Broker Troubleshooting Q&A

K2.COM

GOALS  The purpose of the endpoint broker is to allow a K2 application designer to interact with various types of services quickly and easily and without code.  These brokers are the cornerstone for LOB integration moving forward.

 Supported Endpoint Types  Web services  WCF (WSDL and MEX)  .NET Assemblies (only public, static methods are supported)  Supported Authentication  Service Account  Static  SSO  Impersonate

K2.COM

WHAT ABOUT REST, ODATA AND OAUTH?  All are planned and are coming soon  Earliest possible release vehicle would be 4.7

K2.COM

NON-GOALS  Support endpoints with unserializable constructs  Creation of a new “Complex” property in the SmartObject architecture/API  Creation of a new “List” property in the SmartObject architecture/API  Creation of a new Enumeration property in the SmartObject architecture/API for  XML schema editor  XML mapping tools

K2.COM

HOW DOES IT WORK?  WSDLs, Reflection, Proxy DLLs, and Serialization  For WCF and Web Services we do exactly what Visual Studio does when you add a reference.

 We generate a Proxy DLL based on the WSDL and then use Reflection to figure out all the methods and objects  If you can’t add the reference in Visual Studio then we won’t be able to use it either

 How do we filter the Methods we expose?  WCF – Only methods that have an Operation Contract are exposed  Web – Only methods with SoapRpcMethodAttribute or SoapDocumentMethodAttribute  Assembly – Public Static methods only. No support for Abstract, Generic, or Constructor methods K2.COM

COMPLEX TYPES  The biggest challenge to overcome when trying to interact with services without using code is how to deal with complex objects  Our answer to this is Serialization.

 Serialization allows us to flatten complex objects into strings and then re-expand the strings back into complex objects when needed ID

First Name

Last Name

Email

Phone

Title

0037000000ViN x3AAF

Rose

Gonzalez

[email protected]

(512) 757-6000

SVP, Procurement

Serialize

deserialize

Serialized Contact {"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","Email":"[email protected]","FirstName":"Rose","LastName":"Gonzalez","Phone":"(512) 757-6000","Title":"SVP, Procurement","Id":"0037000000ViNx3AAF"}

K2.COM

WHAT TYPE OF SERIALIZATION?  We looked at a lot of serialization options but most required the objects to be decorated as Serailizable.  In the end we licensed JSON.NET because it does what it says. It serializes all the things

K2.COM

REGISTERING INSTANCES

K2.COM

ASSEMBLY INSTANCE

K2.COM

Option

What it is

Assembly Full Path

The full path, relative to the K2 Server, to the assembly. UNC paths are supported.

Serialization: Compress:

Compress the serialization data for complex types.

Serialization: Include All Assembly types

Includes all available serialization objects regardless of usage in public methods.

Names: Append Property Types

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

Names: Use Method FullName

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

Debugging Enabled

Displays stack trace information in dialog and error information.

WCF INSTANCE

K2.COM

Option

What it is

Service Metadata URL

The URL to the service description (WSDL/MEX) for the Web Service.

Use MEX Endpoint

The service description is provided as MEX instead of WSDL.

Service Endpoint URL

The URL to the service endpoint, typically the .svc address. NOTE: one service instance per binding. (../WCF.SVC/Process)

Serialization: Compress:

Compress the serialization data for complex types.

Serialization: Include All Assembly types

Includes all available serialization objects regardless of usage in public methods.

Names: Append Property Types

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

Names: Use Method FullName

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

Debugging Enabled

Displays stack trace information in dialog and error information.

WEB SERVICE INSTANCE

K2.COM

Option

What it is

WebService URL

The URL to the service description (WSDL) for the Web Service.

Add SoapHttpClientProtocol Parameter to Methods

Required for passing a SOAP Protocol to methods

Default SoapHttpClientProtocol Value

SOAP protocol to pass if none provided

Serialization: Compress:

Compress the serialization data for complex types.

Serialization: Include All Assembly types

Includes all available serialization objects regardless of usage in public methods.

Names: Append Property Types

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

Names: Use Method FullName

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

Debugging Enabled

Displays stack trace information in dialog and error information.

WHAT WE GENERATE  Object Types – All the complex objects discovered by the broker  Service Objects – All the methods discovered by the broker  SOAP Protocol Types (Web Service Only) – The complex objects for building a SOAP header  System Types – basic system types. Used for creating arrays of simple types.

K2.COM

SERIALIZATION METHODS  Objects  Serialize  Deserialize  Deserialize Array  Deserialize Typed Array  Serialize Item to Array  Serialize List to Array  Serialize Add Item to Array  Get Enums

 Methods  Single  Read  Read to Serialized Item  List  List  List to Serialized Item  Read to Serialized Item K2.COM

DESERIALIZE ARRAY  Turns a serialized array of serialized objects into a list of serialized objects

Serialized Array {"$type":“Contact[], WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzalez"},{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Sean","LastName":"Forbes}]}

Contacts "{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzalez"} {"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Sean","LastName":"Forbes}

K2.COM

DESERIALIZE TYPED ARRAY  Turns a serialized array of serialized objects into a list of deserialized objects

Serialized Contact Array {"$type":“Contact[], WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzalez"},{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Sean","LastName":"Forbes}]}

K2.COM

First Name

Last Name

Rose

Gonzalez

Sean

Forbes

SERIALIZE ITEM TO ARRAY  Creates a serialized array of 1 serialized object

First Name

Last Name

Rose

Gonzales

Serialized Contact Array {"$type":"Contact[], WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzales"}]}

K2.COM

SERIALIZE ADD ITEM TO ARRAY  Adds an additional serialized object to a serialized array

Serialized Contact Array {"$type":"Contact[], WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzales"}]}

First Name

Last Name

Sean

Forbes

Serialized Contact Array {"$type":“Contact[], WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzalez"},{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Sean","LastName":"Forbes}]} K2.COM

GET ENUMS  For any ENUM objects this method will return the list of Name Value pairs.

K2.COM

SERIALIZE LIST TO ARRAY  Takes generic .NET list to object array (Assembly broker only)

{"$type":"System.Collections.Generic.List`1[[TestAssembly.Address, TestAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null]], mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089","$values":[{"$type":"TestAssembly.Address, TestAssembly, ….

{"$type":"TestAssembly.Address[], TestAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"TestAssembly.Address, TestAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null","Street":"street","City":"city","Zip":9999},{"$type":"TestAssembly.Address, TestAssembly,….

K2.COM

READ  Does a standard read and returns the result First Name

Last Name

ID

Rose

Gonzalez

0037000000ViNx3AAF

READ TO SERIALIZED ITEM  Does the standard read but returns a serialized object or object array in the case of a List method

{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzalez","Id":"0037000000ViNx3AAF"}

K2.COM

LIST  Does a standard get list and returns the results First Name

Last Name

ID

Stella

Pavlova

0037000000ViNxAAAV

Rose

Gonzalez

0037000000ViNx3AAF

 Returns a list of serialized objects

{"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Stella","LastName":"Pavlova","Id":"0037000000ViNxAAAV"} {"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","FirstName":"Rose","LastName":"Gonzalez","Id":"0037000000ViNx3AAF"}

K2.COM

NESTED SERIALIZATION  You can also nest serialized objects within other serialized objects.  If I have a serialized address object inside a serialized contact object which is inside of a serialized contact list, I have to de-serialize the list then de-serialize the contact and then de-serialize the address. Serialized Contact List {"$type":"Contact[], WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, public ….

Deserialize typed array First Name

Last Name

Serialized Address

John

Smith

{"$type":“Address,...

Sean

Fobes

{"$type":“Address,...

Jack

Rogers

{"$type":“Address,...

K2.COM

Street

City

State

123 2nd St

Seattle

WA

NESTED SERIALIZATION  The reverse is also true  If you need to send a nested serialized object to a create method for example you need to build the serialized object from the inside out Street

City

State

123 2nd St

Seattle

WA

Serailized Address {"$type":“Address,... Serialized Contact {"$type":"Contact, WebServiceSalesForce, Version=0.0.0.0, Culture=neutral, public …. First Name

Last Name

Rose

Gonzales

K2.COM

DEMO - SERIALIZATION

K2.COM

ADVANCED SMARTOBJECTS  Using Advanced Mode for SmartObjects we can chain multiple service objects together for a single SmartObject method to hide away the complexity of serialization from the SmartObject consumer

K2.COM

THE FOR-EACH ISSUE  Currently when a SmartObject executes a service object method that returns a list all other chained service object methods that occur after the list method will not execute.

 The issue is that the service object method that occurs after the list service object method would have to execute FOR EACH list item  We are busy investigating how to be able to add support for this in the future

K2.COM

ENHANCEMENTS  Additional groundwork is being done so that in the future SmartObjects, Controls, and Form generation can be smarter when dealing with complex objects  For example an ENUM object when used in a form should default to a dropdown or picker control  Metadata behind the memo property will indicate the deserialization method for that property so that in the future our tooling can start to auto wire-up some of the complexity we deal with today

K2.COM

DEMO – ADVANCED. SMARTOBJECTS

K2.COM

BINDINGS AND BEHAVIORS  The K2hostserver.exe.config file has a set of basic WCF bindings  It is possible to add additional bindings and behaviors to support more complex requirements such as Client Certificate Authentication.  We support Client Configuration customization

 The trick is that you need to add not only the binding and behavior to the config file but also the client endpoint configuration with the endpoint address. NOTE: This can complicate deployment as this configuration does not exist in the service instance and will not be part of Package and Deployment. K2.COM

USING COMPLEX TYPES IN YOUR OWN BROKER  SourceCode.SmartObjects.Services.Endpoints.Common  This assembly contains most of the logic used by the endpoint brokers which you can use in your own broker for handling complex types

K2.COM

DEMO – CUSTOM BROKER

K2.COM

TROUBLESHOOTING  Message: Object of type ‘[ObjectName]’ cannot be converted to type ‘[ObjectName]’.; ServiceName: [ServiceName]; ServiceGuid: aa2a94cf-365f-48aa-86c0-2186d6f802ff; InnerExceptionMessage: ;  Restart K2 blackpearl service

 The issue is that if you refresh a service instance and a proxy dll already exists a second proxy dll will be created. At runtime type confusion between the proxy dlls occurs.  The underlying issue is that the proxy dlls are loaded into the host server app domain which means that when a refresh occurs we cannot just drop the app domain to clear the previous proxy.  We are working devising a solution which may entail loading the proxy dlls into a separate app domain so that it can be dropped and recreated without requiring a service restart.  KB ARTICLE LINK: http://help.k2.com/en/KB001413.aspx

K2.COM

TROUBLESHOOTING

 Add the Entity Framework config sections to the ‘K2HostServer.exe.Config’ file

 Copy the Entity Framework DLLs into the service broker directory.

K2.COM

K2.COM