1.3.11.5 Call External Web Service

The Call External Web Service processor calls any REST web services that can be reached over standard HTTP/HTTPS connections from the EDQ server, using the processor configuration information, input data, and payload structure (that you provide) and parses the results to the output attributes of this processor. You can use it as a standalone processor, or in conjunction with other processors. For example - Calling Oracle SaaS applications REST web services to get, insert or update data.

The following table describes the configuration options for Call External Web Service processor :

Configuration	Description
Input Attributes	Input attributes can be String, Number, String Array, or Number Array. You can use these attribute values in the request payload, and/or substitute them in to the web service URL, or HTTP headers (from the Advanced tab). Note: You must specify at least one input attribute to work with the processor.
Output Attributes	There are two types of output attributes. They are: Fixed Output Attributes - These attributes are present by default in the processor and cannot be deleted. The fixed output attributes are: HTTP Response Code -The HTTP response code received from the web service such as 200, 400, and so on. HTTP Response Message - The standard HTTP response received, if the processor is not able to call the configured web service. Web Service Error Message - The web service specific error message, received when the web service call made by processor fails. Dynamic Output Attributes - These output attributes are configured in the processor, and their values are created by parsing the response from the web service. For more details refer to the Response tab.
Options	The following options are available in the Options tab: Method - Select the type of method through which you wish to process your request from this drop down menu. You can select from the following options: GET POST PUT DELETE PATCH POST method is selected by default. URL - The URL of the web service. You can use substitution syntax to specify input attribute values as part of the URL. For example, http://URL/abc?ProductId=${Id}, here Id is the input attribute and at run time ${Id} gets substituted with input attribute Id's value. Mutlirecord Request/Response - When you set this option to Yes, you can submit multiple records and get multiple responses. By default this option is set to No. Note: This option is enabled only for POST, PUT and PATCH methods. If you set Multirecord Request/Response option to Yes, the web service you are calling must support the multirecord requests and responses. Batch Records - Note: Batch Records option is enabled only when Multirecord Request/Response option is set to Yes. It specifies the number of records that are sent per web service call. By default this option is set to 50. Is Authentication Required - This option helps you to use basic authentication for the web service. By default this options is set to No. If you set this option to Yes, then the below User Name and Password fields are enabled. User Name - This option allows you to enter the user name for the above selected web service authentication field. Password - This option specifies the password for the above specified user account, used for web service authentication.
Request	The Request tab constitutes the request payload. Its values greatly vary based on the configuration that you perform on the Options tab. It has the following components: Selected Attributes - This text box displays all the selected input attributes. When you set the method to GET or DELETE, Multirecord Request/ Response and JSON Payload Structure options are disabled. When you set the method to POST or PUT or PATCH and Multirecord Request/ Response option to No in the Options tab, the following option appears: JSON Payload Structure - This option allows you to enter the payload structure. For Example - To submit input attribute values as part of the JSON payload of a POST or PUT or PATCH request, use the syntax ${InputAttributeName} within a valid JSON message structure. Note that Number values in JSON do not require quotation marks, but String values do. So for example, use the following syntax to submit an Id attribute of a Number type, and a Name attribute of a String type:{ "Id" : ${Id}, "Name" : "${Name}" } When you set the method to POST or PUT or PATCH and Multirecord Request/ Response option to Yes in the Options tab, the following options appear: JSON Message Structure - This option allows you to configure the message structure for your payload option. Note: If this is left blank, the request payload will be a simple array of records constructed according to the Record Structure option. Otherwise you can specify an outer part of the message and use $records$ to substitute in this array of records. This uses a mandatory template $records$, which is replaced by JSON Record Structure at run time. JSON Record Structure - This option allows you to configure specific information in the payload. You can use the template ${InputSelection} for selected inputs, which can be used in the payload to pass the input values at run time. For Example - { "Id" : ${Id}, "Name" : "${Name}" } Click Generate Example Payload button, to get a sample configuration for this option. For example, With JSON Message Structure: JSON Message Structure - {"ProductName":"edq","Record":$records$} JSON Record Structure - {"ID":${id},"Name":"${Name}"} Batch Records - 3 Actual Request Payload (which is sent to web service ) - {"ProductName":"edq","Record":[ {"ID":1,"Name":"name1"},{"ID":2,"Name":"name2"},{"ID":3,"Name":"name3"}]} When JSON Message Structure is left blank: JSON Message Structure - <left blank> JSON Record Structure - {"ID":${id},"Name":"${Name}"} Batch Records - 3 Actual Request Payload (which is sent to web service ) - [ {"ID":1,"Name":"name1"},{"ID":2,"Name":"name2"},{"ID":3,"Name":"name3"}]
Response	The Response tab helps you to create output attributes from the web service response. It will read the desired value from the response payload as per the configuration while creating the attributes. It constitutes the following three attributes. They are: Name - Name of the created output attribute. Type - Data type of the created output attribute. It can be String, Number, String Array or Number Array. Payload Variable - This option denotes the output attribute path in the response payload. You can create any number of output attributes as per the web service's response payload structure. To create an attribute, click the Add icon present at the left bottom corner of the Response tab. Add Attribute dialog appears, allowing you to type-in the Attribute Name, select the Type (String, String Array, Number or Number Array), enter the Payload Variable name, and select the Level (Record or Message). Note: The Level option is enabled/displayed only when you set method to POST or PUT or PATCH Multirecord Request/ Response option to Yes, in the Options tab. An output attribute with the Level set to Message will have the same value for all records. Here are examples of level and payload selection attribute types. Example of Level Selection For Response Payload { "status":"ok","records":[{"Name":"John","Id":1},{"Name":"Michael","Id":12}] }, Level of output status is Message and Level of output Name is Record. Example of Payload Selection For Response Payload{"productname":"edq","details":{"type":1,"build":{"number":3,"version":"2.1.0"}}}, productname is productname type is details.type number is details.build.number The Payload Variable name should be same as the name specified in your actual payload. Record Path - This option denotes the path of the records in a mutlirecord web service response. Note: This option is enabled/displayed only when you set: method to POST or PUT or PATCH Multirecord Request/ Response option to Yes, in the Options tab. For Example - The Record Path option is left blank, if the response is an array for records, for example-[{"Name":"John","Id":1},{"Name":"Michael","Id":12}] For the response { "status":"ok","records":[{"Name":"John","Id":1},{"Name":"Michael","Id":12}] }, Record Path = records For the response {"status":"ok","data":{"type":1,"emprecords":[{"Name":"John","Id":1},{"Name":"Michael","Id":12}]} }, Record Path = data.emprecords
Advanced	The Advanced tab allows you to configure the following options: Use Proxy - Set this option to Yes, if you wish to configure proxy settings. By default it is set to No. When you set this option to Yes, the following fields are enabled: Host Name - Name of your proxy server. Port - Port number of your proxy server through which it can listen to the requests. Proxy Requires Authentication - Set this option to Yes, if you wish to enable proxy authentication. User Name - Name of the proxy user Password -Password for the above configured proxy user account Timeout - This option allows you to set the Timeout value in milliseconds. When EDQ is waiting for any given web service response and if this configured timeout period is exceeded, the response will return a timeout error. By default this option is set to 120000 milliseconds. HTTP Header - This option allows you to configure the HTTP Header information for your request. Click the Add icon, to add a Name and Value for the header or you can map selected input attribute in HTTP value in the format ${ID} , where ID is an input attribute.

Some of the advanced features of Call External Web Service processor are:

• Array Support -

  • Input Attribute -
    1. This processor supports Number array and String array.
    2. Selected input array can be used in request payload as {"arr" : ${array}}, , where array is the name of selected input attribute.
  • Output Attribute - You can create output attribute of type string array and number array from the response tab.

  For example - {"arr" : ${array}}, {"arr" : ["a", "c\"d", null]}, {"arr" : [1,2,null, 3]}.

• Adding HTTP Header Information - You can define multiple HTTP headers. Selected Input attribute can be used to substitute the HTTP header value, in the format ${InputAttribute}. Refer to the Advanced tab section for more details.
• Adding Multiple Output Attributes - You can create multiple outputs to read the value from response payload. Refer to Response tab section for more details.

• Multirecord Handling - Multiple records can be send in a single request to the web service. This feature can be used only with the web service that supports multiple records in a request.

  There are two main use cases supported for this feature. They are:

  1. Multirecord web services where the whole payload is a structure containing multiple records.

     JSON Message Structure of Request tab should be left empty to handle this use case. Therefore the requested payload will be an array of records.

  2. Multirecord structures and additional attributes in the outer JSON structure.

     You need to use a special template $records$ in JSON Message Structure in request tab to handle this use case.

  For Example -

  JSON Message Structure : 
  
  {
     "company":"Oracle",
      "data_type":"product_info",
      "records":$records$
  }
  
  JSON Record Structure :
  
  {
      "product_id":${id},
      "product_name":"${name}"
  }
  
  

  The final request payload for the input data {(id=11,name=product1), (id=21,name=product2)} would be,

  {
     "company":"Oracle",
      "data_type":"product_info",
      "records": [{"id":11,"name":"product1"},{"id":21,"name":"product2"}]
  }

  Note:

  Id and name used in JSON record structure are the selected input attributes of the processor.

  Multirecord Specific Settings :

  • Option - Method Post , Multirecord Request/Response =Yes, Batch count ( Minimum value is 50 )
  • Request - JSON Message Structure and JSON Record Structure
  • Response -
    1. Create output as per the web service response payload structure ( See the above Response section for more details)
    2. Record Path - Path of records in response payload. It can be left blank if the response payload is an array of records.

    Note:

    Supports N:N request, where Response Payload must contain N records, for N records sent in Request Payload .
• Parameter Substitution in the URL - Selected input attributes can be used to substitute the parameter value in a web service URL.

  For Example - http:webservice.com?Product_id=${ID}, where ID is a selected input attribute.

Null Handling in Request Payloads

Attributes with null values are handled specially when substituted into request payloads. There are three cases:

1. If the attribute reference is not enclosed in quotes (for a number, boolean or array value), then the attribute is replaced with the JSON value null. For example - { "num" : ${numval} } becomes { "num" : null } after substitution if, the attribute numval is null.
2. If the attribute reference is the only content in a quoted value, then the quotes are removed and the replacement is the JSON value null. For example - { "str" : "${strval}" }becomes { "str" : null }after substitution if, the attribute strval is null.
3. If the attribute reference is not the only content in a quoted value, then the attribute replacement is the empty string. For example - { "str" : "abc${strval}def" }becomes { "str" : "abcdef" }after substitution if, the attribute strval is null.

Examples

1. In this example, Call External Web Service is used to fetch the company details of a campus. Campus name will be send as part of the web service URL and the response from the web service will constitute the company details operating from that specific campus.

   The configured options are:

   Configuration Options	Values
   Attribute	Selected Input Name - Campus Name Type - String
   Options	Method - GET URL - http://webservice.com/companyinfo?name=${Campus Name } Multirecord Request/Response - Disabled
   Request	JSON Payload Structure - Disabled
   Response	Response Payload Structure - { "Company": "Company Name", "Country”: "Country Code", "Departments":[{"id":DepartmentId,"Name":"DepartmentName"} ...] }
   Output Attributes	Name = Company Name Type = String Payload Variable = Company Name = Country Code Type = String Payload Variable = Country Name = Department List Type = String Array Payload Variable = Departments.Name Name = Department ID List Type = Number Array Payload Variable = Departments.Id

   Web service Request / Response with input:

   Input Attribute	URL	Response Payload
   Campus Name = Campus1	http://webservice.com/companyinfo?name=Campus1	{ "Company": "Oracle", "Country": "IN", "Departments":[{"id":101,"Name":"Department_1"},{"id":102,"Name":"Department_2"}, {"id":103,"Name":"Department_3"}] }

   Summary View:

   Campus Name	HTTP Response Code	HTTP Response Message	Web Service Error Message	Company Name	Country Code	Department List	Department ID List
   Campus1	200	OK	<Nil>	Oracle	IN	{Department_1}{Department_2} {Department_3}	{101}{102}{103}

2. In this example, Call External Web Service is used to get the details of cities in a state.

   The configured options are:

   Configuration Options	Values
   Attribute	Selected Input: Name = Country Type = String Name = State Type = String Name = Reference ID Type = Number
   Options	Method - POST URL - http://webservice.com/cityinfo Multirecord Request/Response - No
   Request	JSON Payload Structure { "CountryName" : "${Country}", "StateName" : "${State}", "RefId" : "${ReferenceId}" }
   Response	Response Payload Structure - { "CountryName" : "Name", "CountryCode" : "Code", "StateName" : "State Name", "StateData" : {"id":id,"CityDetails":{"Count":count,CityList:["City1","City2", . . . . . ]}} }
   Output Attributes	Name = City Count Type = Number Payload Variable = StateData.CityDetails.Count Name = City Name Type = String Array Payload Variable = StateData.CityDetails.CityList

   Web service Request / Response with input:

   Input Attribute	URL	Response Payload
   Country = Country_1 State = ST1 ReferenceID = 121	{ "CountryName" : "Country_1", "StateName" : "ST1", "RefId" : 121 }	{ "CountryName" : "Country_1", "CountryCode" : "CC", "StateName" : "ST1", "StateData" : {"id":221,"CityDetails":{"Count":21,CityList:["City1","City2","City3","City4"]}} }

   Summary View:

   Country	State	Reference ID	HTTP Response Code	HTTP Response Message	Web Service Error Message	City Count	City Name
   Country1	State1	11	200	OK	<Nil>	21	{City1}{City2}{City3}{City4}

3. In this example, Call External Web Service is used to get the list of customers using a product. This configuration allows you to send and receive multiple records in a single web service call. If N records are sent in a single request, then a valid response from the web service will also contain N records .

   The configured options are:

   Configuration Options	Values
   Attribute	Selected Input: Name = Product Name Type = String Name = Code Type = Number
   Options	Method - POST URL - http://webservice.com/multirecords Multirecord Request/Response - Yes Batch Record - 50
   Request	JSON Message Structure - { "Request Name" : "Product_Cus_List", "RefId" : 101, "Records" : $records$ } JSON Payload Structure - { "ProductName" : "${ProductName}", "Product Code" : ${ code } }
   Response	Response Payload Structure - { "Company" : "Company Name", "MetaData" : "Product Customer List", "Records" : [ {"ProductName" : "P1","Cus_List":["Cus1", "Cus2"]} . . . . . ] } Record Path - Records
   Attribute Options	Name = Company Type = String Payload Variable = Company Level = Message Name = Metadata Type = String Payload Variable = Metadata Level = Message Name = Product Type = String Payload Variable = productName Level = Record Name = Customers Type = String Array Payload Variable = Cus_List Level = Record

   Web service Request / Response (5:5):

   Input Attribute	Request Payload	Response Payload
   Product Name = Prod1 Code = 41 Product Name = Prod2 Code = 512 Product Name = Prod3 Code = 986 Product Name = Prod4 Code = 994 Product Name = Prod5 Code = 208	{ "Request Name" : "Product_Cus_List", "RefId" : 101, "Records" : [ { "ProductName " : "Prod1", "Product Code":41}, { "ProductName " : "Prod2", "Product Code":512}, { "ProductName " : "Prod3", "Product Code":986}, { "ProductName " : "Prod4", "Product Code":994}, { "ProductName " : "Prod5", "Product Code":208} ] }	{ "Company": "Comp1", "MetaData" : "Product Customer List", "Records" : [ {"ProductName" : "Prod1","Cus_List":["P1_Cus1", "P1_Cus2", "P1_Cus3"]} , {"ProductName" : "Prod2","Cus_List":["P2_Cus1", "P2_Cus2"]}, {"ProductName" : "Prod3","Cus_List":["P3_Cus1", "P3_Cus2", "P3_Cus3"]}, {"ProductName" : "Prod4","Cus_List":["P4_Cus1", "P4_Cus2", "P4_Cus3"]}, {"ProductName" : "Prod5","Cus_List":["P5_Cus1", "P5_Cus2", "P5_Cus3", "P5_Cus4"]} ] }

   Summary View:

   Product Name	Code	HTTP Response Code	HTTP Response Message	Web Service Error Message	Company Name	Metadata	Product	Customers
   Prod1	41	200	OK	<Nil>	Comp1	Product Customer List	Prod1	{P1_Cus1}{P1_Cus2}{P1_Cus3}
   Prod2	512	200	OK	<Nil>	Comp1	Product Customer List	Prod2	{P2_Cus1}{P2_Cus2}
   Prod3	986	200	OK	<Nil>	Comp1	Product Customer List	Prod3	{P3_Cus1}{P3_Cus2}{P3_Cus3}
   Prod4	994	200	OK	<Nil>	Comp1	Product Customer List	Prod4	{P4_Cus1}{P4_Cus2}{P4_Cus3}
   Prod5	208	200	OK	<Nil>	Comp1	Product Customer List	Prod5	{P5_Cus1}{P5_Cus2}{P5_Cus3}{P5_Cus4}