Using XML Properties in SmartObjects -...

Using XML Properties in SmartObjects

blackmarket Example

David Loomis

3/5/2009

The statements and opinions made in my postings are my own, and do not reflect the opinions of

SourceCode Technology Holdings, Inc. or its subsidiaries. All information is provided as is with no

warranties express or implied, and grants no rights or licenses.

1

Introduction Since the first release of blackpearl, it has had the little known and little used ability to expose XML

properties on ServiceObjects and map them to SmartObject properties. The most common use of this

feature is with K2 connect to expose SAP data structures as XML that can be consumed as SmartObject

properties. Since schemas can represent serialized .NET objects you have a powerful mechanism for

using complex data types in workflow processes. This article will discuss ServiceObject XML properties

so they can be exposed with SmartObjects. A sample project called DynamicXMLService will be used as

a working example to illustrate the concepts.

A complete discussion of building ServiceObjects is out of scope for this article. It is assumed the reader

has knowledge of building ServiceObjects. A whitepaper on developing custom services can be found at

http://www.k2underground.com/files/folders/technical_product_documents/entry21898.aspx.

Additionally, there are several samples complete with source code in the blackmarket section of

k2underground: http://www.k2underground.com/k2/ProjectLanding.aspx.

Out of the Box Functionality in blackpearl The SmartObject designer has always had the ability to map SmartObject properties to an XML structure

returned by a service. Take for example the following simple XML schema created in Visual Studio

representing an employee:

Note: The Visual Studio Schema Designer is included with Visual Studio 2005 but is only available as a

separate download for Visual Studio 2008.

An XML document that conforms to the schema might look like this:

<?xml version="1.0" encoding="utf-16"?>

<Employee employeeID="5">

<Name>Joe Schmoe</Name>

<Title>Director of Making Bad Loans</Title>

<Salary>150000.00</Salary>

</Employee>

Once a service exposes this schema it

consumer just like any other SmartObject. The consumer is unaware the underlying property is XML.

Here is an example SmartObject with some

When binding a SmartObject method to a service

the property type is XML:

To edit the mappings between the SmartObject

click the Assign button. The Xml Property Mapping

2

Once a service exposes this schema it can be bound to SmartObject properties so it appears to


Here is an example SmartObject with some defined properties.

a SmartObject method to a service method that has an XML property, you will see that

SmartObject properties and the XML, highlight the XML property and

Xml Property Mapping dialog will appear:

can be bound to SmartObject properties so it appears to a


you will see that

properties and the XML, highlight the XML property and

You can choose to Create All fields and automatically map them. You can

SmartObject properties (if the names match) or you can manually control the mapping of field

time by pressing the Add button. By manually mapping the names exposed as SmartObject properties

they do not have to match the names of the XML structure.

Fields created using the XML Property mapping wizard always take on the SmartObject field

“text”. If you need a different data type, go back and edit the field properties in the main SmartObject

designer.

In manual mapping mode you can see the structure of the XML schema in the

expand or contract different sections to choose the XML element or attribute needed.

node you want to map. Then choose to map the node to a

SmartObject Property or to a Specific Value

3

fields and automatically map them. You can Auto Map fields to existing

SmartObject properties (if the names match) or you can manually control the mapping of field

By manually mapping the names exposed as SmartObject properties

do not have to match the names of the XML structure.

Fields created using the XML Property mapping wizard always take on the SmartObject field


In manual mapping mode you can see the structure of the XML schema in the tree view

expand or contract different sections to choose the XML element or attribute needed.

choose to map the node to an existing SmartObject Method Parameter

Specific Value (literal) or create a new one. If the SmartObject property

fields to existing

SmartObject properties (if the names match) or you can manually control the mapping of fields one at a

By manually mapping the names exposed as SmartObject properties

Fields created using the XML Property mapping wizard always take on the SmartObject field data type of


tree view. You can

expand or contract different sections to choose the XML element or attribute needed. Highlight the XML

SmartObject Method Parameter, a

(literal) or create a new one. If the SmartObject property

you want to map to already exists, you can select it from the name drop down and click

property does not exist, click the Create

Once fields have been mapped, the SmartObject will behave like any other. Here are a few things to be

aware of when using the mapping dialog

• You cannot map repeating elements

• You can map single elements and attributes directly to properties

• The behavior when mapping group elem

When to use XML PropertiesXML Properties are not for every situation. When dealing with simple types in custom services it will

often be simpler and quicker to expose the service properties using standard ty

schema. If your custom service is dynamic and the structures used complex then XML Properties might

be the best choice. Keep in mind, the SmartObject property mapper does not allow you to map to

repeating groups.

Creating a Service Object that has XML PropertiesCreating a Service Object that has XML properties is much like creating any other Service.

accompanying this article implements a simple service called the

example used to illustrate the points of using XML properties. Although

are limited, it does enable getting and setting XML elements without code using the SmartObject

Wizard. Once you understand how

Service Object you create.

4

you want to map to already exists, you can select it from the name drop down and click

Create button to add a new property.

apped, the SmartObject will behave like any other. Here are a few things to be

mapping dialog:

You cannot map repeating elements

You can map single elements and attributes directly to properties

apping group elements will is defined by the underlying service

When to use XML Properties XML Properties are not for every situation. When dealing with simple types in custom services it will

often be simpler and quicker to expose the service properties using standard types rather than an XML



Object that has XML Properties Object that has XML properties is much like creating any other Service.

accompanying this article implements a simple service called the DynamicXMLService. Th

lustrate the points of using XML properties. Although real world uses of this service

, it does enable getting and setting XML elements without code using the SmartObject

Once you understand how XML Properties work, you can use them where appropriate in any

you want to map to already exists, you can select it from the name drop down and click OK. If the

apped, the SmartObject will behave like any other. Here are a few things to be

is defined by the underlying service

XML Properties are not for every situation. When dealing with simple types in custom services it will

pes rather than an XML



Object that has XML properties is much like creating any other Service. The example

. This is a simple

real world uses of this service

, it does enable getting and setting XML elements without code using the SmartObject Event

hem where appropriate in any

5

Example Project: DynamicXMLService

This service is an example of a dynamic, rather than static, service. A dynamic service is one that adapts

itself with new properties and methods when a new instance is configured. In contrast, for a static

service all of the properties and methods are known when the service is created. The adaptive part of

this service occurs when you create a new instance: you must supply an XML schema (xsd) file and

schema name. The service then makes the schema available as an XML property. Because the

SmartObject property mapper does not support repeating groups, your ability to use those types of

schemas with this service will be limited.

This service does not implement a persistent data store. When needed, an input parameter called

InputXML is used to receive XML conforming to the schema from another source, be it a data field or a

SmartObject. A return property called ReturnXML is used to return the updated XML so it can be

persisted by another means. In other words, this service transforms inputs and outputs to and from

XML, but leaves the storage of that XML up to the designer.

The service has three methods that can be invoked by a SmartObject:

• Create an instance of an XML document that conforms to the schema. This allows you to create

and initialize a new instance of an XML document. If you use the SmartObject designer to map

input properties to the schema, those input values will be set in the newly created XML

document. A return property called ReturnXML contains the new document.

• Get the XML as properties. When properties are mapped to the XML using SmartObject

designer this allows the SmartObject properties to contain the values of the corresponding XML

elements. The InputXML parameter takes in a string containing the XML and the data is then

available in the SmartObject properties.

• Set the properties in the XML. When properties are mapped to the XML using SmartObject

designer the properties will be set in the corresponding elements and attributes of the XML

document. The InputXML parameter takes in a string containing the XML; the properties are set

in the XML document and then the updated XML document is returned in the ReturnXML

property.

The routine housekeeping tasks of building a Service Object are covered in other K2 articles; this service

closely follows those concepts. Because the ServiceBroker.cs class contains most of this routine

housekeeping, it will not be discussed here. Of primary interest for this example is the

XMLDataConnector.cs file which contains the implementation specifics for this service.

Each service instance has two required properties that are defined in the SetupConfiguration method:

the path to the XSD file, and the name of the schema. From this information, the service is able to

expose the schema as an XML property in the DescribeSchema method.

DescribeSchema

The DescribeSchema method is one of the key methods of a Service Object: it describes to the service

broker infrastructure metadata about the properties and methods that will be exposed by this instance

6

of the service. DescribeSchema describes what the service instance can do while the Execute method

does it. The DescribeSchema method is only invoked when an instance of the service is created or

updated.

One of the first things to be defined in DescribeSchema is the InputXML parameter. Service Object

method parameters are required data needed to make the method operate; they are not optional. The

SmartObject designer can choose to leave these method parameters as SmartObject parameters

(recommended for this service) or connect them to a SmartObject property. The InputXML will take a

string containing the XML document as input into the Get and Set methods from persistent storage

location. This input parameter is a standard Service Object parameter you will see in many types of

Service Objects.

The next item to be defined is the ReturnXML property. This property is used in the Set and Create

methods to return the XML document as a string so it can be stored after it has been manipulated by the

service. ReturnXML is a very typical Service Object property you will see in many types of Service

Objects.

The last property defined is the XmlProperty. The XML Schema that was supplied as a configurable item

for the service instance is used to define the XmlProperty (namespace:

SourceCode.SmartObject.Services.ServiceSDK.Objects). The XmlProperty is the key component of

exposing XML from service instances. This property contains the schema that allows the SmartObject

properties to be mapped to the XML document. There are several properties XmlProperty that are

different from other service properties and parameters: the XML schema; a SoType of SoType.Xml; and

storing a sample XML document that conforms to the schema in the XmlDocument property. This

information is required to expose this schema to the SmartObject and enable mapping.

//The XML of the serialized object

MethodParameter inputXML = new MethodParameter();

inputXML.Name = "InputXML";

inputXML.SoType = SoType.Text;

inputXML.Type = "System.String";

inputXML.MetaData.DisplayName = "InputXML";

inputXML.MetaData.Description = "XML for schema " + schemaName;

//The return XML as a string

Property returnProp = new Property();

returnProp.Name = "ReturnXML";

returnProp.SoType = SoType.Text;

returnProp.Type = "System.String";

returnProp.MetaData.DisplayName = "ReturnXML";

returnProp.MetaData.Description = "XML for schema " + schemaName;

serviceObj.Properties.Add(returnProp);

//The SmartObject XML property to be exposed

XmlProperty xmlProp = new XmlProperty();

xmlProp.Name = schemaName;

xmlProp.MetaData.DisplayName = schemaName;

xmlProp.Type = "System.Xml";

xmlProp.MetaData.Description = schemaName;

xmlProp.SoType = SoType.Xml;

XmlTextReader rdr = new XmlTextReader(schemaFile); //could throw file not

found, and that's OK

xmlProp.Schema = XmlSchema.Read(rdr, null);

xmlProp.XmlDocument = GenerateSampleXml(xmlProp.Schema);

serviceObj.Properties.Add(xmlProp);

7

The Schema property is set by loading the XSD file that was supplied when the instance was configured

into a .NET (System.Xml.Schema) XmlSchema object. For the sample DynamicXMLService

implementation the schema file only has to exist on the K2 server where the instance is initially

configured or updated; it does not have to reside on all K2 servers in a load-balanced farm. Once the

schema is set, it becomes part of the service instance metadata.

Generating sample XML that conforms to the schema is handled in the GenerateSampleXML method.

This method uses a K2 utility—the same one used to generate the sample XML data when you add an

XML data field.

The remainder of DescribeSchema builds out the Get, Set, and Create methods of the service. The

above properties and parameter are attached to the methods as needed. For example, the Get method

has a required input parameter containing the XML document, and returns the XmlProperty as output.

Using this method, you could pass in the original XML from some data store like a data field or another

SmartObject, and then using the SmartObject Event Wizard to map the output from the XML to other

data fields in a process. The Create and Set methods behave similarly.

Execute

The Execute method in the service is the code that actually does the work of the service. Since this is a

very simple service, this method is correspondingly simple. To implement the Get method, all we have

to do is copy the XML supplied for the input parameter to the return XML property. The mapping

performed in the SmartObject designer will know how to map the values from the XML to the

SmartObject properties.

protected XmlDocument GenerateSampleXml(XmlSchema schema)

{

System.IO.StringWriter sw = new System.IO.StringWriter();

System.Xml.XmlTextWriter xw = new System.Xml.XmlTextWriter(sw);

SourceCode.Workflow.Common.Xml.XmlSampleGenerator gen = new

SourceCode.Workflow.Common.Xml.XmlSampleGenerator(schema,

System.Xml.XmlQualifiedName.Empty);

gen.WriteXml(xw);

XmlDocument doc = new XmlDocument();

doc.LoadXml(sw.ToString());

return doc;

}

//Get Method

Method getMethod = new Method();

getMethod.Name = Constants.Operations.Get.ToString();

getMethod.MetaData.DisplayName = Constants.Operations.Get.ToString();

getMethod.Type = MethodType.Read;

getMethod.MetaData.Description = "Get XML properties based on schema " +

schemaName;

getMethod.MethodParameters.Add(inputXML);

getMethod.ReturnProperties.Add(xmlProp);

serviceObj.Methods.Add(getMethod);

8

The Set and Create methods are a little more complex than the Get method, but similar to each other.

For the Set method we take the input XML as a parameter, and then set any values into the XML from

the SmartObject properties. In this case the input parameter is our XmlProperty. This property has a

collection of XPath objects that contain the XPath mapping for each property in the SmartObject and the

current value for that property. The code simply loops through all of the XPath mappings and updates

the XML node specified by the XPath expression to the value from the SmartObject property. Instead of

using methods on the XmlDocument or XPathNavigator classes in .NET, a K2 utility API is used to

perform the update: SourceCode.Workflow.Common.Utilities.XMLFieldMod.SetXMLValue

Note: if the input property is empty, the XML document is not updated.

The Create method is similar, but instead of taking XML as an input it generates a document based on

the schema, and then sets any input properties.

The XMLFieldMod.SetXMLValue method throws an exception if you try to set the value of a field defined

with xsi:nil=”true”. According to the wc3 org at http://www.w3.org/TR/2001/REC-xmlschema-0-

20010502 : “An element with xsi:nil="true" may not have any element content but it may still carry

attributes”. Avoid schemas that allow this setting.

Using the DynamicXMLService

This section will take you through an example step-by-step using the DynamicXMLService. The project

comes complete with source code and all of the sample files mentioned in the discussion below. The

project also includes an installer so you can install the service and start using it. This discussion will

show you how to install the service type, create an instance, then create a SmartObject based on the

instance and use it in a workflow. These instructions are written for K2 blackpearl 0807; other versions

may vary slightly.

In its current form, the DynamicXMLService is unable to handle schemas with qualified namespaces, like

those generated with InfoPath.

Installation

Run the SetupServiceObject.msi on the K2 host server to install the assembly and register the service

type.

case Constants.Operations.Set:

xml = parameters[0].Value.ToString();

foreach (XPath path in (inputs[0] as XmlProperty).XPaths)

{

if (string.IsNullOrEmpty(path.Data)) continue;

xml =

SourceCode.Workflow.Common.Utilities.XMLFieldMod.SetXMLValue(xml, path.Path,

path.Data);

}

returns[0].Value = xml;

break;

If you have more than one load-balanced host server, run the

the other servers, copy the DynamicXMLService.dll to the same directory specified in the setup wizard on

the first server (default \Program Files

Create a Schema

You will need to create or obtain a XSD schema

Employee.xsd is available in the zip file associated with this article.

create schemas: Visual Studio, XSD.exe, and

repeating elements. To work with correctly with this service, the

schema should be empty and qualified namespaces should not be used:

Create Service Instance

To create a new instance of the service, open

SmartObjects | Services | DynamicXMLService and then click the

Enter a name for your schema (it can be any valid name you can enter into the dialog) and the complete

path to your .XSD file, then click Next

9

balanced host server, run the .msi file only on one server to register it. On

e DynamicXMLService.dll to the same directory specified in the setup wizard on

Program Files\k2 blackmarket samples\dynamic xml service).

You will need to create or obtain a XSD schema to configure a service instance. A sample schema called

is available in the zip file associated with this article. There are several tools available to

create schemas: Visual Studio, XSD.exe, and several commercial tools. The schema should contain no

repeating elements. To work with correctly with this service, the targetNamespace setting for the

and qualified namespaces should not be used:

To create a new instance of the service, open K2 Workspace and got to Management Console |

DynamicXMLService and then click the Add button.


Next and then Save.

y on one server to register it. On

e DynamicXMLService.dll to the same directory specified in the setup wizard on

. A sample schema called

There are several tools available to

. The schema should contain no

setting for the

and got to Management Console |


If you update your schema later, simply go to this same location in the managem

schema, choose the Edit button and step through the wizard without changes

changes you have made, any SmartObjects based on this schema may need to be updated.

Create a SmartObject

Create a new empty K2 project, or use the one

accompanies this article. Add a new SmartObject called

remove all of the SmartBox methods.

• Click Add in the SmartObject Methods, then click

• Give the method a name, like

• Click Next

• Use the context browser to select the

• Highlight the input XML property

will appear

• For convenience you can click the

element and attribute. Or you can

10

If you update your schema later, simply go to this same location in the management console, se

and step through the wizard without changes. Depending on the


Create a new empty K2 project, or use the one called DynamicXMLTester in the zip file that

accompanies this article. Add a new SmartObject called XMLEmployee, go into advanced mode and

remove all of the SmartBox methods. Add the methods to connect to the service instance:

in the SmartObject Methods, then click Next

Give the method a name, like Create and a type of Create

Use the context browser to select the Create service instance method

property and then click Assign and the XML Property Mapping dialog

For convenience you can click the Create All button to quickly create a property for each XML

element and attribute. Or you can manually create properties and map them to XML nodes by

ent console, select your

. Depending on the


in the zip file that

, go into advanced mode and

Add the methods to connect to the service instance:

Property Mapping dialog

button to quickly create a property for each XML

create properties and map them to XML nodes by

clicking the Add button. When you

click OK.

You may want to go back to the SmartObject property editor and change the data

Decimal as this dialog makes them all a data type of Text.

• Back at the Add Service Object Me

ReturnXML and then click

then Next and Finish.

• Add another SmartObject Method called

• Bind this to the Get method of the service instance

• Click on the input parameter

• Create a SmartObject Method

• Highlight the return property and click

• This time on the XML Property Mapping

created for the previous method

• Click OK, Next, and Finish

• Add the final SmartObject method,

• Map the input parameter, XMLProperty

steps

• Save the SmartObject

11

. When you’re done the property mapping should look like

You may want to go back to the SmartObject property editor and change the data

Decimal as this dialog makes them all a data type of Text.

Add Service Object Method dialog, click on the return property name of

and then click Add to create a SmartObject property for it, then click

Add another SmartObject Method called Get and make the type Read

method of the service instance

Click on the input parameter InputXML and click the Assign button

SmartObject Method Parameter called InputXML for this parameter, then click

Highlight the return property and click Assign

Property Mapping dialog click Auto Map as the properties where already

created for the previous method

Add the final SmartObject method, Set and make it a type of Update

put parameter, XMLProperty, and the return property like you did in the previous

’re done the property mapping should look like below, then

You may want to go back to the SmartObject property editor and change the data for Salary to

dialog, click on the return property name of

to create a SmartObject property for it, then click OK and

for this parameter, then click OK

as the properties where already

like you did in the previous

Create a process

This process will be used to demonstrate this new SmartObject and service instance using the

SmartObject Event Wizard. This very simple process will create a new XML document, update a field,

and then send the result in an email.

using the zip file accompanying the article, one called

• Create a process level data field (not XML field) called

This field will be used to hold the persisted XML document.

Because XML fields can be quite large, it is a good idea to minimi

log and audit databases by un-checking the

information on log and audit options, see knowledge base article 352:

http://kb.k2workflow.com/articles/kb000352.aspx

There is a bug in release 0807 that throws an exception when you use the SmartObject

store a whole document in an XML field.

this service into an XML data field.

browser into K2 wizards.

• Create a second process data field called

1000

Next we’re going to simulate receiving an XML document from an external source.

where the document comes from.

the Create method on the XMLEmployee SmartObject

some initial values.

• Add a SmartObject Event to the design surface

o Click Next and give the event a name of

o For the SmartObject event, use the context browser to drill down to the

of the SmartObject

12

used to demonstrate this new SmartObject and service instance using the

This very simple process will create a new XML document, update a field,

and then send the result in an email. Add a new process to the project you created previously.

using the zip file accompanying the article, one called DynamicXMLTest has been created for you.

Create a process level data field (not XML field) called EmployeeData with a data type of string

This field will be used to hold the persisted XML document.

Because XML fields can be quite large, it is a good idea to minimize the amount of data stored in the K2

checking the Keep Log and Keep Audit options. For additional

information on log and audit options, see knowledge base article 352:

http://kb.k2workflow.com/articles/kb000352.aspx.

807 that throws an exception when you use the SmartObject

an XML field. Once this is fixed, it will be a natural choice to pers

With XML data fields you can simply drag elements from the

Create a second process data field called Salary of type decimal and give it an initial amount of

Next we’re going to simulate receiving an XML document from an external source.

where the document comes from. In this case, we’re going to add a SmartObject event and invoke

on the XMLEmployee SmartObject to create an empty document and assign it

Add a SmartObject Event to the design surface

and give the event a name of Receive XML

For the SmartObject event, use the context browser to drill down to the

of the SmartObject you created previously

used to demonstrate this new SmartObject and service instance using the

This very simple process will create a new XML document, update a field,

Add a new process to the project you created previously. If you are

has been created for you.

with a data type of string.

ze the amount of data stored in the K2

For additional

807 that throws an exception when you use the SmartObject Event Wizard to

Once this is fixed, it will be a natural choice to persist XML from

simply drag elements from the context

an initial amount of

Next we’re going to simulate receiving an XML document from an external source. It doesn’t matter

In this case, we’re going to add a SmartObject event and invoke

n empty document and assign it

For the SmartObject event, use the context browser to drill down to the Create method

o On the Input Mapping

browser:

� @employeeID

� Name = Process Originator Name

� Salary = Salary process data field

o On the Return Mapping screen, map the

data field so the XML document can be persisted

o Click Finish

In a real process, someone would make a decision

over that part of the workflow and just update the value of the XML element by using another

SmartObject Event Wizard and calling the

• Add a SmartObject Event Wizard to the designer, then click

• Name the event Update

• Use the XMLEmployee Set

• Click Next

• On the Input Mapping page, map the

parameter, and set Salary to a literal value of 2000

• On the Return Mapping page, persist the

and click Finish

In our simple process, we’re going to take a few shortcuts. The last step will be to notify the originator

of the new salary, but we could now pass

system.

• Drag a Server Mail Event onto the designer

• Set the From email to something reasonable and check the

• The subject can be anything

• The message body should contain

13

Input Mapping screen, make the following assignments from the context

@employeeID = Process Instance | Originator | FQN

= Process Originator Name

= Salary process data field

On the Return Mapping screen, map the ReturnXML field to the EmployeeData

data field so the XML document can be persisted

In a real process, someone would make a decision and a value would be updated. We’re going to skip

t of the workflow and just update the value of the XML element by using another

SmartObject Event Wizard and calling the Set method on the XMLEmployee.

Add a SmartObject Event Wizard to the designer, then click Next

Set method

page, map the EmployeeData process field to the SmartObject

to a literal value of 2000

page, persist the ReturnXML back to the EmployeeData


of the new salary, but we could now pass the XML document contained in XMLEmployee

Event onto the designer and click Next

email to something reasonable and check the Originator checkbox

The subject can be anything

The message body should contain some literal text like “The new salary is: ”

from the context

EmployeeData process

and a value would be updated. We’re going to skip

t of the workflow and just update the value of the XML element by using another

process field to the SmartObject InputXML

EmployeeData process field


XMLEmployee to another

checkbox

• Open the context browser and browse drag the

body

o Link the InputXML

o Select Salary as the return value

o Click Finish

If the SmartObject Event Wizard could store to process XML fields, we could

instead of a string and simply drag the field from the context browser

The complete process should look like

with the new salary value.

Conclusion XML Properties can be used map complex

properties. Although there are some limitations, like no repeating groups, this can be a convenient way

to present complex data types in a simple way that can be used anywhere a SmartObject can be used.

14

Open the context browser and browse drag the XMLEmployee Get method onto the message

InputXML parameter to the EmployeeData process field

as the return value

If the SmartObject Event Wizard could store to process XML fields, we could store our document there

simply drag the field from the context browser.

The complete process should look like below. Deploy and run the process. You should receive an email

complex data structures from Service Objects to SmartObject



method onto the message

store our document there

ld receive an email

Objects to SmartObject



Using XML Properties in SmartObjects -...

Documents

Transcript of Using XML Properties in SmartObjects -...