Tutorial: Setting up the WOOL Web Service

In this tutorial you will learn how to set up the WOOL Web Service with your own user account and dialogues.

1. Setting up the Web Service

Start by downloading or pulling the WOOL project from GitHub. The setup guide for the WOOL Web Service can be found in the ReadMe file that is located in the {woolplatform}\wool\java\WoolWebService folder. Complete all steps until you have deployed the Web Service (step 3 in the ReadMe). When configuring your gradle.properties file for use on a localhost make the following adjustments:

  • woolconfigBaseUrl can be changed to for example: http://localhost:8080/wool

  • For woolconfigJwtSecretKey you should generate a secret key (as described in step 2 of the ReadMe).

  • The woolconfigDataDir can be chosen freely.

  • The tomcatDeployPath has to match the woolconfigBaseUrl. If you use URL suggested above, change this to wool.

  • Change remoteTomcatUser and remoteTomcatPassword to the username and password for your Tomcat installation.

If you cannot access the Swagger interface or the deployment showed errors, perform the following checks:

  • If the deployment did not show any errors:

    • Did you set the woolconfigBaseUrl to http://localhost:8080/wool? Then try to access the Swagger interface using that URL.

    • If you set the woolconfigBaseUrl to http://localhost:8080/wool, have you also set your tomcatDeployPath to wool? These need to match for the Swagger interface to be shown correctly.

  • If the deployment did show errors:

    • Is your Tomcat running? If it is, going to http://localhost:8080/manager/html should result in a request for a username and password.

    • Are your Tomcat username and password correct? You can verify this by logging into the manager window at the URL in the previous step.

    • Check if your gradle.properties file has been configured correctly. (See notes above.)

    • The logfiles for Tomcat can be found in the log subfolder of the directory that you defined for woolconfigDataDir.

2. Adding users

During the setup of the Wool Web Service, you have defined a {woolconfigDataDir} in the gradle.properties file. Go to that folder and there you should find a users.xml file. (If that users.xml file is not there, an example file can be found in the {GITDIR}\WOOL\java\WoolWebService\config directory. You can copy this file to the specified location.)

This file contains an overview of all user accounts in the Web Service. New users can be added by adding a user’s email and password. For example:

webservice setup tutorial 1

3. Adding dialogues

Where users are added in the woolconfigDataDir folder, new dialogue scripts can be added to the {woolplatform}\wool\java\WoolWebService\src\main\resources\dialogues\en subfolder (assuming you have an English dialogue).

Once you have added new dialogues, you need to run the .\gradlew updateConfig and .\gradlew build cargoRedeployRemote gradle commands in the {GITDIR}\wool\java\WoolWebService folder.

The dialogues in this folder are available for all defined users.

4. Pre-setting or changing variable values

To pre-set variables for a user, you need to add variable names and values to a JSON-file for that user. There are two ways to do this, which we will both discuss below.

4.1. Change a user’s varstore file.

The JSON-files are located in the varstore subfolder in the {woolconfigDataDir} folder (the directory you defined in the gradle.properties file). If that folder does not exist, you can create it (next to the log folder and the users.xml file). In that folder, the variables for each user are stored in a JSON-file that has the user’s email address as its name. For example:

webservice setup tutorial 2

Each JSON-file that is in that folder (or that you change or newly add) should contain a JSON with combinations of variable names and values. For example:

webservice setup tutorial 3

If you add/remove variables for a user or change variable values in this manner, the WOOL Web Service needs to be restarted (this can be done through the Tomcat manager panel).

4.2. Add or change variables using the Web Service’s endpoints

Alternatively, you can use the /setVariable or /setVariables endpoint to add/change variable values for a user. The first will take a single name and value, while the second will take a JSON with name and value pairs.

Note that with the /setVariable endpoint you cannot set a variable to null, since it will become a String. However, variables can be set to null with the setVariables endpoint.

That concludes this tutorial. Have fun!