Using FilterXML parameter in SmartObject REST Services

When you are using K2 SmartObject REST services then you would have observed a query parameter with name FilterXML for all the list methods. This parameter can be used to filter out the data while executing the list method of SmartObject. But using this parameter is a kind of tricky for beginners unless you follow this simple trick which I’m going to explain below.

Let’s see a sample SmartObject (Students.SMO) which returns list of students as below.

1SMO.jpg

Now the SmartObject Service’s REST endpoint URL for above SMO will be as below

https://k2-server:8443/SmartObjectServices/rest/Vijay/SmartObjects/Students.SMO/Get List?$format={format}&$top={top}&$skip={skip}&filterXml={filterXml}&RollNumber={RollNumber}

As RollNumber is the id column of Students.SMO  smartobject, By default REST URL is giving us the RollNumber as a URIParameter

Now if you want to use other columns as a filter to get data, we have no other option than using filterXML.

As the parameter says it accepts XML based filters.

Now let’s suppose there is scenario where you want get the list of students where percentage is greater than 90. Now the filterXML for this would be like below

Condition: Percentage > 90

<filterexp>
 <greaterthan>
   <left>
     <propertyexp name="Percentage" sotype="Text" />
   </left>
   <right>
     <valueexp sotype="text">90</valueexp>
   </right>
 </greaterthan>
 </filterexp>

 

Condition: Percentage >= 90

<filterexp>
 <or>
   <left>
     <greaterthan>
       <left>
         <propertyexp name="Percentage" sotype="Text" />
       </left>
       <right>
         <valueexp sotype="text">90</valueexp>
       </right>
     </greaterthan>
   </left>
   <right>
    <equals>
      <left>
        <propertyexp name="Percentage" sotype="Text" />
      </left>
      <right>
        <valueexp sotype="text">90</valueexp>
      </right>
    </equals>
  </right>
</or>
</filterexp>

 Now we just have to pass this as a value to URIParameter filterXML

https://k2-server:8443/SmartObjectServices/rest/Vijay/SmartObjects/Students.SMO/Get List?$format=JSON&filterXml=<filterexp><greaterthan><left><propertyexp name=”Percentage” sotype=”Text” /></left><right><valueexp sotype=”text”>90</valueexp></right></greaterthan></filterexp>

Now the simpler way to create these filterXML values is using SmartObjects – Services-Tester utility tool. Select Execute Smartobject and click Set button beside filter option which is shown highlighted in below screen shot

2Filter

Now in below screen we need to select the column that we want to use as filter in Left Property (here it is Percentage) and in Logical Filter select the logical operator (here it is GreaterThan) and Right Property you will have an option to select a column or directly provide a value (here in my case it is 90) and click add to see the xml representation of filter. See below screen shot

3Filter

Now copy the xml from the bottom window, remove the first line (<?xml version=”1.0″ encoding=”utf-16″?>) and then you need to add <filterexp> and </filterexp> at the beginning and end of the copied xml respectively. Also remove the line breaks and spaces in the copied filterXML and then it ready for use.

Copy paste the url in chrome and hit enter button to see the data getting filtered as mentioned in filterXML

4Result.jpg

K2 OOB REST & WCF Services

Hello Guys,

Today I’m going to explain a very interesting yet very useful topic which is nothing but K2 Out of the box Services. Have you ever got a chance to explore about them? If your answer is No then please go through this article and get the idea what exactly they are.

Services.png

Basically K2 have provided many out of the box services of all types like WCF Services, REST Services, which would serve us for many purposes as below

  • Start a workflow instance.
  • Get the worklist items.
  • Action a task.
  • Execute the smart object methods (SmartObject Services)

Let’s see how we enable these WCF and REST services.

We need to edit the web.config file located on K2 server at default location C:\Program Files (x86)\K2 blackpearl\WebServices\K2Services\web.config to enable the Workflow REST services.

In the config file we see 2 sections WCF and REST commented out. We just have to uncomment the sections which we would like to use and then restart K2 Blackpearl Service Instance

  • Now to start the workflow use below URL.
http://{K2Server}/k2services/REST.svc/Process/Definitions({WorkflowName})
/StartInstance?folio={FolioValue}

** Replace the {WorkflowName} with process full name 

  • See complete worklist Items assigned to you.
http://{K2Server}/k2services/REST.svc/Worklist/Items

** By default all the data will be retrieved in XML format, but you can specify parameter $Format= JSON to retrieve the data in JSON format

** Note:  It will show only the worklist items which are assigned to you.

  • Get worklist item details based on SN
http://{K2Server}/k2services/REST.svc/Worklist/Items({SN})?
pidatafield=true&actxmlfield=true

** Replace {SN} with SN value

  • Action a task using SN
http://{k2server}/k2services/REST.svc/Worklist/Items({SN})/Actions
({Action})/Execute

** {SN} needs to be replaced with SN number, {Action} needs to be replaced with workflow action

SmartObject Services

Now we will know about one more interesting feature which are known as K2 SmartObject Services. Each and every SmartObject that we create in K2 can be accessed as REST or WCF Endpoints using this feature.

Now we can enable these SmartObject Services by editing the K2HostServer.exe.config file, so when exposing a SmartObject as an endpoint it will be exposed on both WCF and REST service.

Now to see the all the Smart Object’s and its methods that are exposed as endpoints we can use below URL.

https://{K2Server}:{Port}/SmartObjectServices/endpoints/endpoints.xml

And below is the sample endpoint for a SmartObject

https://{K2Server}:{Port}/SmartObjectServices/rest/Vijay/
GetK2Worklist()/List?$format={format}&$top={top}&$skip={skip}
&filterXml={filterXml}&pUserName={pUserName}

SmartObject Name: Vijay
Method Name: GetK2Worklist()
Parameters: pUserName
$top, $format, filterXml, $skip – these are the default parameters that will be available in all endpoints.

$top – Gives you no. of records to be fetched from top of the list

$format – XML/JSON

$skip – skips no. of records from the list

Filterxml – used for filtering and sorting the list. Example below.

filterXml=<Criteria xmlns="http://schemas.k2.com/worklist/d1">
<Filter Field="ProcessFolio" Comparison="Like" ValueType="String">
Demo</Filter><Sort Field="ProcessStartDate" Order="Descending" />
</Criteria>

 

All the SmartObject parameters will be given as QueryParameters and the types of methods are Create, Read, Update, Delete, List, Execute.

That’s it, this is how we can use the OutoftheBox features that are available in K2

For more Help on exploring these things refer links below

WCF Services

https://help.k2.com/onlinehelp/k2blackpearl/DevRef/4.7/default.htm#WCF_Services.html

https://help.k2.com/onlinehelp/k2blackpearl/DevRef/4.7/default.htm#WorkflowWCFServicesSamples.htm

https://help.k2.com/onlinehelp/k2blackpearl/DevRef/4.7/default.htm#REST_Services.html

https://help.k2.com/onlinehelp/k2blackpearl/DevRef/4.7/default.htm#WorkflowWCFServices.htm%3FTocPath%3DRuntime%2520APIs%2520and%2520Services%7CWorkflow%7CWorkflow%2520WCF%2520services%7C_____0

SmartObject Services

https://help.k2.com/onlinehelp/k2blackpearl/DevRef/4.7/default.htm#REST_Services2.html