We're updating some of our product names. K2 Five will soon be Automation On-Prem. You may see both product names in our help pages while we make this change.

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.

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

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 fo the Developer's Reference

Watch a short video on how to use the K2 REST and WCF Services (Length 13 minutes)

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 (OK) – returned if the call was successful
404 (Not Found) – returned if something requested is no longer available
503 (Service Unavailable) – returned if the K2 Server was unreachable
500 (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

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.

<?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.

<?xml version="1.0" encoding="utf-8"?>
<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.

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 Filter and/or zero or more Sort nodes.

The order of the attributes does not matter.

<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