Data files

Using data files, it is possible to expose static data inside a bot's script without hard-coding it directly in Bubblescript.

This chapter explains how data files can be used inside Bubblescript, how the various data file formats work, and how you can define basic CMS features to let people easily edit these data files.

file management

Using constants for configuration¶

Often it is the case that your bot needs data for it to work. For instance, your bot might need some configuration settings, e.g. opening hours, a list of e-mail addresses that can be contacted, a general welcome text, et cetera.

There are several approaches how you could store these data.

You could "hardcode" them in your bot, e.g. like the following:

dialog check_time do
  if time > "18:00" do
    say "Sorry, we are closed right now."
  end
end

But, when your opening hours change, you need to look in the code where you defined this. For this reason, we added constants, special variables prefixes with a @, which function as read-only constants.

@close_time "18:00"

# more code here…

dialog check_time do
  if time > @close_time do
    say "Sorry, we are closed right now."
  end
end

This way, the logic is separated from the configuration.

However, the constants are still in the same file as the code. Wouldn't it be nice if we had a way to define these settings on another place?

Data files¶

This is where data files come in. As soon as you create a data file, be it either a YAML, JSON or CSV file, these files get automatically exposed in the bot script as a @constant with the same name as the filename.

So it is possible to create a YAML file, for instance settings.yaml looking like this:

open_time: 9:00
close_time: 18:00

And then the variable @settings will be exposed in your script. Given that this YAML file is an object, it contains a @settings.open_time and @settings.close_time property.

The dialog becomes more simple:

dialog check_time do
  if time > @settings.close_time do
    say "Sorry, we are closed right now."
  end
end

And the actual value of settings.close_time is stored outside the script.

Supported data types¶

The supported types of data are YAML, JSON and CSV.

Most of the time, you'll find yourself using YAML: an easy to read and write file format which uses white space to define a data structure, with lists and objects. Watch a video explanation about YAML here.

JSON¶

JSON is the JavaScript Object Notation: a format mostly used by computers to interchange information. Use this data format if you have some external data that you want to statically incorporate in your bot, as-is. It is easy to make syntax errors with JSON, as it is picky with comma's and quotation marks.

Hint: if you need to edit the JSON later, you might want to convert it to YAML first.

CSV¶

Finally, DialoX supports CSV: Comma Separated Values, the format used by spreadsheets to present tabular data. When creating a CSV file, it is exposed in Bubblescript as an array of objects. The first line of the CSV file must contain the column names, and the comma (,) is used to separate the fields. Doublecheck this when exporting data into the studio; some programs use the semicolon (;) by default.

Say, you have the following CSV file, called users:

first_name,last_name,age
Joe,Strongfoot,37
Jim,Baker,25
Melanie,Smith,27

Then you can iterate over this in Bubblescript:

repeat user in @users do
  say "#{user.first_name} is #{user.age} years old."
end

Note

Data files can be made editable for non-technical users by exposing a basic Content Management System for them.

Exposing data files over HTTP¶

It is possible to expose some of the bot's data files on a HTTP endpoint. This way, by adding a Content Management System for the data, the bot can serve as a headless CMS for some of your data.

To enable this, create a YAML file called http_endpoints, and create a structure like this:

- method: "GET"
  route: "config"
  controller:
    type: "script"
    script_title: "my_data_script"

After publishing, the contents from the script named my_data_script will be externally exposed on an API endpoint called https://bsqd.me/api/bot/:bot_id/content/config.

The http_endpoints contains a list of entries, each of which needs to have these keys:

method - the request method, needs to be "GET" currently
route - the part of the URL that the endpoint will be exposed on. The base URL for each entry point is always https://bsqd.me/api/bot/:bot_id/content/; the given route will be appended to this.
controller.type - set to "script"; meaning the content will be served from a data file
controller.script_title - the script title of the data script to serve.

In the future, the HTTP endpoints functionality will most likely be extended to allow updates to the data as well as creating alternative controller besides serving data from a data script.

Endpoint parameters¶

By default, the data that is served on the endpoints is served "un-localized"; that is; $i18n-structures inside YAML / JSON files are returned as-is to the client. By passing in a lang= parameter, these structures are collapsed into their respective language versions:

https://bsqd.me/api/bot/:bot_id/content/config?lang=nl

Exposing all files with the same extension¶

- method: "GET"
  route: "config"
  controller:
    type: "script"
    script_extension: "data"

Would look at all data scripts with a given extension (in this case, all scripts named *.data) and expose these as an array under a single endpoint.