5.19:Workflow-builder-reference-guide/FetchURL

• 5.19 • 5.2 • 5.3 • 5.8

Fetch URL

Requests web content from a URL over HTTP/HTTPS using a GET, POST, PUT, PATCH, or DELETE and parses received data into workflow variables.

Workflow Builder FetchURL 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

Fetch URL workflow block settings

Title text

Title text is 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 application/x-www-form-urlencoded application/soap+xml; charset=utf-8
GET, POST	application/json application/x-www-form-urlencoded application/soap+xml; charset=utf-8 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 application/x-www-form-urlencoded
PATCH	application/json application/x-www-form-urlencoded
DELETE	application/json application/x-www-form-urlencoded

	Messenger integrations LINE and WhatsApp allow users to upload multiple attachments with the same name at the same time. Users should upload files one at a time with unique names as a best practice.

URL to fetch

URL to fetch is the HTTP/HTTPS URL of the web content to get. Query string parameters are specified separately.

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, then type in the name and value.

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 a value like bearer $(accessid) where 'accessid' is set to something like =hmac('SHA-256', '<key>', '<user>:<secret>').

Authenticating with an OAuth 2.0 endpoint typically follows a similar pattern; Once an access token is obtained (e.g. another Fetch URL block calls a token endpoint and saves the result to 'accessToken'), it can be passed into an Authorization header with value bearer $(accessTokenVariable).

For more information about Workflow Builder functions, see Built-in Functions.

URL parameters

Specify URL parameters here; they will be URL-encoded and appended to the request URL. Workflow 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 supported in the request.

Note that the content type drop-down contains the most common suggestions, and you can type your own content type value manually right over the drop-down box suggestion.

Content Type	Request Type (HTTP Method)	Notes
application/json	GET, POST, PUT, PATCH, DELETE
application/x-www-form-urlencoded	GET, POST, PUT, PATCH, DELETE
application/soap+xml	GET, POST
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

Body is the data to be submitted in the request body. The setting is displayed only if request type POST is selected. The format of the data must correspond to the Content Type above. Workflow variable substitutions are allowed.

Username

Username is the request authentication username. Variable substitutions are allowed.

Password

Password is the request authentication password. Variable substitutions are allowed.

Response body content is

The expected format of the response body, with options for text, XML, and JSON.

Initial path in the result JSON

If the response body contains JSON, this setting can be used to save into workflow variables a specific part of the data. Example: myobject.node.list[4]. The default value 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 Use GetNext block to loop through data option, this variable will either contain the full array or its first (and subsequent) elements. See Response data handling below for more information.

Use GetNext block to loop through data

Select this box 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 Get Next block could be used to iterate over the array elements, setting the variable to the next element.

	If you enable this option, the behavior of the Fetch URL block will be the same as it was for Bright Pattern Contact Center version 3.13 and earlier.

Extract variables

If the setting Response body content is indicates an XML response, the contents of Extract variables determines what specific data from the response should be parsed into scenario variables. Any number of XPath expressions with an associated variable name can be defined.

Each XPath expression is used to parse the XML response, and the result is saved in the corresponding variable. If the expression points to multiple values or a node with children, the Use GetNext block to loop through data option determines whether the variable will contain an array of values or only the first value. See Response data handling below for more information.

Response Data Handling

The size of response data is limited to 100 KB for any content type.

If the response data is not encoded as JSON or XML it can be accessed as a string via the $(integrationResultBody) scenario variable described in HTML response codes below.

JSON-Encoded Responses

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 workflow 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 workflow variable will be set to the item to which the initial path is pointing.

Syntax for the initial path setting and the access to the data saved in the workflow variable:

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

XML-Encoded Responses

If the response data is in XML format (and Response body content is indicates XML), each of the XPath expressions defined in Extract variables is used to parse the response and set the value of the associated variable as follows:

• If the XPath points to a specific value: The value is assigned to <variableName>
• If the XPath points to an XML node with children:
  • For each attribute of the node, the variable <variableName>.<attributeName> is assigned the value of the attribute
  • For each child node, the node value is assigned to <variableName>.<childNodeName>. This is applied recursively; if a child node has a child, its value will be assigned to <variableName>.<childNodeName>.<childOfChild>, and so on.
  • In case of a name collision between an attribute and a child node, the value from the child node is assigned and the attribute value is ignored.
• If an XPath does not point to anything in the response XML, the corresponding variable will be assigned to an empty string.
• If the XPath expression points to an array:
  • If Use GetNext block to loop through data is enabled, the variable will initially be assigned the first element of the array indicated by the XPath expression. The Get Next Record block can be used to iterate over the remaining values.
  • If Use GetNext block to loop through data is disabled, the variable will be assigned the full array of values, which can be referenced elsewhere in the scenario with $(<variableName>[index])

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, 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, 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 a variable (JSON-encoded or XML-encoded responses)
• -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 response code

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< Previous | Next >