Skills¶

One of the benefits writing your bots in Bubblescript is the fact that you can reuse code in different dialogs. With Skills, you can reuse parts of one bot, within another bot. Skills can therefore be thought of as a tool that you can buy. Programmers can think of Skills as libraries or packages. A skill can depend on other skills, just as a drill can depend on a drill-bit to perform its function.

DialoX provides a few internally developed skills for you, but of course you can create skills yourself. At the moment, it is not possible to publish skills for other people to install, but this is a planned functionality for the future.

Managing Skills¶

Installing an external Skill¶

Skills provided by DialoX can be installed through the Skills main-menu item. On the underlying page, you can find an overview of skills that are available and the skills that are already installed in your bot. A skill is installed using the "Install" button in the pop-up.

All the dependencies for a skill will be installed automatically.

Configuring a Skill¶

Once a skill is installed, it can, depending on the skill, be configured to perform its task in a way you desire. Configuration of the Skill is done in the "Installed" section by clicking on the cogwheel of a Skill.

Uninstalling a Skill¶

Skills can be uninstalled in the "Installed Skills" by clicking on a Skill and then on the "Uninstall Skill" button. If the Skill you are trying to uninstall has another installed Skill that depends on it, an error will be shown with the name(s) of the Skill(s) that depend on it. Uninstall those skills first.

Disabling a skill¶

Skills can be temporarily disabled. This functionality can be used to first install the skill and then configure it, without exposing the skill yet to the world.

Skill development¶

A skill exists in its own folder in the bot, where all the files that are necessary for the Skill to function properly are stored. Subfolders can be used to create a more structured hierarchy if needed.

The information about the Skill is stored in the skill.yaml file that resides in the directory of the Skill. This file has the following fields that describe the skill:

name string, mandatory, unique identifier of the Skill,
title string, mandatory, a display title for the Skill,
icon string, mandatory, the icon that is displayed in the Skills section (blueprintjs icon),
subtitle string, mandatory, a small description of what the Skill does.
author string,
dependencies list of string, a list of names of other Skills that this Skill depends on,
optional_dependencies list of string, a list of names of other Skills that need to be ordered below this skill,
license string, the license that the skill is published under,
screenshots list of images, screenshots of the Skill,
settings settings schema, a CMS definition of the settings for this Skill,
tags list of strings, a list of tags that apply to this Skill,
version string, a semantic version of the Skill at the time of publishing.

A minimal skill.yaml file:

name:       "company/skill"
title:      "My Skill"
subtitle:   "Provides basic behaviour"
icon:       "badge"
version:    "1.0.0"
dependencies:
  - "bsqd/base"

And a skill which defines a settings screen:

name: "company/skill"
title: "My Skill"
subtitle: "Provides basic behaviour"
icon: "badge"
version: "1.0.0"

settings:
  type: form
  storage:
    type: script
    script_title: config/company_skill
  title: Users
  icon: people
  form:
    schema:
      type: object
      properties:
        name:
          title: "A configurable string field"
          type: string

Testing skills¶

Often you develop multiple skills inside a single bot. In that case, you might want to write test cases that only cover a single skill. In such cases, it is best to disable the other skills in the bot that are not the focus of the current test.

It is possible to automatically disable certain skills for certain test files, by setting the @disabled_skills constant in the test file, like this:

@disabled_skills ["b"]

test "Only testing skill a"
  expect "Hello from a"
end

Migrations¶

Sometimes it can be necessary to run code when a skill upgrades its version, or when it is installed. For this purpose, skill migrations exist. Migrations are tasks, which live within the folder of the skill, which are annotated with a migrate_to: attribute.

Skill upgrade migrations¶

When a skill is upgraded, the following happens:

The source version of the skill is retrieved; this is the currently published version number of the skill;
The target version of the skill is retrieved from the skill in the store;
From the skill's scripts, all tasks are gathered which have a migrate_to attribute with a version number which lies between the source and the target version
These tasks, ordered by their version number, are then performed in the bot.

All log statements in the tasks are collected and presented to the developer afterwards. When a migration task fails, the upgrade of the skill is cancelled.

An error can be raised from within a task by using the fatal statement.

Typically, the write_script(title, contents) function is used inside the migration task to modify some of the content on the bot while the skill is upgrading.

Example:

task migrate_to: "5.1.4" do
  log "Starting content migration"
  data = []
  repeat i in keys(@answers) do
    data[i] = @answers[i]
    # add a new attribute
    data[i].enabled = true
  end
  write_script("answers", data)
  log "All done"
end

The write_script function can only be called from inside the studio, and called by a developer with enough permissions to change the bot's script.

Migration tasks can be tested in the studio by giving the task a name, and from the debug console calling perform on the task.

Skill installation migration¶

To run a migration when a skill is newly installed into a bot, specify :install as the version:

task migrate_to: :install do
  log "Installing the skill..."
  # do your things here
  log "All done"
end