My First Skill: Tell a joke about someone

Overview

We'll be building a skill that when invoked outputs a joke about a person. The skill leverages the Chuck Norris Database API.

The Chuck Norris API allows you to make an HTTP call to http://api.icndb.com/jokes/random and retrieve a random joke about ... Chuck Norris. The JSON output of the API looks something like this:

{
  "type": "success",
  "value": {
    "id": 528,
    "joke": "Chuck Norris doesn't use GUI, he prefers COMMAND line."
  }
}

The API also allows you to pass in another name in place of Chuck Norris. For example a call to http://api.icndb.com/jokes/random?firstName=Peter&lastName=Parker will return:

{
  "type": "success",
  "value": {
    "id": 536,
    "joke": "Don't worry about tests, Peter Parker's test cases cover your code too."
  }
}

Let's see how we can leverage this API to return a joke about a person.

Define the Skill

Start by giving the skill a name and some sample sentences that will trigger this Skill. Since your skill will be immediately available to all your team members, it is recommended to start with a cryptic name (that only you know how to trigger). Here we'll just use one sentence to test it out.

Note that Katella has another built-in tell a joke skill, so your training sentences should try to differentiate the new skill as a joke about a person.

First Draft

Keep it simple for this first draft. We'll leave the Inputs empty, make the API call and simply output the joke text.

You may leave the App field empty. We use this when accessing an App that requires authorization.

The API result can be referenced using output. Using expression {output} alone will just return the full JSON, not terribly useful. Instead we can walk the JSON graph using our Expression Language. We need to first navigate to the child value, then its child named joke. The expression then becomes {output.value.joke}, which returns the text of the joke.

You can now test the skill on a connected client. Here's the output in Slack:

Putting it together

Let's have some fun and replace Chuck Norris with another name of your choosing, something along the line of "tell me a joke about Ronald Park". For this we need to collect a name from the user.

Add a system input of type PERSON. This instructs Katella to extract a person's name from the user's command. If the name is missing, and the input is marked Required, Katella will prompt user to enter a name before proceeding.

You may optionally want to customize the prompt message to make it clear what is expected from the user, something along the line of "Who's the person to make fun of?".

We can now update the API call and reference our Inputs. We only have 1 input of type PERSON, so an expression of {input1} will output the person's name (as how it was entered). Keep it simple by setting the whole name as the firstName and leave lastName empty.

Now is also the time when you want to train a few more sentences to match our changes. Katella will detect a person's name (in upper case), so you don't need to repeat the sentences with different names. Try different ways a person may ask for this skill.

Note: avoid overly generic sentences. Katella is designed to disambiguate similar sounding sentences, but accuracy will be thrown off if skills are trained with wrong sentences.

You can now try out sentences like "say something funny about Jack" on a connected client. For kicks, try this on your Google Home "ask Katella AI to make fun of Paul Ryan".

Congrats! Your very first Katella skill.

Polish It Up

Chuck Norris Database API encodes their output with HTML encoding, so some outputs may contains strange characters. Katella comes with many utilities to help with text formatting, currency conversion, date time manipulation, ... These utility classes are different than our input1, input2, output, ... and are prefixed with special character @. To escape HTML, use expression {@Formatter.decodeHtml(your_encoded_text)}.

The Expression Language also allows simple if/else and loop expressions. The syntax for if/else is as followed: { condition ? execute_this_if_true : otherwise_execute_this }. Currently if the API somehow fails, we'll get an empty output. Instead let's show a friendly error with this expression: if type matches "success" then show the joke otherwise say I can't make fun of this person.

Putting them all together:

Note: whitespaces will be collapsed, so you may use newlines to make the expressions easier to read.

You have completed this tutorial. Remember skills created by you (a Katella admin) are accessible to all your users (Katella users who are part of your team).