SmartObject WCF Services

This content applies to legacy components (such as K2 Studio and K2 for Visual Studio), legacy assemblies, legacy services or legacy functionality. If you have upgraded from K2 blackpearl 4.7 to K2 Five, these items may still be available in your environment. These legacy items may not be available in new installations of K2 Five. These legacy items may also not be available, supported, or behave as described, in future updates or versions of K2. Please see the legacy component support policy for more information about support for these components.

SmartObject WCF Services provide Windows Communication Foundation (WCF) endpoints for SmartObjects on a K2 Server, based on the configuration of the K2 server to expose certain SmartObjects' methods as WCF endpoints (see Configuring SmartObject REST and WCF Services

For information on how to configure K2 Services for Claims Authentication support, go to KB001426.

Service Endpoints

K2 SmartObject Services WCF endpoints provide standard URIs (Uniform Resource Identifiers) for interacting with the available SmartObjects data and operations.  Detailed information on service contracts, data contracts and operation contracts can be found in the endpoint Service Descriptions.  This topic will help in the construction of the appropriate URI for the desired operation.

URI Structure

{Service Root URI}{Service Path}?{Service Description}

2

Service Root URI

Structure: {Scheme}{Server}:{Port}{Service Root}/{Service Type}
This part is the "root" URL that exposes the various, SmartObject-specific endpoints.

  • Scheme = http:// or https:// if SSL is enabled
  • Server = Server Name or Host Header of web site hosting K2 services
  • Port = Port of web site hosting K2 SmartObject Services, the default is 8888
  • Service Root = service endpoint exposed by K2 SmartObject Services.  The default is SmartObjectServices
  • Service Type = for WCF services, the default is WCF

The Service Root URI (up to Service Type) is configured via the scheme, server, port and serviceroot settings in K2HostServer.exe.config.

Service Path

Structure: {CategoryPath}{SmartObjectName}
This part identifies the SmartObject being targeted.

  • CategoryPath = the path to the category/propject folder that contains the SmartObject
  • SmartObjectName = the display name of the SmartObject to call.

The Service Path is inferred by K2 through the location of the SmartObject in the Category System, the SmartObjects' display name.

When enableMetadata="true" is configured, the service description is available by appending ?wsdl to the URI for the endpoint.

Special Characters

K2 SmartObject Services utilizes standard URL escaping for URI construction. 

  • %20 = {space} (standard URL escaping)

Available Endpoints

K2 SmartObject Services makes it easy to determine all the available URIs for the system by providing them in an XML format.  To see the available endpoints, navigate to:

{Scheme}{Server}:{Port}{Service Root}/endpoints/endpoints.xml.

Filter

K2 SmartObject Services utilizes the capabilities of the SmartObjects Filter Framework to enable filtering of your List based results for WCF endpoints.

All SmartObject List methods will have an additional filter method provided via the WCF endpoints.  The name of the filter method will be the name of the list method with “_Filtered()” appended.

The _Filtered() method takes a single string parameter which is the filter represented as XML.

K2Examples.EmployeeSvcClient employeeClient = new K2Examples.EmployeeSvcClient();
//write code to build the filter XML
string filter = BuildFilter();
//use the filter XML against the _Filtered method
K2Examples.Employee[] filteredEmployees = employeeClient.EmployeeSvc_GetList_Filtered(filter);

The filter XML can be created by hand or by using the SourceCode.SmartObjects.Client.Filter object to build up the filter and calling the GetFilterXml() method as outlined below.

  1. Add a reference to SourceCode.SmartObjects.Client.dll
  2. Import the following namespaces:
    • SourceCode.SmartObjects.Client.Filters
    • SourceCode.SmartObjects.Client
    • System.Xml
  3. Create a method that uses the object model to build the filter. An example code snippet is shown below:
//create an "equals" filter
SourceCode.SmartObjects.Client.Filters.Equals lastNameEquals = new Equals();
//set the system name and data type of the SmartObject property that will be used in the filter
PropertyExpression lastNameExpression = new PropertyExpression("Last_Name", PropertyType.Text);
//set the value and data type of the value that will be used in the filter
ValueExpression lastNameValue = new ValueExpression("Cowan", PropertyType.Text);
//set the left and right side of the equals expression
lastNameEquals.Left = lastNameExpression;
lastNameEquals.Right = lastNameValue;
//create a filterexpression object and pass in the filter
FilterExp filterExpression = new FilterExp(lastNameEquals);
//serialize the expression as a string of XML
XmlDocument filterXml = filterExpression.GetFilterXml();
return filterXml.InnerXml;

 The resulting XML for this method would resemble the following (formatted for clarity, if you were to pass this filter in, this value woudl be one long line of XML :

<filterexp>
    <equals>
        <left>
            <propertyexp name="Last_Name" sotype="Text"/>
        </left>
        <right>
            <valueexp sotype="Text">Cowan</valueexp>
        </right>
    </equals>
</filterexp>