1 Services Reference

Transcription

K2 blackpearl Services Reference | 1
1
Services Reference
© 2008 - 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. SEE THE K2 blackpearl Copyright and Trademark
Statement
help file version K2 4.6.6 (
4.12060.1560.0 )
1.1
K2 SmartObject Services
Statement
4.12060.1560.0 )
1.1.1 K2 SmartObject Services Introduction
Overview
The K2 SmartObject Services provide out-of-the-box web service functionality for SmartObjects configured on the K2
Server via common Web service endpoints, such as RESTful web services (REST - Representational State Transfer)
and Windows Communication Foundation (WCF). Developers familiar with the SourceCode.SmartObject.Client APIs
will be able to quickly start using the REST or WCF endpoints in their applications.
Web services create application-to-application interactions and typically work outside of private networks, offering
developers a non-proprietary route to their solutions. Web services also let developers use their preferred
programming languages, and thanks to the use of standards-based communications methods, web services are
virtually platform independent.
Using K2 SmartObject Services
The K2 SmartObject Services expose system (out-of-the-box) and custom SmartObject data and operations to non
K2 environments, allowing custom applications and Service Oriented Architectures (SOA) to consume and supply K2
SmartObject data.
The following topics explain the architecture, configuration and services available at each endpoint.
Architecture
Configuration
REST Services
WCF Services
Statement
4.12060.1560.0 )
1.1.2 Architecture
Architecture
The K2 Server provides a surrogate IIS service that hosts the SmartObjects as virtual web assemblies. When a
service call is made for the SmartObject, the K2 Server intercepts the service call and handles it by providing access
to the K2 SmartObject as a web service call. Unlike a standard web assembly, there is nothing physical outside the
hosting provided by the K2 Server. In other words the K2 SmartObject is accessible only when the K2 Server is
running and K2 SmartObject Services are enabled.
K2 SmartObject Services can expose endpoints for both System (out-of-the-box) and Custom SmartObjects.
System SmartObjects: System SmartObjects are the SmartObjects available on every K2 Server. These
SmartObjects provide access to various aspects of the K2 Server which may be useful as a data service, such as
reporting, Active Directory and Exchange SmartObjects. The System SmartObjects that are exposed is fully
configurable.
Statement
4.12060.1560.0 )
Custom SmartObjects: The custom SmartObjects are those created by end users utilizing the SmartObject
infrastructure within K2. The custom SmartObjects which are exposed is fully configurable.
SmartObject Endpoint Generation
Once K2 SmartObject Services has been enabled, the K2 Server will generate the configured SmartObject service
endpoints at start up and optionally when SmartObjects are deployed. The service location and configuration of the
SmartObject endpoints generated are determined based on the the settings in the K2HostServer.config file – see the
Configuration for more details.
The following items are generated for each configured SmartObject endpoint.
Contract
Description
Service Contract
(aka, Endpoint)
A service contract (endpoint) will be generated for every category in
the category system
Data Contract
A data contract will be generated for every SmartObject in a
category at each endpoint.
Operation Contract
(aka, Binding)
An operation contract (binding) will be generated for every method
of every SmartObject in a category at each endpoint.
Statement
4.12060.1560.0 )
The K2 SmartObject Service will build endpoints using the following logic:
When the K2 Server is started and if the K2 SmartObject Services are enabled (they are off by default)
1. Create a list of excluded categories/subcategories based on the configuration
2. Iterate through the category server building endpoints with SmartObject bindings for every category and
subcategory found that has not specifically been marked as an exclusion
3. Iterate through the SmartObjects listed in the Managed section building 1:1 endpoint:binding mappings
4. All endpoints will be loaded into a single AppDomain by default unless specifically configured for isolation
When a SmartObject is created/updated/deleted and if the K2 SmartObject Services are enabled for events (they
are on by default)
1. The AppDomain that is hosting the endpoint for the SmartObject will be reloaded thus reflecting the
create/update/delete of the SmartObject that caused the reload (and any other Categories/SmartObjects
that might have changed)
System Resource Requirements
Enabling K2 SmartObject Services can affect the performance of the K2 Server in the following ways:
Startup Time
Each SmartObject exposed as a web service requires a Just in Time (JIT) code compilation of the endpoint for that
SmartObject during the startup of the K2 Server. The overall time to JIT for each SmartObject is typically
negligible. A large number of SmartObjects may have an adverse effect on the startup time of K2 Server.
System Memory
Each SmartObject exposed as a web service utilizes additional physical RAM in the hosted assembly. The overall
physical RAM for each SmartObject is typically negligible. A large number of SmartObjects may have an adverse
effect and require monitoring of K2 Server System Memory consumption.
Statement
4.12060.1560.0 )
1.1.3 Configuration
Configuration
K2 SmartObject Services is not enabled by default and must be explicitly turned on. This allows the K2 administrator
to appropriately review all configuration options available before exposing any system or custom SmartObject data to
via endpoints. Additionally, the K2 Server is responsible for publishing these services and handling the requests from
these services, and as such, extremely large queries may put an undo strain on the server. Before enabling the
services, administrators should determine which SmartObjects are to be exposed and how large the queries are for
those SmartObjects.
The configuration options allow to control items such as:
Whether the service is on/enabled
Whether dynamic endpoints are generated for newly deployed SmartObjects
The base service URI (Uniform Resource Indicator) and SSL (Secure Sockets Layer) requirement
Which categories and SmartObjects are exposed
The binding options
Security and Authentication
K2 SmartObject Services supports two primary authentication modes, Windows and Basic. Basic authentication is
inherently insecure over non-SSL transports. K2 SmartObject Services are configured, by default, for Windows
authentication over HTTP. It is recommended to use SSL whenever configuring endpoints using Basic authentication,
and disabling the SSL requirement for Basic authentication should be used for development purposes only.
K2 SmartObject Services can support running both http and https side-by-side with the proper endpoint and binding
configurations.
The authentication mode being used is based on a combination of the service endpoints configured (<smoServices>)
and the authentication binding for that endpoint (<bindings>). Additionally, when the binding is configured to allow
Basic authentication, and a Basic request is sent from the client, the {defaultlabel} attribute is the K2 security label
used to match the user.
The root (base)URL address is set at installation time for new installations., Static URLs do not get set and, if
required, should be manually configured later. The following command is used to set the a static URL:
netsh http add urlacl url=http://HostName:Port/
Configuring an HTTP SPN
Certain environments require the K2 Service Account to have an HTTP SPN set for the local machine where the
endpoints are hosted. If 401 and 400 HTTP errors are encountered then the HTTP SPN must be set.
Example:
User: Domain\K2ServiceAccountUser
HTTP/MachineName
HTTP/MachineName.Domain.com
Or on Cluster environments (if this is the endpoint URL)
HTTP/ClusterName
HTTP/ClusterName.Domain.com
K2HostServer.exe.config
At installation, <smoServices> and <system.serviceModel> sections are configured in the K2HostServer.exe.config
file located at [Installation Directory]\Host Server\Bin\
The following is an example of these settings using a URI of “api.denallix.com” on a fictitious domain.
Copy
Statement
4.12060.1560.0 )
<smoServices enableEndpoints="false" enableEvents="true"
enableCrossDomainPolicy="false" enableMetadata="true" scheme="http"
server="api.denallix.com" port="8888"
serviceRoot="SmartObjectServices" specialCharacterReplacement="_"
defaultSecurityLabel="K2">
<wcf binding="wsHttpBinding"
bindingConfiguration="wsHttpBinding+Windows"
individualSmartObjects="true" />
<rest binding="webHttpBinding"
bindingConfiguration="webHttpBinding+Windows" />
<managedEndpoints>
<excluded all="true" />
</managedEndpoints>
</smoServices>
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="basicHttpBinding+Windows+HTTPS">
<security mode="Transport">
<transport clientCredentialType="Windows" />
</security>
</binding>
<binding name="basicHttpBinding+Basic+HTTPS">
<transport clientCredentialType="Basic" />
</security>
</binding>
<binding name="basicHttpBinding+Windows">
<security mode="TransportCredentialOnly">
</security>
</binding>
<binding name="basicHttpBinding+Basic">
</security>
</binding>
</basicHttpBinding>
Statement
4.12060.1560.0 )
<wsHttpBinding>
<binding name="wsHttpBinding+Windows">
<security mode="Message" />
</binding>
<binding name="wsHttpBinding+TWMC+HTTPS">
<security mode="TransportWithMessageCredential">
<message clientCredentialType="Windows" />
</security>
</binding>
<binding name="wsHttpBinding+HTTPS">
</security>
</binding>
</wsHttpBinding>
<webHttpBinding>
<binding name="webHttpBinding+Basic">
</security>
</binding>
<binding name="webHttpBinding+Windows">
</security>
</binding>
<binding name="webHttpBinding+Basic+HTTPS">
</security>
</binding>
<binding name="webHttpBinding+Windows+HTTPS">
Statement
4.12060.1560.0 )
</security>
</binding>
</webHttpBinding>
</bindings>
</system.serviceModel>
The configuration section consists of four main components:
<smoServices> – these attributes control the default functionality of the services, including if it is enabled to run
or not
<wcf><rest> – these attributes control the bindings for the WCF and REST endpoints, including overriding the
default functionality
<managedEndpoints> – these elements and attributes control which categories and SmartObjects are exposed by
the services
<system.serviceModel> – these elements and attributes control the security binding for the endpoints
Services
enableEndpoints (Boolean) – determines if the K2 SmartObject Services service is started
true – start K2 SmartObject Services and load the configured endpoints
false (default/omitted) – does not start K2 SmartObject Services or load any endpoints
enableEvents (Boolean) – determines if additions and changes to SmartObjects are reflected dynamically without
restarting K2 Server
true (default/omitted) – when SmartObjects are created/changed/deleted the service dynamically reloads the
AppDomain containing the affected SmartObjects
false – when SmartObjects are created/updated/deleted the service will not reflect the changes without
restarting K2 Server
enableCrossDomainPolicy (Boolean) – determines if the service endpoints have cross domain support
true – enable cross-domain support allowing browser-based applications, including Silverlight applications, to
make calls to the service endpoint from a different domain
Files – the files that control the level of cross-domain support are crossdomain.xml and
clientaccesspolicy.xml. These files can be found and edited in the [Installation Directory]\Host
Server\Bin\SmoServices directory.
Note: the server value must be a DNS name or fully-qualified machine name for cross-domain support to
work properly.f
false (default/omitted) – disables cross-domain support disallowing browser-based applications, including
Silverlight applications, to make calls to the service endpoint from a different domain
enableMetadata (Boolean) – determine if a Service Metadata Document (aka, WSDL) will be generated for the
endpoint via ?wsdl
true (default/omitted) – a Service Metadata Document is created for the endpoint
false – a Service Metadata Document is not be created for the endpoint
scheme (String, required) – the default scheme (http or https if SSL is enabled) for the endpoints. Default: http
server (String, required) – the DNS or fully qualified domain name of the server hosting the endpoints. Default:
{Fully Qualified Machine Name}
port (String) – the default port for the endpoints.
Default: 8888,
Omitted: 80
serviceRoot (String) – the default service root for the endpoints.
Default: SmartObjectServices
specialCharacterReplacement (String) – allows administrators to control what character is used in place of
disallowed generated characters such as spaces.
Default/Omitted: _(underscore character)
defaultSecurityLabel (String) – sets the default security label to prepend to the user name for basic authentication
methods.
Default: K2, Omitted: No security label is prepended and the user name must contain the label
WCF
Statement
4.12060.1560.0 )
The <wcf> section contains the default binding configuration for the WCF endpoints and optional WCF specific
Service URI components.
binding (string, required) – sets the default binding type for the WCF endpoint
Support for basicHttpBinding, wsHttpBinding
Default: wsHttpBinding
bindingConfiguration (string, required) – sets the configuration in the <system.serviceModel> section which
contains the binding details for the endpoint.
Default: wsHttpBinding+Windows
individualSmartObjects (Boolean, optional) – sets the configuration for endpoint generation to per Category or per
SmartObject
true – generate an endpoint for each category and additional endpoints for each SmartObject in the category
using the [CategoryName_SmartObjectName] format
false (default/omitted) – generate an endpoint for each category with the SmartObjects contained in that
endpoint
scheme (string) – if present, overrides the default scheme and requires server
server (string) – if present, overrides the default server and requires scheme
port (string) – if present, overrides the default port
serviceRoot (string) – if present, overrides the default service root
defaultSecurityLabel (string) – if present, overrides the default security label
REST
The <rest> section contains the default binding configuration for the REST endpoints and optional REST specific
Service URI components.
binding (string, required) – sets the default binding type for the REST endpoint
Support for webHttpBinding
Default: webHttpBinding
Default: webHttpBinding+Windows
Managed Endpoints
The category is the default high-level object that is bound to the endpoint via the URI. For example, if a category
and SmartObject exist at the same level, the endpoint is bound to the category. In addition to the default binding of
SmartObjects methods within a category endpoint, SmartObjects can be configured to also have their own endpoints
which provides direct URI navigation to the SmartObject. In the case where a category and a SmartObject have the
same endpoint, the category will supercede the SmartObject and be bound to the endpoint. An error is logged for the
conflict but the category functions correctly.
Managing the endpoints allows the administrator to control which categories and SmartObjects are available via WCF
and REST services. There are two main sections:
Excluded - means the category path and the SmartObjects in that category are excluded. Each subcategory is
not automatically excluded and requires a separate entry.
Static - means the specific category and, depending on the scenario, a specific SmartObject is included.
Excluded
Configure excluded endpoints to prevent a category or subcategory, and the SmartObject methods in that
category/subcategory, from having an endpoint generated.
all (Boolean, required) – determine if all categories will be excluded
true (default) – exclude all categories from endpoint generation. This allows for only static endpoints to be
available.
Statement
4.12060.1560.0 )
false – generate endpoints for all categories not explicitly excluded
<endpoints> contains an <endpoint> for each category path to explicitly exclude
categoryPath (string, required) – the path to the category/subcategory
Example 1: Exclude the Task Allocation category from endpoint generation. All subcategories of Task
Allocation are still included unless excludeSubCategories is true.
<endpoint categoryPath="Task Allocation"/>
Example 2: Exclude the Workflow Reports/Workflow General subcategory from endpoint generation. The
parent category, Workflow Reports, and any subcategories are still included unless excludeSubCategories is
true.
<endpoint categoryPath="Workflow Reports/Workflow General"/>
excludeSubCategories (Boolean, optional) – the path to the category/subcategory
true – exclude the parent category and all subcategories from endpoint generation.
false (default) – generate endpoints for all subcategories not explicitly excluded
Example: Exclude the Task Allocation category and all its subcategories from endpoint generation.
<endpoint categoryPath="Task Allocation" excludeSubCategories="true"/>
Static
Static endpoints can be configured to allow the following:
A one-to-one mapping of a SmartObject to an endpoint
Aliasing of the SmartObject URI
Creation of a custom AppDomain
A different binding type
Selection of a specific SmartObject version
categoryPath (String) (required) – the path to the category/subcategory
Example: Including all SmartObjects in a category.
<endpoint categoryPath="MyCategory/MyProject" />
When specified without a specific SmartObject name in the smartobjectName attribute, all SmartObjects in
the category path are generated. Additionally, if a category path specified does not exist, it is monitored so
that when a SmartObject is deployed to this category path at a later time, the endpoint is generated.
smartobjectName (string, optional) – the name of the specific SmartObject
Specified – when specified, the endpoint is generated for the SmartObject
Omitted – when not specified, all SmartObjects present in the category path are included in the endpoint
alias (string, optional) – the new path to be used for navigating to the endpoint for this SmartObject or Category.
Path search will use the display name while the binding that is generated uses system name.
If there is a collision with an existing Category or SmartObject, then the last one configured wins. For
example, if you configure two static endpoints with exactly the same alias, the second one in the list assumes
the alias and the first one is not present.
Example: alias="MySmartObjectAlias" generates a SmartObject endpoint binding at
http://api.denallix.com:8888/SmartObjectServices/MySmartObject
isolationLevel (string, optional) – used to specify the AppDomain the endpoint uses
shared (default/omitted) – by default all endpoints use a single AppDomain. Not setting isolationLevel or
specifying isolationLevel="shared" has the same effect of using the default AppDomain of the service.
single – setting the isolationLevel="single" ensures that the endpoint for this SmartObject has its own
AppDomain allowing for isolation from other endpoints. This is useful when the SmartObject is changing
often as the reload of the endpoint does not affect other endpoint
smartobjectVersion (string, optional) – used to specify a specific version of the SmartObject definition to
bind to the endpoint. The latest version of the SmartObject definition is bound by default.
The <wcf> or <rest> section, if present, overrides the WCF and/or REST configuration for the service for this
static endpoint.
binding (string) – if present, overrides the default binding type configured for the WCF or REST service
Support for basicHttpBinding, wsHttpBinding, webHttpBinding
Statement
4.12060.1560.0 )
bindingConfiguration (string) – if present, overrides the default binding configuration for the WCF/REST service
Service Models
The <system.serviceModel> section controls the security binding for the configured endpoints.
Each endpoint defines an associated <binding> via the bindingConfiguration attribute. This allows each endpoint to
support a different security binding allowing for the mixing of authentication and SSL requirements for the same
service. The REST endpoints are associated with <webHttpBinding> bindings while WCF endpoints are associated
with either <wsHttpBinding> or <basicHttpBinding> bindings. For example, the default bindingConfiguration for the
WCF service endpoints is wsHttpBinding+Windows found in the <bindings><wsHttpBinding><binding
name="wsHttpBinding+Windows"> section.
Copy
<wcf binding="wsHttpBinding"
bindingConfiguration="wsHttpBinding+Windows" />
The <bindings> section contains the configuration details for each binding. The two main configuration elements
related to SmartObject Services bindings are <security> and <transport>.
The <security mode=""> element/attribute defines whether or not SSL is supported. Although None allows K2 to
manage the binding requirements this is not the case with WCF. Unfortunately, WCF does not allow both SSL
(HTTPS) and non-SSL (HTTP) support on the same endpoint. Therefore, SmartObject Services must have multiple
endpoints and mappings to multiple bindings to support both SSL (HTTPS) and non-SSL (HTTPS) for the same
service. Examples for all the supported binding configurations have been provided in the <system.serviceModel>
section.
K2 recommends setting <security mode="Message"> (WCF) or <security mode="TransportCredentialOnly"> (REST)
for standard non-SSL (HTTP) support and <security mode="TransportWithMessageCredential"> (WCF) or <security
mode="Transport"> (REST) to enable SSL (HTTPS) support. Remember that when bindings are enabled, an
associated service endpoint must also be enabled.
The <transport clientCredentialType=""/> element/attribute defines what credential types will be supported by client
requests headers. K2 recommends setting <transport clientCredentialType="Windows"/> when Windows credentials
are available. The setting of <transport clientCredentialType="Windows"/> should be used to enable support for
Basic. Remember that when bindings are enabled, an associated service endpoint must also be enabled.
Example
The following example shows the usage of all Service and Managed Endpoint configuration options. The K2
SmartObject Services start when K2 Server starts and load endpoints at the
http://api.denallix.com:8888/SmartObjectServices base URI. Other facts about this configuration include:
Basic authentication via HTTP for WCF mapped to the K2SQL security label and Windows authentication via HTTPS
for REST.
Cross Domain Policies are not supported.
When SmartObjects are created, updated or deleted their endpoints will be reloaded and generated using a “_” for
special characters.
All categories and their SmartObjects are loaded except for those found at Task Allocation or Workflow
Reports/Workflow General.
Finally, a static endpoint supporting Basic authentication for REST using the K2SQL security label is generated in a
separate application domain for the K2 Examples/Employee at the aliased URI
http://api.denallix.com:8889/SmartObjects/MySmartObjectAlias
Copy
Statement
4.12060.1560.0 )
<smoServices enableEndpoints="true" enableEvents="true"
enableCrossDomainPolicy="false" enableMetadata="true"
scheme="http" server="api.denallix.com" port="8888"
serviceRoot="SmartObjectServices"
specialCharacterReplacement="_"
defaultSecurityLabel="K2">
<wcf binding="basicHttpBinding+Basic"
bindingConfiguration="wsHttpBinding+Basic"
defaultSecurityLabel="K2SQL" />
bindingConfiguration="webHttpBinding+Windows+HTTPS"
scheme="https" server="api.denallix.com" port="8890"
serviceRoot="SmartObjectServices" />
<managedEndpoints> <excluded all="false">
<endpoints>
<endpoint categoryPath="Task Allocation"
excludeSubCategories="true"/>
<endpoint categoryPath="Workflow Reports/Workflow
General"/>
</endpoints>
</excluded>
<static>
<endpoints>
<endpoint categoryPath="K2 Examples/Employee">
bindingConfiguration="webHttpBinding+Windows"
scheme="http" server="denallix.denallix.com" port="8889"
serviceRoot="SmartObjects" defaultSecurityLabel="K2SQL"/>
</endpoint>
</endpoints>
</static>
</managedEndpoints>
</smoServices>
Statement
4.12060.1560.0 )
1.1.3.1 Windows Authentication with SSL for K2 SmartObject Services
Windows Authentication with SSL for K2 SmartObject Services
To configure the K2 SmartObject Services with standard Windows Authentication using SSL, find the
(<smoServices>) section in the K2HostServer.exe.config file in the {SystemRoot}\Program Files(x86)\K2
blackpearl\Host Server\Bin directory and follow the steps below:
1.
2.
3.
4.
Change enableEndpoints="false" to enableEndpoints="true"
Change scheme="http" to scheme="https"
Change port="8888" to port="8443"
Change wcf binding="wsHttpBinding" bindingConfiguration= "wsHttpBinding+Windows" to wcf
binding="wsHttpBinding" bindingConfiguration= "wsHttpBinding+HTTPS"
5. Change rest binding="webHttpBinding" bindingConfiguration= "webHttpBinding+Windows" to rest
binding="webHttpBinding" bindingConfiguration= "webHttpBinding+Windows+HTTPS"
6. Change excluded all="true" to excluded all="false"
7. Configure the URL Access Control List so that the service account can use the https url:
Open a command prompt
Execute the following command (replace [server] with the server entry in (<smoServices>) section, and
replace [domain\ServiceAccountUsername] with the service account details)
Copy
netsh http add urlacl url=https://[server]:8443/
user=[domain\ServiceAccountUsername]
8. Configure the SSL for the port:
Open a command prompt
Execute the following command (replace [CertificateThumbprint] with the thumbprint of the server
certificate on the server)
Copy
netsh http add sslcert ipport=0.0.0.0:8443
certhash=[CertificateThumbprint]
appid={4dc3e181-e14b-4a21-b022-59fc669b0914}
9. Restart the K2 blackpearl Server service.
10. Validate that you can access the endpoints by navigating to the following url (replace [env] with Dev, SQA, or
Demo depending upon which environment you are working on)
https://[server]:8443/SmartObjectServices/endpoints/endpoints.xml
Statement
4.12060.1560.0 )
1.1.4 REST Services
REST Services
Overview
K2 SmartObject Services provide RESTful web services (REST) endpoints for configured system and custom
SmartObjects on a K2 Server.
The information in this section provides full details on the standard methods available for the services including
examples to help get you started.
The sample code provided in this section as a demonstration of the REST Services
usage is written for use with Web based forms. Sample code for Windows based forms
will be available in a future release of the Developer's Reference
Service Endpoints
K2 SmartObject Services REST endpoints provide standard URIs (Uniform Resource Identifiers) for interacting with
the available SmartObjects data and operations. These topics will help in the construction of the appropriate URI for
the desired operation.
The following custom Employee SmartObject will be used for examples in this section.
URIs for REST Services
Standard SmartObject Methods
Create
Read
Update
Delete
List
Statement
4.12060.1560.0 )
Execute
Errors and Response Codes
The K2 SmartObjects Services uses the following standard HTTP status codes.
200
400
404
405
503
500
(OK) – returned if the call was successful
(Bad Request) – returned if the Request Body was not correctly formatted
(Not Found) – returned if something requested is no longer available
(Method Not Allowed) – returned if the method is not allowed for the SmartObject
(Service Unavailable) – returned if the K2 Server was unreachable
(Server Error) – returned if any other error occurred
Different languages and platforms handle HTTP status codes differently. Ensure that sufficient error handling is
present for these status codes.
Statement
4.12060.1560.0 )
1.1.4.1 URIs_for_REST
URIs for Services
The sample code provided as a demonstration is written for use with Web based forms. Sample code for Windows based forms will be
available in a future release of the Developer's Reference
URI Structure
{Service Root URI}{Service Path}?{Query Options}
Returns a collection of the first two Employees, starting with the tenth one, in XML format.
Service Root URI = {Scheme}{Server}:{Port}{Service Root}/{Service Type}
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 = /REST
The Service Root URI up to Service Type is configured via, the scheme, server, port and serviceroot settings in K2HostServer.exe.config.
Service Path = {CategoryPath}{SmartObjectName}{MethodName} – Identifies the SmartObject method to be interacted with, such as Employee Get List.
CategoryPath = the path to the category that contains the SmartObject
SmartObjectName = the display name of the SmartObject
MethodName = the display name of the SmartObject method to execute
Query Options = {System Query Options }&{Custom Query Options}
Multiple parameters can be combined using and & between them
System Query Options – optional query string parameters that can be used to control the format and amount of data returned. The System Query Options start with a $
and are typically available for all URIs that return data.
$format = xml (default), atom, or json
Specifies the format to return the results. Uses default if omitted.
https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$format=atom
Collection Options
$skip = 0 (default), or N
Specifies N number of records to skip. Uses 0 when omitted, which will return all records.
https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$skip=2
$top = 0 (default), or N
Specifies the first N records to retrieve. Uses 0 when omitted, which will return all records.
https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$top=5
filterXml = {filterXml}
Specifies the SmartObject filter to use to limit the results. Uses no filter when omitted, which will return all records. See the Filter section for more information.
https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?filterXml=<filterexp><equals><left><propertyexp name="Last_Name"
sotype="Text"/></left><right><valueexp sotype="Text">Cowan</valueexp></right></equals></filterexp>
Custom Query Options – additional parameters specific to each SmartObject
Special Characters
K2 SmartObject Services utilizes standard URL escaping for URI construction.
%20 = {space} (standard URL escaping
Filter
K2 SmartObject Services utilizes the capabilities of the SmartObjects Filter Framework to enable filtering of your List based results for REST endpoints.
All SmartObject List methods will support the filterXml={filterXml} system query option via the REST endpoints.
The filterXml query option takes a single string parameter which is the filter represented as XML.
Copy
GET /SmartObjectServices/REST/K2%20Examples/Employee/Get%20List?filterXml=<filterexp>
<equals><left><propertyexp name="Last_Name" sotype="Text"/></left><right><valueexp
sotype="Text">Cowan</valueexp></right></equals></filterexp>
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. Add a using statement using SourceCode.SmartObjects.Client.Filters;
3. Use the object model to build the filter
Copy
static string BuildFilter()
Statement
4.12060.1560.0 )
{
Equals lastNameEquals = new Equals();
PropertyExpression lastNameExpression = new PropertyExpression("Last_Name",
PropertyType.Text);
ValueExpression lastNameValue = new ValueExpression("Cowan", PropertyType.Text);
lastNameEquals.Left = lastNameExpression;
lastNameEquals.Right = lastNameValue;
// Serialize
FilterExp filterExpression = new FilterExp(lastNameEquals);
XmlDocument filterXml = filterExpression.GetFilterXml();
return filterXml.InnerXml;
}
The resulting XML for this BuildFilter() method would resemble the following:
Copy
<filterexp><equals><left><propertyexp name="Last_Name"
sotype="Text"/></left><right><valueexp sotype="Text">Cowan</valueexp></right></equals>
</filterexp>
Copy XML Return Example
GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=xml&$skip=10&$top=2
<ArrayOfEmployee xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Employee>
<Id>11</Id>
<Username>DENALLIX\Rick</Username>
<First_Name>Rick</First_Name>
<Last_Name>Cowan</Last_Name>
<Email>rick@denallix.com</Email>
</Employee>
<Employee>
<Id>12</Id>
<Username>DENALLIX\Koos</Username>
<First_Name>Koos</First_Name>
<Last_Name>du Preez</Last_Name>
<Email>koos@denallix.com</Email>
</Employee>
</ArrayOfEmployee>
Copy ATOM Return Example
GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom&$skip=10&$top=2
<feed xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<title type="text">K2 SmartObject Feed</title>
<subtitle type="text">K2 SmartObject Feed</subtitle>
<id>uuid:3c37d960-b60c-459f-9c9b-f65ede207107;id=1</id>
<updated>2011-02-17T18:27:40-07:00</updated>
<category term="Employee:GetList"/>
<author>
<name>K2 Server</name>
<uri>http://www.k2.com</uri>
<email>admin@k2.com</email>
</author>
<link rel="alternate"
href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?
$format=atom"/>
<entry>
<id>a6eacb3a-6a98-4cdc-8321-cd5544f91ae4</id>
<title type="text">Employee Row 1</title>
<summary type="text"/>
$format=atom"/>
<content type="application/xml">
Statement
4.12060.1560.0 )
<m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
<d:Id m:type="Edm.Int32">1</d:Id>
<d:Username m:type="Edm.String">DENALLIX\Rick</d:Username>
<d:First_Name m:type="Edm.String">Rick</d:First_Name>
<d:Last_Name m:type="Edm.String">Cowan</d:Last_Name>
<d:Email m:type="Edm.String">rick@denallix.com</d:Email>
</m:properties>
</content>
</entry>
<entry>
<id>c8eb486f-da64-45af-b48c-c69bd08480ec</id>
$format=atom"/>
<d:Username m:type="Edm.String">DENALLIX\Koos</d:Username>
<d:First_Name m:type="Edm.String">Koos</d:First_Name>
<d:Last_Name m:type="Edm.String">du Preez</d:Last_Name>
<d:Email m:type="Edm.String">koos@denallix.com</d:Email>
</m:properties>
</content>
</entry>
</feed>
GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom&$skip=10&$top=2
<feed xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<title type="text">K2 SmartObject Feed</title>
<subtitle type="text">K2 SmartObject Feed</subtitle>
<id>uuid:3c37d960-b60c-459f-9c9b-f65ede207107;id=1</id>
<category term="Employee:GetList"/>
<author>
<name>K2 Server</name>
<uri>http://www.k2.com</uri>
<email>admin@k2.com</email>
</author>
$format=atom"/>
<entry>
<id>a6eacb3a-6a98-4cdc-8321-cd5544f91ae4</id>
$format=atom"/>
<d:Username m:type="Edm.String">DENALLIX\Rick</d:Username>
<d:First_Name m:type="Edm.String">Rick</d:First_Name>
<d:Last_Name m:type="Edm.String">Cowan</d:Last_Name>
<d:Email m:type="Edm.String">rick@denallix.com</d:Email>
</m:properties>
</content>
</entry>
<entry>
<id>c8eb486f-da64-45af-b48c-c69bd08480ec</id>
$format=atom"/>
Statement
4.12060.1560.0 )
<d:Username m:type="Edm.String">DENALLIX\Koos</d:Username>
<d:First_Name m:type="Edm.String">Koos</d:First_Name>
<d:Last_Name m:type="Edm.String">du Preez</d:Last_Name>
<d:Email m:type="Edm.String">koos@denallix.com</d:Email>
</m:properties>
</content>
</entry>
</feed>
Copy JSON Return Example
GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=json&$skip=10&$top=2
[{"Id":1,"Username":"DENALLIX\\Rick","First_Name":"Rick","Last_Name":"Cowan","Email":"rick@denallix.com"},
{"Id":2,"Username":"DENALLIX\\Koos","First_Name":"Koos","Last_Name":"du
Preez","Email":"koos@denallix.com"}]
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.
Endpoints XML Example
A default installation of K2 blackpearl configured to generate endpoints for all system (out-of-the-box) SmartObjects produced this endpoints.xml (showing only REST endpoints).
Copy
GET /SmartObjectServices/endpoints/endpoints.xml
<?xml version="1.0"?>
<endpoints>
<rest-endpoints>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD
User/Create</endpoint>
User/Update?Name={Name}</endpoint>
User/Disable?Name={Name}</endpoint>
User/AddToGroups?Name={Name}&Groups={Groups}</endpoint>
User/RemoveFromGroups?Name={Name}&Groups={Groups}</endpoint>
User/RemoveFromAllGroups?Name={Name}</endpoint>
Group/Create</endpoint>
Group/Update?Name={Name}</endpoint>
Group/Remove?Name={Name}</endpoint>
Group/AddMembers?Name={Name}&Members={Members}</endpoint>
Group/RemoveMembers?Name={Name}&Members={Members}</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange
Calendar/New Meeting</endpoint>
Calendar/New Appointment</endpoint>
Management/Enable Mailbox</endpoint>
Management/Disable Mailbox</endpoint>
Task/New Task</endpoint>
Meeting/Check Specific Time?$format={format}&$top={top}&$skip={skip}&filterXml=
{filterXml}&OnBehalfOf={OnBehalfOf}&RequiredAttendees=
{RequiredAttendees}&StartDateTimeFreeBusy=
{StartDateTimeFreeBusy}&EndDateTimeFreeBusy={EndDateTimeFreeBusy}</endpoint>
Meeting/Get Meeting Suggestions?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&OnBehalfOf={OnBehalfOf}&RequiredAttendees=
{RequiredAttendees}&StartDateTimeFreeBusy=
{StartDateTimeFreeBusy}&EndDateTimeFreeBusy=
{EndDateTimeFreeBusy}&MeetingDurationMinutes={MeetingDurationMinutes}</endpoint>
Statement
4.12060.1560.0 )
Metadata/Get Available Exchange Servers?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}</endpoint>
Metadata/Get Available Storage Groups?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&ServerName={ServerName}</endpoint>
Metadata/Get Available Mailbox Databases?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&ServerName={ServerName}</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task
Allocation/RoundRobinSO/Create</endpoint>
Allocation/RoundRobinSO/Save?RoleName={RoleName}</endpoint>
Allocation/RoundRobinSO/Delete?RoleName={RoleName}</endpoint>
Allocation/RoundRobinSO/Load?RoleName={RoleName}</endpoint>
Allocation/RoundRobinSO/Get List?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&RoleName={RoleName}</endpoint>
Allocation/TaskAllocationADMethods/Get Manager?UserName={UserName}</endpoint>
Allocation/TaskAllocationADMethods/Get Direct Reports?$format={format}&$top=
{top}&$skip={skip}&filterXml={filterXml}&UserName={UserName}</endpoint>
Allocation/TaskAllocationRoleMethods/Get Least Work?RoleName={RoleName}</endpoint>
Allocation/TaskAllocationRoleMethods/Get Most Work?RoleName={RoleName}</endpoint>
Allocation/TaskAllocationRoleMethods/Get Round Robin?RoleName={RoleName}</endpoint>
Allocation/TaskAllocationRoleMethods/Get Fastest User?RoleName={RoleName}&MinTime=
{MinTime}&MaxTime={MaxTime}</endpoint>
Allocation/TaskAllocationRoleMethods/Get Slowest User?RoleName={RoleName}&MinTime=
{MinTime}&MaxTime={MaxTime}</endpoint>
Allocation/TaskAllocationRoleMethods/Get Role Peers?$format={format}&$top=
{top}&$skip={skip}&filterXml={filterXml}&RoleName={RoleName}&UserName=
{UserName}</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/Users
and Groups/Get E-mail For User?User_Fully_Qualified_Name={User_Fully_Qualified_Name}
</endpoint>
and Groups/Get E-mail For Group?Group_Fully_Qualified_Name={Group_Fully_Qualified_Name}
</endpoint>
and Groups/Get E-mail For Group Users?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&Group_Fully_Qualified_Name=
{Group_Fully_Qualified_Name}&User_Provider_Label={User_Provider_Label}</endpoint>
and Groups/Get E-mail For Role Users?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&Role_Name={Role_Name}</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow
Reports/Workflow General/Process Instance/List?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&ProcessInstanceID={ProcessInstanceID}</endpoint>
Reports/Workflow General/Activity Instance/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Event Instance/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Process Overview/List?$format={format}&$top={top}&$skip=
{skip}&filterXml={filterXml}&ProcessSetID={ProcessSetID}</endpoint>
Reports/Workflow General/Activity Data/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Process Data/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Process Definition/List Process Definitions?$format=
{format}&$top={top}&$skip={skip}&filterXml={filterXml}</endpoint>
Reports/Workflow General/Process XML/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Activity XML/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Activity Slot Data/List?$format={format}&$top={top}&$skip=
Statement
4.12060.1560.0 )
Reports/Workflow General/Activity Slot XML/List?$format={format}&$top={top}&$skip=
Reports/Workflow General/Activity Instance Destination/List?$format={format}&$top=
{top}&$skip={skip}&filterXml={filterXml}</endpoint>
Reports/Workflow Solutions/K2Demo/ClaimsSample/ClaimsSample Process Instances/List Process
Instances?$format={format}&$top={top}&$skip={skip}&filterXml={filterXml}
</endpoint>
</rest-endpoints>
</endpoints>
Statement
4.12060.1560.0 )
1.1.4.2 Using K2 Web Services with ASP.NET Applications
Using K2 Web Services with ADO.NET Applications
Introduction
The K2 Services provide REST connectivity to the K2 system, allowing developers to use GET and POST requests to retrieve,
send, and modify data; to interact with a K2 process; and to access a K2 user’s worklist. This functionality is XML based and
therefore accessible to the standard XML tooling provided in Microsoft Visual Studio and other development environments.
K2 SmartObject Services
Using the K2 SmartObject REST services provides the developer with Create, Read, Update, Delete, List, and Execute
SmartObject based functions. These functions are URI based, and can therefore be accessed using standard HTTP GET and
POST requests in the code file portion of an ASP.NET application.
Simple Example
For this example, create a SmartObject with the following properties:
The default K2HostServer.exe.config file must be modified in order to activate the SmartObject Services. See Developer
Reference > Services Reference > K2 SmartObject Services > REST Services > Configuration. Use the endpoints XML list to
confirm that the SmartObject had been published as a REST service (i.e. navigate to
http://demo.local:8888/smartObjectServices/endpoints/endpoints.xml).
This ASP.NET Web example project demonstrates a POST request that is used to create a new SmartObject record (using the
Create endpoint) and display the confirmation data within a DetailsView, and a GET request (using the List endpoint) that is
used to return the full contents of the SmartObject to a GridView.
Default.aspx:
Copy
<%@ Page Title="Home Page" Language="C#" MasterPageFile="~/Site.master"
AutoEventWireup="true"
CodeFile="Default.aspx.cs" Inherits="_Default" %>
<asp:Content ID="BodyContent" runat="server" ContentPlaceHolderID="MainContent">
<h1>
K2 SmartObject REST Services Example
</h1>
<p>
Name:<asp:TextBox ID="SO_Data" runat="server" Text=""></asp:TextBox>
Statement
4.12060.1560.0 )
<asp:Button ID="Create_SO_Data" runat="server" onclick="Create_SO_Data_Click"
Text="Create SmartObject Data" />
</p>
<p>
<asp:DetailsView ID="SODetailsView" runat="server" Height="50px"
Width="125px">
</asp:DetailsView>
</p>
<p>
<asp:Button ID="ReturnSmartObjectData" runat="server"
onclick="ReturnSmartObjectData_Click" Text="Return SmartObject Data" />
</p>
<p>
<asp:GridView ID="SO_DataGrid" runat="server">
</asp:GridView>
</p>
</asp:Content>
Default.aspx.cs:
Copy
using System;
using System.Data;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.IO;
using System.Net;
using System.Text;
public partial class _Default : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
}
protected void Create_SO_Data_Click(object sender, EventArgs e)
{
//
Uri address = new
Uri("http://demo.local:8888/SmartObjectServices/rest/K2SmartObjectProject2/Rest_Demo_SO01/Create");
// create the XML Returned variable
string XML_Return;
// Create the web request
HttpWebRequest request = WebRequest.Create(address) as HttpWebRequest;
// Assign Credentials
request.Credentials = CredentialCache.DefaultCredentials;
// Set type to POST
request.Method = "POST";
request.ContentType = "application/xml";
// Create the data we want to send
string SO_Create_POST = "<Rest_Demo_SO01><Name>" + SO_Data.Text + "</Name>
</Rest_Demo_SO01>";
StringBuilder data = new StringBuilder();
data.Append(SO_Create_POST);
// Create a byte array of the data we want to send
byte[] byteData = UTF8Encoding.UTF8.GetBytes(data.ToString());
// Set the content length in the request headers
request.ContentLength = byteData.Length;
// Write data
using (Stream postStream = request.GetRequestStream())
Statement
4.12060.1560.0 )
{
postStream.Write(byteData, 0, byteData.Length);
}
// Get response
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
// Get the response stream
StreamReader reader = new StreamReader(response.GetResponseStream());
// assign resonse the XML Returned variable
XML_Return = reader.ReadToEnd();
}
//create the DataTable
DataSet SO_DataSet = Xml_to_DataSet(XML_Return);
//assign the SmartObject information to our DetailsView
SODetailsView.DataSource = SO_DataSet;
SODetailsView.DataBind();
}
protected void ReturnSmartObjectData_Click(object sender, EventArgs e)
{
// create the SmartObject REST URI
string SO_URI =
"http://demo.local:8888/SmartObjectServices/rest/K2SmartObjectProject2/Rest_Demo_SO01/Get%20List?
format=xml";
// create the XML Returned variable
string XML_Return;
// get the SmartObject XML information
// create the web request
HttpWebRequest request = WebRequest.Create(SO_URI) as HttpWebRequest;
// get response
{
// get the response stream
// assign resonse the XML Returned variable
XML_Return = reader.ReadToEnd();
}
//create the DataTable
DataSet SO_DataSet = Xml_to_DataSet(XML_Return);
// the dataset is used as the data source for our newly created datatrid DataGrid1
SO_DataGrid.DataSource = SO_DataSet;
SO_DataGrid.DataBind();
}
private DataSet Xml_to_DataSet(string xmlString)
{
//create a new DataSet that will hold the XML
DataSet returnedDataSet = null;
//check if the xmlString is not blank
if (String.IsNullOrEmpty(xmlString))
{
//stop the processing
return returnedDataSet;
}
try
{
//create a StringReader object to read the xml string
using (StringReader stringReader = new StringReader(xmlString))
{
//initialize our DataSet
returnedDataSet = new DataSet();
//load the StringReader to our DataSet
Statement
4.12060.1560.0 )
returnedDataSet.ReadXml(stringReader);
}
}
catch
{
//return null
returnedDataSet = null;
}
//return the DataSet containing the SmartObject information
return returnedDataSet;
}
}
When run, the ASP.NET web application will display the SmartObject information as shown in the example screenshot below:
Statement
4.12060.1560.0 )
1.1.4.3 Using K2 REST Services with K2SQLUM
Using K2 REST Services with K2SQLUM
The following configuration is required when using the K2 REST Services with K2SQLUM:
1. Change the security label in the web.config file to K2SQL in the following location:
C:\Program Files (x86)\K2 blackpearl\WebServices\K2Services\
2. Set the default security label to K2SQL in the SecurityLabel table within SQL.
3. Restart K2HostServer.
4. Construct the Credential Cache for the HttpRequest header. Below is an example:
Copy
namespace SQLUM_Execution
{
class Program
{
static void Main(string[]
args)
{
XDocument document
= HttpGet("http://sal-davidg:81/K2Services/REST.svc/Worklist/Items",
"testuser", "password");
if (document != null)
Console.WriteLine(document.ToString());
else
Console.WriteLine("Empty
data returned, start a process instance and make your logged in
user a destination user");
Console.Read();
}
Statement
4.12060.1560.0 )
private static XDocument HttpGet(String url, string user, string password)
{
XDocument document = null;
try
{
var request
= (HttpWebRequest)WebRequest.Create(url);
request.PreAuthenticate = true;
CredentialCache cache = new CredentialCache();
cache.Add(new Uri(url), "Basic", new NetworkCredential(user, password));
request.Credentials = cache;
using (HttpWebResponse response
= request.GetResponse() as HttpWebResponse)
{
document = XDocument.Load(reader);
}
}
catch (Exception ex)
{
Console.WriteLine("Error
: " + ex.Message);
}
return document;
}
}
}
Test:
Statement
4.12060.1560.0 )
1.1.4.4 Create
Create
Executes the Create type method on the SmartObject with the data posted.
URI
{Service Root URI}{Service Path}
http://api.denallix.com:8888/SmartObjectServices/REST/K2%20Examples/Employee/Create
Method
POST
This method cannot be called via URI construction in the address bar of standard browsers. Tooling such as Fiddler or .NET
code may be required to execute the POST.
Request Headers
Ensure that the request has the correct Content-type set.
Content-type: application/xml
Request Body
The request body contains the SmartObject item to create represented as XML. The root for the XML is the system
name of the SmartObject and the elements are the system names of the properties you want in the new item. The
SmartObject XML returned from SmartObject GET methods (Load and List) can be used as a starting point for the
XML input of this POST method.
Request Body Example
Calling the Read method (Load) for ID=1 on the Employee SmartObject will result in the following return data.
Copy
<Employee>
</Employee>
Return Type
Error and Response Codes
Due to the asynchronous nature of the POST, a successful call may not return anything depending on the tooling used to
execute the POST.
Return Example
Calling the Create method on the Employee SmartObject with the data in the Request Body example will result in the
following return data.
Statement
4.12060.1560.0 )
Copy
POST
/SmartObjectServices/REST/K2%20Examples/Employee/Create
<Employee xmlns:i="http://www.w3.org/2001/XMLSchemainstance">
<Id>1</Id>
</Employee>
Statement
4.12060.1560.0 )
1.1.4.5 Read
Read
Executes the Read type method on the SmartObject for the SmartObjectKey specified returning the SmartObject.
URI
{Service Root URI}{Service Path}?{SmartObjectKey}&{Query Options}
http://api.denallix.com:8888/SmartObjectServices/REST/K2%20Examples/Employee/Load?Id=1
Method
GET
The Update method requires both a Request Body and a SmartObject Key via the query parameters in the URL. The
SmartObject Key will indicate the record to update and the Request Body will contain the new data for the properties
that should be changed. It is not necessary to specify all the fields, only the ones that should be changed. The
SmartObject Key can contain multiple properties separated by ampersand (&), for example Id1=100&Id2=2001.
Query Options
Optional
• System Query Options
Return Type
SmartObject or Error and Response Codes
Return Example
Calling the Read method (Load) for ID=1 on the Employee SmartObject will result in the following return data.
Copy
GET
/SmartObjectServices/rest/K2%20Examples/Employee/Load?
Id=1
<Id>1</Id>
</Employee>
Statement
4.12060.1560.0 )
1.1.4.6 Update
Update
Executes the Update type method on the SmartObject with the data posted for the SmartObjectKey specified.
URI
{Service Root URI}{Service Path}?{SmartObjectKey}
http://api.denallix.com:8888/SmartObjectServices/REST/K2%20Examples/Employee/Save?Id=1
Method
PUT
code may be required to execute the PUT.
The Update method requires both a Request Body and a SmartObject Key via the query parameters in the URL. The
SmartObject Key will indicate the record to update and the Request Body will contain the new data for the properties
that should be changed. It is not necessary to specify all the fields, only the ones that should be changed. The
SmartObject Key can contain multiple properties separated by ampersand (&), for example Id1=100&Id2=2001.
Request Headers
Request Body
The request body contains the SmartObject item to update represented as XML. The root for the XML is the system
name of the SmartObject and the elements are the system names of the properties you want to update the item.
The SmartObject XML returned from SmartObject GET methods (Load and List) can be used as a starting point for
the XML input of this PUT method.
Copy Request Body Example
<Employee>
<Last_Name>Jones</Last_Name>
</Employee>
Return Type
Due to the asynchronous nature of the PUT, a successful call may not return anything depending on the tooling used to
execute the PUT.
Return Example
Calling the Update method (Save) for ID=1 on the Employee SmartObject with the data in the Request Body
example will result in the following return data.
PUT /SmartObjectServices/REST/K2%20Examples/Employee/Save?Id=1
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 17 Feb 2011 22:38:01 GMT
Statement
4.12060.1560.0 )
1.1.4.7 Delete
Delete
Executes the Delete type method on the SmartObject for the SmartObjectKey specified.
URI
{Service Root URI}{Service Path}?{SmartObjectKey}
http://api.denallix.com:8888/SmartObjectServices/REST/K2%20Examples/Employee/Delete?Id=1
Method
DELETE
code may be required to execute the DELETE.
The Delete method requires a SmartObject Key via the query parameters in the URL. The SmartObject Key will
indicate the record to delete. The SmartObject Key can contain multiple properties separated by ampersand (&), for
example Id1=100&Id2=2001.
Request Headers
Return Type
Due to the asynchronous nature of the DELETE, a successful call may not return anything depending on the tooling used to
execute the DELETE.
Return Example
Calling the Delete method for ID=1 on the Employee SmartObject will have the following result.
DELETE /SmartObjectServices/REST/K2%20Examples/Employee/Delete?Id=1
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Server: Microsoft-HTTPAPI/2.0
Date: Thu, 17 Feb 2011 22:48:08 GMT
Statement
4.12060.1560.0 )
1.1.4.8 List
List
Executes the List type method on the SmartObject returning a collection of the SmartObject items.
URI
{Service Root URI}{Service Path}?{SmartObjectKey}&{Query Options}
http://api.denallix.com:8888/SmartObjectServices/REST/K2%20Examples/Get%20List?format=xml
Method
GET
The List method optionally allows a SmartObject Key via the query parameters in the URL. The SmartObject Key will
indicate the single record to return (same as Read). The SmartObject Key can contain multiple properties separated
by ampersand (&), for example Id1=100&Id2=2001.
Query Options
Optional
Return Type
SmartObject[] or Error and Response Codes
Return Example
Calling the List method (Get List) on the Employee SmartObject will result in the following return data.
Copy
GET
/SmartObjectServices/REST/K2%20Examples/Employee/Get%20List
<ArrayOfEmployee xmlns:i="http://www.w3.org/2001/XMLSchemainstance">
<Employee>
<Id>1</Id>
</Employee>
<Employee>
<Id>2</Id>
<Username>DENALLIX\Koos</Username>
<First_Name>Koos</First_Name>
<Last_Name>du Preez</Last_Name>
<Email>koos@denallix.com</Email>
</Employee>
</ArrayOfEmployee>
Statement
4.12060.1560.0 )
1.1.4.9 Execute
Execute
Executes the Execute type method on the SmartObject with the data posted.
URI
{Service Root URI}{Service Path}
http://api.denallix.com:8888/SmartObjectServices/REST/K2%20Examples/Employee/Execute
Method
POST
NOTE: This method cannot be called via URI construction in the address bar of standard browsers. Tooling such as Fiddler
or .NET code may be required to execute the POST.
Request Headers
Request Body
The request body contains the SmartObject item to execute represented as XML. The root for the XML is the system
name of the SmartObject and the elements are the system names of the properties needed as input parameters for
the execute method. The SmartObject XML returned from SmartObject GET methods (Load and List) can be used as
a starting point for the XML input of this POST method.
<Employee>
</Employee>
Return Type
NOTE: Due to the asynchronous nature of the POST, a successful call may not return anything depending on the tooling
used to execute the POST.
Return Example
Calling the Execute method on the Employee SmartObject with the data in the Request Body example will result in
the following return data.
Copy
POST
/SmartObjectServices/REST/K2%20Examples/Employee/Execute
</Employee>
Statement
4.12060.1560.0 )
Statement
4.12060.1560.0 )
1.1.5 WCF Services2
WCF Services
Overview
K2 SmartObject Services provide Windows Communication Foundation (WCF) endpoints for configured system and
custom SmartObjects on a K2 Server.
The information in this section provides full details on determining the standard methods available for the services.
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.
URIs for WCF
Statement
4.12060.1560.0 )
1.1.5.1 URIs for WCF
URIs for WCF
URI Structure
{Service Root URI}{Service Path}?{Service Description}
The WCF endpoint for the Employee SmartObject in the K2 Examples category.
Service Root URI = {Scheme}{Server}:{Port}{Service Root}/{Service Type}
Scheme = http:// or https:// if SSL is enabled
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 = /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 = {CategoryPath}{SmartObjectName} – Identifies the Category and/or SmartObject to be interacted with, such as K2
Examples/Employee.
CategoryPath = the path to the category that contains one or more SmartObjects
SmartObjectName (static endpoints only) = the name of the SmartObject
Service Description = wsdl – 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.
Executing K2 WCF Endpoints
The following line is required to execute a K2 WCF endpoint and should be present under the Client Connections section:
Copy
roleService.ClientCredentials.Windows.AllowedImpersonationLevel =
System.Security.Principal.TokenImpersonationLevel.Impersonation;
When using a console app in VS2010, Impersonation details will need to be supplied.
Endpoints XML Example
A default installation of K2 blackpearl configured to generate endpoints for all system (out-of-the-box) SmartObjects produced this
endpoints.xml (showing only WCF endpoints).
Statement
4.12060.1560.0 )
Copy
GET /SmartObjectServices/endpoints/endpoints.xml
<?xml version="1.0"?>
<endpoints>
<wcf-endpoints>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/wcf/Active
Directory</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/wcf/Exchange</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/wcf/Task
Allocation</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/wcf/Workflow
Reports/Workflow General</endpoint>
<endpoint>http://api.denallix.com:8888/SmartObjectServices/wcf/Workflow
Reports/Workflow Solutions/K2Demo/ClaimsSample</endpoint>
</wcf-endpoints>
</endpoints> 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.
Copy
K2Examples.EmployeeSvcClient employeeClient = new
K2Examples.EmployeeSvcClient();
string filter = BuildFilter();
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. Add a using statement
using SourceCode.SmartObjects.Client.Filters;
3. Use the object model to build the filter
Copy
static string BuildFilter()
{
Equals lastNameEquals = new Equals();
PropertyExpression lastNameExpression = new
PropertyExpression("Last_Name", PropertyType.Text);
ValueExpression lastNameValue = new ValueExpression("Cowan",
PropertyType.Text);
lastNameEquals.Left = lastNameExpression;
lastNameEquals.Right = lastNameValue;
// Serialize
FilterExp filterExpression = new FilterExp(lastNameEquals);
XmlDocument filterXml = filterExpression.GetFilterXml();
return filterXml.InnerXml;
}
Statement
4.12060.1560.0 )
The resulting XML for this BuildFilter() method would resemble the following:
Copy
<filterexp><equals><left><propertyexp name="Last_Name" sotype="Text"/>
</left><right><valueexp sotype="Text">Cowan</valueexp></right></equals>
</filterexp>
Statement
4.12060.1560.0 )
1.2
K2 Services
Statement
4.12060.1560.0 )
1.2.1 Introduction to K2 Services
Overview
The K2 Services provide out of the box web service functionality for a portion of the SourceCode.Workflow.Client
namespace via common Web service endpoints, such as RESTful web services (REST - Representational State
Transfer), Windows Communication Foundation (WCF) and legacy SOAP (WS). Developers familiar with the
SourceCode.Workflow.Client APIs will be able to quickly start using the REST, WCF or WS endpoints in their
applications.
Web services create application-to-application interactions and typically work outside of private networks, offering
developers a non-proprietary route to their solutions. Web services also let developers use their preferred
programming languages, and thanks to the use of standards-based communications methods, web services are
virtually platform independent.
Using K2 Services
The K2 Services expose workflow, process and identity data and operations to non K2 environments, allowing custom
applications and Service Oriented Architectures (SOA) to consume and supply K2 workflow, process and identity
data.
The following topics explain the configuration and services available at each endpoint.
Configuration
REST Services
WCF Services
Web Services
Watch a short video on how to use the K2 REST and WCF Services (Length 13 minutes)
Statement
4.12060.1560.0 )
1.2.2 Configuration
Configuration
Changes to the K2 Services configuration requires an IISRESET and browser restart.
The K2 installation will create K2 Services as a virtual directory for the K2 Workspace Web Site provided or selected
during installation. The physical path to this virtual directory will be [Installation Directory] \WebServices\K2Services.
The contents of the directory contain files for the various endpoints installed for K2 Services.
WCF.svc – used for WCF Services
SyncWCF.svc – used for WCF Services optimized for batch processing
REST.svc – used for REST Services
SyncREST.svc – used for REST Services optimized for batch processing
WS.ASMX – used for Web Services
The K2 Services directory also contains the web.config which is used to configure the services, such as default
inclusions, security settings and services provided by each endpoint. There are three main sections of the web.config
file – <services>, <bindings> and <basicAuthentication>.
Security
K2 Services supports two primary authentication modes – Windows (NTLM or Negotiate) and Basic. Basic
authentication is inherently insecure over non-SSL (Secure Sockets Layer) transports; as such K2 Services will be
configured by default to disallow Basic authentication over HTTP. In order to use Basic authentication SSL for the
website should be configured. Disabling the SSL requirement for Basic authentication is provided for development
purposes only.
The authentication mode being used will be based on a combination of the service end points <services> and the
authentication binding for that endpoint <bindings> and IIS Authentication options. Additionally, when the binding is
configured to allow Basic authentication, and a Basic request is sent from the client, the basic configuration will also
be applied <basicAuthentication>. To ensure support for the K2 security label, K2 has implemented the Basic
authentication rather than relying on the IIS implementation.
Statement
4.12060.1560.0 )
1.2.2.1 Service Settings
Service Settings
Basic Authentication
The <sourceCode.services><basicAuthentication> tag contains the attributes that configure the Basic authentication used by K2
Services.
requireSSL (Boolean) – the HTTPS requirement is configured by default at the binding level. This setting can be used to
override the SSL requirement of the HTTP binding configurations.
True (default): will cause an error if SSL is not enabled on the hosting web site
False: will cause an error if SSL is enabled on the hosting web site
enabled (Boolean) – determines if K2 Services endpoints are enabled
True (default): will enable K2 Services endpoints
False: will disable K2 Services endpoints
realm (String) – sets the Basic realm to apply to incoming users
{ServerName} (default): K2 services will utilize the server name if this value is not provided
cachingEnabled (Boolean) – determines if K2 Services will use caching for batch operations
True (default): will enable K2 Services endpoint caching
False: will disable K2 Services endpoint caching
cachingDuration (Integer) – determines duration (in minutes) to cache batch results
15 (default): will cache batch results for 15 minutes
defaultSecurityLabel (String) – sets the default security label to apply to incoming user names
K2 (default): will apply “K2” as the security label for user names
Inclusions
The <sourceCode.services><inclusions> tag contains the default settings for inclusions in data returned K2 Services.
userExtendedProperties (Boolean) – determines if K2 Services will return all user details
False (default): will not return extended properties for users
hiddenFields (Boolean) – determines if K2 Services will return hidden fields
False (default): will not return hidden fields
maxWorklistItems (Integer) – determines the maximum worklist items K2 Services will return
0 (default): will return all worklist items
processDataFields (Boolean) – determines if K2 Services will return process data fields
False (default): will not return process data fields. Use Query Options to override the default behavior.
processXmlFields (Boolean) – determines if K2 Services will return process XML fields
False (default): will not return process XML fields. Use Query Options to override the default behavior.
activityDataFields (Boolean) – determines if K2 Services will return activity data fields
False (default): will not return activity data fields. Use Query Options to override the default behavior.
activityXmlFields (Boolean) – determines if K2 Services will return activity XML fields
False (default): will not return activity XML fields. Use Query Options to override the default behavior.
<include> – optional granular control on the categories of data and XML fields K2 Servies will return. K2 Services will return
all categories if none are explicitly found (default).
category (String) – determines if K2 Services will return specific categories of data and XML fields
None (special keyword): will not return any categories for data or XML field
Copy
<sourceCode.services>
<basicAuthentication requireSSL="True" enabled="True"
cachingEnabled="True" cachingDuration="15"
defaultSecurityLabel="K2" />
<inclusions userExtendedProperties="False"
hiddenFields="False" maxWorklistItems="0"
processDataFields="False" processXmlFields="False"
activityDataFields="False" activityXmlFields="False">
</inclusions>
</sourceCode.services>
Statement
4.12060.1560.0 )
Service Endpoints and Bindings
The <services><service> section contains the default configuration for the endpoints provided by K2 Services. The default
configuration provides Task, Identity and Core services at the SyncREST.svc and SyncWCF.svc endpoints along with Worklist,
Process, Identity and Core services at the REST.svc and WCF.svc endpoints.
Each endpoint defines an associated <binding> via the bindingConfiguration attribute. This allows each endpoint to support a
different security binding allowing for the mixing of authentication and SSL requirements for the same virtual directory. The
REST endpoints are associated with <webHttpBinding> bindings while WCF/SOAP endpoints are associated with
<basicHttpBinding> bindings. For example, the default bindingConfiguration for the Task service at SyncREST.svc endpoint is
SourceCode.Services.SyncRestBinding+HTTPS found in the <bindings><webHttpBinding><binding
name="SourceCode.Services.SyncRestBinding+HTTPS"> section.
Copy
<endpoint address="Task"
behaviorConfiguration="SourceCode.Services.RestBehavior"
binding="webHttpBinding"
bindingConfiguration="SourceCode.Services.SyncRestBinding+HTTPS"
contract="SourceCode.Services.ServiceContracts.ITaskService" />
The <bindings> section contains the configuration details for each binding. The two main configuration elements related to K2
Services bindings are <security> and <transport>.
The <security mode=""> element/attribute defines whether or not SSL is supported. Although None *should* allow IIS to
manage the binding requirements this is not the case with WCF. Unfortunately, WCF will not allow both SSL (HTTPS) and nonSSL (HTTP) support on the same endpoint. Therefore, K2 Services must have multiple endpoints and mappings to multiple
bindings to support both SSL (HTTPS) and non-SSL (HTTPS) for the same service. Example configurations for these have been
provided in comments in the web.config and the product documentation.
K2 recommends setting <security mode="TransportCredentialOnly"> for standard non-SSL (HTTP) support and <security
mode="Transport"> to enable SSL (HTTPS) support. Remember that when bindings are enabled, an associated service endpoint
must also be enabled.
The <transport clientCredentialType=""/> element/attribute defines what credential types will be supported by client requests
headers. <transport clientCredentialType="None"/> allows for the greatest flexibility by allowing the client application to provide
the appropriate supported header – Basic, Windows (NTLM or Negotiate) or NTLM. Changing this value to Windows or NTLM will
force the endpoint to require a Windows-based request thus disabling Basic authentication.
K2 recommends setting <transport clientCredentialType="None"/> to enable support for Basic and Windows (NTLM or Negotiate)
depending on the client request header. Remember that when bindings are enabled, an associated service endpoint must also be
enabled.
Below is an example web.config file with the default security configuration for the service endpoints bindings. Update these
sections to change the endpoints and bindings.
Copy Service Endpoints
<services>
<service behaviorConfiguration="SourceCode.Services.RestBehavior"
name="SourceCode.Services.Rest">


<endpoint address="Process"
bindingConfiguration="SourceCode.Services.RestBinding+HTTP"
contract="SourceCode.Services.ServiceContracts.IProcessNavigationService"
Statement
4.12060.1560.0 )
/>
<endpoint address="Worklist"
contract="SourceCode.Services.ServiceContracts.IWorklistNavigationService"
/>
<endpoint address="Identity"
contract="SourceCode.Services.ServiceContracts.IIdentityService" />
<endpoint address="Core"
contract="SourceCode.Services.ServiceContracts.ICoreService" />


<host>
<baseAddresses>
<add baseAddress="http://DLX:81/K2Services/REST.svc" />
</baseAddresses>
</host>
</service>
<service behaviorConfiguration="SourceCode.Services.SoapBehavior"
name="SourceCode.Services.Wcf">


behaviorConfiguration="SourceCode.Services.SoapBehavior"
binding="basicHttpBinding"
bindingConfiguration="SourceCode.Services.WcfBinding+HTTP"
contract="SourceCode.Services.ServiceContracts.IProcessService" />
contract="SourceCode.Services.ServiceContracts.IWorklistService" />
Statement
4.12060.1560.0 )


<host>
<baseAddresses>
<add baseAddress="http://DLX:81/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
name="SourceCode.Services.SyncRest">





Statement
4.12060.1560.0 )
<host>
<baseAddresses>
<add baseAddress="http://DLX:81/K2Services/SyncREST.svc" />
</baseAddresses>
</host>
</service>
name="SourceCode.Services.SyncWcf">



bindingConfiguration="SourceCode.Services.SyncWcfBinding+HTTPS"
<host>
<baseAddresses>
<add baseAddress="http://DLX:81/K2Services/SyncWCF.svc" />
</baseAddresses>
Statement
4.12060.1560.0 )
</host>
</service>
</services>
<bindings>
<webHttpBinding>


<binding name="SourceCode.Services.RestBinding+HTTP">
</security>
</binding>






<binding name="SourceCode.Services.SyncRestBinding+HTTPS">
</security>
</binding>
</webHttpBinding>
<basicHttpBinding>


<binding name="SourceCode.Services.WcfBinding+HTTP">
</security>
</binding>






<binding name="SourceCode.Services.SyncWcfBinding+HTTPS">
</security>
</binding>
</basicHttpBinding>
</bindings>
Multiple Service Hosting
It is possible to host multiple services which include both non-SSL and SSL services. To add the SSL service a few manual steps
are required post installation. Take the following into consideration:
Microsoft Framework .NET 3.5 does not support multiple bindings in IIS without configuring a single address and setting up a
prefix filter as per the following MSDN KB (Refer to section ‘Multiple IIS Binding Support in .NET Framework 3.5’):
http://msdn.microsoft.com/en-us/library/aa751841.aspx
Some of the following errors may occur when bindings are incorrectly configured:
• Could not find a base address that matches scheme http for the endpoint with binding WebHttpBinding. Registered base
address schemes are [].
• No protocol binding matches the given address 'http://api.denallix.com:85/K2Services/REST.svc/Worklist/Items'. Protocol
bindings are configured at the Site level in IIS or WAS configuration.
• The resource cannot be found.
• This collection already contains an address with scheme http. There can be at most one address per scheme in this collection.
Parameter name: item
The K2 installation will not configure entries. To configure K2 Services to support a web site with multiple bindings add a prefix
entry for the binding you wish to support in the section of the K2 Services web.config found at [Installation
Directory]\WebServices\K2Services\web.config.
The HTTPS port needs to be set manually to 443 in the web.config as well.
Example of supporting the http://api.denallix.com:81 binding on an IIS site with multiple bindings:
Copy
<serviceHostingEnvironment aspNetCompatibilityEnabled="true">
<baseAddress>
<add prefix="http://api.denallix.com:81" />
<add prefix="https://api.denallix.com:443" />
</baseAddress>
</serviceHostingEnvironment>
Note that the HTTPS section in the web.config file is commented out by default. The following section therefore needs to be
enabled. Note that the first two lines are headings only and should stay commented out. The highlighted section below needs to
be enabled:
Copy


behaviorConfiguration="SourceCode.Services.RestBehavior" binding="webHttpBinding"
contract="SourceCode.Services.ServiceContracts.IProcessNavigationService" />
Statement
4.12060.1560.0 )
contract="SourceCode.Services.ServiceContracts.IWorklistNavigationService" />
Statement
4.12060.1560.0 )
1.2.2.2 Recommended Configuration
Statement
4.12060.1560.0 )
1.2.2.2.1 SSL - Recommended Configuration
SyncREST.svc (SSL)
Service Endpoint
Copy
<service
contract="SourceCode.Services.ServiceContracts.IIdentityService"
/>
</service>
Binding
Copy
<webHttpBinding>
<binding
name="SourceCode.Services.SyncRestBinding+HTTPS">
</security>
</binding>
</webHttpBinding>
Basic Settings
Copy
Statement
4.12060.1560.0 )
</inclusions>
IIS Authentication
Copy
Anonymous Authentication = Enabled
Windows Authentication = Enabled
• Providers: NTLM and Negotiate
SyncWCF.svc (SSL)
Service Endpoint
Copy
<service
/>
</service>
Binding
Copy
<basicHttpBinding>
<binding
name="SourceCode.Services.SyncWcfBinding+HTTPS">
</security>
</binding>
</basicHttpBinding>
Basic Settings
Statement
4.12060.1560.0 )
Copy
</inclusions>
IIS Authentication
Copy
Statement
4.12060.1560.0 )
1.2.2.2.2 Non SSL - Recommended Configuration
REST.svc (Non-SSL)
Recommended Client Authentication Header: Windows or Basic
Service Endpoint
Copy
/>
/>
</service>
Binding
Copy
<webHttpBinding>
</security>
</binding>
</webHttpBinding>
Basic Settings
Copy
Statement
4.12060.1560.0 )
</inclusions>
IIS Authentication
Copy
WCF.svc (Non-SSL)
Service Endpoint
Copy
/>
/>
</service>
Binding
Copy
<basicHttpBinding>
<transport clientCredentialType="None"/>
</security>
</binding>
</basicHttpBinding>
Statement
4.12060.1560.0 )
Basic Settings
Copy
</inclusions>
IIS Authentication
Copy
Statement
4.12060.1560.0 )
1.2.2.3 IIS Authentication
IIS Authentication
K2 Services authentication support depends on the appropriate settings in IIS Authentication. The default
configuration for K2 Services on a new site will enable Anonymous Authentication and Windows Authentication with
the Windows Providers set to NTLM and Negotiate. When an upgrade is performed, K2 Configuration Analysis will
recommend enabling Anonymous Authentication and Windows Authentication with the Windows Providers set to
NTLM and Negotiate but will require manually clicking the “Repair” option for any changes to happen to an existing
site. This is to ensure that K2 does not automatically change something that was configured a specific way by design.
The IIS Authentication type Anonymous must be enabled for Basic authentication to work. If this authentication
type is disabled, K2 Services will only support Windows-based authentication.
The IIS Authentication type Windows must be enabled for Windows authentication to work. If this authentication
type is disabled, K2 Services will only support Basic -based authentication. When Windows authentication is enabled,
the type of Windows header passed between the client request and IIS will be can vary depending on the Windows
environmental configuration. It is recommended to enable both Providers (NTLM and Negotiate) to ensure proper
challenge/response and client request header creation regardless of the environmental configuration. The providers
can be reduced to only NTLM or Negotiate if the challenge/response and client request header can be guaranteed to
match in your environment.
IIS Bindings
K2 Services requires IIS bindings for SSL (HTTPS) and non-SSL (HTTP) support. For more information about
configuring SSL, please see the Configure SSL topic.
Statement
4.12060.1560.0 )
1.2.2.3.1 Configure SSL
Configure SSL
The information in this section provides details for ensuring that SSL is configured for the web site hosting K2 Services and its web.config. All
steps assume a default K2 installation.
IIS settings
1. Start Internet Information Services (IIS) Manager
2. Navigate to {Server} > Sites > K2
3. Select Bindings… and Add a binding for https selecting the appropriate SSL certificate
4. Select OK to see the Site Bindings
5. Close the Site Bindings dialog
6. Select SSL Settings and ensure the following
Require SSL: unchecked (default)
Client Certificates
Ignore: checked (default)
8. Select Authentication and ensure the following
Windows Authentication: Enabled
Anonymous Authentication: Disabled
Statement
4.12060.1560.0 )
Basic Authentication: Disabled NOTE: K2 implements Basic for you
Highlight Windows Authentication and select Providers… and ensure the following:
Providers: NTLM; Negotiate
9. Navigate to {Server} > Sites > K2 > K2Services
10. Select SSL Settings and ensure SSL is not enabled.
a. Require SSL: unchecked (default)
b. Client Certificates
a. Ignore: checked (default)
a. Windows Authentication: Enabled
b. Anonymous Authentication: Enabled
c. Basic Authentication: Disabled NOTE: K2 implements Basic for you
13. Navigate to {Server} > Application Pools
14. Select K2 blackpearl and ensure the following:
a. .NET Framework Version: 2.0
b. Pipeline mode: Classic
Statement
4.12060.1560.0 )
Web.config Settings
1. Open C:\Program Files (x86)\K2 blackpearl\WebServices\K2Services\web.config
2. To support BASIC + HTTPS
a. Set the requireSSL tag to True
Copy Web.config
<configuration>
</configuration>
b. Set the service endpoints and base addresses for HTTPS
Copy
<services>
<service
/>
<host>
<baseAddresses>
<add
baseAddress="https://api.denallix.com:443/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
<service
Statement
4.12060.1560.0 )
/>
<host>
<baseAddresses>
<add
baseAddress="https://api.denallix.com:443/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
</services>
c. Set the security mode to Transport for the endpoint bindings
Copy
<bindings>
<webHttpBinding>
<binding name="SourceCode.Services.SyncRestBinding+HTTPS">
</security>
</binding>
</webHttpBinding>
<basicHttpBinding>
<binding name="SourceCode.Services.SyncWcfBinding+HTTPS">
</security>
</binding>
</basicHttpBinding>
</bindings>
3. To support Windows + HTTPS
a. Set the service endpoints for HTTPS
Copy
<services>
/>
Statement
4.12060.1560.0 )
/>
<host>
<baseAddresses>
<add baseAddress="https://api.denallix.com:443/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
<host>
<baseAddresses>
<add baseAddress="https://api.denallix.com:443/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
</services>
b. Set the security mode to Transport for the endpoint bindings
Copy
<bindings>
<webHttpBinding>
<binding name="SourceCode.Services.RestBinding+HTTPS">
</security>
</binding>
</webHttpBinding>
<basicHttpBinding>
Statement
4.12060.1560.0 )
</security>
</binding>
</basicHttpBinding>
</bindings>
Statement
4.12060.1560.0 )
1.2.2.3.2 Configure Non-SSL (Development only)
Configure Non-SSL (Development Only)
K2 Services is configured by default to require SSL and should always be configured this way in production environments. The information provided in
this section is for testing (non-production) purposes only.
It may be desired to remove the SSL requirement during development and testing against K2 Services endpoints. This section details the
steps necessary to remove the SSL requirement. All steps assume a default K2 installation.
IIS Settings
1. Start Internet Information Services (IIS) Manager
3. Select Bindings… and ensure there are no SSL bindings
4. Close the Site Bindings dialog
5. Select SSL Settings and ensure the following
a. Require SSL: unchecked (default)b
b. Anonymous Authentication: Disabled
d. Highlight Windows Authentication and select Providers… and ensure the following
e. Providers: NTLM; Negotiate
Statement
4.12060.1560.0 )
9. Select SSL Settings and ensure SSL is not enabled
a. Require SSL: unchecked (default)
11. Select Authentication and ensure the following:
b. Anonymous Authentication: Enabled
12. Navigate to {Server} > Application Pools
13. Select K2 blackpearl and ensure the following
a. .NET Framework Version: 2.0
b. Pipeline mode: Classic
Web.config Settings
1. Open C:\Program Files (x86)\K2 blackpearl\WebServices\K2Services\web.config
Statement
4.12060.1560.0 )
2. To support BASIC + HTTP
a. Set the requireSSL tag to False
Copy Web.config
<configuration>
<basicAuthentication requireSSL="False" enabled="True"
</configuration>
b. Set the service endpoints and base addresses for HTTP
Copy Web.config
<services>
<service
/>
<host>
<baseAddresses>
<add
baseAddress="http://api.denallix.com:81/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
<service
/>
<host>
<baseAddresses>
<add
baseAddress="http://api.denallix.com:81/K2Services/WCF.svc" />
</baseAddresses>
</host>
Statement
4.12060.1560.0 )
</service>
</services>
c. Set the security mode to TransportCredentialOnly for the endpoint bindings
Copy
<bindings>
<webHttpBinding>
<binding name="SourceCode.Services.SyncRestBinding+HTTP">
</security>
</binding>
</webHttpBinding>
<basicHttpBinding>
</security>
</binding>
</basicHttpBinding>
</bindings>
3. To support Windows + HTTP
a. Set the service endpoints and base addresses for HTTP
Copy
<services>
/>
/>
<host>
<baseAddresses>
<add baseAddress="http://api.denallix.com:81/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
Statement
4.12060.1560.0 )
<host>
<baseAddresses>
<add baseAddress="http://api.denallix.com:81/K2Services/WCF.svc" />
</baseAddresses>
</host>
</service>
</services>
b. Set the security mode to TransportCredentialOnly for the endpoint bindings
Copy
<bindings>
<webHttpBinding>
</security>
</binding>
</webHttpBinding>
<basicHttpBinding>
</security>
</binding>
</basicHttpBinding>
</bindings>
Configure SSL and Non-SSL
The configuration from the SSL and Non-SSL sections can be combined to support both SSL and Non-SSL endpoints at the same K2 Services
virtual directory. The Troubleshooting > Multiple Bindings information should be reviewed when combining multiple bindings.
Statement
4.12060.1560.0 )
1.2.2.4 Client Configuration
Client Configuration
The default app.config file that gets created by Visual Studio when making a service reference to WCF endpoints will
contain the same settings as found in the service web.config. Since SyncWCF.svc is configured with a
clientCredentialType="None" client calls to the service endpoint will use Anonymous and fail. It is recommended that
the clientCredentialType in the client side app.config be set to Basic or Windows depending on the desired
authentication.
Copy
<binding name="BasicHttpBinding_ICoreService">
</security>
</binding>
Additionally, in a Kerberos distributed environment, it is necessary to include the Service Principal Name (SPN)
setting in the app.config by including the following nodes for each <client><endpoint> element.
Copy
<identity>
<servicePrincipalName value="spn"/>
</identity>
The value of the value attribute should be set to a valid client SPN to avoid unexpected behavior in future .NET
framework releases. See the .NET Framework Readme for more information:
http://download.microsoft.com/download/a/2/8/a2807f78-c861-4b66-9b31-9205c3f22252/dotnet35sp1readme.htm
- Section 2.3.2.2
Statement
4.12060.1560.0 )
1.2.2.5 Troubleshooting
Troubleshooting
1. Multiple Bindings
Microsoft .NET Framework 3.5 does not support multiple bindings in IIS without configuring a single address
and setting up a prefix filter as per the following MSDN KB (Refer to section ‘Multiple IIS Binding Support in
.NET Framework 3.5’): http://msdn.microsoft.com/en-us/library/aa751841.aspx
Some of the following errors may occur when bindings are incorrectly configured.
Could not find a base address that matches scheme http for the endpoint with binding WebHttpBinding.
Registered base address schemes are [].
No protocol binding matches the given address
'http://api.denallix.com:85/K2Services/REST.svc/Worklist/Items'. Protocol bindings are configured at the
Site level in IIS or WAS configuration.
The resource cannot be found.
This collection already contains an address with scheme http. There can be at most one address per
scheme in this collection. Parameter name: item
The K2 installation will not configure <baseAddressPrefixFilters> entries. To configure K2 Services to support
a web site with multiple bindings add a prefix entry for the bindings you wish to support in the
<serviceHostingEnvironment><baseAddressPrefixFilters> section of the K2 Services web.config found at
[Installation Directory]\WebServices\K2Services\web.config.
Example of supporting the http://api.denallix.com:81 and https://api.denallix.com:443 bindings on an IIS site
with multiple bindings.
Copy
<baseAddressPrefixFilters>
<add prefix="http://api.denallix.com:81" />
<add prefix="https://api.denallix.com:443" />
</baseAddressPrefixFilters>
</serviceHostingEnvironment>
Statement
4.12060.1560.0 )
1.2.3 REST Services
REST Services
K2 Services provide RESTful web services (REST) endpoints for a portion of the SourceCode.Workflow.Client APIs.
The SourceCode.Workflow.Client Namespace documentation contains additional information on the underlying
classes, properties, methods and sample code. This namespace can be referenced for additional information when
utilizing the REST endpoints.
Developers familiar with using the SourceCode.Workflow.Client APIs as locally referenced resources will be
immediately productive accessing these same resources via REST endpoints. However, it is not necessary to have
prior knowledge of the SourceCode.Workflow.Client namespace to use K2 Services REST endpoints. The information
in this section provides full details on all the methods available for the services including examples to help you get
started.
The sample code provided as a demonstation is written for use with Web based forms.
Sample code for Windows based forms will be available in a future release fo the
Developer's Reference
Service Endpoints
K2 Services REST endpoints provide standard URIs for interacting with the available data and operations. These
topics will help in the construction of the appropriate URI for the desired operation.
URIs for Services
Services
Core Service
Identity Service
Task Service
Worklist Service
Process Service
Developers who wish to build applications that use RESTful services while interacting with processes, worklists and
user information in a similar fashion to the K2 Workflow Client API will want to utilize the Worklist, Process, Identity
and Core services, commonly referred to as “Workflow Client”. You will find the Workflow Client services configured
by default as the REST.svc endpoint.
Developers who wish to build applications that use RESTful services to access and update a user’s task list, optimized
for low bandwidth and offline batch processing scenarios, such as mobile devices, will want to utilize the Task,
Identity and Core services, commonly referred to as “Sync”. You will find the Sync services configured by default at
the SyncREST.svc endpoint.
Errors and Response Codes
The K2 REST Services uses the following standard HTTP status codes.
200
404
503
500
(OK) – returned if the call was successful
(Not Found) – returned if something requested is no longer available
(Service Unavailable) – returned if the K2 Server was unreachable
(Server Error) – returned if any other error occurred
Different languages and platforms handle HTTP status codes differently. Ensure that sufficient error handling is
present for these status codes.
Success
Statement
4.12060.1560.0 )
Successful calls which have no return value information will return a <success> element to the client along with the
HTTP 200 (OK) response. NOTE: Some asynchronous calls will not provide a return to the client depending on the
browser or web request tool being used. In these cases, no return data can indicate success.
Copy
<?xml version="1.0" encoding="utf-8"?>
<success xmlns="http://schemas.k2.com/api/framework"/> Failure
Unsuccessful calls will return an <Failure> element to the client along with the appropriate HTTP error response. The
error message contains useful information for debugging, regarding the error that occurred on the server. Any call to
the server may return this element.
Code – the error code specified by the service. -1 is used for unclassified errors.
Copy
<Failure ID="0" Code="-1"
xmlns="http://schemas.k2.com/framework/d1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Message>25223 Process K2 Examples\Order Process not
found</Message>
<Description>client-failure</Description>
</Failure>
Filtering and Sorting
K2 Services utilize the capabilities of the Workflow Client Criteria framework to enable filtering and sorting results for
REST endpoints.
The Worklist/Items and Task/Items GET methods support the filterXml={filterXml} query option while the
Worklist/Items/Filtered and Task/Items/Filtered POST methods support the filter XML in the request body.
The filterXml query option takes a single string parameter which is the filter represented as XML.
Copy
GET /K2Services/REST.svc/Worklist/Items?filterXml=
<Criteria xmlns="http://schemas.k2.com/worklist/d1">
<Filter Field="ProcessFolio" Comparison="Like"
ValueType="String">Demo</Filter><Sort
Field="ProcessStartDate" Order="Descending" /></Criteria>
GET /K2Services/REST.svc/Task/Items?filterXml=<Criteria
xmlns="http://schemas.k2.com/worklist/d1"><Filter
Field="ProcessFolio" Comparison="Like"
ValueType="String">Demo</Filter><Sort
Field="ProcessStartDate" Order="Descending" /></Criteria>
The filter XML can be built using the same techniques as using the SourceCode.Workflow.Client.WorklistCriteria
classes, properties and enumerations. The structure of the filter XML consists of a Criteria node with zero or more
Statement
4.12060.1560.0 )
Filter and/or zero or more Sort nodes.
The order of the attributes does not matter.
Copy
<Criteria xmlns="http://schemas.k2.com/worklist/d1"
ManagedUser="{optional}"
Platform="{optional}">

<Filter Comparison="{valid WCCompare value: Equal,
NotEqual, Less, Greater, LessOrEqual, GreaterOrEqual,
Like, NotLike}"
Field="{valid WCField value}"
Logical="{valid WCLogical value: And, Or,
AndBracket, OrBracket, StartBracket, EndBracket}"
SubField="{optional, valid subfield to
compare}"
ValueType="{Boolean, Date, Decimal, Double,
Integer, Long, String, Binary}">{Filter Value}</Filter>

<Sort Field="{valid WCField value}"
SubField="{optional, valid subfield to compare}"
Order="{optional, valid WCSortOrder value:
Ascending (default/omitted), Descending}" />
</Criteria>
Schemas and Namespaces
There are several namespaces used by the services.
Namespace
Purpose
http://schemas.k2.com/framework/d1
Contains contracts for error and success
messages
http://schemas.k2.com/core/d1
Contains contracts for basic system
functionality
http://schemas.k2.com/user/d1
Contains contracts for user retrieval
http://schemas.k2.com/task/d1
Contains contracts for task retrieval and
updating
http://schemas.k2.com/worklist/d1
Contains contracts for worklist retrieval
and updating
http://schemas.k2.com/process/d1
Contains contracts for process retrieval
and updating
http://schemas.k2.com/activity/d1
Contains contracts for activity retrieval
and updating
http://schemas.k2.com/event/d1
Contains contracts for event retrieval
and updating
Statement
4.12060.1560.0 )
1.2.3.1 URIs for Services
URIs for Services
URI Structure
{Service Root URI}{Service Path}?{Query Options}
Returns a collection of the first five users, starting with the tenth one, in XML format.
Service Root URI = {Scheme}{Server}:{Port}{Service Root}
Scheme = http:// or https:// if SSL is enabled (default)
Port = Port of web site hosting K2 Services
Service Root = Virtual directory and service endpoint exposed by K2 Services. The values for Service Root are configurable. The defaults are:
/K2Services/REST.svc
/K2Services/SyncREST.svc
Service Path – Identifies the service to be interacted with, such as Process Instance, Worklist, Task, Identities and Core. The service paths that are made available can be configured for each Service Root URI.
Service Paths are case sensitive.
Query Options = {System Query Options }&{Custom Query Options}
Multiple parameters can be combined using an & between them
System Query Options – optional query string parameters that can be used to control the format and amount of data returned. The System Query Options start with a $ and are typically available for all URIs that return data.
$format = xml (default), atom, or json
Specifies the format to return the results. Uses default if omitted.
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom
POST data will be deserialized according to the Content-type specified in the Request Header. The response from the server will be serialized according to the $format tag, or the Content-type if the $format tag is omitted.
Collection Options
$skip = 0 (default), or N
Specifies N number of records to skip. Uses 0 when omitted, which will return all records.
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$skip=2
$top = 0 (default), or N
Specifies the first N records to retrieve. Uses 0 when omitted, which will return all records.
https://api.denallix.com:443/K2Services/REST.svc/ Identity/Users?$top=5
Custom Query Options – additional parameters specific to each service. These are not case sensitive.
Replacement Characters
To prevent the need for double escaping, K2 accepts the following replacement characters when passed as part of the Service Path. There is no need to use replacement characters when passing values as Query Options.
_U_
_S_
_B_
_C_
%20
=
=
=
=
=
_ (Underscore)
/ (Forward Slash)
\ (Backslash)
: (Colon)
{space} (standard URL escaping)
Examples
Copy XML Return Example
GET /K2Services/REST.svc/Identity/Users?$format=xml&$skip=10&$top=2
<UserCollection xmlns="http://schemas.k2.com/user/d1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<User Username="DENALLIX\Brandon" Fqn="K2:DENALLIX\Brandon" Email="Brandon@denallix.com" Manager="DENALLIX\Erica"
DisplayName="Brandon Brown"/>
<User Username="DENALLIX\Mark" Fqn="K2:DENALLIX\Mark" Email="Mark@denallix.com" Manager="DENALLIX\Erica" DisplayName="Mark
Green"/>
</UserCollection>
ATOM Return Example
GET /K2Services/REST.svc/Identity/Users?$format=atom&$skip=10&$top=2
<feed xmlns="http://www.w3.org/2005/Atom">
<title type="text">Users</title>
<subtitle type="text">Users</subtitle>
<id>uuid:1c0d7d3f-b0e1-4162-999b-3fe2092c63d4;id=1</id>
<category term="Identity"/>
<link rel="alternate" href="https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?
$format=atom&$skip=10&$top=2"/>
<entry>
<id>K2:DENALLIX\Brandon</id>
<title type="text">Brandon Brown</title>
<summary type="text">
Username = DENALLIX\Brandon
Fqn = K2:DENALLIX\Brandon
Email = Brandon@denallix.com
Manager = DENALLIX\Erica
DisplayName = DENALLIX\Erica
</summary>
<published>2011-02-14T07:45:00-07:00</published>
<link href="https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom&$skip=10&$top=2"/>
<User xmlns="http://schemas.k2.com/user/d1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<DisplayName>Brandon Brown</DisplayName>
<Email>Brandon@denallix.com</Email>
<Fqn>K2:DENALLIX\Brandon</Fqn>
<Manager>DENALLIX\Erica</Manager>
Statement
4.12060.1560.0 )
<Properties i:nil="true"/>
<Username>DENALLIX\Brandon</Username>
</User>
</content>
</entry>
<entry>
<id>K2:DENALLIX\Mark</id>
<title type="text">Mark Green</title>
<summary type="text">
Username = DENALLIX\Mark
Fqn = K2:DENALLIX\Mark
Email = Mark@denallix.com&#xD
Manager = DENALLIX\Erica
DisplayName = DENALLIX\Erica
</summary>
<published>2011-02-14T07:45:00-07:00</published>
<link href="https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom&$skip=10&$top=2"/>
<User xmlns="http://schemas.k2.com/user/d1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<DisplayName>Mark Green</DisplayName>
<Email>Mark@denallix.com</Email>
<Fqn>K2:DENALLIX\Mark</Fqn>
<Manager>DENALLIX\Erica</Manager>
<Properties i:nil="true"/>
<Username>DENALLIX\Mark</Username>
</User>
</content>
</entry>
</feed>
JSON Return Example
Copy JSON Return Example
GET /K2Services/REST.svc/Identity/Users?$format=json&$skip=10&$top=2
[{"DisplayName":"Brandon
Brown","Email":"Brandon@denallix.com","Fqn":"K2:DENALLIX\\Brandon","Manager":"DENALLIX\\Erica","Properties":null,"Username":"DENALLIX\\Brandon"},
{"DisplayName":"Mark
Green","Email":"Mark@denallix.com","Fqn":"K2:DENALLIX\\Mark","Manager":"DENALLIX\\Erica","Properties":null,"Username":"DENALLIX\\Mark"}]
Filter XML Request Body Example
Copy Filter XML Request Body Example
<Filter Field="ProcessFolio" Comparison="Like" ValueType="String">Demo</Filter>
<Sort Field="ProcessStartDate" Order="Descending" />
</Criteria>
Statement
4.12060.1560.0 )
1.2.3.2 Using K2 REST Services with ASP.NET Applications
Using K2 REST Services with ASP.NET Applications
Using the K2 REST services provides a developer with the ability to start new process instances, access process
instances data and XML fields, retrieve and action items from a user’s K2 worklist, search for K2 users, and access
and update a user’s tasks items. These functions are URI based, and can therefore be accessed using standard HTTP
GET and POST requests in the code file portion of an ASP.NET application.
Retrieving And Displaying Worklist Item Information
The following project demonstrates the use of the Worklist/Items REST service. It will retrieve all the user’s worklist
items and then display the first item using language integrated query (LINQ) data structures to locate the data in the
returned XML data stream:
Default.aspx:
Copy
<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs"
Inherits="TestASP_Web_Application_for_REST._Default" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title></title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Button ID="getDataButton" runat="server"
onclick="getDataButton_Click" Text="Get Worklist Data" />
<br />
<table style="width: 100%;">
<tr>
<td>
Process Name:
</td>
<td>
<asp:TextBox ID="processName" runat="server"></asp:TextBox>
</td>
</tr>
<tr>
<td>
Serial Number:
</td>
<td>
<asp:TextBox ID="serialNumber" runat="server">
</asp:TextBox>
</td>
</tr>
<tr>
<td>
Alloocated User:
</td>
<td>
<asp:TextBox ID="allocatedUser" runat="server">
</asp:TextBox>
</td>
</tr>
<tr>
<td>
Process DataField Value:
</td>
<td>
<asp:TextBox ID="procDataField" runat="server">
</asp:TextBox>
</td>
Statement
4.12060.1560.0 )
</tr>
<tr>
<td>
Activity DataField Value:
</td>
<td>
<asp:TextBox ID="actDataField" runat="server">
</asp:TextBox>
</td>
</tr>
<tr>
<td>
Available Actions:
</td>
<td>
<asp:DropDownList ID="actionsDropDownList" runat="server"
Width="129px">
</asp:DropDownList>
</td>
</tr>
</table>
</div>
</form>
</body>
</html>
Default.aspx.cs:
Copy
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Net;
using System.Xml.Linq;
using System.Xml;
using System.IO;
namespace TestASP_Web_Application_for_REST
{
public partial class _Default : System.Web.UI.Page
{
// Change the RestURL to match your workspace environment
private const string RestUrl = "http://savdocs:81/K2Services/REST.svc/Worklist/Items?piDataField=true&actXmlField=true";
private static readonly XNamespace WorklistNamespace =
"http://schemas.k2.com/worklist/d1";
private static readonly XNamespace ActivityNamespace =
"http://schemas.k2.com/activity/d1";
private static readonly XNamespace ProcessNamespace =
"http://schemas.k2.com/process/d1";
private static readonly XNamespace EventNamespace =
"http://schemas.k2.com/event/d1";
protected void Page_Load(object sender, EventArgs e)
{
}
protected void getDataButton_Click(object sender, EventArgs e)
{
GetData();
}
private void GetData()
Statement
4.12060.1560.0 )
{
// create the web request
HttpWebRequest request = WebRequest.Create(RestUrl) as
HttpWebRequest;
// get response
XDocument responseDocument;
using (HttpWebResponse response = request.GetResponse() as
HttpWebResponse)
using (Stream responseStream = response.GetResponseStream())
using (XmlReader responseReader = XmlReader.Create(responseStream))
{
responseDocument = XDocument.Load(responseReader);
}
//Call method to extract a specific value
PopulateAllocatedUserTextBox(responseDocument);
PopulateActivityDataTextBox(responseDocument);
PopulateProcessDataTextBox(responseDocument);
PopulateWorklistItemSerialNumberTextBox(responseDocument);
PopulateProcessNameTextBox(responseDocument);
PopulateActions(responseDocument);
}
private void PopulateActions(XDocument responseDocument)
{
var actionsQuery =
from worklistItemCollection in
responseDocument.Elements(WorklistNamespace + "WorklistItemCollection")
from worklistItem in
worklistItemCollection.Elements(WorklistNamespace + "WorklistItem")
from action in worklistItem.Elements(WorklistNamespace +
"Action")
select new
{
SerialNumber =
(string)worklistItem.Attribute("SerialNumber"),
Name = (string)action.Attribute("Name"),
Batchable = (bool)action.Attribute("Batchable")
};
foreach (var action in actionsQuery)
{
var listItem = new ListItem()
{
Text = action.Name,
Value = action.SerialNumber,
Enabled = action.Batchable,
};
string thisSerialNumber = listItem.Value.ToString();
if (thisSerialNumber == serialNumber.Text)
{
actionsDropDownList.Items.Add(listItem);
}
}
}
private void PopulateProcessDataTextBox(XDocument responseDocument)
{
var dataFieldValueQuery =
from processInstance in worklistItem.Elements(ProcessNamespace
+ "ProcessInstance")
from dataField in processInstance.Elements(ProcessNamespace +
"DataField")
where (string)dataField.Attribute("Name") ==
"MyProcessDataField"
select (string)dataField;
Statement
4.12060.1560.0 )
var firstResult = dataFieldValueQuery.FirstOrDefault();
procDataField.Text = firstResult;
}
private void PopulateActivityDataTextBox(XDocument responseDocument)
{
var dataFieldValueQuery =
from activityInstanceDestination in
worklistItem.Elements(ActivityNamespace + "ActivityInstanceDestination")
from dataField in
activityInstanceDestination.Elements(ProcessNamespace + "DataField")
where (string)dataField.Attribute("Name") ==
"MyActivityDataField"
select (string)dataField;
var firstResult = dataFieldValueQuery.FirstOrDefault();
actDataField.Text = firstResult;
}
private void PopulateAllocatedUserTextBox(XDocument responseDocument)
{
var allocatedUserFieldValueQuery =
select (string)worklistItem.Attribute("AllocatedUser").Value;
var firstResult = allocatedUserFieldValueQuery.FirstOrDefault();
allocatedUser.Text = firstResult;
}
private void PopulateProcessNameTextBox(XDocument responseDocument)
{
var processFullNameFieldValueQuery =
from processInstance in worklistItem.Elements(ProcessNamespace
+ "ProcessInstance")
select (string)processInstance.Attribute("FullName").Value;
var firstResult = processFullNameFieldValueQuery.FirstOrDefault();
processName.Text = firstResult;
}
private void PopulateWorklistItemSerialNumberTextBox(XDocument
responseDocument)
{
var processFullNameFieldValueQuery =
select (string)worklistItem.Attribute("SerialNumber").Value;
var firstResult = processFullNameFieldValueQuery.FirstOrDefault();
serialNumber.Text = firstResult;
}
}
}
Statement
4.12060.1560.0 )
1.2.3.3 Configuring REST Services to work with K2SQLUM
Configure K2 REST Services for use with K2 SQLUM
K2 REST services are setup to use the Active Directory User Manager by default. Use the following steps to enable the use of the K2
REST Services with K2 SQLUM:
1. Change the security label in the <sourcecode.services> section of the WebServices web.config to K2SQL. This file is located
in “C:\Program Files (x86)\K2 blackpearl\WebServices\K2Services\”
2. Set the default label to K2SQL in the HostServer SecurityLabel table of the K2 HostServer databse:
3. In your application construct the CredentialCache for the HttpRequest header using the following code sample as an example:
Copy
static void Main(string[] args)
{
//Worklist
XDocument document =
HttpGet("http://tester:82/K2Services/Rest.svc/worklist/Items", "testuser",
"k2");
if (document != null)
{
Console.WriteLine(document.ToString());
}
Console.Read();
}
private static XDocument HttpGet(string url, string user, string password)
{
XDocument document = null;
try
{
var request = (HttpWebRequest)WebRequest.Create(url);
request.PreAuthenticate = true;
CredentialCache cache = new CredentialCache();
cache.Add(new Uri(url), "Basic", new NetworkCredential(user, password));
Statement
4.12060.1560.0 )
request.Credentials = cache;
{
document = XDocument.Load(reader);
}
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
return document;
}
Statement
4.12060.1560.0 )
1.2.3.4 Core Service
Core Service
The Core service is useful for ensuring a connection can be established to the services and determining the current
user context making the call.
Core Methods
Core/WhoAmI
Statement
4.12060.1560.0 )
1.2.3.4.1 Core/WhoAmI
Core/WhoAmI
Returns the user name for the context of the person making the request.
URI
{Service Root URI}/Core/WhoAmI
https://api.denallix.com:443/K2Services/REST.svc/Core/WhoAmI
Method
GET
Return Type
String or Failure
Copy Return Example
GET /K2Services/REST.svc/Core/WhoAmI
<string>DENALLIX\Anthony</string>
Statement
4.12060.1560.0 )
1.2.3.5 Identity Service
Identity Service
The Identity service is useful for finding users that the K2 Server has access to; for example, when the user wishes
to redirect an item to another user.
Identity Methods
Identity/Users
Identity/Users/SearchForUsers
Identity/Users({FQN}) © 2008 - 2013 SOURCECODE TECHNOLOGY HOLDINGS, INC. SEE THE K2 blackpearl Copyright and Trademark
Statement
4.12060.1560.0 )
1.2.3.5.1 Identity /Users
Identity/Users
Returns a collection of users configured for the K2 server.
URI
{Service Root URI}/Identity/Users?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users
Method
GET
Query Options
No filters are applied if options are not provided.
Optional
Return Type
UserCollection or Failure
Copy
GET /K2Services/REST.svc/Identity/Users?
$format=xml&$skip=10&$top=2
<UserCollection xmlns="http://schemas.k2.com/user/d1"
<User Username="DENALLIX\Brandon"
Fqn="K2:DENALLIX\Brandon" Email="Brandon@denallix.com"
Manager="DENALLIX\Erica" DisplayName="Brandon Brown"/>
<User Username="DENALLIX\Mark" Fqn="K2:DENALLIX\Mark"
Email="Mark@denallix.com" Manager="DENALLIX\Erica"
DisplayName="Mark Green"/>
</UserCollection>
Statement
4.12060.1560.0 )
1.2.3.5.2 Identity /SearchForUsers
Identity/Users/SearchForUsers
Returns a collection of users configured for the K2 server
URI
{Service Root URI}/Identity/Users/SearchForUsers?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users/SearchForUsers?username=DENALLIX\Brandon
Method
GET
Query Options
Use wildcard characters to search for partial matches.
Starts with: userName=Brando*
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users/SearchForUsers?username=DENALLIX\Brando*
Ends with: userName=*randon
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users/SearchForUsers?username=DENALLIX\*randon
Contains: userName=*Brandon*
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users/SearchForUsers?username=DENALLIX\*Brandon*
Optional
System Query Options
Custom Query Options
username (String) = the user name (or part with wildcard) for the users. Example: DENALLIX\Brandon
displayName (String) = the display name (or part with wildcard) for the users. Example: Brandon Brown
FQN (String) = the fully qualified name (or part with wildcard) for the users. Example: K2:DENALLIX\Brandon
manager (String) = the user’s manager user name (or part with wildcard) for the users. Example:
DENALLIX\Erica
email (String) = the user’s e-mail address. Example: bob@denallix.com
Return Type
UserCollection or Failure
Copy Return Example
GET K2Services/REST.svc/Identity/Users/SearchForUsers?
username=DENALLIX\Brandon
<UserCollection xmlns="http://schemas.k2.com/user/d1"
<User Username="DENALLIX\Brandon"
Fqn="K2:DENALLIX\Brandon" Email="Brandon@denallix.com"
Manager="DENALLIX\Erica" DisplayName="Brandon Brown"/>
</UserCollection>
Statement
4.12060.1560.0 )
1.2.3.5.3 Identity/Users{FQN}
Identity/Users({FQN})
Returns a single user matching the specified fully qualified name (FQN).
URI
{Service Root URI}/Identity/Users({FQN})
https://api.denallix.com:443/K2Services/REST.svc/Identity/Users(K2_C_DENALLIX_B_Anthony)
Method
GET
Service Path Options
Required
FQN (String) – the fully qualified name of the user. Requires the use of Replacement Characters.
Return Type
User or Failure
Copy Return Example
GET
/K2Services/REST.svc/Identity/Users(K2_C_DENALLIX_B_Anthony)
<User Username="DENALLIX\Anthony" Fqn="K2:DENALLIX\Anthony"
Email="Anthony@denallix.com" Manager="DENALLIX\Bob"
DisplayName="Anthony Petro" xmlns="
xmlns:xsd="http://www.w3.org/2001/XMLSchema"/>
Statement
4.12060.1560.0 )
1.2.3.6 Task Service
Task Service
The Task service is useful for determining what outstanding tasks a user has, as well as batch-actioning tasks that a
user might have actioned while they were offline.
This data returned via the Task service is designed to be cached offline on the client. It is recommended that a
configurable polling/syncing interval be provided in the client application.
Only actions which have been configured to support batch processing can be updated via the Task service. Use the Worklist
service to action items that do not support batch processing.
ITaskService is very simple, but it mostly requires that data is sent in the POST payload (as opposed to the GET
parameters) and does not encourage “URL exploration”. It is built for sync and not for web apps. So when you ask
ITaskService for Task(1_18) you will get that Task (worklist item) and there is no way to drill down into it – you get
ALL the data and are expected to cache it.
IWorklistNamespaceService, however, can be used in a way that most of the data can be returned directly from GET
without having to manually poke into objects that are returned. For example, we could get the WorklistItem(1_18)
and that would return EVERYTHING in the process, but we could also drill down and only get data from inside it (e.g.
WorklistItem(1_18)/DataFields(CustomerName)).
Task Methods
Task/Items
Task/Items({SerialNumber})
Task/Items/Filtered
Task/Items/UpdateTask
Task/Items/UpdateTasks
Statement
4.12060.1560.0 )
1.2.3.6.1 Task/Items
Task/Items
Returns a collection of task items for the current user limited by the query options.
URI
{Service Root URI}/Task/Items?{Query Options}
https://api.denallix.com:443/K2Services/SyncREST.svc/Task/Items?piDataField=true&piXmlField=true
Method
GET
Query Options
Optional
filterXml = {filterXml} – specifies the task filtering and sorting to use to limit the results. Uses no filter when omitted, which will return all records. See the Filtering and Sorting section for more information.
By default task detail data will not be returned. Changing either the service configuration (web.config) or providing these query options can override whether detail data is returned
piDataField (Boolean) – determines if process level data fields should be returned
piXmlField (Boolean) – determines if process level XML fields should be returned
actDataField (Boolean) – determines if activity level data fields should be returned
actXmlField (Boolean) – determines if activity level XML fields should be returned
Return Type
TaskCollection or Failure
Copy Return Example
GET /K2Services/SyncREST.svc/Task/Items?piDataField=true&piXmlField=true
<TaskCollection xmlns="http://schemas.k2.com/task/d1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Task SerialNumber="17_10">
<ProcessName>Order Process</ProcessName>
<StartDate>2011-02-15T01:22:45.017Z</StartDate>
<ProcessFullName>K2 Examples\Order Process</ProcessFullName>
<ProcessFolio>Order Process - K2</ProcessFolio>
<ActivityName>Manager Approval</ActivityName>
<Priority>1</Priority>
<Status>Available</Status>
<Originator>K2:DENALLIX\BOB</Originator>
<Data>http://DLX:81/Workspace/ClientEventPages/K2_Examples/Order_Process_Page_9103682c.aspx?SN=17_10</Data>
<Action Name="Approve" Batchable="true"/>
<Action Name="Decline" Batchable="true"/>
<Action Name="Rework" Batchable="true"/>
<ProcessDataField Name="MyProcessDataField" xmlns="http://schemas.k2.com/process/d1">My process data field initial value</ProcessDataField>
<ProcessXmlField Name="MyProcessXMLField"
xmlns="http://schemas.k2.com/process/d1"><items><item><id>1</id><name>Widgets</name><quantity>4</quantity></item></items>
</ProcessXmlField>
</Task>
<ProcessFolio>Order Process - Acme</ProcessFolio>
<Originator>K2:DENALLIX\BOB</Originator>
<ProcessDataField Name="MyProcessDataField" xmlns="http://schemas.k2.com/process/d1">My process data field initial value</ProcessDataField>
<ProcessXmlField Name="MyProcessXMLField"
xmlns=">http://schemas.k2.com/process/d1"><items><item><id>1</id><name>Widgets</name><quantity>4</quantity></item></items>
</ProcessXmlField>
</Task>
</TaskCollection>
Statement
4.12060.1560.0 )
1.2.3.6.2 Task Service
Task Service
The Task service is useful for determining what outstanding tasks a user has, as well as batch-actioning tasks that a
user might have actioned while they were offline.
This data returned via the Task service is designed to be cached offline on the client. It is recommended that a
configurable polling/syncing interval be provided in the client application.
ITaskService is very simple, but it mostly requires that data is sent in the POST payload (as opposed to the GET
parameters) and does not encourage “URL exploration”. It is built for sync and not for web apps. So when you ask
ITaskService for Task(1_18) you will get that Task (worklist item) and there is no way to drill down into it – you get
ALL the data and are expected to cache it.
IWorklistNamespaceService, however, can be used in a way that most of the data can be returned directly from GET
without having to manually poke into objects that are returned. For example, we could get the WorklistItem(1_18)
and that would return EVERYTHING in the process, but we could also drill down and only get data from inside it (e.g.
Task Methods
Task/Items
Task/Items/Filtered
Statement
4.12060.1560.0 )
1.2.3.6.3 Task Items({Serial Number})
Returns a single task item matching the specified SerialNumber.
URI
{Service Root URI}/Task/Items({SerialNumber})
https://api.denallix.com:443/K2Services/SyncREST.svc/Task/Items(16_8)
Method
GET
Required
Serial-Number (String) – the serial number for task item
Query Options
Optional
Return Type
Task or Failure
Copy
GET /K2Services/SyncREST.svc/Task/Items(16_8)
<Task SerialNumber="16_8" xmlns="http://schemas.k2.com/task/d1"
<ProcessFolio>Order Process - K2</ProcessFolio>
<Originator/>
<Data>http://DLX:81/Workspace/ClientEventPages/K2_Examples/Order_Process_Page_9103682c.aspx?
SN=16_8</Data>
</Task>
Statement
4.12060.1560.0 )
1.2.3.6.4 Task/Items({Serial Number})/Actions/Release
Task/Items({SerialNumber})/Actions/Release
Performs the system action of releasing a task with the specified SerialNumber.
URI
{Service Root URI}/Task/Items({SerialNumber})/Actions/Release
https://api.denallix.com:443/K2Services/SyncREST.svc/Task/Items(16_8)/Actions/Release
Method
GET
Required
Serial-Number (String) – the serial number for task item
Query Options
Optional
Return Type
Success or failure
Statement
4.12060.1560.0 )
1.2.3.6.5 Task/Items/Filtered
Task/Items/Filtered
Returns a filtered and sorted collection of task items for the current user.
URI
{Service Root URI}/Task/Items/Filtered
https://api.denallix.com:443/K2Services/SyncREST.svc/Task/Items/Filtered
Method
POST
This method cannot be called via URI construction in the address bar of standard browsers. Tooling such as Fiddler or .NET code may be required to execute the POST.
Request Headers
Ensure that the request has at least these headers set.
Authorization – Basic or NTLM (Windows)
Content-type – application/xml
Copy
Authorization: Basic {encrypted token goes here}
Request Body
The request body contains the filter XML. See the Filtering and Sorting section for more information on building a valid filter XML.
Copy
ValueType="String">Demo</Filter>
</Criteria>
Return Type
TaskCollection or Failure
Due to the asynchronous nature of the POST, a successful call may not return anything depending on the tooling used to execute the POST.
Return Example
Copy
POST /K2Services/SyncREST.svc/Task/Items/UpdateTask
{Raw}
HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 1409
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNet-Version: 2.0.50727
Persistent-Auth: true
X-Powered-By: ASP.NET
X-UA-Compatible: IE=EmulateIE7
Date: Thu, 07 Jul 2011 06:11:24 GMT
<TaskCollection xmlns="http://schemas.k2.com/task/d1"
Statement
4.12060.1560.0 )
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
<ProcessName>Classic Rework</ProcessName>
<ProcessFullName>K2 Examples\Classic Rework</ProcessFullName>
<ProcessFolio>Classic Rework Demo2</ProcessFolio>
<ActivityName>First Approval</ActivityName>
<Originator>K2:DENALLIX\administrator</Originator>
<Data>http://DLX:81/Workspace/ClientEventPages/K2_Examples/Classic_Rework_Page_c5cc30cf.aspx?
SN=12_8</Data>
<Action Name="Approved" Batchable="true"/>
<Action Name="Declined" Batchable="true"/>
</Task>
<ProcessName>Classic Rework</ProcessName>
<ProcessFullName>K2 Examples\Classic Rework</ProcessFullName>
<ProcessFolio>Classic Rework Demo1</ProcessFolio>
<ActivityName>First Approval</ActivityName>
<Status>Open</Status>
<Originator>K2:DENALLIX\administrator</Originator>
SN=11_8</Data>
</Task>
</TaskCollection>
Statement
4.12060.1560.0 )
1.2.3.6.6 Task/Items/UpdateTask
Updates a single task with the data posted.
URI
{Service Root URI}/Task/Items/UpdateTask
https://api.denallix.com:443/K2Services/SyncREST.svc/Task/Items/UpdateTask
Method
POST
Request Headers
Request Body
The request body contains the UpdateTask item represented as XML. The Task item XML returned from Task GET
methods can be used as a starting point for the XML input of this POST method. Any invalid elements or attributes
will be ignored.
The UpdateTask XML consists of the following.
Namespaces
The UpdateTask XML requires namespaces to be defined.
xmlns:t="http://schemas.k2.com/task/d1" (required) – contains the task attributes and nodes
xmlns:p="http://schemas.k2.com/process/d1" (optional) – contains the nodes for process and activity data fields
when provided
Elements and Attributes
<UpdateTask>
@ID (Integer, required) – a number to assign to the task action used to correlate results
@Action (String, required) – the type of action to perform. Available actions:
a:[ActionName] – performs the process-specific action
r:[FQN] – redirects a task to the user specified as a Fully Qualified Name
d:[FQN] – delegates a task to the user specified as a Fully Qualified Name
s:[Duration] –performs the system action to sleep a task based on the duration provided.
Duration = (>0) – sleeps the item the amount of seconds specified
Duration = (0) – sleeps the item indefinitely
Duration = (<0, e.g. -1) – wakes the item
Duration = {DateTime} – sleeps the item until specified date time. Standard DateTime with time zone is
supported: http://www.w3.org/TR/xmlschema11-2/#dateTime.
Statement
4.12060.1560.0 )
<Task> – values not present in the XML for Task GET methods are not supported in updates.
@SerialNumber (String, required) – the serial number of the task to update
@Priority (Integer) – the priority to assign to the task
@ProcessFolio (String) – the folio to assign to the task
<ProcessDataField> (XML) – the process data fields to update in XML format. In .Net use XmlConvert.ToString
to get the string value otherwise use XmlConvert.To[Type] to get the actual value.
<ProcessXmlField> (XML) – the process XML fields as escaped XML. In .Net use XML objects to get the value:
XmlDocument.InnerText, XmlReader.InnerText, XmlWriter.InnerText, or XDocument.Value.
<ActivityDataField> (XML) – the activity data fields to update in XML format. In .Net use XmlConvert.ToString
to get the string value otherwise use XmlConvert.To[Type] to get the actual value.
<ActivityXmlField> (XML) – the activity XML fields as escaped XML. In .Net use XML objects to get the value:
<t:UpdateTask xmlns:t="http://schemas.k2.com/task/d1"
xmlns:p="http://schemas.k2.com/process/d1"
Action="a:Rework">
<t:Task SerialNumber="2_24" >
<p:ProcessDataField Name="MyProcessDataField">Some
process data value</p:ProcessDataField>
<p:ProcessXmlField
Name="MyProcXmlField"><XmlDocument>Some Process XML
document</XmlDocument></p:ProcessXmlField>
<p:ActivityDataField Name="MyActDataField">Some
activity data value</p:ActivityDataField>
<p:ActivityXmlField
Name="MyActXmlField"><XmlDocument>Some Activity XML
document</XmlDocument></p:ActivityXmlField>
</t:Task>
</t:UpdateTask>
Return Type
Success/Failure
execute the POST.
Copy
POST /K2Services/SyncREST.svc/Task/Items/UpdateTask
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 16 Feb 2011 03:01:36 GMT
Statement
4.12060.1560.0 )
1.2.3.6.7 Task/Items/UpdateTasks
Updates a multiple task items in batch with the data posted.
URI
{Service Root URI}/Task/Items/UpdateTasks
https://api.denallix.com:443/K2Services/SyncREST.svc/Task/Items/UpdateTasks
Method
POST
Request Headers
Request Body
The request body contains an UpdateTaskCollection of the multiple UpdateTask items represented as XML. The Task
item XML returned from Task GET methods can be used as a starting point for the XML input of this POST method.
Any invalid elements or attributes will be ignored.
The UpdateTaskCollection XML consists of the following.
Namespaces
The UpdateTaskCollection XML requires namespaces to be defined.
xmlns:t="http://schemas.k2.com/task/d1" (required) – contains the task attributes and nodes
when provided
<UpdateTask>
@ID (Integer, required) – a number to assign to the task action that can be used to correlate results
@Action (String, required) – the type of action to perform. Available actions:
a:[ActionName] – performs the process-specific action
r:[FQN] – redirects a task to the user specified as a Fully Qualified Name
d:[FQN] – delegates a task to the user specified as a Fully Qualified Name
Statement
4.12060.1560.0 )
s:[Duration] –performs the system action to sleep a task based on the duration provided.
Duration = (<0, e.g.-1) – wakes the item
<Task> – values not present in the XML for Task GET methods are not supported in updates.
@SerialNumber (String, required) – the serial number of the task to update
@Priority (Integer) – the priority to assign to the task
@ProcessFolio (String) – the folio to assign to the task
<ProcessDataField> (XML) – the process data fields to update in XML format. In .Net use
XmlConvert.ToString to get the string value otherwise use XmlConvert.To[Type] to get the actual value.
<ProcessXmlField> (XML) – the process XML fields as escaped XML. In .Net use XML objects to get the
value: XmlDocument.InnerText, XmlReader.InnerText, XmlWriter.InnerText, or XDocument.Value.
<ActivityDataField> (XML) – the activity data fields to update in XML format. In .Net use
XmlConvert.ToString to get the string value otherwise use XmlConvert.To[Type] to get the actual value.
<ActivityXmlField> (XML) – the activity XML fields as escaped XML. In .Net use XML objects to get the
value: XmlDocument.InnerText, XmlReader.InnerText, XmlWriter.InnerText, or XDocument.Value.
This POST will attempt to update two tasks. The first task (ID=1000) will perform the Rework action. The second
task (ID=1001) will redirect to the DENALLIX\Joe user.
Copy
<?xml version=”1.0” encoding="utf-8"?>
<t:UpdateTaskCollection
xmlns:t="http://schemas.k2.com/task/d1"
xmlns:p="http://schemas.k2.com/process/d1">
<t:UpdateTask ID="1000" Action="a:Rework">
<p:ProcessXmlField
<p:ActivityXmlField
</t:Task>
</t:UpdateTask>
<t:UpdateTask ID="1001" Action="r:DENALLIX\Joe">
<p:ProcessXmlField
<p:ActivityXmlField
</t:Task>
</t:UpdateTask>
</t:UpdateTaskCollection>
Statement
4.12060.1560.0 )
Return Type
MultiOperationResult – a Success/Failure result for each Task item in the batch
execute the POST.
Return Example
The results of the batch POST show that one task (ID=1000) updated successfully while another task (ID=1001)
failed because rights were insufficient.
Copy
Type your example code here. It will be automatically
colorized when you POST
/K2Services/SyncREST.svc/Task/Items/UpdateTasks
<MultipleOperationResult
xmlns="http://schemas.k2.com/framework/d1"
<Failure ID="1001" Code="-1">
<Message>24411 K2:DENALLIX\Bob from 192.168.1.110:49 is
not allowed to open the worklist item with
SN=2_34</Message>
<Description>client- failure</Description>
</Failure>
<Success ID="1000"/>
</MultipleOperationResult>
Statement
4.12060.1560.0 )
1.2.3.7 Worklist Services
Worklist Service
The Worklist service is useful for interacting with worklist items.
The sample code provided as a demonstration is written for use with Web based
forms. Sample code for Windows based forms will be available in a future release of
the Developer's Reference
IWorklistNamespaceService can be used in a way that most of the data can be returned directly from GET without
having to manually poke into objects that are returned. For example, we could get the WorklistItem(1_18) and that
would return EVERYTHING in the process, but we could also drill down and only get data from inside it (e.g.
ITaskService, however, mostly requires that data is sent in the POST payload (as opposed to the GET parameters)
and does not encourage “URL exploration”. It is built for sync and not for web apps. So when you ask ITaskService
for Task(1_18) you will get that Task (worklist item) and there is no way to drill down into it – you get ALL the data
and are expected to cache it.
Worklist Methods
Worklist/Items
Worklist/Items/SearchForWorklistItems
Worklist/Items/ExecuteAction
Worklist/Items/Filtered
Worklist/Items({SerialNumber})
Worklist/Items({SerialNumber})/Actions
Worklist/Items({SerialNumber})/Actions({Action})
Worklist/Items({SerialNumber})/Actions/Delegate
Worklist/Items({SerialNumber})/Actions/Redirect
Worklist/Items({SerialNumber})/Actions/Release
Worklist/Items({SerialNumber})/Actions/Sleep
Worklist/Items({SerialNumber})/Actions({Action})/Execute
Worklist/Items({SerialNumber})/ProcessInstance
Worklist/Items({SerialNumber})/ProcessInstance/DataFields
Worklist/Items({SerialNumber})/ProcessInstance/DataFields({DataFieldName})
Worklist/Items({SerialNumber})/ProcessInstance/XmlFields
Worklist/Items({SerialNumber})/ProcessInstance/XmlFields({XmlFieldName})
Worklist/Items({SerialNumber})/ActivityInstanceDestination
Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields
Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields({DataFieldName})
Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields
Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields({XmlFieldName})
Worklist/Items({SerialNumber})/Destinations
Worklist/Items({SerialNumber})/Destinations({DestinationName})
Worklist/Items({SerialNumber})/EventInstance
Statement
4.12060.1560.0 )
1.2.3.7.1 Worklist/Items
Worklist/Items
Returns a collection of worklist items for the current user.
URI
{Service Root URI}/Worklist/Items?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items?piDataField=true&actXmlField=true
Method
GET
Query Options
Optional
filterXml = {filterXml} – specifies the Worklist filtering and sorting to use to limit the results. Uses no filter when omitted, which will return all records.
See the Filtering and Sorting section for more information.
By default task detail data will not be returned. Changing either the service configuration (web.config) or providing these query options can override
whether detail data is returned.
Return Type
WorklistItemCollection or Failure
Copy
GET /K2Services/REST.svc/Worklist/Items?
$top=2&piDataField=true&piXmlField=true&actDataField=true
<WorklistItemCollection xmlns="http://schemas.k2.com/worklist/d1"
<WorklistItem AllocatedUser="K2:DENALLIX\BOB" ID="24" SerialNumber="18_10"
Status="Available">
SN=18_10</Data>
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Order Process - ACME"
FullName="K2 Examples\Order Process" Guid="d71d0185-c2c4-44cf-bd9a-08c321b40460" ID="18"
Name="Order Process" Priority="1" StartDate="2011-02-16T20:26:25.53Z" Status="Active"
xmlns="http://schemas.k2.com/process/d1">
<Description/>
<Metadata>Blank</Metadata>
<DataField Name="MyProcessDataField">My process data field initial value</DataField>
<XmlField Name="MyProcessXMLField"><XmlDocument>Some Process XML
document</XmlDocument></XmlField>
</ProcessInstance>
<ActivityInstanceDestination ActID="9" ActInstID="7" ExpectedDuration="0" ID="10"
Name="Manager Approval" Priority="1" ProcInstID="18" StartDate="2011-02-16T20:26:25.557Z"
xmlns="http://schemas.k2.com/activity/d1">
<Description/>
<Metadata/>
<DataField Name="MyActivityDataField" xmlns="http://schemas.k2.com/process/d1">My activity
data field initial value</DataField>
</ActivityInstanceDestination>
<ActivityInstanceDestination ExpectedDuration="0" ID="14" Name="Order Approval" Priority="1"
StartDate="2011-02-16T20:26:28.107Z" xmlns="http://schemas.k2.com/event/d1">
<Description/>
<Metadata/>
</WorklistItem>
<WorklistItem AllocatedUser="K2:DENALLIX\BOB" ID="25" SerialNumber="19_10"
Status="Available">
SN=19_10</Data>
Statement
4.12060.1560.0 )
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Order Process - K2"
FullName="K2 Examples\Order Process" Guid="7e8f9361-148e-44ec-8ed0-23f9d52ddfde" ID="19"
<Description/>
<XmlField Name="MyProcessXMLField"><XmlDocument>Some Process XML
</ProcessInstance>
<Description/>
<Metadata/>
<DataField Name="MyActivityDataField" xmlns="http://schemas.k2.com/process/d1">My activity
data field initial value</DataField>
<Description/>
<Metadata/>
</WorklistItem>
</WorklistItemCollection>
Statement
4.12060.1560.0 )
1.2.3.7.1.1 Accessing the View Flow URL with the REST service
Accessing the View Flow URL with the REST service
The View Flow URL can be accessed through the REST service using Worklist Items
URI
{Service Root URI}/Worklist/Items?{Query Options}
https://K2.denallix.com/K2Services/REST.svc/Worklist/Items?piDataField=true&actXmlField=true
Method
GET
Return Type
The View Flow section is highlighted in blue in the code below:
Copy
GET /K2Services/REST.svc/Worklist/Items?
$top=2&piDataField=true&piXmlField=true&actDataField=true
<?xml version="1.0" encoding="utf-8" ?>
- <WorklistItemCollection xmlns="http://schemas.k2.com/worklist/d1"
+ <WorklistItem AllocatedUser="K2:DENALLIX\Administrator" ID="2082" SerialNumber="2029_8"
Status="Available">
<Data>http://www.google.co.za?SN=2029_8</Data>
<Action Name="Task Completed" Batchable="true" />
- <ProcessInstance ExpectedDuration="0" Folder="K2Project2" Folio="3/11/2013 11:04 PM"
FullName="K2Project2\Process" Guid="d0a15da7-c02a-415a-86f6-14c1bfc8c683" ID="2029"
Name="Process" Priority="1" StartDate="2013-03-12T06:04:47.507Z" Status="Active"
<Description />
<ViewFlow
xmlns="http://schemas.k2.com/worklist/d1">http://k2.denallix.com:80/ViewFlow/ViewFlow.aspx?
ProcessID=2029</ViewFlow>
</ProcessInstance>
- <ActivityInstanceDestination ActID="2249" ActInstID="5" ExpectedDuration="0" ID="8"
Name="DefaultActivity" Priority="1" ProcInstID="2029" StartDate="2013-03-12T06:04:50.527Z"
<Description />
<Metadata />
- <ActivityInstanceDestination ExpectedDuration="0" ID="11" Name="ClientEvent" Priority="1"
<Description />
<Metadata />
</WorklistItem>
- <WorklistItem AllocatedUser="K2:DENALLIX\Administrator" ID="2089" SerialNumber="2036_16"
Status="Open">
<Data>http://www.google.co.za?SN=2036_16</Data>
<Action Name="Task Completed" Batchable="true" />
- <ProcessInstance ExpectedDuration="0" Folder="testProject" Folio="3/13/2013 10:29 PM"
FullName="testProject\Process1" Guid="2e98cbd7-5c95-4c09-a5ff-9d31318019fe" ID="2036"
Name="Process1" Priority="1" StartDate="2013-03-14T05:29:46.647Z" Status="Active"
<Description />
<DataField Name="MyProcessDataField">Process1</DataField>
<ViewFlow
xmlns="http://schemas.k2.com/worklist/d1">http://k2.denallix.com:80/ViewFlow/ViewFlow.aspx?
ProcessID=2036</ViewFlow>
</ProcessInstance>
- <ActivityInstanceDestination ActID="2269" ActInstID="13" ExpectedDuration="0" ID="16"
Name="DefaultActivity" Priority="1" ProcInstID="2036" StartDate="2013-03-14T05:29:49.23Z"
<Description />
<Metadata />
Statement
4.12060.1560.0 )
- <ActivityInstanceDestination ExpectedDuration="0" ID="19" Name="ClientEvent" Priority="1"
<Description />
<Metadata />
</WorklistItem>
Statement
4.12060.1560.0 )
1.2.3.7.2 Worklist/Items/SearchForWorklistItems
Worklist/Items/SearchForWorklistItems
Returns a collection of worklist items for the current user.
URI
{Service Root URI}/Worklist/Items/SearchForWorklistItems?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items/SearchForWorklistItems?folio=Order Process – K2&piDataField=true&actXmlField=true
Method
GET
Query Options
Optional
Custom Query Options – by default task detail data will not be returned. Changing either the service configuration (web.config) or providing these query options can override whether detail data is returned.
processFullName (String) – the process full name of the worklist items to retrieve
folio (String) – the folio of the worklist items to retrieve
Return Type
Copy
GET /K2Services/REST.svc/Worklist/Items/SearchForWorklistItems?processFullName=K2 Example\Order Process&piDataField=true&piXmlField=true&actDataField=true
<WorklistItemCollection xmlns="http://schemas.k2.com/worklist/d1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<WorklistItem AllocatedUser="K2:DENALLIX\BOB" ID="24" SerialNumber="18_10" Status="Available">
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Order Process - ACME" FullName="K2 Examples\Order Process" Guid="d71d0185-c2c4-44cf-bd9a08c321b40460" ID="18" Name="Order Process" Priority="1" StartDate="2011-02-16T20:26:25.53Z" Status="Active" xmlns="http://schemas.k2.com/process/d1">
<Description/>
<XmlField
Name="MyProcessXMLField"><items><item><id>1</id><name>Widgets</name><quantity>4</quantity></item></items>
</XmlField>
</ProcessInstance>
<ActivityInstanceDestination ActID="9" ActInstID="7" ExpectedDuration="0" ID="10" Name="Manager Approval" Priority="1" ProcInstID="18" StartDate="2011-0216T20:26:25.557Z" xmlns="http://schemas.k2.com/activity/d1">
<Description/>
<Metadata/>
<DataField Name="MyActivityDataField" xmlns="http://schemas.k2.com/process/d1">My activity data field initial value</DataField>
<ActivityInstanceDestination ExpectedDuration="0" ID="14" Name="Order Approval" Priority="1" StartDate="2011-02-16T20:26:28.107Z"
xmlns="http://schemas.k2.com/event/d1">
<Description/>
<Metadata/>
</WorklistItem>
<WorklistItem AllocatedUser="K2:DENALLIX\BOB" ID="25" SerialNumber="19_10" Status="Available">
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Order Process - K2" FullName="K2 Examples\Order Process" Guid="7e8f9361-148e-44ec-8ed023f9d52ddfde" ID="19" Name="Order Process" Priority="1" StartDate="2011-02-16T20:26:29.343Z" Status="Active" xmlns="http://schemas.k2.com/process/d1">
<Description/>
<XmlField Name="MyProcessXMLField"><XmlDocument>Some Process XML document</XmlDocument></XmlField>
</ProcessInstance>
<ActivityInstanceDestination ActID="9" ActInstID="7" ExpectedDuration="0" ID="10" Name="Manager Approval" Priority="1" ProcInstID="19" StartDate="2011-0216T20:26:29.43Z" xmlns="http://schemas.k2.com/activity/d1">
<Description/>
<Metadata/>
<DataField Name="MyActivityDataField" xmlns="http://schemas.k2.com/process/d1">My activity data field initial value</DataField>
<ActivityInstanceDestination ExpectedDuration="0" ID="14" Name="Order Approval" Priority="1" StartDate="2011-02-16T20:26:29.487Z"
xmlns="http://schemas.k2.com/event/d1">
<Description/>
<Metadata/>
</WorklistItem>
Statement
4.12060.1560.0 )
1.2.3.7.3 Worklist/Items/ExecuteAction
Worklist/Items/ExecuteAction
Executes the action specified and updates the worklist item with the data posted.
Only actions which have been configured to support batch processing can be updated via this GET method. Use the
Worklist/Items/Execute service to action items that do not support batch processing.
The Worklist service can only execute process specific actions for a single item. Use the Task service to action items with
system actions (Delegate, Redirect or Sleep) and perform batch processing.
URI
{Service Root URI}/Worklist/Items/ExecuteAction?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items/ExecuteAction
Method
POST
Query Options
Required
action (String) – the process-specific configurable action to perform for the worklist item
Optional
Custom Query Options – by default processing will not be done synchronously. Changing either the service
configuration (web.config) or providing these query options can force synchronous processing.
synchronous (Boolean) – determines if the server performs this action synchronously
Request Headers
Request Body
The request body contains the WorklistItem represented as XML. The Worklist Item XML returned from Worklist GET
methods can be used as a starting point for the XML input of this POST method. Any invalid elements or attributes
will be ignored.
The WorklistItem XML consists of the following.
Namespaces
The WorklistItem XML requires namespaces to be defined.
xmlns:w="http://schemas.k2.com/worklist/d1" (required) – contains the worklist item attributes and nodes
xmlns:p="http://schemas.k2.com/process/d1" (optional) – contains the nodes for process data and XML fields
when provided
<WorklistItem>
@SerialNumber (Integer, required) – the serial number of the worklist item to update
Statement
4.12060.1560.0 )
<ProcessInstance>
@ExpectedDuration (Integer) – a expected duration in minutes to assign to the process instance
@Priority (Integer) – the priority to assign to the process instance
@Folio (String) – the folio value to assign to the process instance
<DataField> (XML) – the process data fields to update in XML format. In .Net use XmlConvert.ToString to get the
string value otherwise use XmlConvert.To[Type] to get the actual value.
<XmlField> (XML) – the process XML fields as escaped XML. In .Net use XML objects to get the value:
<w:WorklistItem SerialNumber="25_72"
xmlns:w="http://schemas.k2.com/worklist/d1"
xmlns:p="http://schemas.k2.com/process/d1"
xmlns:a="http://schemas.k2.com/activity/d1">
<p:ProcessInstance ExpectedDuration="40" Priority="4"
Folio="Updated Folio">
<p:DataField Name="MyProcessDataField">My process data
field updated</p:DataField>
</p:ProcessInstance>
</w:WorklistItem>
Return Type
Success/Failure
execute the POST.
Return Example
POST /K2Services/SyncREST.svc/Worklist/Items/ExecuteAction?action=Rework&synchronous=true
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 16 Feb 2011 03:01:36 GMT
Statement
4.12060.1560.0 )
1.2.3.7.4 Worklist/Items/Filtered
Worklist/Items/Filtered
Returns a filtered and sorted collection of worklist items for the current user.
URI
{Service Root URI}/Worklist/Items/Filtered
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items/Filtered
Method
POST
This method cannot be called via URI construction in the address bar of standard browsers. Tooling such as Fiddler or .NET code may be required to execute the POST.
Request Headers
Request Body
The request body contains the filter XML. See the Filtering and Sorting section for more information on building a valid filter XML.
Copy
ValueType="String">Demo</Filter>
</Criteria>
Return Type
Due to the asynchronous nature of the POST, a successful call may not return anything depending on the tooling used to execute the POST.
Return Example
Copy
POST /K2Services/SyncREST.svc/Worklist/Items/Filtered
{Raw}
HTTP/1.1 200 OK
Content-Length: 2683
Content-Type: application/xml; charset=utf-8
Date: Thu, 07 Jul 2011 06:53:21 GMT
<WorklistItemCollection xmlns="http://schemas.k2.com/worklist/d1"
<WorklistItem AllocatedUser="K2:DENALLIX\administrator" ID="45" SerialNumber="12_8"
Status="Available">
Statement
4.12060.1560.0 )
SN=12_8</Data>
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Classic Rework Demo2"
FullName="K2 Examples\Classic Rework" Guid="a7452d47-e020-4c72-8ab0-c87a689f3111" ID="12"
Name="Classic Rework" Priority="1" StartDate="2011-07-07T06:09:02.393Z" Status="Active"
<Description/>
</ProcessInstance>
Name="First Approval" Priority="1" ProcInstID="12" StartDate="2011-07-07T06:09:02.537Z"
<Description/>
<Metadata/>
<ActivityInstanceDestination ExpectedDuration="0" ID="11" Name="FormsGenerationEvent"
Priority="1" StartDate="2011-07-07T06:09:06.063Z" xmlns="http://schemas.k2.com/event/d1">
<Description/>
<Metadata/>
</WorklistItem>
<WorklistItem AllocatedUser="K2:DENALLIX\administrator" ID="43" SerialNumber="11_8"
Status="Open">
SN=11_8</Data>
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Classic Rework Demo1"
FullName="K2 Examples\Classic Rework" Guid="cc1cb5fd-8ef5-45f2-b0ef-1d54aae2f8f8" ID="11"
Name="Classic Rework" Priority="1" StartDate="2011-07-06T21:35:45.35Z" Status="Active"
<Description/>
</ProcessInstance>
Name="First Approval" Priority="1" ProcInstID="11" StartDate="2011-07-06T21:35:45.52Z"
<Description/>
<Metadata/>
<DelegatedUser Name="K2:DENALLIX\JONO"/>
<ActivityInstanceDestination ExpectedDuration="0" ID="11" Name="FormsGenerationEvent"
Priority="1" StartDate="2011-07-06T21:35:49.087Z" xmlns="http://schemas.k2.com/event/d1">
<Description/>
<Metadata/>
</WorklistItem>
Statement
4.12060.1560.0 )
1.2.3.7.5 Worklist/({SerialNumber})
Worklist/Items({SerialNumber})
Returns a worklist item for the matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)?piDataField=true&actDataField=true
Method
GET
Required
SerialNumber (String) – the serial number for the worklist item
Query Options
Optional
Custom Query Options – by default task detail data will not be returned. Changing either the service configuration (web.config) or providing these query
options can override whether detail data is returned.
allocate (Boolean) – determines if the worklist item will be allocated to current user on retrieval
Return Type
WorklistItem or Failure
Copy Return Example
GET /K2Services/REST.svc/Worklist/Items(19_10)
<WorklistItem AllocatedUser="K2:DENALLIX\Bob" ID="25" SerialNumber="19_10" Status="Open"
xmlns="http://schemas.k2.com/worklist/d1" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
SN=19_10</Data>
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples" Folio="Order Process - K2"
FullName="K2 Examples\Order Process" Guid="7e8f9361-148e-44ec-8ed0-23f9d52ddfde" ID="19"
<Description/>
</ProcessInstance>
<Description/>
<Metadata/>
<Description/>
<Metadata/>
</WorklistItem>
Statement
4.12060.1560.0 )
1.2.3.7.6 Worklist/Items({SerialNumber})/Actions
Worklist/Items({SerialNumber})/Actions
Returns a collection of actions for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions
Method
GET
Required
Query Options
Optional
Return Type
ActionCollection or Failure
Copy Return Example
GET /K2Services/REST.svc/Worklist/Items(19_10)/Actions
<ActionCollection
xmlns="http://schemas.k2.com/worklist/d1"
</ActionCollection>
Statement
4.12060.1560.0 )
1.2.3.7.7 Worklist/Items({SerialNumber})/Actions({Action})
Worklist/Items({SerialNumber})/Actions({Action})
Returns the action matching the Action for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions({Action})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions(Rework)
Method
GET
Required
Action (String) – the action for the for the worklist item
Query Options
Optional
Return Type
Action or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/Actions(Rework)
<Action Name="Rework" Batchable="true"
Statement
4.12060.1560.0 )
1.2.3.7.8 Worklist/Items({SerialNumber})/Actions/Delegate
Worklist/Items({SerialNumber})/Actions/Delegate
Performs the system action to delegate a task to the user specified as a Fully Qualified Name for the worklist item
matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions/Delegate?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Delegate?
destination=DENALLIX\Jono
Method
GET
Required
• SerialNumber (String) – the serial number for the worklist item
Query Options
Required
destination (String) – the Fully Qualified Name of the user to delegate the task to.
Optional
•
configuration (web.config) or providing this query options can force synchronous processing.
synchronous (Boolean) – determines if the server starts performs this action synchronously
Return Type
Success/Failure
Return Example
Copy
GET
/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Delegate?
destination=K2:DENALLIX\Jono
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 06 Jul 2011 21:36:24 GMT
Statement
4.12060.1560.0 )
1.2.3.7.9 Worklist/Items({SerialNumber})/Actions/Redirect
Worklist/Items({SerialNumber})/Actions/Redirect
Performs the system action to redirect a task to the user specified as a Fully Qualified Name for the worklist item
matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions/Redirect?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Redirect?
destination=DENALLIX\Jono
Method
GET
Required
Query Options
Required
destination (String) – the Fully Qualified Name of the user to redirect the task to.
Optional
Return Type
Success/Failure
Return Example
Copy
GET
/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Redirect?
destination=K2:DENALLIX\Jono
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 06 Jul 2011 21:36:24 GMT
Statement
4.12060.1560.0 )
1.2.3.7.10 Worklist/Items({SerialNumber})/Actions/Release
Worklist/Items({SerialNumber})/Actions/Release
Performs the system action to release a task for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions/Release
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Release
Method
GET
Required
Query Options
Required
None.
Optional
Return Type
Success/Failure
Statement
4.12060.1560.0 )
1.2.3.7.11 Worklist/Items({SerialNumber})/Actions/Sleep
Worklist/Items({SerialNumber})/Actions/Sleep
Performs the system action to sleep a task the amount of time specified for the worklist item matching the
SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions/Sleep?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Sleep? duration=2002-1010T12:00:00−05:00
Method
GET
Required
Query Options
Required
duration (String) – the amount of time to sleep the task based on the duration provided.
Optional
Return Type
Success/Failure
Return Example
Copy
GET
/K2Services/REST.svc/Worklist/Items(19_10)/Actions/Sleep?
duration=2002-10-10T12:00:00−05:00
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 06 Jul 2011 21:36:24 GMT
Statement
4.12060.1560.0 )
1.2.3.7.12 Worklist/Items({SerialNumber})/Actions({Action})/Execute
Worklist/Items({SerialNumber})/Actions({Action})/Execute
Executes the action matching the Action for the worklist item matching the SerialNumber.
The Worklist service can only execute process-specific actions for a single item. Use the Task service to action items
with system actions (Delegate, Redirect or Sleep) and perform batch processing.
Only actions which have been configured to support batch processing can be updated via this GET method. Use the
Worklist/Items/ExecuteAction service to action items that do not support batch processing.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Actions({Action})/Execute?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/Actions (Rework)/Execute
Method
GET
Required
Action (String) – the process-specific configured action or system action for the for the worklist item. Requires
the use of Replacement Characters.
Available Actions
{Action} or Action:{Action} or A:{Action} – performs the configured action. The configured action is not case
sensitive.
Redirect:[FQN] or R:[FQN] – performs the system action to redirect a task to the user specified as a Fully
Qualified Name. The system action is not case sensitive.
Delegate:[FQN] or D:[FQN] – performs the system action to delegate a task to the user specified as a Fully
Qualified Name. The system action is not case sensitive.
Sleep:[Duration] or S:[Duration] – performs the system action to sleep a task based on the duration provided.
Duration = (<0, e.g -1) – wakes the item
.
Action Examples
Copy
Action:Rework
(Rework)/Execute
(Action_C_Rework)/Execute
(A_C_Rework)/Execute
Delegate:DENALLIX\Jono
(Delegate_C_DENALLIX_S_Jono)/Execute
(D_C_DENALLIX_S_Jono)/Execute
Redirect:DENALLIX\Jono
Statement
4.12060.1560.0 )
(Redirect_C_DENALLIX_S_Jono)/Execute
(R_C_DENALLIX_S_Jono)/Execute
Sleep:2002-10-10T12:00:00−05:00
(Sleep_C_2002-10-10T12_C_00_C_00−05_C_00)/Execute
GET
/K2Services/REST.svc/Worklist/Items(19_10)/Actions(S_C_200210-10T12_C_00_C_00−05_C_00)/Execute
Sleep:3600 (1 hour)
(Sleep_C_3600)/Execute
(S_C_3600)/Execute
Sleep:0 (indefinitely)
(Sleep_C_0)/Execute
(S_C_0)/Execute
Query Options
Optional
configuration (web.config) or providing this query options can force synchronous processing
Return Type
Success/Failure
Return Example
GET /K2Services/REST.svc/Worklist/Items(19_10)/Actions(Rework)/Execute
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 17 Feb 2011 00:56:50 GMT
Statement
4.12060.1560.0 )
1.2.3.7.13 Worklist/Items({SerialNumber})/ProcessInstance
Worklist/Items({SerialNumber})/ProcessInstance
Returns the process instance for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ProcessInstance?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance
Method
GET
Required
Query Options
Optional
Return Type
ProcessInstance or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance
<ProcessInstance ExpectedDuration="0" Folder="K2 Examples"
Folio="Order Process - K2" FullName="K2 Examples\Order
Process" Guid="7e8f9361-148e-44ec-8ed0-23f9d52ddfde"
ID="19" Name="Order Process" Priority="1" StartDate="201102-16T20:26:29.343Z" Status="Active"
<Description xmlns="http://schemas.k2.com/process/d1"/>
<Metadata
xmlns="http://schemas.k2.com/process/d1">Blank</Metadata>
</ProcessInstance>
Statement
4.12060.1560.0 )
1.2.3.7.14 Worklist/Items({SerialNumber})/ProcessInstance/DataFields
Worklist/Items({SerialNumber})/ProcessInstance/DataFields
Returns the process instance data field collection for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ProcessInstance/DataFields?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/DataFields
Method
GET
Required
Query Options
Optional
Return Type
DataFieldCollection or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/DataFields
<DataFieldCollection xmlns="http://schemas.k2.com/process/d1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance>"
<DataField Name="MyProcessDataField">My process data field initial
value</DataField>
</DataFieldCollection>
Statement
4.12060.1560.0 )
1.2.3.7.15 Worklist/Items({SerialNumber})/ProcessInstance/DataFields({DataFieldName})
Worklist/Items({SerialNumber})/ProcessInstance/DataFields({DataFieldName})
Returns the process instance data field matching the DataFieldName for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ProcessInstance/DataFields({DataFieldName})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/DataFields(MyProcessDataField)
Method
GET
Required
• DataFieldName (String) – the data field name for the process instance
Query Options
Optional
Return Type
DataField or Failure
Copy
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/DataFields(MyProcessDataField)
<DataField Name="MyProcessDataField" xmlns="http://schemas.k2.com/process/d1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">My process data field initial
value</DataField>
Statement
4.12060.1560.0 )
1.2.3.7.16 Worklist/Items({SerialNumber})/ProcessInstance/XmlFields
Worklist/Items({SerialNumber})/ProcessInstance/XmlFields
Returns the process instance XML field collection for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ProcessInstance/XmlFields?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/XmlFields
Method
GET
Required
Query Options
Optional
Return Type
XmlFieldCollection or Failure
Copy
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/XmlFields
<XmlFieldCollection xmlns="http://schemas.k2.com/process/d1"
<XmlField Name="MyProcessXMLField"><XmlDocument>Some Process
XML document</XmlDocument></XmlField>
</XmlFieldCollection>
Statement
4.12060.1560.0 )
1.2.3.7.17 Worklist/Items({SerialNumber})/ProcessInstance/XmlFields({XmlFieldName})
Worklist/Items({SerialNumber})/ProcessInstance/XmlFields({XmlFieldName})
Returns the process instance XML field matching the XmlFieldName for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ProcessInstance/XmlFields({XmlFieldName})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/XmlFields(MyProcessXMLField)
Method
GET
Required
• XmlFieldName (String) – the XML field name for the process instance
Query Options
Optional
Return Type
XmlField or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ProcessInstance/XmlFields(MyProcessXMLField)
<XmlField Name="MyProcessXMLField" xmlns="http://schemas.k2.com/process/d1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><XmlDocument>Some Process XML
Statement
4.12060.1560.0 )
1.2.3.7.18 Worklist/Items({SerialNumber})/ActivityInstanceDestination
Worklist/Items({SerialNumber})/ActivityInstanceDestination
Returns the activity instance destination for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ActivityInstanceDestination?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination
Method
GET
Required
Query Options
Optional
Return Type
ProcessInstance orFailure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination
<ActivityInstanceDestination ActID="9" ActInstID="7"
ExpectedDuration="0" ID="10" Name="Manager Approval" Priority="1"
ProcInstID="19" StartDate="2011-02-16T20:26:29.43Z"
xmlns="http://schemas.k2.com/activity/d1"
<Description/>
<Metadata/>
Statement
4.12060.1560.0 )
1.2.3.7.19 Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields
Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields
Returns the activity instance destination data fields collection for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/DataFields
Method
GET
Required
Query Options
Optional
Return Type
Copy ReturnExample
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/DataFields
<DataFieldCollection xmlns="http://schemas.k2.com/process/d1"
<DataField Name="MyActivityDataField">My activity data field initial
value</DataField>
Statement
4.12060.1560.0 )
1.2.3.7.20 Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields({DataFieldName})
Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields({DataFieldName})
Returns the activity instance destination data field matching the DataFieldName for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ActivityInstanceDestination/DataFields({DataFieldName})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/DataFields(MyProcessDataField)
Method
GET
Required
• DataFieldName (String) – the data field name for the activity instance destination
Query Options
Optional
Return Type
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/DataFields(MyActivityDataField)
<DataField Name="MyActivityDataField" xmlns="http://schemas.k2.com/process/d1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">My
activity data field initial value</DataField>
Statement
4.12060.1560.0 )
1.2.3.7.21 Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields
Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields
Returns the activity instance destination XML fields collection for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/XmlFields
Method
GET
Required
Query Options
Optional
Return Type
Copy
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/XmlFields
<XmlFieldCollection xmlns="http://schemas.k2.com/process/d1"
<XmlField Name="MyActivityXMLField"><XmlDocument>Some Activity XML
Statement
4.12060.1560.0 )
1.2.3.7.22 Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields({XmlFieldName})
Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields({XmlFieldName})
Returns the activity instance destination XML field matching the XmlFieldName for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/ActivityInstanceDestination/XmlFields({XmlFieldName})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/XmlFields(MyActivityXMLField)
Method
GET
Required
• XmlFieldName (String) – the XML field name for the activity instance destination
Query Options
Optional
Return Type
XmlField or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(19_10)/ActivityInstanceDestination/XmlFields(MyActivityXMLField)
<XmlField Name="MyActivityXMLField" xmlns="http://schemas.k2.com/process/d1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><XmlDocument>Some Activity XML
Statement
4.12060.1560.0 )
1.2.3.7.23 Worklist/Items({SerialNumber})/Destinations
Worklist/Items({SerialNumber})/Destinations
Returns a collection of destinations that have been delegated for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Destinations?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(24_10)/Destinations
Method
GET
Required
Query Options
Optional
Return Type
DestinationCollection or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(20_10)/Destinations
<DestinationCollection
xmlns="http://schemas.k2.com/process/d1"
<Destination Name="K2:DENALLIX\Holly"/>
<Destination Name="K2:DENALLIX\Brandon"/>
</DestinationCollection>
Statement
4.12060.1560.0 )
1.2.3.7.24 Worklist/Items({SerialNumber})/Destinations({DestinationName}
Worklist/Items({SerialNumber})/Destinations({DestinationName}
Returns a destination matching the DestinationName that has been delegated for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/Destinations({DestinationName})?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(24_10)/Destinations(K2_C_DENALLIX_B_Holly)
Method
GET
Required
DestinationName (String) – the name of the destination that has been delegated the worklist item. Requires the use of
Replacement Characters.
Query Options
Optional
Return Type
Destination or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(20_10)/Destinations(K2_C_DENALLIX_B_Holly)
<Destination Name="K2:DENALLIX\Holly" xmlns="http://schemas.k2.com/process/d1"
Statement
4.12060.1560.0 )
1.2.3.7.25 Worklist/Items({SerialNumber})/EventInstance
Worklist/Items({SerialNumber})/EventInstance
Returns an event instance for the worklist item matching the SerialNumber.
URI
{Service Root URI}/Worklist/Items({SerialNumber})/EventInstance?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Worklist/Items(24_10)/EventInstance
Method
GET
Required
Query Options
Optional
Return Type
EventInstance or Failure
Copy Return Example
GET
/K2Services/REST.svc/Worklist/Items(20_10)/EventInstance
<EventInstance ExpectedDuration="0" ID="14" Name="Order
Approval" Priority="1" StartDate="2011-0216T20:26:34.027Z" xmlns="http://schemas.k2.com/event/d1"
<Description/>
<Metadata/>
</EventInstance>
Statement
4.12060.1560.0 )
1.2.3.8 Process Service
Process Service
The Process service is useful for interacting with process definitions and process instances.
Process Methods
Process/Definitions({FullName})/StartInstance
Process/Instances/StartInstance
Process/Instances/UpdateProcessInstance
Process/Instances({ProcessInstanceID})
Process/Instances({ProcessInstanceID})/DataFields
Process/Instances({ProcessInstanceID})/DataFields({DataFieldName})
Process/Instances({ProcessInstanceID})/XMLFields
Process/Instances({ProcessInstanceID})/XMLFields({XMLFieldName})
Statement
4.12060.1560.0 )
1.2.3.8.1 Process/Definitions({FullName})/StartInstance
Process/Definitions({FullName})/StartInstance
Starts a new process instance for the specified process definition full name.
URI
{Service Root URI}/Process/Definitions({FullName})/StartInstance?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Process/Definitions(K2%20Examples_B_Order%20Process)/StartInstance?folio=Order-K2
Method
GET
Required
• FullName (String) – the full name of the process definition. Requires the use of Replacement Characters.
Query Options
Optional
• Custom Query Options
o Folio (String) – the folio value to assign to the process instance. Uses current DateTime as default if no value is provided.
Return Type
Process Instance Id (Long) or Failure
Copy Return Example
GET
/K2Services/REST.svc/Process/Definitions(K2%20Examples_B_Order%20Process)/StartInstance?
folio=Order-K2
<long>3</long>
Statement
4.12060.1560.0 )
1.2.3.8.2 Process/Instances/StartInstances
Process/Instances/StartInstance
Starts a new process instance with the data posted.
URI
{Service Root URI}/Process/Instances/StartInstance?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances/StartInstance?synchronous=false
Method
POST
Query Options
Optional
Custom Query Options – by default worklist item detail data will not be returned and processing will not be done
synchronously. Changing either the service configuration (web.config) or providing these query options can
override whether detail data is returned and force synchronous processing.
synchronous (Boolean) – determines if the server starts this process synchronously
Request Headers
Request Body
The request body contains the ProcessInstance item represented as XML. The ProcessInstance item XML returned
from Process GET methods can be used as a starting point for the XML input of this POST method. Any invalid
elements or attributes will be ignored.
The ProcessInstance XML consists of the following.
Namespaces
The ProcessInstance XML requires namespaces to be defined.
xmlns:w="http://schemas.k2.com/worklist/d1" (required) – contains the process instance and nodes
when provided
<ProcessInstance>
@FullName (String, required) – the name of the process definition to start an instance of in Folder\Name
format
@Folio (String) – the folio value to assign to the process instance. Uses current DateTime as default if no
value is provided.
<DataField> (XML) – data field values are XML formatted. In .Net use XmlConvert.ToString to get the string
value otherwise use XmlConvert.To[Type] to get the actual value.
<XmlField> (XML) – XML field values are XML escaped. In .Net use XML objects to get the value:
Statement
4.12060.1560.0 )
Copy Return Body Example
<w:ProcessInstance
xmlns:w="http://schemas.k2.com/worklist/d1" xmlns:p="http://schemas.k2.com/process/d1"
ExpectedDuration="20" FullName="K2 Examples\Order
Process" Folio="Order-ACME" Priority="3">
<p:DataField Name="MyProcessDataField">Some process data
value</p:DataField>
<p:XmlField
Name="MyProcessXMLField"><XmlDocument>Some Process
XML document</XmlDocument></p:XmlField>
</w:ProcessInstance>
Return Type
execute the POST.
Copy Return Example
POST /K2Services/REST.svc/Process/Instances/StartInstance?
piDataField=true&piXmlField=true
<ProcessInstance ExpectedDuration="20" Folder="K2 Example "
Folio="Order-ACME" FullName="K2 Example\Order Process"
Guid="b8cf5da7-7cf9-4af2-abc6-7fb91a69354c" ID="8" Name="Order
Process" Priority="3" StartDate="2011-02-16T04:52:47.6876172Z"
Status="Running" xmlns="http://schemas.k2.com/worklist/d1"
<Metadata
<DataField Name="MyProcessDataField"
xmlns="http://schemas.k2.com/process/d1">Some process data
value</DataField>
<XmlField Name="MyProcessXMLField"
xmlns="http://schemas.k2.com/process/d1"><XmlDocument>Some
Process XML document</XmlDocument></XmlField>
</ProcessInstance>
Statement
4.12060.1560.0 )
1.2.3.8.3 Process/Instances/UpdateProcessInstance
Process/Instances/UpdateProcessInstance
Updates an existing process instance with the data posted.
URI
{Service Root URI}/Process/Instances/UpdateProcessInstance?{Query Options}
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances/UpdateProcessInstance?synchronous=true
Method
POST
NOTE: This method cannot be called via URI construction in the address bar of standard browsers. Tooling such as Fiddler
or .NET code may be required to execute the POST.
Query Options
Optional
Custom Query Options – by default worklist item detail data will not be returned and processing will not be done
synchronously. Changing either the service configuration (web.config) or providing these query options can
override whether detail data is returned and force synchronous processing.
synchronous (Boolean) – determines if the server starts this process synchronously
Request Headers
Request Body
The request body contains the ProcessInstance item represented as XML. The ProcessInstance item XML returned
from Process GET methods can be used as a starting point for the XML input of this POST method. Any invalid
elements or attributes will be ignored.
The ProcessInstance XML consists of the following.
Namespaces
The ProcessInstance XML requires namespaces to be defined.
• xmlns:w="http://schemas.k2.com/worklist/d1" (required) – contains the process instance and nodes
• xmlns:p="http://schemas.k2.com/process/d1" (optional) – contains the nodes for process and activity data fields
when provided
<ProcessInstance>
@ID (Integer, required) – the identifier of the process instance
@Folio (String) – the folio value to assign to the process instance
<DataField> (XML) – data field values are XML formatted. In .Net use XmlConvert.ToString to get the string
value otherwise use XmlConvert.To[Type] to get the actual value.
<XmlField> (XML) – XML field values are XML escaped. In .Net use XML objects to get the value:
Statement
4.12060.1560.0 )
<w:ProcessInstance
xmlns:w="http://schemas.k2.com/worklist/d1"
xmlns:p="http://schemas.k2.com/process/d1" ID="8"
Priority="1" Folio="Order-ACME-Updated"
ExpectedDuration="60">
<p:DataField Name="MyProcessDataField">Some process data
value</p:DataField>
<p:XmlField
XML document</XmlDocument></p:XmlField>
</w:ProcessInstance>
Return Type
NOTE: Due to the asynchronous nature of the POST, a successful call may not return anything depending on the tooling
used to execute the POST..
Return Example
POST /K2Services/REST.svc/Process/Instances/UpdateProcessInstance
{Raw}
HTTP/1.1 200 OK
Content-Length: 0
Date: Wed, 16 Feb 2011 05:20:57 GMT
Statement
4.12060.1560.0 )
1.2.3.8.4 Process/Instances({ProcessInstanceID})
Process/Instances({ProcessInstanceID})
Returns a single process instance for the matching ProcessInstanceID.
URI
{Service Root URI}/Process/Instances({ProcessInstanceID})
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances(5)
Method
GET
Required
• ProcessInstanceID (Integer) – the identifier of the process instance (ProcInstID)
Query Options
Optional
Custom Query Options – by default worklist item detail data will not be returned. Changing either the service
configuration (web.config) or providing these query options can override whether detail data.
Return Type
Copy Return Example
GET /K2Services/REST.svc/Process/Instances(8)?
piDataField=true&piXmlField=true
<?xml version="1.0" encoding="utf-8"?><ProcessInstance
ExpectedDuration="60" Folder="K2 Examples" Folio="Order-ACMEUpdated" FullName="K2 Examples\Order Process" Guid="b8cf5da77cf9-4af2-abc6-7fb91a69354c" ID="8" Name="Order Process"
Priority="1" StartDate="2011-02-16T04:52:47.687Z"
Status="Active" xmlns="http://schemas.k2.com/worklist/d1"
<Metadata
xmlns="http://schemas.k2.com/process/d1">Some process data
value</DataField>
xmlns="http://schemas.k2.com/process/d1"><XmlDocument>Some
</ProcessInstance>
Statement
4.12060.1560.0 )
1.2.3.8.5 Process/Instances({ProcessInstanceID})/DataFields
Process/Instances({ProcessInstanceID})/DataFields
Returns a data field collection for the Process process Instance instance matching the specified process instance
identifierProcessInstanceID.
URI
{Service Root URI}/Process/Instances({ProcessInstanceID})/DataFields
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances(8)/DataFields
Method
GET
Required
• ProcessInstanceID (Integer) – the identifier of the process instance (ProcInstID)
Query Options
Optional
Return Type
Copy Return Example
GET /K2Services/REST.svc/Process/Instances(8)/DataFields
<DataFieldCollection
<DataField Name="MyProcessDataField">Some process data
value</DataField>
Statement
4.12060.1560.0 )
1.2.3.8.6 Process/Instances({ProcessInstanceID})/DataFields({DataFieldName})
Process/Instances({ProcessInstanceID})/DataFields({DataFieldName})
Returns a data field matching the DataFieldName for the Process process Instance instance matching the specified
process instance identifierProcessInstanceID.
URI
{Service Root URI}/Process/Instances({ProcessInstanceID})/DataFields({DataFieldName})
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances(8)/DataFields(MyProcessDataField)
Method
GET
Required
ProcessInstanceID (Integer) – the identifier of the process instance
DataFieldName (String) – the name of the process data field
Return Type
Copy Return Example
GET /K2Services/REST.svc/Process/Instances(8)/DataFields
xmlns:xsd="http://www.w3.org/2001/XMLSchema">Some process
data value</DataField>
Statement
4.12060.1560.0 )
1.2.3.8.7 Process/Instances({ProcessInstanceID})/XMLFields
Process/Instances({ProcessInstanceID})/ XmlFields
Returns an XML field collection for the Process process Instance instance matching the specified process instance
identifierProcessInstanceID.
URI
{Service Root URI}/Process/Instances({ProcessInstanceID})/XmlFields
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances(8)/XmlFields
Method
GET
Required
ProcessInstanceID (Integer) – the identifier of the process instance(ProcInstID)
Query Options
Optional
Return Type
Copy Return Example
GET /K2Services/REST.svc/Process/Instances(8)/XMLFields
<?xml version="1.0" encoding="utf-8"?><XmlFieldCollection
<XmlField
XML document</XmlDocument></XmlField>
Statement
4.12060.1560.0 )
1.2.3.8.8 Process/Instances({ProcessInstanceID})/XMLFields({XMLFieldName})
Process/Instances({ProcessInstanceID})/DataFields({XmlFieldName})
Returns an XML field matching the XmlFieldName for the Process process Instance instance matching the specified
process instance identifierProcessInstanceID.
URI
{Service Root URI}/Process/Instances({ProcessInstanceID})/XmlFields({XmlFieldName})
https://api.denallix.com:443/K2Services/REST.svc/Process/Instances(5)/XmlFields(MyProcessXmlField)
Method
GET
Required
ProcessInstanceID (Integer) – the identifier of the process instance
XmlFieldName (String) – the name of the process XML field
Return Type
XmlField or Failure
Copy Return Example
GET
/K2Services/REST.svc/Process/Instances(5)/XMLFields(MyProcessXMLField)
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><XmlDocument>Some
Statement
4.12060.1560.0 )
1.2.4 WCF Services
WCF Services
K2 Services provide Windows Communication Foundation (WCF) endpoints for a portion of the
SourceCode.Workflow.Client APIs. Developers familiar with using the SourceCode.Workflow.Client APIs as locally
referenced resources will be immediately productive accessing these same resources via WCF endpoints.
The SourceCode.Workflow.Client Namespace documentation contains information on the underlying classes,
properties, methods and sample code. Reference this namespace when utilizing the WCF endpoints.
Detailed information on service contracts, data contracts and operation contracts can be found in the endpoint
Service Descriptions.
URI – Service Description
{Service Root URI}?wsdl
http://api.denallix.com:81/K2Services/WCF.svc?wsdl
Server = Server or Host Name of web site hosting K2 services
Service Root = Virtual directory and service endpoint exposed by K2 Services. The values for Service Root are
configurable. The defaults are:
/K2Services/WCF.svc
/K2Services/SyncWCF.svc
WCF Methods
The following operations are supported by the WCF.svc endpoint.
ICoreService
• WhoAmI() – returns User making the request
IIdentityService
GetAllUsers() – returns User[] of all the users
GetUser(string fqn) – returns User for specified parameters
SearchUsers(string username, string displayName, string e-mail, string manager) – returns User[] for specified
parameters
IProcessNavigationService
OpenProcessInstance(string processInstanceId, bool piDataField, bool piXmlField) – returns a ProcessInstance
for the specified process instance ID with or without data and XML fields
StartNewProcessInstance(ProcessInstance processInstance, bool synchronous, bool actDataField, bool
actXmlField, bool piDataField, bool piXmlField) – starts a process for the specified ProcessInstance and returns the
updated ProcessInstance with or without data and XML fields
StartNewProcessInstanceScalar(string fullName, string folio, bool synchronous) – starts a process instance for
the specified process definition name. Returns the process instance ID as a long.
UpdateProcessInstance(ProcessInstance processInstance) – updates the specified ProcessInstance
IWorklistNavigationService
ExecuteActionBySerial(string serialNumber, string action, bool synchronous) – executes action for specified
serial number
DelegateWorklistItem(string serialNumber, string destination) – performs the system action to delegate a task
to the user specified as a Fully Qualified Name
RedirectWorklistItem(string serialNumber, string destination) – performs the system action to redirect a task to
the user specified as a Fully Qualified Name
ReleaseWorklistItem(string serialNumber) - performs the system action to release a task
Statement
4.12060.1560.0 )
SleepWorklistItem(string serialNumber, string duration) – performs the system action to sleep a task based on
the duration specified
supported: http://www.w3.org/TR/xmlschema11-2/#dateTime
ExecuteActionByWorklistItem(WorklistItem item, string action, bool synchronous) – executes action for
specified worklist item
OpenWorklist(bool actDataField, bool actXmlField, bool piDataField, bool piXmlField) – returns WorklistItem[]
with or without data and XML fields
OpenWorklistFiltered(SourceCode.Worklist.Client.WorklistCriteria filter, bool actDataField, bool actXmlField,
bool piDataField, bool piXmlField) – returns filtered and sorted WorklistItem[] with or without data and XML fields
OpenWorklistItem(string serialNumber, bool allocate, bool actDataField, bool actXmlField, bool piDataField, bool
piXmlField) – returns WorklistItem for specified serial number with or without data and XML fields, optionally
allocating the item to the current user
SearchForWorklistItems(string processFullName, string folio, bool actDataField, bool actXmlField, bool
piDataField, bool piXmlField) – returns WorklistItem[] for specified process full name or folio with or with data and
XML fields
SyncWCF Methods
The following operations are supported by the SyncWCF.svc endpoint.
ICoreService
WhoAmI() – returns User making the request
IIdentityService
GetAllUsers() – returns User[] of all the users
GetUser(string fqn) – returns User for specified parameters
SearchUsers(string username, string displayName, string e-mail, string manager) – returns User[] for specified
parameters
ITaskService
GetTask(bool allocate, string serialNumber, bool actDataField, bool actXmlField, bool piDataField, bool piXmlField)
– returns Task for the specified serial number with or without data and XML fields
GetTasks(bool actDataField, bool actXmlField, bool piDataField, bool piXmlField) – returns Task[] with or without
data and XML fields
GetTasksFiltered(SourceCode.Worklist.Client.WorklistCriteria filter, bool actDataField, bool actXmlField, bool
piDataField, bool piXmlField) – returns filtered and sorted Task[] with or without data and XML fields
UpdateTask(UpdateTask task, string Action, int ID, string serialNumber) - the Action here is "rl" to release the
item, the ID is the process ID, and returns success or failure
UpdateTask(UpdateTask task) – updates the UpdateTask specified
UpdateTasks(UpdateTask[] tasks) – returns MultipleOperationResult for the UpdateTask[] specified
Filtering
WCF Filtering example
Copy
WcfK2Services.WorklistNavigationServiceClient client =
new WcfK2Services.WorklistNavigationServiceClient();
WcfK2Services.Criteria criteria = new
WcfK2Services.Criteria()
{
Filter = new []
{
Statement
4.12060.1560.0 )
new WcfK2Services.CriteriaFilter()
{
Field =
WcfK2Services.CriteriaField.ProcessFolio,
Comparison =
WcfK2Services.CriteriaComparison.Equal,
Value = "Approve Customer",
ValueType =
WcfK2Services.ValueType.String
},
new WcfK2Services.CriteriaFilter()
{
Logical =
WcfK2Services.CriteriaLogical.And,
Field =
WcfK2Services.CriteriaField.ProcessData,
SubField = "Customer Name",
Comparison =
WcfK2Services.CriteriaComparison.Like,
Value = "*Mary*",
ValueType =
WcfK2Services.ValueType.String
}
},
Sort = new []
{
new WcfK2Services.CriteriaSort()
{
Field =
WcfK2Services.CriteriaField.ProcessStartDate,
Order =
WcfK2Services.CriteriaSortOrder.Ascending
}
}
};
WcfK2Services.WorklistItem[] items =
client.OpenWorklistFiltered(criteria, false, false,
false, false);
Statement
4.12060.1560.0 )
1.2.4.1 Starting a Workflow with the SOAP WCF service
How to start a Workflow with a simple ASP.NET page while using the Workflow WCF
service
The steps below show an example of how to start a Workflow with a simple ASP.NET page while using the Workflow WCF
service.
1: Add a
reference
to the
SOAP
service
http://[k2 server website]/K2Services/WCF.svc, e.g. http://k2.denallix.com/K2Services/WCF.svc
2: Do the
required
Web.config
changes
Change each of the 4 basicHttpBinding entries in the Web.config file as follows (changes are
highlighted in red)
<transport clientCredentialType="Ntlm" proxyCredentialType="None"
realm="" />
Set the application to use windows authentication (if that is what you want)
<system.webServer>
<security>
<authentication>

<anonymousAuthentication enabled="false" />

<windowsAuthentication enabled="true" />
</authentication>
</security>
<system.web>
<authentication mode="Windows">
</authentication>
<identity impersonate="true"/>
3: Write
the code
The code below assumes the namespace of the reference is set to the service “K2WorkflowSoapService”
//instantiate the process service
K2WorkflowSoapService.ProcessNavigationServiceClient
processSvcClient = new
K2WorkflowSoapService.ProcessNavigationServiceClient();
//instantiate the process “definition”
ProcessInstance k2ProcInst = new ProcessInstance();
//set the workflow you want to start
k2ProcInst.FullName = @"K2Learning\300NRT Leave Approval
Sample";
//set the folio
k2ProcInst.Folio = txtName.Text + " - " +
ddlLeaveType.SelectedValue;
//set up the collection of datafields
List<DataField> dataFieldsCollection = new List<DataField>();
//string field example
Statement
4.12060.1560.0 )
dataFieldsCollection.Add(new DataField() { Name = "FieldName",
Value = “FieldValue”});
//dates require special massaging, otherwise you get XMLAny
errors. In this sample we’ll take the current date
//note the use of the XmlConvert function. You may need to do
this with other datafields, too.
dataFieldsCollection.Add(new DataField() { Name = "FieldName",
Value =
XmlConvert.ToString(DateTime.Now(),XmlDateTimeSerializationMode.
Local)});
//pass the collection to datafields into the workflow
k2ProcInst.DataField = dataFieldsCollection.ToArray();
//start the workflow
//there is a bug in this service where an error is thrown even
if the workflow is started successfully. This bug exists
//in 1390 and 1420 for sure, not sure about 4.6.x
try
{
processSvcClient.StartNewProcessInstance(k2ProcInst, false,
false, false, true, false);
}
catch (Exception bugex)
{
if (!bugex.Message.Contains("to open"))
{
throw;
}
}
Statement
4.12060.1560.0 )
1.2.4.2 Accessing the View Flow URL with the WCF service
Accessing the View Flow URL with the WCF service
The View Flow URL can be accessed through the WCF service
URI
[WORKSPACE BASE URL]/K2Services/WCF.svc
Setup
Follow the steps below to set up an example for accessing the View Flow URL:
1. Open the URL :
2. The following page will open
3. Copy the URL and Open K2 Designer for Visual Studio
4. Create a new C# Console Application
5. In the Solution Explorer right click on the References Node and select Add Service Reference:
6. In the Address paste the URL and click on Go
7. Change the Namespace to WCF and click OK :
Statement
4.12060.1560.0 )
8. Type the following code in the Static void Main(string[] args) method
Copy
WCF.ProcessNavigationServiceClient client = new
WCF.ProcessNavigationServiceClient();
WCF.ProcessInstance pi = client.OpenProcessInstance("1", true,
true); //change the "1" to your process instance
Console.WriteLine(pi.ViewFlow);
Console.Read();
Note : Change the “1” to your process instance ID number
9. Run the console application
10. The View Flow URL is returned
Troubleshooting
If you receive the following error, you will have to update the web.config
Statement
4.12060.1560.0 )
Follow the steps below to update the web.config
1. Open the web.config in the following location : C:\Program Files (x86)\K2 blackpearl\WebServices\K2Services
2. Search for the following XML:
Copy
<basicHttpBinding>

</security>
</binding>


Statement
4.12060.1560.0 )
</security>
</binding>

<!-- Ensure the SyncWCF.svc endpoints are enabled when
enabling this binding
</security>
</binding>
4. Save the file, re-open your console application, right click on your service reference and click on Update Service Reference:
5. Run the console application again
Statement
4.12060.1560.0 )
1.2.5 Web Services
Web Services
K2 Services provide legacy SOAP Web service (WS) endpoints for a portion of the SourceCode.Workflow.Client APIs. Developers familiar with using the SourceCode.Workflow.Client
APIs as locally referenced resources will be immediately productive accessing these same resources via WS endpoints.
The SourceCode.Workflow.Client Namespace documentation contains information on the underlying classes, properties, methods and sample code. Reference this namespace when
utilizing the WS endpoints.
Detailed information on service contracts, data contracts and operation contracts can be found in the endpoint Service Descriptions.
URI – Service Description
{Service Root URI}?wsdl
http://api.denallix.com:81/K2Services/WCF.asmx?wsdl
Server = Server or Host Name of web site hosting K2 services
Service Root = Virtual directory and service endpoint exposed by K2 Services. The values for Service Root are configurable. The defaults is:
/K2Services/WS.asmx
WS Methods
The following operations are supported by the WS.asmx endpoint.
ExecuteActionBySerial
ExecuteActionByWorklistItem
OpenProcessInstance
OpenWorklist
OpenWorklistItem
ReleaseWorklistItem
StartNewProcessInstance
StartNewProcessInstanceScalar
UpdateProcessInstance
Accessing Datafields returned by the WebService
The WS.asmx WebService consumes Datafields differenlty from the standard K2 API usage. For instance, in the satandard K2 API one can access the Datafield like this:
Datafield x = processInstance.Datafields[“MyDatafield”];
As WebServices maps everything as array objects it is not possible to follow the normal K2 API usage. The following example code demonstrates how to access the contents of a
Datafield that has been returned using the WebService:
Copy
WSService.WorklistItem item = client.OpenWorklistItem(serialNumber, true);
item.ProcessInstance.DataField.GetDataFieldByName("MyValue").Value = "New DataField Value";
public static class ExtensionMethods
{
public static WSService.DataField GetDataFieldByName(this WSService.DataField[] dataFields, string name)
{
foreach (WSService.DataField dataField in dataFields)
{
if (string.Equals(dataField.Name, name, StringComparison.OrdinalIgnoreCase))
{
return dataField;
}
}
return null;
}
}
Populating Datafields or XMLFields
To enable Datafields/XMLfields to be populated, the settings in the web.config located in the K2Services folder needs to be changed:
Copy
<inclusions userExtendedProperties=”False” hiddenFields=”False” maxWorklistItems=”0”
processDataFields=”True” processXmlFields=”True” activityDataFields=”False”
activityXMLFields=”False”>
Statement
4.12060.1560.0 )
Accessing Datafields by Name
Default Webservice behavior will cause a 'collection' call to be changed to an 'array object'. Therefore one cannot simply use the Webservice to return Datafields by name. The work
around for accessing a Datafield by name is to create a custom extension method to handle the collection. The following sample code is an example custom extension to handle this
situation:
Copy
WSService.WorklistItem item = client.OpenWorklistItem(serialNumber, true);
item.ProcessInstance.DataField.GetDataFieldByName("MyValue").Value = "New DataField Value";
public static class ExtensionMethods
{
public static WSService.DataField GetDataFieldByName(this WSService.DataField[] dataFields, string name)
{
foreach (WSService.DataField dataField in dataFields)
{
if (string.Equals(dataField.Name, name, StringComparison.OrdinalIgnoreCase))
{
return dataField;
}
}
return null;
}
}
Statement
4.12060.1560.0 )

1 Services Reference

Transcription

Similar documents

Radiologist / Technologist Dataflow

Why Panda Security? “Its reliability, its simple and remote

Efficient XML

Leisure activities and relaxation

Batch Production of Driving Distances and Times Using SAS® and

Hypertension Objective Treatment Based on Measurement by

MIDI-PYRENÉES

Fluvial Fr RoVo.indd

Automated Forensics Research at NPS

Giving yourself all the chances to succeed... in college !