K2 REST Service Broker (v4.7)

After the release of K2 4.7, REST service broker is one of the major release and topic of discussion for all the developers. So I have consolidated all the data provided by K2 and other portal and came up with the below simple steps to integrate any REST API with our K2 application:

  • Create Swagger descriptor file that exposes your REST API.
  • Register an app and provide delegated permission.
  • Configuration change in K2 Management.
  • Register Service Instance.
  • Create SmartObject.
  • Use the SmartObject in K2 Smartform and Workflow

Before starting with the detail description of every steps let’s take a look back to the basics we need to know for completing the steps.

  •  Using REST before K2 4.7 release

Previously we have to write a load of code to wrap around the REST service and then access it via the Endpoint assembly broker.

  • Using REST after K2 4.7 release

After the release of REST service broker, consuming REST services become very easy as it uses Swagger to define the Service Objects and methods.

  • Scenario

The example which we are going to take is “Fetching logged in user profile data from office 365”.

  • Step 1: Create Swagger descriptor file that exposes your REST API.

As we know swagger file is nothing but a descriptor file of our REST API so for that firstly we need to have our REST API ready. For our scenario we are going to use Microsoft graph API provided by Microsoft which is a one stop destination for all the office 365 REST API.

You can explore and test Microsoft Graph API here.

API for fetching the logged in user profile from o365 is https://graph.microsoft.com/v1.0/me/

Now we have our REST API so next step is to create a swagger file and there are several ways for creating the swagger file, some of them are

  • Download an existing descriptor file, whether it is exposed by the service itself or previously generated by someone else
  • Use the Swashbuckle NuGet project to your API to generate a Swagger file. Click here for more information
  • Write a descriptor file by hand
  • Use a tool like RESTUnited.com to generate a descriptor file.

Note: K2 REST Service broker uses Swagger 2.X version so our swagger file should be in 2.X version and its extension would be .json or .yaml.

Skeleton of any swagger file contain 3 main section:

  • Swagger Information

This section include the basic info about the swagger file for example version, base URL etc.

Sample example:

 "swagger": "2.0",
 "info": {
 "version": "v1",
 "title": "Microsoft Graph - Example"
 },
 "host": "graph.microsoft.com",
 "schemes": [
 "https"
 ]
  • Swagger path

This section include the path to the specific resource which we want to use, later these path will only be converted into SmartObject methods.

Example

"paths": {
 "/beta/me": {
 "get": {
 "tags": [ "Me"],
 "operationId": "Me",
 "consumes": [ ],
 "produces": [
 "text/json",
 "application/json"
 ],
 "parameters": [ ],
 "responses": {
 "200": {
 "description": "OK",
 "schema": {
 "$ref": "#/definitions/GraphUser"
 }
 }
 },
 "deprecated": false
 }
 }

Here we can add any number of paths we want.

This section describes the response from the API and here we can restrict the number of columns we want to display.

Example:

 "definitions": {
 "Object": {
 "type": "object",
 "properties": { }
 },
 "GraphUser": {
 "type": "object",
 "properties": {
 "companyName": {
 "type": "string"
 },
 "country": {
 "type": "string"
 },
 "displayName": {
 "type": "string"
 },
 "givenName": {
 "type": "string"
 },
 "jobTitle": {
 "type": "string"
 },
 "mail": {
 "type": "string"
 },
 "mobilePhone": {
 "type": "string"
 },
 "surname": {
 "type": "string"
 },
 "userPrincipalName": {
 "type": "string"
 }
 }
 },

Here one thing to be noted is the result of the API and the properties mentioned in Definition section should have the exact same name and hierarchy.

What I would suggest you is to execute the REST API in POSTMAN and analyze the response and make sure the properties name is exactly same.

Here is the complete swagger file which we are going to use for our scenario.

 

{
 "swagger": "2.0",
 "info": {
 "version": "v1",
 "title": "Microsoft Graph - Example"
 },
 "host": "graph.microsoft.com",
 "schemes": [
 "https"
 ],

"paths": {
 "/beta/me": {
 "get": {
 "tags": [
 "Me"
 ],
 "operationId": "Me",
 "consumes": [ ],
 "produces": [
 "text/json",
 "application/json"
 ],
 "parameters": [ ],
 "responses": {
 "200": {
 "description": "OK",
 "schema": {
 "$ref": "#/definitions/GraphUser"
 }
 }
 },
 "deprecated": false
 }
 }
 },

"definitions": {
 "Object": {
 "type": "object",
 "properties": { }
 },

"GraphUser": {
 "type": "object",
 "properties": {
 "companyName": {
 "type": "string"
 },

"country": {
 "type": "string"
 },

"displayName": {
 "type": "string"
 },

"givenName": {
 "type": "string"
 },

"jobTitle": {
 "type": "string"
 },

"mail": {
 "type": "string"
 },

"mobilePhone": {
 "type": "string"
 },

"surname": {
 "type": "string"
 },

"userPrincipalName": {
 "type": "string"
 }

}

},

}

}

Now we are done with the Step 1: Create Swagger descriptor file that exposes your REST API.

  • Step 3: Register an app and provide delegated permission.

For fetching the logged in user info from O365 you must validate the user from AAD and for that we are going to use OAuth.

For using oAuth configuration, firstly we need to register the App and provide the required permission, for registering the app we are going to use the new (currently in beta) Application Registration Portal – https://apps.dev.microsoft.com/

Navigate to the Application Registration Portal and login with your tenant admin credentials.

Click Add an App for Converged Application and provide the valid name and click on Create Application

As soon as you click on Create Application you will be redirected to app registration page where in Application id will be created that is nothing but your client ID.

Below Application id, Application Secrets will be there so click on “Generate New Password” and save the password somewhere for future use because you will not be able to see the password again. After complication screen will look like

Application Id

Below Application Secret, Platforms section will be there and will be used to provide the redirect URI where we have to navigate after successful authentication. So click on “Add Platform” and select “Web” then enter the redirect URI.

Application secret

For our scenario we will be giving the redirect URI in the below pattern.

https://<Server name>/identity/token/oauth/2

Form will look like below after completion.

After setting the redirect URI last step is to provide the required permission for this app so for our scenario we will be giving “Sites.Read.All” under delegated permission.

Now we are done with the registration so in a nutshell after completing step 2 we will be having the following information with us which we will be using in step 3.

  • Application ID/Client ID
  • Application Secret/ Client Secret
  • Redirect URI
  • Permission
  • Step 2: Configuration change in K2 Management.

Under this step we will be configuring oAuth on the K2 Server by using the information collected in step 2.

So for this navigate to https://<Server Name>/Runtime/Runtime/Form/Manage+OAuth+Resources/ or find the Manage OAuth Resources form in K2 Designer.

Click “New” for adding a new resource and enter the following details for OAuth Resource.

Resource OAUth

Click OK

On the form select the newly created OAuth Resource. This will list the Resource Parameters that now need to be configured.

Under Resource Parameters double click on a parameter to edit it.

[Authorization, Token]

Other parameters do not need configuring, Once the configuration is done it will look likeResource parameter OAuth

  • Step 4: Register Service Instance.

For creating the service instance, open SmartObject Service Tester and expand ServiceObject Explorer.

Right click on the “REST” service broker included by K2and click on “Register Service Instance”

Service instance

After click on Register Service Instance, a popup will be opened for adding the service instance.

In the pop up window select the authentication mode as “OAuth” and in OAuth Resource select the resource which we have configured in K2 Management screen in previous step.

Paste your newly created swagger file to the local server and paste the path for the swagger file in “Descriptor Location field”. Screen should look like below

Create Service instance

Once you are done with the configuration, Click on NEXT a validation pop up will come and ask for validation.

Oauth Error

Click OK and you will be redirected to Microsoft login page, enter your credentials and click OK.

Then It will ask you to grant the permission provided by you at the time of registering the App.

Once its done, click on “Next” to create the service instance.

  • Step 5: Create SmartObject.

 Once the service instance is created, Right click on the newly created service instance and click “Generate SmartObjects”

SMO

Select the method for which you have to create the SmartObject and click OK. SmartObject will be created under the folder named same as of your service instance.

Generate SMO

  • Step 6: Use the SmartObject in K2 Smartform and Workflow.

Once the SmartObject is created, navigate to the selected smartObject and execute it you will be getting the logged in user profile data which will look similar to the below screenshot.

Execute SMO

Now you can use this SmartObject in smartforms or workflow to achieve business requirement.

In the same way we can consume any REST API provided by any vendor and we can use that in our smartform or workflows by creating the service instance and smartobject for the same.

Just follow the 6 steps and integrate any API to K2.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s