Skill Flow Builder: Using SFB editor and Basic Concepts

In this blog we will explain how to use the Skill flow Builder Editor GUI to create, edit, and preview content for your skill. The project can be downloaded here .

Once you open the SFB editor you will see a similar image as above. The main elements you will find are:

1. Project creations and Project history. Here you will be able to open or create a new project or review a recent project from the Recent Projects list.
2. File and View Menu.
   1. File. Where you will be able to open, create and close projects. In addition, it has options to “build” the project (similar to the command alexa-sfb build), “reset” the editor and a troubleshooting action “clear-voice-preview-cache” (the functionality will be explained in the project simulation section).
   2. View. To modify the views of the editor.
3. Edit and Simulate tabs . Here is the main editor of your interactive story files you can recognize in your SFB project because they are stored with the extension .abc . From left to right you have the “source” (‘</>’) view where you can see the text view of the story file, “guided” view (compass icon) offers a graphic interface to edit the story files and “simulate” (play icon) that will allow you to simulate your flows. Every story content can be stored in one or multiple story files (.abc). These stories will follow a specific syntax and can be edited and simulated in these views.
4. Map and resources palette. This palette contains the resources (“images”, “snippets”, “slots”, “audio”) and the “map” (tree icon) where you can see a tree structure representing the flow nodes of your story. The details for adding nodes will be explained later.
5. Log views. It includes the different logs recorded after opening the editor. From left to right you have “Log Messages” recording any editor event (save, open,etc.), “Error Messages” containing any syntax error in our flow and “Build Output” containing any information related to the last “build” of the project.

Go to “File Menu” or “Project History” and select “New project”. After clicking it you will see a screen like this:

From all the options the most relevant is the type of “Starter Template” Existing templates contain rich samples you can use to build your skill:

• Blank: create a flow builder skill from scratch.
• Example Story and Adventure: select one of these templates when you want to create a narrative story. This is a really useful template you can use to have a better understanding of the different SFB features.
• Quiz: this template contains all the components required to create a Quiz and it can be used to load questions defined in the story file(.abc ) or to load them from an external file (.csv). Consider this last option if you want to build skills that can access questions from an external source.

We will start our development from scratch. Select “Blank template”, write your project name and project directory, then, click OK.

SFB is organized around the idea of scenes and and we can consider them as the main building blocks. A scene imitates a film or theatrical screenplay, in which the narrative is told through a series of scenes. In a scene, a small portion of the narrative unfolds, through characters, visuals, and sound design. Then, the players makes a decision, speaks that decision to Alexa, and the skill advances to the appropriate scene.
After creating your blank project the editor will open the “Map view” and the “Source view” showing your story.abc file. The node or scene added in this blank template is a special one: @start which is the first scene for a new user to the story or after a restart of the story.
For now we will just focus on the main elements of a scene. Select your start  scene in the “Map view” and change the view to “Guided”. 

Main elements of a scene are:

• say: This is what Alexa says to the user when it plays the scene. This is what the narrator or character says and you can use Amazon Polly to support multiple voices/characters.
• recap: This is what Alexa says when the user says an unexpected response.
• reprompt: This is what Alexa says if the user says nothing when the scene expects a user response (“Hear Action”).
• then or navigation actions: These are the instructions or commands executed after Alexa plays the content (say, recap or reprompt) of the scene. There are two type of actions:
  • Go to ( -> ) . Defines how the scene will transition to the next one.
  • Hear. It specifies the words or phrases to listen to, and what should happen if heard.

For now, let's add 2 scenes that will be connected to our start node. Go to the “Map” view, select the node and click ‘+’ (bottom right corner in the “Map” view), then select the new one and repeat the process. Now you should have 3 scenes connected in your map view as the below image: 

Edit the say, recap and reprompt on each scene, and then “Save” the project. If you prefer you can go to the “Source view” and paste the following code:

SFB's hear action allows the skill to select the next scene based on the user’s response. To create one, select the last scene ‘learn say and reprompt’ and go to the guided view, select “Add hear Action” and add the following content (it will add a new scene called ‘learn choices’ that we will use in the next exercise). Then save it.

So far we have added a hear action but you would probably like to add multiple choices and not just one. Go to your new ‘learn choices’ scene and in the “Guided view” add two “Hear actions” (one should go to the scene ‘more on choices’ and the other to ‘learn variables’) . You can copy/paste the following code in the scene:

Remember: If the user says an utterance that is not supported in our hear actions, SFB will read the reprompt message and if it's not defined it will repeat the say text again.

SFB is a graph so you can navigate to a scene from multiple nodes . Let’s try it: Go to your new scene ‘more on choices’ and add a “Hear action” to the scene ‘learn variables’.
After completing these steps your “Map view” should look similar to this one:

Terminators , noted as ‘>>*’, are special instructions you can include in your scenes. The most important terminators are:

• >>END: will end the flow and next time user restarts the skill it will go to the @start scene.
• >>RESTART: will restart the flow and it will move to the @start scene. It will reset all choices (flags) but it will not reset variables.
• >>RESUME: will go to the scene where the player last left off.
• >>BACK: will go to the scene of the previous interaction.
• >>REPEAT: replays the audio artifact that the user just heard.

SFB offers a list of special scenes you can use in your skills. Like any other scene, the scene identifier is unique so you cannot repeat it. The most relevant scenes are:

• @start: is required in any SFB skill and it’s executed for all new users and after a restart.
• @pause: triggered after user says ‘cancel’, ‘pause’ or ‘stop’ (AMAZON.CancelIntent, AMAZON.PauseIntent and AMAZON.StopIntent) or after using the special terminator >>PAUSE.
• @resume: this scene is played when the user comes back to the skill. From this scene you can send users back to where they left off by using a >>RESUME
• @global prepend: the content of this scenes is prepended to every scene in the game. It will be executed before the current scene.
• @global append: the content of this scene is appended to every scene in the game. It will be executed after the current scene.

In the following exercise we will add a global help, repeat, restart and a previous scene handler to our flow (e.g: the user can ask for help in any scene) and we will also add the special scenes @resume, @pause .

1) Open the “Source view”.
2) Copy and paste the following code to add the scenes.

3) Save the project and switch to “Map view”. You should see something like this:

4) Select ‘resume’ scene. Go to “Guided view” and add to say following test:

“This is a resuming scene. This scene is played when the user re-launches your skill after exiting. Do you want to continue your story from where you last left off?”

5) Add to the scene two hear actions (Utterance: ‘Yes’, action: → Resume; Utterance: ‘No’, action: → Restart) and save the project.
6) Select the Pause scene and add this say message: “Thanks for playing!”
7) Select the @global append scene and add the following hear actions:
- Utterances: restart, start again ; Action: → Restart
- Utterances: repeat, say again, repeat it, what did you say, I didn’t understand ; Action: → Repeat
- Utterances: help, I need help, please help me ; Action: Go to Scene help (help is a new scene)
- Utterances: back, previous, rewind ; Action: → Back
8) Select the new ‘Help’ scene and add this say message: “This is a help message. In this story, this scene is set up to be reachable only through the global scene.”
9) Add an action to the ‘Help’ scene and select ‘Back’.

If you have followed correctly all instructions you source code should include this at the end:

SFB allow developers to collect and use values in their stories. These values can be simple variables representing a number, a string, a predefined enumeration (e.g: names, actors, cities, etc.) or a custom value that developers can define in the “Slot types” (e.g: list of fruits, player classes, etc.).

The simplest way to capture a value is using the command hear and the {slot} value in the utterance. The slot instruction tells Alexa that when we are using {slot} for a hear it should expect to hear a number, string, or an enum (depending on the slot type definition). For example:

The above code will tell Alexa that when a user says ‘my name is XXX’ it should expect a name in XXX from the list of available names in the AMAZON.US_FIRST_NAME type. You can select any built-in type (be sure the type is available in your locale) or create your own type.

You can also reference your collected value by using {slot} notation in the say command.
Go to your start node and select the “Source view”, then copy and paste the following code:

Now we are going to use that value in our say command. Go to the ‘learn scenes’ “Source view” and then replace the content with this:

“Save” and “Build” the project again.
You can also add a value in the “Guided view” by double clicking the word (without brackets) and selecting “Value”.

To create your own type you need to go to the “Slot type view” (icon ‘?’) under the “Map view”. Then select a “New slot type”:

You can now add values by clicking the ‘+’ button

These slot types can be used in the same way as any AMAZON built in type.
Create a CustomFruitType slot and add ‘pear’, ‘pineapple’, ‘apple’, and ‘orange’ as values. 

SFB allows developers to store information about the progress of the story, manipulate that information and make it persistent even after closing the session. Based on the type of value we can classify them in three types:

• Boolean values (true or false). These variables are declared and set using the commands flag (declare and set value = true) and unflag (declare and set value = false).
• Primitive values (numbers and strings). Used to store a string or number. They are declared using the set command
• Enumerated types (a limited list of string values). This has already been described in previous section and they are declared using slot command.

You can use the variables in your say as explained previously but you can also use them to define navigation logic in your flow using if
Go to ‘learn variables’ scene and modify the code in the “Source view”

We are declaring a numeric variable that will be initialized to 0.
Now add the scene ‘learn conditional’ with the following code:

This scene will verify the value of our variable antidote and it will send us to different scenes depending on the value (0, 1 or other). Note that in this scene we didn’t include any say command so in case we resume the skill right here then it will restart in the previous scene ‘learn variables’.

Now complete the code adding the snippet below. If the user leaves the game while in these scenes then the value of the variable antidotes will be kept. If we want to remove the value we need to use the command clear.

The table below describes the syntax you can use in your scenes depending on the types used.

Now that we have covered the most important topics when building a SFB skill we can take a look at how to improve the skill engagement by adding images, music and voices to your skill.
First we will use show which displays the visual components assigned within this section. As this is a basic tutorial we will use the 'default' APL template included in the project.
Go to the ‘images’ scene, go to the “Source View” and then copy and paste the following code:

This template will create a simple presentation with a title and a background image.
Now we will add a background sound while Alexa reads the say text. To do that we will use the instruction bgm <audiourl> that needs to be included in the then section and it requires Amazon Polly to be enabled in your skill configuration. As Polly is enabled by default in our project we don’t need to worry about it. In addition, you can also use SSML tags in the say section.
Create a new ‘background music’ scene and add this code:

As final step add a last scene named ‘congrats’

Snippets allow developers to provide a shorter syntax for performing common operations in *.abc files. They can be found in the editor with the scissor symbol.

Snippets can be used to shorten the URLs to resources used in your skill such links to audio or image files. To use a snippet, use brackets that enclose the snippet name like [<snippetName>] in any of your skill say, recap, prompt again, or then sections.

To create a snippet:

1. click on “New snippet” button

2. then name it as “trumpet” and add the following ssml code:

1. <audio src='https://s3.amazonaws.com/alexa-ml/sounds/sound-library-loud/Instruments/Trumpet_1.mp3' />

3. Then click on “Create”. This code will play a trumpet sound when the snippet is used.

Repeat previous steps and create following snippets:

Now lets use our snippets:

1. Go to the “Map View” and create a new scene ‘snippets’, connect previous ‘background music’ scene to this one and add a hear action (yes, continue, ready) to redirect to ‘congrats’ scene.
2. Add to the say message this text:

The updated code should look like this:

As you have noticed one of the snippets we created is using ‘$1’ that is the way we pass parameters (“2s”). This can be really useful when we want to reuse code in the .abc file. There is no limit of the number of parameters, just ensure you define them in your snippet code ($1, $2,$3, etc.)
Finally there is a predefined variable you can use in your code to substitute your skills default content URL: $SNIPPET_S3_RESOURCES_URI. For example, this code <audio src='$SNIPPET_S3_RESOURCES_URI/audio/$1'/> will be replaced during runtime/simulate by this one: sfx": "<audio src='https://s3.amazonaws.com/alexa-ml/testadventureskill/en-US/audio/$1'/>.

Note: This special variable replacement can also help with content localization of audio/images files, as the generated URL contains the locale in the generated URL.

We have completed our skill and we want to see how it works . Before we try it out please save your project and check there is no error message.
Once saved, select one scene in your “Map view” (e.g: background music) and click the tab “Simulate” (play icon). You should see an image like this:

• Simulate from Start will send you to the start node and you will be able to test the full flow.

• Simulate from current will start the simulation from the current node

• Load state XX will allow you to test previously tested and store scenes.

• Voice preview toggle will enable or disable speakers. This is quite useful if you just need to test the flow and don’t want to wait till Alexa reads the say text.

Select “Simulate from Current” (this may take several seconds till SFB prepares the code and audio) and then you will see this image:

From the “Simulate View” you will be able to navigate to any of the available scenes (e.g hear options: ‘continue’, ‘restart’, ‘repeat’, etc) by clicking one of the buttons. If you have variables and images you will also see them in the “Simulate view”.

If you have errors opening the “Simulate view” or is not refreshed go to “File”→“Troubleshooting”→“Clear Voice Preview Cache” and try it again.

In this basic tutorial, we learnt the basics of Skill Flow Builder editor and how to use this powerful tool to create engaging stories for your customers. In order to get started you can check the resources aboves, and star building your own projects!

• Skill Flow Builder Editor
• Basic Skill Flow Builder Syntax
• Advanced Skill Flow Builder Syntax
• Skill Flow Builder Reference
• Speech Synthesis Markup Language (SSML) Reference
• Understand Alexa Presentation Language (APL)