General

This code is solely for exemplary purposes. This is not production-ready code, so use at your own risk.

Axbot-blueprint is a django project that connects the dialogflow webservice for natural language understanding with the AX Semantics webservice for automated text generation.

This project uses docker, nginx, gunicorn and django. The default settings of this tools were slightly changed to speed up the development process. For production you have to check the settings and configure them appropriately (e.g: remote/cloud database).

Prerequisite

1. install docker
2. install docker-compose

Authentification

1. Enter the Refresh Token that belongs to your AX Semantics account to your app. It gives your app the permission to communicate with AX Semantics.

   • go to AX Semantics cockpit

   • go to your profile settings

   • select Advanced settings

   • click API access

   • copy the Refresh Token

   • set the refresh_token in your app

     • navigate to the views.py file in your app directory e.g.: ../axbot-blueprint/axbot/YOURAPP/views.py
     • in the code, search for the class ...Bot(AX)
     • paste the refresh token as value for the variable refresh_token

   • Documentation: https://documentation.ax-semantics.com/v2/api/authentification

Instant Generation API

1. Activate Instant Generation Endpoints for your account.
   • go to AX Semantics cockpit
   • go to your profile settings
   • select Advanced settings
   • click on the switch for Instant Generation Endpoints
2. Create an Instant Generation Endpoint for your project.

   • switch into your AX Semantics project

   • click the gear symbol next to the project name in the top left corner

   • select the Instant Generation Endpoints entry

   • click the green button create a new instant generation endpoint

   • fill out fields

     • webhookurl pattern: $DOMAINNAME/$APPNAME/axwebhook/
     • e.g.: www.example.de/myfirstapp/axwebhook/

   • configure the endpoint

     • Delivery Format : text
     • Used Ruleset Version: draft for testing, publish for production

   • set the instant generation endpoint id in your app

     • copy the ID from the Instant Generetion Endpoints
     • navigate to the views.py file in your app directory e.g.: ../axbot-blueprint/axbot/YOURAPP/views.py
     • in the code, search for the class ..AxWebhook(AxWebhook)
     • paste the ID as value for the variable instant_id

   • set the instant generation endpoint webhook secret in your app

     • copy the webhook secret from the Instant Generetion Endpoints
     • navigate to the views.py file in your app directory e.g.: ../axbot-blueprint/axbot/YOURAPP/views.py
     • in the code, search for the class AxWebhook(View)
     • paste the webhook secret as value for the variable webhooksecret

   • Documentation: https://documentation.ax-semantics.com/v2/api/instant-generation

   • Dev-Docs: https://developers.ax-semantics.com/v2/instant-generation-requests/instant-request-api

Dialogflow Fulfillment

1. Configure your Dialogflow Agent to use the AX Semantics webservice
   • got to your dialogflow project/agent
   • select the fulfillment menu
   • enter the endpoint (url) of your project as webhook url in dialogflow e.g.: www.example.de/myfirstapp/text/
   • press SAVE!
   • activate the fulfillment option in your intents
     • select the intent menu
     • open your intent(s)
     • scroll to the section Fulfillment
     • press the button Enable webhook call for this intent
     • SAVE!

For local testing

1. use the tool ngrok
   • start ngrok
     • use the port that you configured in docker (we set port 8000)
   • use the generated ngrok-url as webhook url in dialogflow (e.g. https://123456.ngrok.io/YOURAPPNAME/text/)

Setup

Before you start to build and run the docker you need to create and insert a SECRET_KEY

cd axbot-blueprint/axbot/axbot/settings/
vim base.py

dev/test

cd axbot-blueprint
docker-compose build --pull
docker-compose pull
docker-compose run --rm web python3 manage.py reset_db
docker-compose run --rm web python3 manage.py migrate
docker-compose up -d

deploy

• configure the docker port in docker-compose.deploy.yml to your enviroment
  • at the moment the port is only mapped to localhost:8000
  • use your preferred webserver and proxy it to localhost:8000

cd axbot-blueprint
sudo docker-compose -f docker-compose.deploy.yml build --pull
sudo docker-compose -f docker-compose.deploy.yml pull
docker-compose -f docker-compose.deploy.yml run --rm django python3 manage.py reset_db
sudo docker-compose -f docker-compose.deploy.yml run --rm django python3 manage.py migrate
sudo docker-compose -f docker-compose.deploy.yml up -d

• optional:
  docker-compose run --rm web createsuperupser