TECHNICAL NOTE HOW TO USE WEB SERVICES. Document: Kalipso_TechDocs_Web_Services. Revision: 1.0. Kalipso version:

Transcription

1 TECHNICAL NOTE HOW TO USE WEB SERVICES Document: Kalipso_TechDocs_Web_Services Revision: 1.0 Kalipso version: Date: 08/03/2018 Kalipso documentation How to Use Web Services 1

2 Contents 1. About How SOAP Web Services work How REST Web Services work Advantages Disadvantages Web Services in Kalipso SOAP Web Services... 5 Webservices... 6 Webservice Run RESTful Webservices... 6 HTTP Request Tutorial Demo App SOAP RESTful Kalipso documentation How to Use Web Services 2

3 1. About Web services are client and server operations that communicate over the World Wide Web (WWW) using the Hypertext Transfer Protocol (HTTP). They are self-contained, modular, distributed, dynamic applications that can be described, published, located, or invoked over the network to create products, processes and supply chains. They are built on top of open standards such as TCP/IP, HTTML, HTML, and XML. There are two main types of webservices: SOAP and REST. SOAP (originally Simple Object Access Protocol) is a protocol specification for exchanging structured information in the implementation of web services in computer networks. REST stands for REpresentational State Transfer. REST is a web standards-based architecture and uses HTTP Protocol for data communication How SOAP Web Services work A Web Service is described by a document in XML format, in the XML language known as WSDL (Web Services Description Language). This describes the service in terms of the operations, messages, and bindings that it contains, and may provide a URL at which the service may be called. The structure of the messages is described using XML Schema (XSD) which is either contained in or referred by the WSDL. The messages sent to, and received from, the web service are all in the form of XML that complies to the schema, and which follows the protocols described by the WSDL, using an XML protocol known as SOAP (Simple Object Access Protocol) How REST Web Services work In REST architecture, a REST Server simply provides access to resources and the REST client accesses and presents the resources. Here, each resource is identified by URIs/ Global IDs. REST uses various representations to represent a resource like Text, JSON and XML. The user must be familiarized with the requirements and other details related with the used API. JSON (JavaScript Object Notation) is now the most popular format being used in Web Services, is a lightweight data-interchange format, easy for humans to read and write and for machines to parse and generate. Kalipso documentation How to Use Web Services 3

4 1.3. Advantages Exposing the Existing Function on the network. Interoperability Standardized Protocol Low Cost of Communication 1.4. Disadvantages Availability Immutable interfaces Matching requirements Kalipso documentation How to Use Web Services 4

5 2. Web Services in Kalipso In Kalipso you can use Web services to send and receive data. Kalipso supports both SOAP and RESTful Web Services SOAP Web Services Web Services are a set of routines/processes/functions on a remote server which serves as a host for these services. In Kalipso you can import these Web Services definitions through their WSDL description and then execute them with the Web Service Run Action. When using SOAP, Kalipso provides a Wizard to, through the Web service s WSDL, retrieve all the available operations. Kalipso documentation How to Use Web Services 5

6 Webservices Webservice Run RESTful Webservices To work with RESTful Web services, Http Requests need to be made to send and receive the data required. HTTP Request Kalipso documentation How to Use Web Services 6

7 3. Tutorial Demo App In this tutorial we are going to exemplify how to use Soap and Restful Web Services. 1. Create a New Project SOAP The Web Service used in this demo is the following: 2. Double-click the icon presented in the project tree. Kalipso documentation How to Use Web Services 7

8 3. In the Web Service setup window click the Icon and select Wizard. 4. Give a name to the Web Service and add the WSDL Address and other details if needed. Kalipso documentation How to Use Web Services 8

9 5. Click Next. 6. When the WSDL file content is displayed, click Next. 7. Select the desired operations, in this case we only need FullCountryInfoAllCountries. 8. Click Done. Kalipso documentation How to Use Web Services 9

10 9. Create a new Form. Configure the Left Arrow to close the Form. 10. In the button Click event add the Close Form action. Kalipso documentation How to Use Web Services 10

11 11. Rename the Title Label. 12. In the Open Form event add the Web Service Run and define a variable to receive the Target XML in the General Tab. Kalipso documentation How to Use Web Services 11

12 13. In the Web Service Tab select the Operation FullCountryInfoAllCountries and press Save. Some webservices need authentication and return a token that needs to be used in the subsequent requests. Although these fields are automatically filled, they can be edited, if necessary, to include for instance the authentication token. 14. Test the application on the Simulator to verify the returned XML. Kalipso documentation How to Use Web Services 12

13 In Kalipso, a Webservice is used as input/output interface. The collected data, in XML format, is then processed/imported to a local database table that needs to be created. 15. Now we need to create a Local Database Table to store the retrieved data. In this example the following Columns will be needed. ISOCode, Name, Capital, PhoneCode, ContinentCode, CurrencyISOCode, ContryFlag and LanguageName. Kalipso documentation How to Use Web Services 13

14 16. Edit the Web Service Run action to save to a variable only the structure that will be imported to the database. a. In the Outputs tab, select the <content> above the element that contains the countries list ( tcountryinfo ) since it always has a single element containing that list (unbounded). b. Select Modify and choose a variable to save the data. Kalipso documentation How to Use Web Services 14

15 17. Test to verify the data to import. Now use the XML Import to Table action to process the data in the Variable. 18. Select Text as Source and the Variable which stored the Country Info Kalipso documentation How to Use Web Services 15

16 19. In the Group Element Tab define "tcountryinfo" as the XML Group Element, since this is the element that will be repeated(unbounded) and contains all the items related a specific country. 20. In the Column List Tab, right-click and select Add Element, to collect the country subelement. Kalipso documentation How to Use Web Services 16

17 21. In the Element Name set to "sisocode", enable the Define Target checkbox to select the ISOCode Column from the Local Database Table. 22. Click OK. 23. Repeat the process to add the other elements to be imported (sname, scapitalcity, sphonecode, scontinentcode, scurrencyisocode, and scountryflag). Kalipso documentation How to Use Web Services 17

18 24. Add the Languages element without defining a target, since the desired element is nested. 25. Right-click the Languages element and select Add Element to Current/Previous Table. Kalipso documentation How to Use Web Services 18

19 26. In the Element s Name define as tlanguage also without a target. 27. Right-Click the tlanguage and select Add Sub Element to Current/Previous Table. 28. Set the Element Name to sname and the target column to LanguageName and press OK, Save and Save again in the Actions list. Kalipso documentation How to Use Web Services 19

20 29. Test. 30. In the Trace Window click SQL to verify the imported data. 31. In the SQL Trace Window Double-Click the Countries Table to generate a Query automatically. 32. Press Execute to reveal the data. Kalipso documentation How to Use Web Services 20

21 33. Exit the application. 34. In the Form events add a DELETE statement when the Form Opens to always start the application without data. Now to display the data we can drag from the table in the Project Tree to the Form to automatically Create a Table control. Kalipso documentation How to Use Web Services 21

22 35. Drag the Countries Table to the Form and select Create a Table Control. 36. Select the Columns Name and Capital. Kalipso documentation How to Use Web Services 22

23 37. Press Done and adjust the table dimensions. 38. Now in the Open Form event add the Refresh Control action. 39. Test the Application. Kalipso documentation How to Use Web Services 23

24 3.2. RESTful The API used for this example is "api.openweathermap.org". this will allow to obtain a list of weather data for several countries. For more information about the Open Weather Map please visit the following website: This will allow the user to obtain its own API key to use in the example. 1. Create a new Form. Kalipso documentation How to Use Web Services 24

25 Configure the Left Arrow to close the Form. 2. In the button Click event add the Close Form action. 3. Rename the Title Label. Kalipso documentation How to Use Web Services 25

26 4. In the Open Form event define the API key to be used with the Set Value Action. In order to perform the request, we need to obtain the City IDs and store then in a Local Database Table. 5. Double-Click the Database in the Project Tree. In the Local Profile add a new Table called cities. Kalipso documentation How to Use Web Services 26

27 With the following columns. In the API web site, its available a JSON file with that information Place the JSON File in the Files To Send Folder of the Project. Here is a sample of the city.list.json contents. [ { } ] "id": , "name": "Hurzuf", "country": "UA", "coord": { }, "lon": , "lat": ( ) Kalipso documentation How to Use Web Services 27

28 When the Form Opens we need to import the Json data to the Local Database Table. 7. In the Open Form event add the action JSON Import to Table with the source type as File, Since the Source file is in the Project folder, it can be accessed using the PFOLDER Keyword. The database table will be the one previously created (cities). Like in the following image. 8. In the Column List tab, right-click and select Add Item to add the id element. Kalipso documentation How to Use Web Services 28

29 9. Set id as the Item Name and, after enabling the Define Target Checkbox, select the id column. 10. Repeat the same process to the name and country items. Kalipso documentation How to Use Web Services 29

30 The city.list.json file contains an extensive list of cities, the import process will take some time. In order to prevent duplicating the process each time the application starts, we will perform a select query to evaluate if the cities table already has some records. 11. Add the SELECT action before the JSON Import to Table action. 12. Click the button to load the id Column. 13. Press OK and Save. Kalipso documentation How to Use Web Services 30

31 After que Select query is made, the number of returned records can be obtained by the RECORDCOUNT keyword. The keyword can be used as a condition to perform the Import action. 14. Add an IF statement to verify if RECORDCOUNT is Add a Combo Box. Kalipso documentation How to Use Web Services 31

32 In the Content tab, link the Control using SQL advanced to obtain the Country codes and press Save. This will allow to use the distinct function so that the country names don t be repeated. 16. Reposition and resize the Control. Kalipso documentation How to Use Web Services 32

33 In the Open Form event add the Refresh Control action to refresh the Combo Box contents. 17. Now to test, let s create a Menu Form to open both examples. And configure it as the First Form. 18. Rename the TITLE label to MENU and configure the left arrow to Close the Form. Kalipso documentation How to Use Web Services 33

34 From the Project Tree drag the FormCountries and FormWeather to the Menu form. This will automatically create Text Buttons to open those Forms. 19. Resize and reposition the Buttons. 20. Test the new Form. Kalipso documentation How to Use Web Services 34

35 When selecting a Country ID we need to generate a list with the city IDs to send along in the request. 21. In the Combo Box Selection Change event, add a For Each action and select Browse the result of a Select Statement. 22. Click Next. 23. And in the SELECT press the button, select the id Column from the cities local table and press OK. 24. Press OK and edit the line by double-clicking the id line. Kalipso documentation How to Use Web Services 35

36 25. Select a variable to store the id returned. 26. In the Where tab, add the sentence FIELD(cities,country)= CTRL(ComboCountry). 27. Press Save. Kalipso documentation How to Use Web Services 36

37 In the For Each loop we are going to generate an array with all the city ids returned. This array will be used as a parameter when performing the request to the webservice. 28. Add the action Set Value with the following expression. Now we need to remove the first comma (, ) from the variable. 29. Add the action Set Value to save the tvidlist length-1. Kalipso documentation How to Use Web Services 37

38 30. And extract the first character (, ) from the list using the Right() Function. 31. Test. Now we can make an Http Request using the Id list. Kalipso documentation How to Use Web Services 38

39 32. In the Selection Change event of the Combo Box, add the HTTP Request action and set the Answer Body target to a variable in the General tab 33. In the Details tab use "api.openweathermap.org" as the server. in the object we need to call the API for several IDs In the API website an example is listed: Kalipso documentation How to Use Web Services 39

40 34. We also need to include the API Key, so in our case we should use: "/data/2.5/group?id=" + TVAR(tvIdList) + "&units=metric&appid=" + VAR(WeatherAPIKey) Where TVAR(tvIdList) has the IDs list and VAR(WeatherAPIKey) the API key. 35. Test to see the Answer. Kalipso documentation How to Use Web Services 40

41 Here s a sample of the JSON returned: This JSON contains an array ( list ) with an element for each ID requested with the weather details as sub elements. To store the returned data, we need to create a Local Database Table. 36. Double-click the Database Icon in the device tree and create a table called weather. Kalipso documentation How to Use Web Services 41

42 37. Add the following Columns. 38. In the ComboBox Selection Change event, add the action DELETE to clean the table every time a new country is selected. Kalipso documentation How to Use Web Services 42

43 39. Add the JSON Import to Table action to import the items from the variable to the weather table. 40. In the Column List set the Array/Item Name to list and add the sys, weather and main without a target. Kalipso documentation How to Use Web Services 43

44 Add the item name and define its target to the name Column. 41. Right-click the sys Item and select Add Sub Item to Current/Previous Table. Kalipso documentation How to Use Web Services 44

45 42. Set the Item Name to country and define the target to the country Column. 43. Add the sub Item description to the weather Item. Kalipso documentation How to Use Web Services 45

46 44. Add the Sub Items temp and humidity to the main Item. 45. Test. Kalipso documentation How to Use Web Services 46

47 46. Now drag the weather table from the Project Tree to the Form and select Create a Table Control. 47. Select maintemp, name and weatherdesc. Kalipso documentation How to Use Web Services 47

48 48. Adjust the Table Control size and position. And finally, in the Combo Box Selection Change event add the Refresh Control action to display the data in the Table Control. 49. Test. NOTE: Due to the API key used (free) the requests can only contain up to 20 IDs. If we select a country containing more than 20 IDs, the request will return an error, since this is only available as a paid feature. As a workaround, we can change the For Each action to perform the SQL query in Advanced mode and limit the results to 20 ids. Kalipso documentation How to Use Web Services 48

49 50. In the Combo Box Selection Change event, edit the For Each action. 51. Press the Previous button and change to the option to Browse the Result of a SQL Advanced. 52. Select Offline Mode and press Next. Kalipso documentation How to Use Web Services 49

50 53. In the SQL add the Sentence: "select id from cities where Country = '" + CTRL(ComboCountry) + "' limit 20" 54. Click Next and set a Target to the same variable used earlier. 55. Press Ok and Save. Kalipso documentation How to Use Web Services 50

51 56. Test. Kalipso documentation How to Use Web Services 51