This example demonstrates how to call a RESTful web service that returns JSON-formatted data for use in the Workflow. Note that Agent Guidance can only consume RESTful JSON-type APIs.

 

1) Select the Web Service datasource type:

 

 

2) Enter the root URL of the web service you wish to call. This can either be a static URL, or reference a Field or Variable containing a dynamic URL. If a Field or Variable are used, then a test URL must be provided:

Note: this can be provided as an Environment Variable, either via the picker or by manually typing.

 

 

3) If there are any query parameters to be appended to the endpoint URL, they can be added here:

Note: It is also possible to choose, if a parameter's value is blank, whether to simply pass on the blank value or instead omit (skip) the parameter.

Note: these values can be provided as Environment Variables, either via the picker or by manually typing.

 

In this example, the test service URL queried during configuration would be http://www.exampleapi.com/query?customerID=3

 

 

4) Select the timeout period for the query, and the HTTP Request method; the selected method will determine the other options displayed on this step and the subsequent steps. You can also specify where the HTTP response code and full response object (External Data Source only) should be mapped in the Workflow, if so desired, and which response status ranges will be counted as "failing" (preventing Column Mapping and Update Links, and triggering an error dialog for the agent):

 

 

5) If a Request Method was selected in the previous step that includes a body, then the body content can be specified here:

Note: It is also possible to choose, if a parameter's value is blank, whether to simply pass on the blank value, pass a null, or instead omit (skip) the parameter.

Note: The type determines the output data type in the body for that parameter. As all Agent Guidance values are internally held as strings, the provided value must be successfully convertible to the selected data type for each parameter.

Note: these values can be provided as Environment Variables, either via the picker or by manually typing.

 

 

6) The authentication method (if any) can be selected to easily configure the required header:

Note: it is possible to configure alternative authentication methods by directly specifying the header content in Step 6.

Note: these values can be provided as Environment Variables, either via the picker or by manually typing.

 

 

7) Header content can be manually specified for inclusion in the request:

Note: It is also possible to choose, if a parameter's value is blank, whether to simply pass on the blank value or instead omit (skip) the parameter.

Note: these values can be provided as Environment Variables, either via the picker or by manually typing.

 

 

8) A sample response is required; the data values are optional, but the keys are used to construct the grid-structure in the next step. This response can either be pulled directly from the web service, or manually entered:

Note: if Get response data from web service is selected, then it will execute the query against the specified endpoint with the specified parameters when Next is clicked. As such, if you've provided either a hardcoded query or test data that will cause data to be altered at the endpoint then this action will occur at this time. To avoid actually querying the endpoint during configuration, use the Manually enter expected JSON response data option instead.

 

 

9) Map the data structure provided in the previous step to a representative grid containing the desired information. Firstly, click into the Rows Data section, and select the node that contains all of the data you wish to use (root in this example). Once you've done this, select the Column Data that you wish to actually read data from (root > contactId, root > firstName, root > lastName, root > email, and root > title in this example):

 

 

i) The Table Field's reference column needs to be specified; this is a unique identifier that is stored as the value of the Table Field when a row is selected in it. If the Multiple Select option is enabled in the Options tab, then multiple rows in the Table can be selected simultaneously, with the Table Field's value being set as a comma-separated list of the reference column values:

Note: if the reference column doesn't enforce unique values, then selecting a row will also select all other rows with the same reference value.

 

 

ii) The data to be used in the Table Field is then defined, both for display and for subsequent mapping. The Reference Column is always listed first, but can be hidden by unticking the Visible column for it. Any column in the returned data can be mapped to the Table, and have its name and column width formatted. It's also possible to set whether the column is searchable, or hide columns if their values are needed for mapping but they shouldn't be displayed in the Table itself:

 

 

The List Box Field's value and display text columns need to be specified; the value of the selected row(s) are used as the Field's value, and the Display Text is what's shown to the agent in the List Box:

Note: if the value column doesn't enforce unique values, then selecting a row will also visually select all other rows with the same value.

 

 

The Agent Assist - Rebuttals Field's objection and rebuttal columns need to be specified, and the prompt can optionally be provided:

Note: the objection & rebuttal values must be unique.

Note: the prompt values can be left blank - a default prompt will be used instead if so.

 

 

10) Mapping the returned value for each column to a Field or Variable is configured in this step, as is whether the value should always overwrite any pre-existing data within the mapped Field or Variable, or only if the mapped Field or Variable is empty at the time:

Note: the List Box and Agent Assist - Rebuttals can only map the utilised columns, and will always overwrite existing data within the target Field or Variable.

Note: if Multiple Selection is enabled for a Table or List Box, then no data will be mapped even if only a single row is currently selected.

Note: if any of the returned values are null then they won't be mapped, even if overwrite is enabled; to overwrite a Field with blank data, an empty string must be used.

 

 

11) When an External Data Source completes its query or the agent selects an item from a Table, List Box, or Agent Assist - Rebuttals, the Field can be configured to trigger certain other Fields to perform an action. In this example, when our External Data Source has completed its query, it will trigger a Table to source or refresh its content:

Note: Update Links are a deceptively powerful tool, allowing the chaining of multiple Fields together into automated sequences of actions. For example; when an agent selects a row in a Table, this can map a series of values to other fields like a Text Box, as well as triggering a second Table to refresh its data set based on the selection in the first Table. The second Table will then display a related set of data based upon the selection in the original Table. This could then be taken further, with the second Table being set to trigger a JavaScript - Button when a row was selected, causing some specific behaviour to then occur in-Workflow based on the current selections.

 

12) Click Finish.