Installation¶
Requirements¶
Services and APIs¶
CART acts as an integration layer between different services (and APIs), and specific configurations within CART itself. To use it, you will need:
- Access to a SQL database
- Access to a web service to publish CART (using Python 3.X)
- An account with DialogFlow
- An account with the Microsoft Bot Framework
- A copy of the CART code
Optionally, you also would need access to an online questionnaire tool (e.g., Qualtrics, SurveyMonkey) if you are integrating CART into a survey flow.
Note: For #1 and #2, you can use your own server (if available), or AWS RDS (database) and Heroku (web service) as demonstrated in the Installation and Setup Guide.
Python Packages¶
CART uses a set of Python packages (e.g., PyMySQL, microsoftbotframework, google-cloud-dialogflow etc.). By downloading CART and running the step-by-step instructions in the installation guide (below), all the necessary packages will be installed on the server.
Installation and Setup Guide¶
Important note: these steps show how to install and setup an agent using AWS RDS (as a database server) and Heroku (as a web service) along with DialogFlow and the MS Bot Framework. Advanced users can replace AWS RDS and Heroku by their own servers.
Step 1. Download CART to your computer¶
- Access [ANONYMIZED LINK OF THE GITHUB REPOSITORY] and select
clone or download
and download CART as a zip file.- Extract the zip file in a folder you want to store the agent
Step 2. Rename the config.yaml file¶
The config.yaml
file, located at the folder cart
, will contain all the basic configurations needed to connect to the services (MS Bot Framework and the SQL database), including usernames and passwords. Never make it publicly available.
- To create it, you need to:
- Copy (or rename) the file called
config_example.yaml
toconfig.yaml
- In the steps 3, 4 and 6 (below), you will need to update this file with information coming from each service.
- Copy (or rename) the file called
Step 3. Create an agent in DialogFlow¶
- Log in to DialogFlow and select
Create Agent
. For CART, all tests have been done with the ES (simpler) version.- Follow the instructions from DialogFlow to enable the API, create a service account, and download the service key account file in JSON format. You will use it on step 5, as part of the web service configuration.
Step 4. Create a database for logging¶
CART requires the the URL (host) of a MySQL database, database name, and username and password to connect to and log the conversations between the agent and participants. The username provided needs to have all privileges (including CREATE) in the database. This information needs to be made included in the config.yaml
file.
- If using AWS RDS, the following steps need to be followed:
- Log into your AWS account and select RDS
- Create a database using MySQL, and make sure to include the username and the password also in the
config.yaml
file - When asked for the database name, make sure to inform it, and also include it in the
config.yaml
file. - Select the endpoint of the database (check the dabatase details page), and paste it in the
database_url
field ofconfig.yaml
. - After the database is launched, make sure to check the security group (see database details), and open the inbound port to the server that you will be using.
- Notes:
- Usually a micro or small instance in AWS is sufficient for testing purposes, and can later be upgraded to medium/large when the agent is live and handling several conversations at the same time (e.g., during an experiment)
- For security reasons, it is recommended not to allow any IP to connect to your database. When using Heroku, see this list of plugins that can create a static IP for your app.
- When running the agent in the server for the first time, it will automatically create two tables in the database:
logs
, which records every interaction between the agent and the participantconversations
, which records each individual conversation (i.e., in general, each participant = one conversation) that is started with the agent.
Step 5. Publish the agent as a web service¶
After completing the steps above, it is time to publish the agent as a web service. This can be done using Heroku (as demonstrated below) or in any other server that supports Python and Flask applications. It is important to note that the server should also be able to serve pages in https.
- If using Heroku:
- Log into your Heroku account and create a new app
- Set the environment variables (called in Heroku “config vars”) for DialogFlow. See note 2, below, for details.
- Select the deployment method
- Deploy the app
- After the build has been completed, select
open app
- Copy the URL of the app (it should start with the app-name, and end with
herokuapp.com
) to use in the next step
Note 1: the URL of the app is needed so it can be registered in the MS Bot Framework (next step). The registration in the MS Bot Framework will also provide authentication credentials. These credentials will need to be added to the config.yaml
file, and the agent will need to be published again in Heroku (as outlined in the next step).
Note 2: Open the service account file downloaded on step 3(above) locally in a text editor, remove all line breaks, and substitute the double quotes (”) by single quotes (‘). In the web service, add this as an environment variable called DF_CREDENTIALS. Create another environment variable called DF_LANGUAGE_CODE and set its value to the appropriate language (e.g., en).
Step 6. Connect the agent to the MS Bot Framework¶
After a URL for the agent as a web service is available (e.g., for Heroku: https://NAMEOFTHEAPP.herokuapp.com/
), the agent can be registered in the MS Bot Framework. To do so:
- Log in your Microsoft Bot Framework account, selecting
My Bots
- Select
create a bot
. You will be redirected to Azure Bot Service- Select
Bot Channels Registration
- Provide the information required
- The messaging endpoint will be the URL of the Heroku app +
api/messages
- example:https://NAMEOFTHEAPP.herokuapp.com//api/messages
- After the channel registration is deployed, select
Go to resource
(or simply open it in Azure)- In the
Settings
, go to the Microsoft App ID area- Copy the Microsoft App ID and add it to the
config.yaml
file underapp_client_id
- Click on
Manage
for the Microsoft App ID- In the new window, select
Generate new password
. Copy this password and add it to theconfig.yaml
file underapp_client_secret
- Click on
save
and close this window- In the
config.yaml
file, add the name of the agent underagent_name
- Go back to Heroku and re-deploy the app (with the latest version of the
config.yaml
file).- After the redeployment, you can use
Test in Web Chat
function on Azure Bot Service (same area where theSettings
were) to test the connection.
Step 7. Customize the agent¶
After the agent is connected to the MS Bot Framework, the basic setup is done. The researcher can then use several features within CART to customize the agent. For more details, see Using CART
Step 8. Making the agent available¶
After the agent is ready to interact with users, you can use the Microsoft Bot Framework to publish it as a Web Chat (see Get bot embed codes
), or on other channels such as Skype, Facebook Messenger, or Telegram.