Referenced Web Services

It is possible to configure calling web services via REST to populate referenced tables in the Therefore™ database. During the configuration, the user sets up rules to retrieve the data from a web service. The configuration of the REST call is similar to the Call REST Service workflow task. Right-clicking a referenced web service will bring up a context menu.

Synchronize Now
Fetch data from a web service that will be displayed in a referenced table. During configuration a schedule for fetching the data can be configured (for example: once a day, multiple times a day). Use this option to synchronize data immediately in case data needs to be retrieved from the web service outside of the scheduled times.

Delete Rows
Deletions in the web service are not automatically deleted in Therefore™. Use this option to manually delete rows in a referenced table if something has been configured incorrectly. This option can also be used to take a look at the referenced table to see if synchronization is working correctly.

Note: Activate logging for synchronizing referenced table data from web services under the 'Advanced' tab in the Therefore™ settings. The log file is located in the LogFiles sub-directory of the buffer folder.

The 'Referenced Web Service' dialog has three tabs that can be configured.

Table Data

This tab is used to define the structure of the referenced table the data from the web service will be saved in.

Name
Enter an intuitive name for the referenced table that will be created.

Referenced Table columns
Define the name and data types for the columns of the referenced table. Take a look at the response sample in the documentation of your REST API provider to find out which columns you will need.

Unique ID
The table's primary key. This is a unique element to identify the referenced table in the data base, and it is used to identify the table when adding it to a category.

Column name
Name the columns of the referenced table. The name does not have to match the corresponding one in the JSON response.

Data Type
Select the matching data type for the referenced table column. The available data types are text (=string), date, decimal, and integer. When in doubt, choose 'text'.

Length
Length of text or numeric precision.

Scale
Digits after the comma for the decimal data type.

Add
Add a new column to the referenced table.

Delete
Delete a selected column from the referenced table.

Synchronize

Synchronize Now
Start retrieving data from the web service instantaneously.

Reset
Reset the synchronization. The rows of the table are deleted. Use this option to delete data from the table if something was configured incorrectly. Once the table is referenced in a category and documents are saved this option is limited.

Synchronization

This tab is used to configure the REST calls to the web service data is being retrieved from.

Icon	Description
	Add a new REST call.
	Edit a rest request.
	Delete a REST request.
	Move the REST request up in the list. By default, the calls are executed top to bottom.
	Move the REST request down in the list.

Clicking 'Add a new REST call' or double-clicking on an existing REST call opens a new dialog that allows the user to configure the REST request. After configuring a REST request, return to the Synchronization tab and click the 'Test' button to retrieve data from the referenced web service. After this step, the Assignments will be available.

For a detailed view on configuring a REST request, see the reference:

Call REST Service

Table column assignments
Map the data in the response JSON to the corresponding column in the referenced table.

Test
Open the Test Call REST service dialog to take a look at the data that is being retrieved using the current configuration.

Test Call REST Service

Test the REST call that is being executed using the current configuration.

Start
Click this button to start the test.

REST Requests
The name of the REST call that is being tested.

Request
Name, method, URI, and headers of the REST call that is being tested.

Status code
The status code of the REST request. 2XX corresponds to a success code.

Response body
The REST response in JSON format.

Schedule

Define a schedule for the synchronization of data from the web service.

Once per day
Synchronize the data once every day at the specified time.

Multiple times per day
Synchronize the data X times a day within the specified time frame.

Disabled
Don't synchronize data.