How-To: Create a REST Service Instance and SmartObject

Summary

In this video tutorial by Nintex, the process of integrating K2 applications with REST-based service endpoints is explained. By using the K2 REST service broker, a service instance for a third-party RESTful web service is created and exposed as a smart object. This enables the use of REST services within K2 smart forms and workflows, demonstrated using the Open Weather Map service. The tutorial details setting up a Swagger definition file for the REST service, creating a service instance through K2's management site, and building a smart object using the K2 designer. The process includes deserializing the JSON data and displaying it in a smart form, enabling easy interaction with REST data from within a K2 application.

Highlights

• Integrate K2 applications with REST endpoints using the REST service broker. 🚀
• Create a Swagger definition file to define the REST service properties. 📜
• Build a service instance for the Open Weather Map service in K2. 🌤
• Utilize JSON descriptor files to define and manage K2 service interactions. 📝
• Generate and display weather data in smart forms effortlessly. 🌡

Key Takeaways

• Learn to integrate K2 applications with REST endpoints easily using the REST service broker. ⚡
• Gain insights into creating and utilizing Swagger definition files for REST services. 📄
• Understand how to create and manage service instances within K2. 🔧
• Master the art of deserializing JSON data for K2 smart forms. 📊
• Discover how to display REST service data on smart forms engagingly. 📱

Overview

The Nintex tutorial provides a step-by-step guide on integrating REST service endpoints with K2 applications using the REST service broker. It simplifies the complexities of integrating restful services by allowing K2 to utilize external data effectively in workflows and smart forms. The primary example used is Open Weather Map's RESTful service, showcasing how to leverage data in K2 applications.

A Swagger definition file serves as the backbone for integrating REST services, detailing the JSON schema needed for service interactions. By following the tutorial, users can learn to create a service instance via the K2 management site. These service instances enable seamless communication between K2 and the chosen RESTful services, helping in efficiently managing data flow.

Finally, the use of the K2 designer to build a smart object is illustrated, showing how deserialized JSON data can be formatted and presented in a K2 smart form. This tutorial proves invaluable for developers looking to enhance their K2 applications with efficient data handling and display, making interactions smooth and visually appealing.

Chapters

• 00:00 - 00:30: Introduction The chapter titled 'Introduction' discusses the K2 REST Service Broker, its role in integrating K2 applications with REST-based service endpoints, and its application in creating a service instance for third-party RESTful web services. The chapter aims to expose these as smart objects for use in K2 smart forms and workflows. The lesson proceeds under the assumption that the reader has prior knowledge of the individual components necessary for a REST integration.
• 00:30 - 01:00: K2 REST Service Integration Components The chapter titled 'K2 REST Service Integration Components' provides an overview of various components required for integration using K2. Key components discussed include OAuth resources for security, K2 service instances, SmartObjects, and SmartForms, REST endpoint services, and JSON descriptor files. The chapter outlines the end-to-end integration scenario where a REST endpoint, located either in the cloud or within a corporate environment, requires the creation of a REST-based service instance in K2 to interface effectively with the endpoint.
• 01:00 - 02:00: Setting Up a REST Service Instance In the chapter 'Setting Up a REST Service Instance', the process of creating a REST service instance using a JSON descriptor file, compliant with the Swagger specification format, is discussed. This setup enables interaction with RESTful services within K2 through smart objects. The example provided utilizes a weather service endpoint from Open Weather Map to illustrate how current weather data can be seamlessly integrated and presented in K2 smart forms and workflows.
• 02:00 - 03:00: Creating a Swagger Definition File The chapter discusses building a Swagger definition file that describes the JSON data object returned from a weather service's REST API endpoint. It specifies that detailing how to build this file is beyond the video's scope, but the basic steps are outlined. The process involves locating information about the JSON object schema from the API provider, such as Open Weather Map.
• 03:00 - 05:00: Configuring the Service Instance on K2 Management Site This chapter explains how to configure a service instance on the K2 Management Site with a focus on utilizing REST service endpoints. Specifically, it uses the 'current weather' endpoint as an example. The chapter outlines necessary steps such as creating an account and retrieving an API key from a service provider like OpenWeatherMap. It also touches on configuring OAuth settings, highlighting that requirements may differ between service providers.
• 05:00 - 07:00: Creating a Smart Object in K2 Designer The chapter guides on creating a smart object in K2 Designer by utilizing API services. Initially, an authorization token is typically required, but the provider in this context doesn't need it. OpenWeatherMap provides necessary information, and users can edit descriptor files using the Swagger online editor. Users have the option to edit in YAML or Swagger JSON formats. After editing, the file needs to be downloaded and saved.
• 07:00 - 10:00: Method Chaining and Deserialization The chapter discusses method chaining and deserialization, focusing on the importance of creating accurate Swagger JSON definitions for service brokers. It suggests utilizing resources like swagger.io for tools and example files to assist in building these files effectively. Furthermore, it advises consulting additional materials on help.k2.com for a deeper understanding of the REST service broker and integration with K2 platform definition files. These resources offer extensive support for integrating REST services efficiently.
• 10:00 - 15:00: Building a Simple Smart Form to Display Data The chapter discusses the process of building a simple smart form aimed at displaying data, primarily focusing on using a swagger definition file. It mentions using the K2 management site integration options to create a service instance with the REST service broker. It assumes familiarity with swagger definition files and points out the importance of knowing the file's location.
• 15:00 - 16:00: Conclusion and Additional Capabilities The chapter titled 'Conclusion and Additional Capabilities' begins with a focus on the Open Weather Map service hosted on a website. The service works with the K2 cloud, and in some cases with K25, allowing the JSON file to be pulled from a local file store location. Upon opening the file, the format is not JSON, but it provides endpoint location information and a description of the JSON data object expected from the API call. This is exemplified over in the K2 management site.

How-To: Create a REST Service Instance and SmartObject Transcription

• 00:00 - 00:30 the k2 rest service broker is designed to help you integrate your k2 applications with rest based service endpoints in this lesson we're going to use the rest service broker to create a service instance for a third-party restful web service then expose it as a smart object so k2 can use it in smart forms and workflows for the sake of time i'm going to assume you are familiar with the individual components for a rest
• 00:30 - 01:00 integration in k2 which are typically oauth resources for security k2 service instances smart objects and smart forms rest endpoint services and basic json descriptor files however when you piece all of these components together the end-to-end scenario looks like this you have a rest endpoint either sitting out in the cloud or somewhere within your corporate environment you will then need to create a rest based service instance in k2 to interface with the endpoint
• 01:00 - 01:30 using a json descriptor file that documents the schema of the rest service you want to call based on the swagger specification format from there you set up a smart object that enables the data from the rest service to be used within k2 smart forms and workflows with this demonstration we're going to use a restful service endpoint provided by a weather service called open weather map to provide data for current weather conditions and present it on a smart form to make this work in k2 we must
• 01:30 - 02:00 first build out a swagger definition file which describes the json data object that is transmitted back from the call to the weather service's rest endpoint api for the sake of time building this file is beyond the scope of this video but in a nutshell the basic steps look like this from the api provider you're going to locate information about what their json object schema looks like in this example open weather map provides this information off their site
• 02:00 - 02:30 for each of the endpoints they provide i'm just going to use the current weather endpoint in this demonstration so let's look at that page for a minute not every provider is the same but here we can see the json parameters described on this page as with most rest service providers for this call to work we also have to create an account and retrieve an api key i've already taken care of that task with open weather map but keep in mind this is also where you would configure your oauth settings to
• 02:30 - 03:00 get your authorization token however we won't need to do that with this provider with this information that's provided by open weather map we can use the online editor provided by swagger at the following link visible here on the screen or you can also download and install their editing tools locally to build out a descriptor file by using either the yaml format or you can use the swagger json format either way when finished with the editing the file must be downloaded and saved in the
• 03:00 - 03:30 swagger json format for the service broker to read it successfully you can visit www.swagger.io which provides tools example files and more information on how to build a swagger definition file also be sure to review help.k2.com for more information about the rest service broker and how it works with your definition files to integrate a rest service with k2 on that page you will also find some more information that links to some other options that can help you with
• 03:30 - 04:00 your swagger definition file like the rest united website or the nuget swashbuckle project once you have your swagger definition ready to go you can move on to create your service instance with the rest service broker for this demonstration i'm going to use the k2 management site integration options to create the service instance which i also assume you're somewhat familiar with it's always a good idea to make sure you know where your swagger definition file is located before
• 04:00 - 04:30 you begin as you can see i have one for the open weather map service hosted on a website for simplicity this works with k2 cloud this way however in some cases with k25 you can also pull the json file in from a local file store location upon opening up the file notice it isn't the json format and provides information for the endpoint location and a description of the json data object that will come back from the api call over in the k2 management site
• 04:30 - 05:00 i'll open up the integration group of options and select the service types node from the menu i want to create a service instance pointing to open weather map using the rest based service type here so i'll select that option on the second page of this list then click the new instance button in the menu at the top i'll give this service instance the name of open weather map with a brief description
• 05:00 - 05:30 because open weather map does not require the oauth authentication mode we can leave the default setting for authentication to impersonate but keep in mind this is where you will need to enter your resource information when setting up a service that requires oauth all i need to do for this service instance is provide the location for the descriptor file through this url i'll go ahead and paste that in the rest of the settings can be left as they are for more information about these options
• 05:30 - 06:00 you can reference product information for the rest service broker on help.k2.com from here i'll click ok to add the new service instance to the k2 environment with that successfully added let's check out what it created over under the service instances menu option on the left side of the page we now have a service instance for open weather map later on when working with the service object explorer and k2 designer
• 06:00 - 06:30 we will see under this instance we have also created service object types based on the entities within the json descriptor file for clouds wind and so forth the endpoint method we want to call is actually a part of the weather object and it's named getweather when we call this with our smart object open weather map will return a serialized json-based response and k2 will make it available in the return parameters shown here we can get to the values that are in
• 06:30 - 07:00 this serialized data by calling the deserialize methods provided by the entity service objects for the corresponding return parameter when we build our smart object to get a better understanding of this let's go over to k2 designer and start our design of the smart object k2 designer will give us more flexibility to customize and return the properties we want from the get weather method in our smart object what i mean by that is this because the get weather method returns weather data
• 07:00 - 07:30 in serialized json format it is initially harder to get to the weather properties from that method alone we want to make this easy for our form designers to get to this data in one method call so we can use method chaining to extract weather values out of the serialized data and expose the properties we want like the current high and low temperatures and things like humidity in this lesson i have already created an empty advanced smart object named weather to speed
• 07:30 - 08:00 things up and allow us to chain methods together my requirement is to be able to call get weather from a smart form and display some current weather conditions on the form based on an entered location i'm actually going to get properties for this smart object from the service object methods we call rather than manually add them to do this i'll open the methods tab then click on the add button go into the open weather map service object
• 08:00 - 08:30 and to get to the method we want we can drill down into the object types folder then go down into the weather type and select the get weather method then i'll click the next button for name i'll change this value to get current weather we can leave it set to the read type and leave the transaction type as continue nothing else is needed on this window so we can move on mapping input parameters and return
• 08:30 - 09:00 properties is next to make this easy i'm just going to select create all and have k2 create all the parameters for me and automatically bind them then as an example i need to go down into the return properties section and clear a few of these properties since i'm not concerned with exposing them at this point that should do it upon reviewing what i just did we can see that the parameters and return properties are automatically set up for us to call getweather
• 09:00 - 09:30 if we publish the smart object at this point when we call getweather we will get serialized json objects back in each of these return properties we need to make this a little more meaningful for our form designers at this point this is where method chaining comes into play and i'll click next to get this going for demonstration purposes i just want something like current weather description with an icon and maybe current temperature on a smart form to get to these values i know from
• 09:30 - 10:00 building the descriptor file that they live in the main and weather return properties so i need to run each of those values through their respective deserialized methods to get those properties out let's begin with the weather property i'll add another method then from the service object method box we can click on the ellipses option to open the service objects list again i'll go down into the weather object type in the open weather map service object
• 10:00 - 10:30 here i need to select the deserialize typed array method which will also give me the ability to create the specific return properties i want from here i'll click create all to create each property automatically for now the serialized array input property for this method does need to be changed and assigned to the weather array property that comes out of the getweather method we just configured so let's set that up by selecting this property for input then click on the assign
• 10:30 - 11:00 button and for smart object property i'll select weather i only want description and icon so i'm going to clear the id and main bindings because i'm not going to use those values in my form this is where the deserialized values for description and icon will land when this method is called by doing this they can be dropped into smart forms and workflows much easier i'll click ok now to go back and add another method i want to do the same thing for the main
• 11:00 - 11:30 return property from get weather so we can get to the temperature and humidity values this json object is not an array but it is still serialized so we could just call the deserialize method under the main service object i'll click the add button to add another method drill down into the main service object type under open weather map and select deserialize
• 11:30 - 12:00 moving on from here i'll select create all but then change the serialized item input binding to the main property and that should do it i'll keep the rest of these return properties and finish this dialogue out let's take a look at the results of this step as we built this chained method the actions we took created the smart object properties for us as you can see over on the properties
• 12:00 - 12:30 tab when we call getcurrentweather from a smart form these properties will be populated according to the order in which the chained methods run to lay it out the serialized return properties of the direct call to open weather map like wind weather and base are populated then we push those values through the deserialized methods which populate properties such as temp pressure and humidity i'll finish this out and save it back to k2 this is the process you'll take when
• 12:30 - 13:00 working with serialized json objects the nice thing is now we only have to call one method to pull in data from the rest endpoint and it deserializes it into the values we need for our application let's take a look at a simple form i've created that calls this method and then displays the weather data i want in an application i have an instance of a smart form view showing with some data label controls that show weather data in this example you can just plug in a
• 13:00 - 13:30 city name or a zip code to get data back but you could also wire this up with the location control and use location information from a mobile device to make a call for weather based on your current location and gps settings upon clicking the get weather button this view calls the smart object method we just created called get current weather and that brings back data from the open weather map rest service and drops it on the view as you can see using simple formatting capabilities we
• 13:30 - 14:00 can then display current conditions using the icon temperature and description return properties i want to show you what the rules on that view look like to provide some context on how we got here i have k2 designer opened up to this location view notice i put a text box on this view to capture a location from the user and also drop data label controls near the top to show weather data i created a rule based on the button click event when this event fires it will execute
• 14:00 - 14:30 the getcurrentweather method from our smart object let's review that configuration on this screen i'm just basically getting the entered location values from the textbox control from the view and for purposes of the demo i did need to store an application id for open weather map in a k2 environment variable under the miscellaneous group and load that in as well to get the data labels to show the data i want i actually use the transfer data action and here i built the html image tag for
• 14:30 - 15:00 the icon to appear as an image and make a note this data label has the literal setting enabled for this to work the temperature comes down from open weather map and kelvins so i do need to set up an expression to convert celsius and drop the description field in that's pretty much it so in review we can get data from a restful service using the rest service broker with a swagger json descriptor file pull that data in from the endpoint
• 15:00 - 15:30 deserialize down to the properties we want then use them on a form this constitutes a get method but we can also post back to a rest endpoint to update data using the rest broker at this point in time we recommend using a json based payload when doing that