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

Advertisements

Creating Endpoint REST Service instance for a REST api which needs authorization bearer token

 

This post is in continuation to my previous post K2 Integration with REST Api Services which explains how to integrate K2 with REST Api Services. In my previous post, I have integrated with an Api Service which doesn’t require any Authorization Token that needs to be passed. But there is a chance that you find some REST api Services that needs an authorization bearer token to be passed to execute its methods. Now in this post we will see how to integrate to one of those REST Api services which needs the Authorization Bearer Tokens.

To get the swagger file follow the steps that were mentioned in my previous post which is using RESTUnited.com. There will not be any changes in steps to generate swagger except in authentication tab you will have to mention authentication token details and add it which will be as shown in below screenshots.

1AddAuthentication

 

2AddedAuthRESTUnited.jpg

 

Now once we get the Swagger file generated proceed to create Service Instance using EndPoints REST option in Smart Objects – Services – Tester Utility.

Now in Service Keys Section, Default HTTP Request Headers field you need to add this Authorization Token key in below format without any line breaks

{“$type”:”SourceCode.SmartObjects.Services.Endpoints.Common.HttpHeader[], SourceCode.SmartObjects.Services.Endpoints.Common, Version=4.0.0.0, Culture=neutral, PublicKeyToken=null”,”$values”:[{“$type”:”SourceCode.SmartObjects.Services.Endpoints.Common.HttpHeader, SourceCode.SmartObjects.Services.Endpoints.Common, Version=4.0.0.0, Culture=neutral, PublicKeyToken=null”,”Name”:”Authorization”,”Value”:”Bearer eyJhbGciOiJub25lIn0.eyJVc2V==”}]}

*Replace the Values with the token that needs to be passed. Also we can pass multiple header Tokens here.

Now give the path of the Swagger file in the descriptor location field and leave rest of the options with default values

3.jpg

That’s It, Now just create a SmartObject using this Service instance and execute to see the result.

If you get any error with message like “Unable to Deserialize…” then its issue with the format of token that’s passed in HTTP Request Headers section…Just ensure that it is in above mentioned format without any line breaks . That’s It.

Also please note that this procedure should be used only for development purpose as per K2. Don’t ask me the reason (B’cuz I too don’t know :))

Note: Recently, when one of my friend tried to create a SmartObject over a REST Service instance that he created for a REST service which needs authorization bearer token, he was constantly getting 401, 404, 0 as response code but the same service he was able to run from Postman and fiddler without any issue. He tried all above mentioned things but still we couldn’t figure out what is the issue with REST when we are trying to connect with K2. so we approached K2 Team for help and when they investigated they found that its the issue with REST Service Api URL which has spaces in it and K2RESTBroker is trying to encode the URL which is already encoded…so as a fix we have removed spaces in REST service endpoint URL and the k2 is still investigating the actually issue behind the k2 encoding the already encoded URL. So just ensure that your REST Service URL doesn’t have any spaces in it.

Below are the community posts which will give you related information regarding this.

http://community.k2.com/t5/K2-blackpearl/How-toHandle-Authorization-Token-while-Creating-Endpoints-REST/m-p/101521#M33759

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

K2 Integration with REST Api Services

Cover.jpg

We know that K2 has ability to integrate with multiple LOB’s, let us have a look at how we can integrate K2 with REST Api’s.

This post will explain you

  • How we create a REST Service Instance for a REST Api using K2 REST Service broker.
  • Create a Smart Object to get the data from REST Api.
  • Execute that Smart Object Method.

Creating REST Service Instance

K2 uses Swagger Definition of REST Service for creating a Service Instance. Swagger definition can be obtained by using an online Tool RESTUnited.com

RESTUnited.com is an online tool to generate the swagger definition of a service.

Now for this sample I have used the openWeatherMap.org which provides free REST API’s of weather information with multiple querying options for free along with some paid featured services too.

To Use their free services you need to register with your mail ID and some other basic details. Once registered, you would get an API Key which you need to use for all the API calls.

They have provided enough documentation of their wide range of API’s with details at below link

https://openweathermap.org/api

WeatherAPIKey.jpg

Here is a sample call to one of the REST Api which takes city name as input and gives the weather response. Please note that API key needs to be passed as URL Parameter APPID

http://api.openweathermap.org/data/2.5/weather?q={CITYNAME}&APPID={APIKEY}

PostmanCall.jpg

Once you have Api ready, we need to get the swagger definition of that service. Now to get that use RESTUnited.com an online tool. You need to register here for a free trail to use the tool. Now follow the instructions as given at below link.

https://help.k2.com/kb001758

Once you have completed all the steps you will see below screen in which you would be able to download the Swagger definition by selecting Swagger Tab and clicking Export Button.

RESTUnited

Once you have the Swagger Definition/Descriptor file,

  • Open SmartObjects – Services – Tester utility tool(find this utility at C:/Program Files/K2 Blackpearl/bin),
  • Expand ServiceObject Explorer right click on REST,
  • Click Register ServiceInstance and you will be seeing below screen where in highlighted area you need to give the path of that swagger file that we just downloaded.

RESTServiceInstance

  • Now Click Next button and you should see below screen and Click Add.

RESTServiceInstance2

RESTServiceInstance3

Now you should be able to see the Service Instance Added under the REST Category as below, you can explore the methods and types under it from here.

RESTServiceInstance4

Creating Smart Object

Now it’s time to create a smart object using this Service Instance. We can use K2 Designer or Visual Studio or K2 Studio for creating but here I would prefer to use the same SmartObjects – Services – Tester utility tool to create as it’s the fastest way to create and publish an SMO.

Just give a right click on the object type or method that you want to use from Service Instance and Select Create SmartObject, now you would be seeing below screen. In that give you’re SmartObject a Name and select the folder under Category dropdown and Click Publish SmartObject

SMOCreation

That’s it. Now navigate to your SMO and execute the method to see the results.

Below are the serialized data responses from the Api, now to get the individual Values, we need to deserialize them. For knowing how to deserialize the serialized responses check here Handling Complex Objects in K2 SmartObjects

SMOResults.jpg

This is how we can integrate K2 with REST Api Services .

Cheers Guys!!!