DES/Current/Designer/HTTPREST - Revision history

Brian.marshall@genesys.com: Published

2021-11-18T01:32:31Z

Published

Brian.marshall@genesys.com: Published

2021-06-28T19:32:20Z

Published

Ed.jamer@genesys.com: Ed.jamer@genesys.com moved page PEC-ROU/Current/Designer/HTTPREST to DES/Current/Designer/HTTPREST: Text replacement - "PEC-ROU/Current/Designer/" to "DES/Current/Designer/"

2021-04-21T13:57:59Z

Ed.jamer@genesys.com moved page PEC-ROU/Current/Designer/HTTPREST to DES/Current/Designer/HTTPREST: Text replacement - "PEC-ROU/Current/Designer/" to "DES/Current/Designer/"

WikiSysop: Text replacement - "\|Platform=([^\|])GenesysEngage-onpremises([\|])" to "|Platform=$1GenesysEngage-cloud$2"

2020-07-25T02:33:43Z

Text replacement - "\|Platform=([^\|]*)GenesysEngage-onpremises([\|]*)" to "|Platform=$1GenesysEngage-cloud$2"

WikiSysop: Text replacement - "\|Platforms?=([^\|])PureEngage([\|])" to "|Platform=$1GenesysEngage-onpremises$2"

2020-07-15T11:44:57Z

Text replacement - "\|Platforms?=([^\|]*)PureEngage([\|]*)" to "|Platform=$1GenesysEngage-onpremises$2"

Bgrenon: Published

2020-06-08T15:21:25Z

Published

New page

{{Article
|Standalone=No
|DisplayName=HTTP REST Block
|TocName=HTTP REST Block
|Context=Use this block to access an external system using a RESTful API over HTTP.
|ComingSoon=No
|Platform=PureEngage
|Role=Administrator
|Application=Designer
|Section={{Section
|alignment=Vertical
|structuredtext=You can use the '''HTTP REST''' block for accessing external systems using a RESTful API, over HTTP. You can read or write to these web services, although routing applications typically read from web services.

You can read or write to any external system that houses and exposes data through a REST web service. This could be a generic web service, such as one that returns the weather forecast for a specific location, or one that converts a monetary value from one currency to another. Or this could be a company's internal web service that fetches a customer's account details and billing history from the company's internal databases.

This block can be used in all four phases of the application.

{{NoteFormat|
*Check that the RESTful API you are accessing will return data in the format that you expect. While most web services typically return JSON data, there are some that may not. You may want to use an external tool to test the RESTful API outside of Designer to ensure it behaves the way you expect, before attempting to access it within your application.
*If the request timeout period is reached and no response is received from the REST web service, the output variables have a value of '''undefined'''.|2}}
|Status=No
}}{{Section
|sectionHeading=Service Details tab
|anchor=ServiceDetailstab
|alignment=Vertical
|structuredtext=Enter the URL of the RESTful web service in the '''HTTP URL''' field. Enable the check box to use a variable, or disable the check box to use a string.

In the drop-down menu beside the '''HTTP URL''' field, select the HTTP method to access the web service: '''get''', '''post''', '''put''', or '''delete'''.

If you are using '''post''' or '''put''' as the HTTP method, select an '''Encoding Type'''. (Otherwise, you will not see this option.)

In the '''Request Timeout''' field, enter the time, in seconds, that the application waits for a response from the web service before moving on to the next block.

If you want to post the results of a recording captured by the {{Link-SomewhereInThisManual|topic=RecordUtterance|anchor=top|display text=Record Utterance}} block to the specified URL, you can specify the variable that holds a recorded file in the '''Upload Record Utterance''' field. (This option is only supported in the Self Service phase, as the recording file captured by the {{Link-SomewhereInThisManual|topic=RecordUtterance|anchor=top|display text=Record Utterance}} block is no longer available after the Self Service phase.)

Select '''Disable DTMF buffering''' if you want to prevent any DTMF inputs made during fetch audio playback from being buffered and carried forward into subsequent {{Link-SomewhereInThisManual|topic=UserInput|anchor=top|display text=User Input}} or {{Link-SomewhereInThisManual|topic=Menu|anchor=top|display text=Menu}} blocks.

Select '''Play fetch audio''' if you want to specify an audio resource to play to the caller while the data is fetched.

{{NoteFormat|Only Announcements containing audio files are supported. TTS audio will not be played.}}

<ul>
<li>Enable the check box beside the '''Play fetch audio''' check box to specify a variable.</li>
<li>In the '''Play fetch audio minimum for''' field, you can enter the minimum length of time to play the audio, even if the document arrives in the meantime.</li>
<li>In the '''Start fetch audio after''' field, you can enter a period of time to wait before audio is played.</li>
</ul>

{{NoteFormat|In the '''Self Service''' phase, fetch audio playback stops when the end of the audio file is reached, even if the fetch request is still in progress. In the '''Assisted Service''' phase, fetch audio playback loops until the request times out.}}

====Input Parameters====
In the '''Input Parameters''' tab, specify the inputs to the web service. You can choose either:
<ul>
<li>'''JSON Payload''' — Send a JSON value from a variable as an input to the web service. This option is applicable only for '''put''' and '''post''' methods.</li>
<li>'''Key Value pairs''' — Click '''Add Parameters''' and enter the '''Name''' of the parameter expected by the web service, and the '''Value''' to pass to the input. You can toggle the '''Value''' between a string and a variable.</li>
</ul>

====Output Parameters====
{{NoteFormat|You must only specify an output parameter if you are certain the web service will provide a consistent response. Otherwise, your application will generate an error if the web service provides a response that does not conform to what you have specified in the '''JSON Expression''' field (for example, a '''400''' error or a '''200''' code with no output).

If the web service will not provide a consistent response, you can select a variable in the '''Results''' tab in which to store the entire HTTP response. Next, use an {{Link-SomewhereInThisManual|topic=AssignVar|anchor=top|display text=Assign Variables block}} to check for specific properties in the response and, if these properties are present, specify a JSON expression to assign to the variable.}}

In the '''Output Parameters''' tab, click '''Add Parameters''' to specify how and where to store the results of the web service call. The '''Variable Name''' is the application variable in which to store the data, and the '''JSON Expression''' is the key in which you expect the result to be in the response object.

See the code sample and table below for an example:

<source lang="java">
{
"thing": {
"otherthing": "abc"
},
"arrayofthings": [
"thing1", "thing2"
]
}
</source>

{{{!}}
!'''JSON Expression'''
!'''Result'''
{{!}}-
{{!}}<tt>thing.otherthing</tt>
{{!}}'''abc'''
{{!}}-
{{!}}<tt>arrayofthings[1]</tt>
{{!}}'''thing2'''
{{!}}}

[[File:des_httprest_service.png|border|center]]
|Status=No
}}{{Section
|sectionHeading=Authentication tab
|anchor=Authenticationtab
|alignment=Vertical
|structuredtext=Enable the '''Enable Basic Authentication''' check box to use HTTP basic authentication as part of the web service request. When enabled, the '''User Name''' and '''Password''' fields are displayed. Optionally, click the check box to select a variable for either of these fields.
|Status=No
}}{{Section
|sectionHeading=Results tab
|anchor=Resultstab
|alignment=Vertical
|structuredtext=Select a variable to store the outcome status ('''true''' or '''false''') of the HTTP fetch.

You can also select variables in which to store the data and headers of the HTTP response, and the HTTP error code if the operation failed.

You must also select an action to take if the fetch operation is not successful. You can choose to "Continue with normal processing" or "Execute error handler blocks".

If you select "Execute error handler blocks", an '''Error Handler''' child block appears under the '''HTTP REST''' block.

Use the '''Error Handler''' block to send the application to another target block that you select from the '''Navigation''' tab, or add child blocks that will perform the actual error handling.

In this example, the '''Navigation''' tab is used to specify a target block. If there is an error, the application will go to the '''Play Message''' block and play an error message:

[[file:des_httprest_error_navigation.png]]

In this example, a child block is used to invoke a module that will perform the error handling:

[[file:des_httprest_error_child.png]]

{{NoteFormat|
* If you select a target block from the '''Navigation''' tab, then any child blocks you've added to the '''Error Handler''' parent block are ignored.
* Standard validation rules still apply — any child blocks that you add to the '''Error Handler''' block must be valid for the application phase in which they are being used.
|2}}
|Status=No
}}{{Section
|sectionHeading=Advanced tab
|anchor=Advancedtab
|alignment=Vertical
|structuredtext=The '''Use Designer service to make this request''' check box is enabled by default. This allows the fetch request to use a HTTP proxy, which is typically required when sending requests to external resources.

Select '''Internal Genesys Service''' if the application is sending a fetch request to an internal Genesys service. This type of request does not go through a HTTP proxy.

Click '''Add Header''' if you want to use a custom HTTP header.

{{NoteFormat|If this '''HTTP REST''' block is used in a '''Self Service''' phase or shared module, there might be a processing delay due to the use of a proxy to perform the HTTP fetch. This delay does not apply to '''HTTP REST''' blocks that are used in '''Assisted Service''' phases or shared modules.}}
|Status=No
}}{{Section
|sectionHeading=Test tab
|anchor=Testtab
|alignment=Vertical
|structuredtext=The '''Test''' tab lets you test an API call from the block without making an actual test call.

Select the variables to be used as Input Parameters (make sure you specify them in the requested format, using single quotes for strings and "()" for JSON values) and any other variables to be used.

If the variables had a default value set in the '''Initialize''' phase, you can choose to keep those values or provide your own. The application will remember the values used the next time you open the application.

{{NoteFormat|Any literal values stored in the block will also be used for the test request.}}

Click '''Send Test Request''' to run the test and generate the results.
|Status=No
}}{{Section
|sectionHeading=Scenarios
|anchor=Scenarios
|alignment=Vertical
|structuredtext=If you want to:

*Play weather information for a customer for whom you have a profile and address:
**This scenario assumes that the weather API expects two input parameters ('''date''' and '''location''') and provides its output in JSON format, under the key '''result'''. The corresponding input information is stored in two variables: '''currentdate''' and '''zipcode'''.
**Add the '''HTTP REST''' block to the '''Self Service''' portion of the application, in a position after you have retrieved the customer location.
**In the '''HTTP URL''' field, enter the URL of the weather web service (for example, <tt>http://sample.webservice.com/api/weather/</tt>).
**Select '''get''' as the HTTP method.
**In the '''Input Parameters''' tab, click '''Add Parameters''' twice.
**For the first parameter, use the following information:
***'''Name''': <tt>date</tt>
***'''Type''': <tt>variable</tt>
***'''Value''': <tt>currentdate</tt>
**For the second parameter, use the following information:
***'''Name''': <tt>location</tt>
***'''Type''': <tt>variable</tt>
***'''Value''': <tt>zipcode</tt>
**In the '''Output Parameters''' tab, click '''Add Parameters''' and use the following information:
***'''Variable Name''': <tt>weather</tt>
***'''JSON Expression''': <tt>result</tt>
|Status=No
}}
}}

@@ Line 32: / Line 32: @@
 In the '''Request Timeout''' field, enter the time, in seconds, that the application waits for a response from the web service before moving on to the next block.
-If you want to post the results of a recording captured by the {{Link-SomewhereInThisManual|topic=RecordUtterance|anchor=top|display text=Record Utterance}} block to the specified URL, you can specify the variable that holds a recorded file in the '''Upload Record Utterance''' field. (This option is only supported in the Self Service phase, as the recording file captured by the {{Link-SomewhereInThisManual|topic=RecordUtterance|anchor=top|display text=Record Utterance}} block is no longer available after the Self Service phase.)
+If you want to post the results of a recording captured by the {{Link-SomewhereInThisManual|topic=RecordUtterance|anchor=top|display text=Record Utterance}} block to the specified URL, you can specify the variable that holds a recorded file in the '''Upload Record Utterance''' field. (This option is only supported in the Self Service phase, as the recording file captured by the {{Link-SomewhereInThisManual|topic=RecordUtterance|anchor=top|display text=Record Utterance}} block is no longer available after the Self Service phase.) If you enable this option, you can use the '''Recording Handle Name''' option to select a file handle name to use for the audio file to be added to the upload request. If you don't make a selection, the default file handle name ('''recordfile''') is used.
 Select '''Disable DTMF buffering''' if you want to prevent any DTMF inputs made during fetch audio playback from being buffered and carried forward into subsequent {{Link-SomewhereInThisManual|topic=UserInput|anchor=top|display text=User Input}} or {{Link-SomewhereInThisManual|topic=Menu|anchor=top|display text=Menu}} blocks.

@@ Line 10: / Line 10: @@
 |Section={{Section
 |alignment=Vertical
-|structuredtext=You can use the '''HTTP REST''' block for accessing external systems using a RESTful API, over HTTP. You can read or write to these web services, although routing applications typically read from web services.
+|structuredtext=You can use the '''HTTP REST''' block for accessing external systems using a RESTful API, over HTTP. You can read or write to these web services, although routing applications typically read from web services. The block also supports HTTPS for web services that are using server-side authentication.
-You can read or write to any external system that houses and exposes data through a REST web service. This could be a generic web service, such as one that returns the weather forecast for a specific location, or one that converts a monetary value from one currency to another. Or this could be a company's internal web service that fetches a customer's account details and billing history from the company's internal databases.
+You can read or write to any external system that houses and exposes data through a REST web service. This could be a generic web service, such as one that returns the weather forecast for a specific location or converts a monetary value from one currency to another, or a company's internal web service that fetches a customer's account details and billing history from the company's internal databases.
 This block can be used in all four phases of the application.
@@ Line 24: / Line 24: @@
 |anchor=ServiceDetailstab
 |alignment=Vertical
-|structuredtext=Enter the URL of the RESTful web service in the '''HTTP URL''' field. Enable the check box to use a variable, or disable the check box to use a string.
+|structuredtext=Enter the URL of the RESTful web service in the '''HTTP URL''' field. Enable the check box to use a variable or disable the check box to use a string.
 In the drop-down menu beside the '''HTTP URL''' field, select the HTTP method to access the web service: '''get''', '''post''', '''put''', or '''delete'''.
@@ Line 86: / Line 86: @@
 {{!}}}
-[[File:des_httprest_service.png|border|center]]
+[[File:des_httprest_service.png]]
 |Status=No
 }}{{Section

← Older revision	Revision as of 13:57, April 21, 2021
(No difference)

@@ Line 5: / Line 5: @@
 |Context=Use this block to access an external system using a RESTful API over HTTP.
 |ComingSoon=No
-|Platform=GenesysEngage-onpremises
+|Platform=GenesysEngage-cloud
 |Role=Administrator
 |Application=Designer

DES/Current/Designer/HTTPREST - Revision history

Brian.marshall@genesys.com: Published

Brian.marshall@genesys.com: Published

Ed.jamer@genesys.com: Ed.jamer@genesys.com moved page PEC-ROU/Current/Designer/HTTPREST to DES/Current/Designer/HTTPREST: Text replacement - "PEC-ROU/Current/Designer/" to "DES/Current/Designer/"

WikiSysop: Text replacement - "\|Platform=([^\|]*)GenesysEngage-onpremises([\|]*)" to "|Platform=$1GenesysEngage-cloud$2"

WikiSysop: Text replacement - "\|Platforms?=([^\|]*)PureEngage([\|]*)" to "|Platform=$1GenesysEngage-onpremises$2"

Bgrenon: Published

WikiSysop: Text replacement - "\|Platform=([^\|])GenesysEngage-onpremises([\|])" to "|Platform=$1GenesysEngage-cloud$2"

WikiSysop: Text replacement - "\|Platforms?=([^\|])PureEngage([\|])" to "|Platform=$1GenesysEngage-onpremises$2"