WOOL 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.

Table of Contents

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:

  1. 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.
  2. 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:

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:

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:

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/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!

Back to "Tutorials".