From Bright Pattern Documentation
Jump to: navigation, search
(Undo revision 143737 by Marissa.hudson (talk))
Tag: Undo
Line 1: Line 1:
 +
<translate>
 +
 
= Fetch URL=
 
= Fetch URL=
  
−
The '''Fetch URL''' scenario block retrieves web content from a URL by using a specified method and parsing it into scenario variables.  
+
The '''Fetch URL''' scenario block retrieves web content, including JSON-formatted data, from a URL, using a specified method and parses it into scenario variables.  
  
 
{{Note | HTTP, HTTPS and basic authentication are supported.}}
 
{{Note | HTTP, HTTPS and basic authentication are supported.}}
Line 8: Line 10:
  
 
=== Conditional Exits ===
 
=== Conditional Exits ===
−
The Fetch URL block takes one of three conditional exits:
+
The Fetch URL block may take one of three conditional exits:
  
 
;Failed
 
;Failed
−
:The Failed conditional exit is taken if an error occurs during the HTTP method execution. See HTTP Response Codes below for details.
+
:The Failed conditional exit is taken if an error occurred during the HTTP method execution. See HTTP Response Codes below for details.
 
;No Data
 
;No Data
−
:The No Data conditional exit is executed if no data is returned in the HTTP response body.
+
:The No Data conditional exit is executed if no data is returned in the body of the HTTP response.
 
;Timeout
 
;Timeout
 
:The Timeout conditional exit executes when the processing time exceeds the value entered in the '''Request Timeout''' field.
 
:The Timeout conditional exit executes when the processing time exceeds the value entered in the '''Request Timeout''' field.
Line 29: Line 31:
 
! Request Type (HTTP Method)
 
! Request Type (HTTP Method)
 
! Content Type
 
! Content Type
 +
! Notes
 
|-
 
|-
 
| GET
 
| GET
−
|
+
| Application/json
−
* application/json
+
|
−
* application/x-www-form-urlencoded
 
−
* application/soap+xml; charset=utf-8
 
 
|-
 
|-
 
| POST
 
| POST
 
|  
 
|  
−
* application/json  
+
* Application/json  
−
* application/x-www-form-urlencoded
+
* Multipart/form-data  
−
* application/soap+xml; charset=utf-8
+
* Single file upload, content-type set below
−
* multipart/form-data  
+
|
−
* <single file upload; content-type set below>
+
* Allows adding multiple attachment or text parts
 +
* Content type is optional. If not specified, the system uses the attachment’s content type
 +
 
 
|-
 
|-
 
| PUT
 
| PUT
 +
| Application/json
 
|  
 
|  
−
* application/json
 
−
* application/x-www-form-urlencoded
 
 
|-
 
|-
 
| PATCH
 
| PATCH
−
|
+
| Application/json
−
* application/json
 
−
* application/x-www-form-urlencoded
 
 
|  
 
|  
 
|-
 
|-
 
| DELETE
 
| DELETE
−
|
+
| Application/json
−
* application/json
 
−
* application/x-www-form-urlencoded
 
 
|  
 
|  
 
|}
 
|}
  
 
; URL to fetch
 
; URL to fetch
−
: The HTTP/HTTPS URL of the web resource that this block will access. Query string parameters, if any, should be specified in '''URL parameters'''. If parameters are defined, they will be appended to the URL. The '?' and '&' separators are automatically inserted.
+
: The HTTP/HTTPS URL of the web resource that this block will access. Query string parameters, if any, should be specified in the URL parameters (see below). If parameters are defined, they will be appended to the URL, and the '?' and '&' separators will be automatically inserted.
  
 
; Extra headers
 
; Extra headers
−
: The HTTP headers to add to the request, usually for authentication purposes. Functions can be used by inserting them as a value. Click '''add''' to define a header, then type in the ''name'' and ''value''.
+
: The HTTP headers to add to the request (e.g. for authentication purposes). Functions can be used by inserting them as a value. Click '''add''' to define a header, type in the ''name'', and type in the ''value''.
  
 
{{LightBulb | For example, a payment gateway may have a RESTful interface that requires authentication via “Authorization” header and SHA-256 hash of time, username, and password. To enable authentication, you would provide a request header with the ''name''  “Authorization” and the ''value'' ''“accessid hmac(“SHA-256”, key, message)”''.}}
 
{{LightBulb | For example, a payment gateway may have a RESTful interface that requires authentication via “Authorization” header and SHA-256 hash of time, username, and password. To enable authentication, you would provide a request header with the ''name''  “Authorization” and the ''value'' ''“accessid hmac(“SHA-256”, key, message)”''.}}
Line 77: Line 75:
  
 
; Content Type
 
; Content Type
−
: The type of data to be submitted in request body, or received in the response body.
+
: The type of data to be submitted in request body.
  
−
: Select ''application/json'' for a JSON data structure, ''application/x-www-form-urlencoded'' for URI-encoded data, or ''application/soap+xml; charset=utf-8'' for bodies formatted in XML.
+
: Select ''application/json'' for a JSON data structure, or select ''application/x-www-form-urlencoded'' for a URI-encoded data in the body of the message.
  
 
:{| class="wikitable"  
 
:{| class="wikitable"  
Line 87: Line 85:
 
! Notes
 
! Notes
 
|-
 
|-
−
| application/json
+
| Application/json
 
| GET, POST, PUT, PATCH, DELETE
 
| GET, POST, PUT, PATCH, DELETE
 
|  
 
|  
−
|-
 
−
| application/x-www-form-urlencoded
 
−
| GET, POST, PUT, PATCH, DELETE
 
−
|
 
−
|-
 
−
| application/soap+xml; charset=utf-8
 
−
| POST
 
−
|
 
 
|-
 
|-
 
| Multipart/form-data
 
| Multipart/form-data
Line 119: Line 109:
 
; Password
 
; Password
 
: The request authentication password. Variable substitutions are allowed.
 
: The request authentication password. Variable substitutions are allowed.
−
 
−
; Expected response body content is
 
−
: The expected format of the response body, with options for text, XML, and JSON.
 
  
 
; Initial path in the result JSON
 
; Initial path in the result JSON
−
: If the response body contains JSON, this setting can be used to save specific parts of the data into scenario variables. Example: ''myobject.node.list[4]''. The path starts from the root of the returned JSON.
+
: If the response body contains JSON, this setting can be used to save into scenario variables a specific part of the data. Example: ''myobject.node.list[4]''. The default is "none"; the path starts from the root of the returned JSON.
  
 
; Scenario variable prefix for JSON data
 
; Scenario variable prefix for JSON data
 
: This string will be used as the name of the variable to receive parsed JSON data. Note that if the initial path above points to an array, depending on the value of the ''GetNext'' option, this variable would either contain the array or its first (and subsequent) elements.
 
: This string will be used as the name of the variable to receive parsed JSON data. Note that if the initial path above points to an array, depending on the value of the ''GetNext'' option, this variable would either contain the array or its first (and subsequent) elements.
−
 
−
; Extract variables
 
−
: If the response body contains XML, this setting saves specific data into scenario variables organized by XPath and recordset name. These variables are dynamically listed in the following format: ''XPath : recordset''.
 
−
:
 
−
: Example: ''/response/receipt/ReceiptID: receiptID''
 
−
 
  
 
; Request timeout
 
; Request timeout
−
: This option allows sets a timeout for situations when processing external web service APIs run longer than expected, enabling the system to move to the next block if there is no API response within the time configured. The range for this field is between 2 and 100 seconds; when left blank, the time is set to 100 seconds. Note that this field is present only if an explicit value is entered.
+
: This option allows sets a timeout for situations when processing external web service APIs run longer than expected, enabling the system to move to the next block if there is no API response within the time configured. The range for this field is between 2 and 100 seconds; when left blank, the set time defaults to 100 seconds. Note that this field is present only if an explicit value is entered.
  
 
; Use GetNext block to loop through data
 
; Use GetNext block to loop through data
Line 149: Line 130:
 
=== Response Data Handling ===
 
=== Response Data Handling ===
  
−
The size of response data is limited to 100 KB across all content types.
+
In all cases, the response data is limited to 50 KB.
  
 
If the response data is not JSON-encoded, it could be accessed as string via the ''$(integrationResultBody)'' scenario variable described below.
 
If the response data is not JSON-encoded, it could be accessed as string via the ''$(integrationResultBody)'' scenario variable described below.
Line 168: Line 149:
 
* combinations (e.g., ''item.subitem.array[index].value.array[attr=x].value'')
 
* combinations (e.g., ''item.subitem.array[index].value.array[attr=x].value'')
  
−
 
−
If the response data is in XML format, the name of a recordset is set depending on what XPath is pointing to.
 
−
The recordset name will be a variable set to the value from XPath if XPath points to a value; if XPath points to a node, the recordset's value will be <recordset>.<attributename> for each of the node's attributes, and <recordset>.<childnodename> for each child node that doesn't contain subchildren.
 
−
If a child node shares the same name as an attribute, the resulting recordset will contain the value from the child node.
 
−
 
−
If the XML response data is successfully parsed, XPaths are applied and recordsets are set accordingly. If an XPath doesn't match a recordset, the recordset will be set to an empty string. An XPath that matches and returns an array of values allows use of `GetNext` to retrieve the next value.
 
  
 
=== Fetch URL Result Code Based On HTTP Response Codes ===
 
=== Fetch URL Result Code Based On HTTP Response Codes ===
Line 209: Line 184:
 
* 305 Use Proxy (since HTTP/1.1)
 
* 305 Use Proxy (since HTTP/1.1)
 
* 306 Switch Proxy
 
* 306 Switch Proxy
 +
 +
 +
</translate>

Revision as of 19:21, 2 April 2024

• 5.19 • 5.3 • 5.8

<translate>

Fetch URL

The Fetch URL scenario block retrieves web content, including JSON-formatted data, from a URL, using a specified method and parses it into scenario variables.


Info.40x40.png HTTP, HTTPS and basic authentication are supported.


The Fetch URL scenario block.

Conditional Exits

The Fetch URL block may take one of three conditional exits:

Failed
The Failed conditional exit is taken if an error occurred during the HTTP method execution. See HTTP Response Codes below for details.
No Data
The No Data conditional exit is executed if no data is returned in the body of the HTTP response.
Timeout
The Timeout conditional exit executes when the processing time exceeds the value entered in the Request Timeout field.

Settings

Title text
The name of the instance of the block displayed in the flowchart.
Request type
The HTTP method used in the fetch.
Request Type (HTTP Method) Content Type Notes
GET Application/json
POST
  • Application/json
  • Multipart/form-data
  • Single file upload, content-type set below
  • Allows adding multiple attachment or text parts
  • Content type is optional. If not specified, the system uses the attachment’s content type
PUT Application/json
PATCH Application/json
DELETE Application/json
URL to fetch
The HTTP/HTTPS URL of the web resource that this block will access. Query string parameters, if any, should be specified in the URL parameters (see below). If parameters are defined, they will be appended to the URL, and the '?' and '&' separators will be automatically inserted.
Extra headers
The HTTP headers to add to the request (e.g. for authentication purposes). Functions can be used by inserting them as a value. Click add to define a header, type in the name, and type in the value.


Bulb-on.50x50.png For example, a payment gateway may have a RESTful interface that requires authentication via “Authorization” header and SHA-256 hash of time, username, and password. To enable authentication, you would provide a request header with the name “Authorization” and the value “accessid hmac(“SHA-256”, key, message)”.



For more information about Scenario Builder functions, see Built-in Functions.
URL parameters
The parameters to be URL encoded and appended to the URL. Scenario variables can be used by inserting them as $(varname). Click add to define URL parameters, type in the name, and type in the value.
Content Type
The type of data to be submitted in request body.
Select application/json for a JSON data structure, or select application/x-www-form-urlencoded for a URI-encoded data in the body of the message.
Content Type Request Type (HTTP Method) Notes
Application/json GET, POST, PUT, PATCH, DELETE
Multipart/form-data POST Allows adding multiple attachment or text parts
Single file upload, content-type set below POST Content type is optional. If not specified, the system uses the attachment’s content type.
Body
This property is displayed when the Content Type is set to application/json and specifies the data to be transmitted with the given request in JSON format. Scenario variable substitutions are allowed.
Form parameters
This property is displayed when the Content Type is set to application/x-www-form-urlencoded and is used to specify the data to be transmitted with the given request as a URL-encoded key/value string. To define each parameter, click add, type in the parameter name, and set the value. Scenario variable substitutions are allowed.
Username
The request authentication username. Variable substitutions are allowed.
Password
The request authentication password. Variable substitutions are allowed.
Initial path in the result JSON
If the response body contains JSON, this setting can be used to save into scenario variables a specific part of the data. Example: myobject.node.list[4]. The default is "none"; the path starts from the root of the returned JSON.
Scenario variable prefix for JSON data
This string will be used as the name of the variable to receive parsed JSON data. Note that if the initial path above points to an array, depending on the value of the GetNext option, this variable would either contain the array or its first (and subsequent) elements.
Request timeout
This option allows sets a timeout for situations when processing external web service APIs run longer than expected, enabling the system to move to the next block if there is no API response within the time configured. The range for this field is between 2 and 100 seconds; when left blank, the set time defaults to 100 seconds. Note that this field is present only if an explicit value is entered.
Use GetNext block to loop through data
This box is selected if the JSON response data (at the initial path) is an array. The scenario variable will be set to the first element of the array and GetNext block could be used to iterate over the array elements, setting scenario variable to the next element.


Info.40x40.png If GetNext is enabled, the behavior of the Fetch URL block will be the same as it was for Bright Pattern Contact Center version 3.13 and earlier.



Fetch URL scenario block settings


Response Data Handling

In all cases, the response data is limited to 50 KB.

If the response data is not JSON-encoded, it could be accessed as string via the $(integrationResultBody) scenario variable described below.

If the response data is JSON, the following will happen:

  1. It will be parsed.
  2. If the "GetNext" option is enabled and the item the initial path is pointing to is a regular, non-associative array:
    1. The scenario variable will be set to the first item of the array.
    2. The GetNext block could be used to initialize the variable to the next and subsequent items.
  3. Otherwise, the scenario variable will be set to the item to which the initial path is pointing.


Possible syntax for the initial path setting and the access to the data saved in the scenario variable is as follows:

  • item. Subitem
  • item[index]
  • item[attr1=value].attr2
  • combinations (e.g., item.subitem.array[index].value.array[attr=x].value)


Fetch URL Result Code Based On HTTP Response Codes

The status code and the body of the received HTTP response will be stored in local variables $(integrationResultCode) and $(integrationResultBody), respectively. For troubleshooting purposes, you may use the EMail or Internal Message block to obtain content of responses indicating a failed attempt. For more information, see the description of variable $(integrationResultBody).

For backward compatibility reasons, the code and the body of the received HTTP response are also stored in local variables $(fetchURLResultCode) and $(fetchURLResultBody).

The possible values of the $(fetchURLResultCode) variable are as follows:

  • 0: 200 OK response (i.e., a successful HTTP request response)
  • -1: 200 OK response, but unable to parse the body into recordset
  • -2: 200 OK response, but body length exceeds 50 KB
  • -3: Unable to connect to HTTP server or other connection errors
  • -4: Incorrect JSON syntax in the request body when using PUT or POST requests
  • Other: Actual non-200 HTTP response code, such as 400 or 500

Note: When responding with error codes like 500, some servers will not provide any extra information. If there is extra info, it is passed as a plain string to the scenario. From this point, you may check the specific web server for reported errors (if any) or use regex to extract details from the response body.


HTTP Redirect Response Handling

The Fetch URL block handles 3xx Hypertext Transfer Protocol (HTTP) response codes in the following way.

When the following codes are received, the block retries the request to the provided redirect URL using the GET request method:

  • 301 Moved Permanently
  • 302 Found
  • 303 See Other (since HTTP/1.1)

When the following codes are received, the block retries the request to the provided redirect URL using the originally specified request method:

  • 307 Temporary Redirect (since HTTP/1.1)
  • 308 Permanent Redirect (RFC 7538)

When the following status codes are received, the conditional exit Failed will be selected:

  • 300 Multiple Choices
  • 304 Not Modified (RFC 7232)
  • 305 Use Proxy (since HTTP/1.1)
  • 306 Switch Proxy


</translate>

< Previous | Next >
Retrieved from "https://help.brightpattern.com/index.php?title=5.19:Scenario-builder-reference-guide/ScenarioBlocks/FetchURL&oldid=143751"