Web Service Configuration for Fetching Data using the GET Method

The groupkt.com Website (http://services.groupkt.com/state) offers a Web service called State to get and search states and territories of a country. This type of Web service is simple and uses the GET HTTP method. This URL does not allow data to be posted.

To configure the Web service, perform the following steps:

1. In Sigma Studio, click Connections on the left pane.
   The connections created will be available in the Connections List on the right pane.
   
   
   
   
2. Right-click the Web service connection of your choice, e.g. WSCONNECTION and select Manage Data Sources.
   
   
   
   
3. In the Manage Data Sources window, click Create Data Source.
   
   
   The Create New Data Source screen displays.
   
   
   
   
4. In the Create New Data Source screen, configure the property fields in the Mandatory Configuration tab as follows:
   1. Connection Name: This is a non-editable field and displays the unique name provided by you for the connection. For example, WSCONNECTION.
   2. Data Source Name: Provide a unique data source name. For example, WEBSERVICEGROUPKT.

   3. Relative part of the URL: Provide the relative URL. For example,

      state/search/#getPathFilter({'id':'country'})#?text=#getPathFilter({'id':'name'})#

      
      
      In the case of http://services.groupkt.com/state/get/IND/all URL, http://services.groupkt.com/ is the base URL (domain name) and /state/get/IND/all are the relative part of the URL. Here, state is the Web service, which based on the parameters specified returns all the states within India as shown in the following screen shot:
      
      
      
      Extracting specific data from the Web service
      If the http://services.groupkt.com/state/get/IND/all URL is given, all the states of India will be listed. If you want to query the data and list all the states which have the text 'Ma' in the state name, the http://services.groupkt.com/state/search/IND?text=Ma URL can be used. Here, 'IND' is the path param and '?text=Ma' is the query. However, there is one drawback if we provide the query directly in the Relative part of the URL field. If you want to use the same Web service data source for another view and display different data, you will have to modify the data source. However, if the data source is modified, the app view which is already using the data source will get impacted.
      
      Therefore, to make the filtering process more dynamic and to support runtime filters, Canvas provides you the getPathFilter() method for specifying the JSON path and query param in the Relative Part of the URL field as follows:

      The query param concept applies only to Web services using the GET HTTP method.

      state/search/#getPathFilter({'id':'country'})#?text=#getPathFilter({'id':'name'})#

      Here, id is the JSON field name in which the actual field name is sent. In our Web service example, country (IND – path param) and name (text - query) are two variables which are being passed from the client code. These variables must be passed in the config of the CWEC.EXTRA_PARAMS_HDLR function attached to the app.
      
      The CWEC.EXTRA_PARAMS_HDLR function must be registered in the CWEH registry in any JavaScript file. Sample code is as follows:
      

      CWEH.registerHandler('STATES_LIST', CWEC.EXTRA_PARAMS_HDLR, function(config) 
      {
      	config['country']="IND";
      	config['name']="Ma";
      	return config;
      }); 
      
      /* Note: If you are using the getPathFilter() method, you must ensure to pass the variables 
      * as extra parameters in the CWEC.EXTRA_PARAMS_HDLR. This is to ensure that the app loads with 
      * data when you access it. If the runtime filters are enabled for the variables, you can filter 
      * the app data at runtime as per your need. Canvas will check if the variables are available in 
      * the runtime filters, if not, the data will be fetched from the extra parameters configured in 
      * the CWEC.EXTRA_PARAMS_HDLR.
      *
      * To enable runtime filters in the app for the country and name variables, you must map these 
      * variables in the Response data Mapping panel in the Create New Datasource page. Also, enable 
      * the filtering option for country and name while creating the app using App Designer.
      *
      * If you want to use the values present in the other predefined objects like request, session etc. 
      * the 'level' keyword can be used to indicate the object from which the data must be fetched.
      * For example, getPathFilter{'id':'name','level':'request'}.
      */

      
      Apart from the level keyword, Canvas has a list of reserved keywords whose purpose have been defined in the Canvas Reserved Keywords and Predefined Objects.

      The getPathFilter() method and other methods to configure the Web services are specified in the com.intellectdesign.canvas.defaultviews.DefaultRestServiceInstruction.Java file. You can extend the DefaultRestServiceInstruction Java class and use your own methods or you can use the updateAndFilter() method provided in the Java class to modify the parsed path filter data.

   4. Communication App ID: The Rest GET JSON Gateway option is auto-populated by default in this field. For more information on this field, refer the Field Descriptions.
   5. In the Response Data Mapping panel, provide inputs in the fields as follows:
      1. Column Root: Provide the hierarchical path to the element that contains the JSON array of data from the Web service response. For example, $.RestResponse.result will be the root element for the State Web service.
      2. Value Select Expression: For the State Web service, the value select expression will be country, name, area, and so on. Each value select expression that you want from the web service to be displayed in the app must be configured here individually.
         
         The following screen shot shows the root element and the value select expression with respect to the State Web service.
         
         
         
         

      3. View Column Id: Provide the column name for each of the value select expressions of the web service that you want to display in the app. For example, country, name, etc. can be the column names for the value select expressions.

         • Same column name must be provided in the Column ID field in App Designer page.
         • If the View Column Id is changed for any Value Select Expression in the data source screen later, those columns must be re-mapped in the App Designer page to reflect the changes.
      4. Click to add more columns.
         
         

   6. In the Request JSON Configuration field, provide the inputs as follows:

      Refer Passing Data as a View Specific Filter to Web Service to get more information on sending view specific filters as parameters to a web service.
      Refer Passing Data as Header Parameter in Request to get more information on sending data as header parameter to the request.
      You can ignore the Request JSON Configuration field if the Relative part of the URL field contains the query param along with the path param:

      state/search/#getPathFilter({'id':'country'})#?text=#getPathFilter({'id':'name'})# 

      If the Relative part of the URL field contains only the path param such as state/search/#getPathFilter({'id':'country'})# the query param must be given in the Request JSON Configuration field as shown in the following screen shot:

      {
      	'request': '?text=#getPathFilter({'id':'name'})#'
      }

      
      Here, request is the key and ?text=#getPathFilter({'id':'name'})# is the text.
      
      
      
      Following is the screen shot of the Request JSON Configuration field after providing the JSON:
      
      
      
      When you hover over the confirmed JSON, the following icons can display:
      
      : To enable or disable a field in the JSON.
      
      : To add a field in the JSON.
      
      : To delete the JSON from the Request JSON Configuration field.
      
      If you want to add an additional query, let us say you want to also fetch the largest city in India along with the state names containing 'ma' text, you can provide the following query param in the Request JSON Configuration field as shown in the recent screen shot:

      {'request': '?text=#getPathFilter({'id':'name'})#&text2=#getPathFilter({'id':'largest city'})#'} 

      
      Here, request is the key and ?text=#getPathFilter({'id':'name'})#&text2=#getPathFilter({'id':'largest city'})#'} is the text.
      
      

5. In the Create New Data Source page, configure the property fields in the Additional Configuration tab as follows:

   1. Service Type: The field is auto-populated with the GET option when the Rest GET JSON Gateway option is selected in the Communication App ID field. The State Web service is simple and uses the GET HTTP method. Therefore, retain this option. For more information on this field, refer the Field Descriptions.

   2. Instruction Class: This field is auto-populated with the default Java instruction class com.intellectdesign.canvas.defaultviews.DefaultRestServiceInstruction. For more information on this field, refer the Field Descriptions.

      • The query param concept applies only to Web services using the GET HTTP method. You have the option to provide the query param in the Relative part of the URL or the Request JSON Configuration field. However, the path param must be provided in the Relative part of the URL field only.
      • If the Relative part of the URL field contains the query param along with the path param, the Request JSON Configuration field is not required.
      • If the Relative part of the URL field contains only the path param, then the Request JSON Configuration field is mandatory.
      • Request JSON Configuration field is used when there are many variables to be passed on to the Web service.

6. Click Save.
   
   Once the data source is successfully created for the connection, the data source can be linked to View > App. For more information, refer /wiki/spaces/CTv21/pages/2160560157. The following screen shots are of the CountryStateList app in the Modelhouse application displaying data fetched from the State web service:
   
   
   
   We had enabled the filtering option for country and name variables in the App designer page. The following screen shots show the run time filters available for Country and Name columns in the app.