Automatically Update and Publish Your Skill’s Slot Values with the Reference-Based Catalog Management API

We’re excited to announce automatic scheduled updates for the reference-based catalog management API, a new way to update your skill’s slot values from an external data source and update your live skill automatically. This is especially useful if you have a skill with a large catalog of slot values that frequently change, like that of a restaurant menu. Setting up automatic slot value updates with dynamic catalog updates will save you time by preventing you from manually having to update your skill, and improve your customer experience by ensuring you skill is always up to date.

Below are a few use cases where scheduled catalog updates may save you time and improve skill accuracy:

Recipe and Restaurant Skills
Recipe and restaurant skills are very popular on Alexa. Before this feature, maintainers of the skill would have to manually rebuild the list of ingredients, recipes, or meal options available to their customers on a regular basis. After this launch, developers can set up the jobs once and have the skill update their live models without any additional developer effort.

Movies/Cinema Skills
We also noticed that skills that give customers movie synopses, showtimes, or reviews, frequently updated their content in a manual fashion, or had complex work-arounds to integrate those updates into their deployment pipelines. Now, these skills can deliver fresh content automatically as developers update the catalog’s external data source.

Q&A/Trivia Skills
Another large category — skills that offer quizzes, question and answer content, or trivia, face the same challenges as Recipe/Restaurant and Movies/Cinema skills. With this update, developers can build dynamic skills can provide a positive customer experience through regularly updated content.

With the reference-based catalog management API, you can specify frequency or criteria for when Alexa should update and rebuild the slot, and schedule catalog data — significantly reducing overhead in your efforts to maintain catalog updates, and enabling opportunities for automation and streamlining deployment.

To illustrate the capabilities of the API and the latest automatic update feature, you’ll build an Alexa skill that lets you schedule updates to a list of ingredients used in a recipe.

In this demo, you’ll use the AWS CLI and ASK CLI to create:

• A new skill, Recipe Ingredients
• A reference-based model catalog to maintain a dynamic list of ingredients
• Ingredients for the catalog

You can follow along with the instructions and code below.

You’ll use the ASK CLI to create and manage an Alexa-hosted skill. Make sure your ASK CLI is up to date. At the time of this writing, the latest version is 2.15.0. To install or update your version, run the following command:

You’ll use Git to push your code to the Alexa Skills Kit. Make sure you have Git installed on your computer.

Start by opening your terminal and navigating to a new project folder. Use “ask new” to create a new skill. This demo will use NodeJS as the runtime.

Choose your preferred option for hosting your skill’s backend resources. In in this, demo we’ll use “Alexa-hosted skills”:

Choose the appropriate locale for your skill, e.g., “en-US”:

Choose the default region for your skill, e.g., “us-east-1”:

and give your skill the name of “Recipe Ingredients” and a folder name of “RecipeIngredients”. Change your directory to the “RecipeIngredients” folder that is created for you:

In a few easy steps, you’ll create an interaction model catalog to store ingredients that you or users of your skill would use to add to a list.

Copy ingredients.json from https://github.com/alexa-labs/reference-based-catalog-management/blob/master/ingredients.json to your “RecipeIngredients” directory.

You need to upload this file somewhere so your skill can reference it. You can choose to host this file on a publicly accessible website or one you own, or host on Amazon S3. For S3, you can use the AWS console or the AWS CLI to upload the file to an S3 bucket. An AWS CLI example to upload to Amazon S3 is shown below:

Be sure to replace “[bucket-name]” with the name of a bucket you have write permissions to. Note the use of Amazon S3’s Access Control List --acl property of “public-read“, so that the catalog can ingest the ingredients.

Now, create the first version version of your catalog. You can think of catalog versions as your latest-and-greatest list of entities, in this example, a list of ingredients. Note, the --source-url parameter is the HTTPS link to the ingredients file in your S3 bucket. For us-east-1, for example, it might look something like https://my-bucket.s3.amazonaws.com/ingredients.json

You should see “Command executed successfully!” after creating your catalog version.

You created a sample project at the beginning of this blog post when you used the ask new command. You’ll update a couple of files in your project before deploying and testing your skill.

The ask new command created a “skill-package” folder in the root of your RecipeIngredients directory. Navigate to your “./skill-package/interactionModels/custom/” directory:

Your skill’s interaction model is a JSON file that lives in this directory, and is named after the locale you chose when you created the skill, for example, en-US.json.

Using a text editor, replace the contents of your interaction model (e.g., en-US.json) with the contents at https://github.com/alexa-labs/reference-based-catalog-management/blob/master/en-US.json. Notice that the invocation name is now “recipe ingredients”. Make sure to update the catalogId value near the bottom of the file to reflect the `catalogId` you created in Step 1. Save your file.

Back in your command line, navigate to the “lambda” folder. Replace the contents of “index.js” with the contents at https://github.com/alexa-labs/reference-based-catalog-management/blob/master/index.js, then save your file and return to the command line.

Return to the root directory of your project so that you can deploy your skill. Since we choose “Alexa-hosted” as our skill’s backend, deploying our skill will be done with Git. When you push your files, the master branch gets deployed to skill's development stage. The prod branch gets deployed to skill's live stage. We'll stage our changes and deploy to the master branch, so that we can test our code.

Pushing your code automatically enables your deployed skill. After about a minute or so, your skill’s model will be built, and you can start testing it on your device or using the ask dialog command:

Start with “open recipe ingredients,” then “help” to see some of the commands you can use:

Now let’s add an ingredient we know exists in our ingredients.json file. Try “add black pepper to my ingredients list”:

Now try to add an ingredient that does not currently exist in your ingredients.json file. Try “add mushrooms to my ingredients list”:

So, what happened with those mushrooms we tried to add? They weren’t in our original ingredients.json list, so our skill couldn’t add them to our ingredients list — but we can add them to our catalog so that they become available. Consider a scenario where you might want your catalog to update on a particular schedule, and as part of that update, add new or missing items. You might be creating a recipe skill where a new recipe is released each week, and you’ll want the catalog to reflect the new ingredients automatically. You can specify the frequency or the criteria for when Alexa should update and rebuild the slot and the catalog data through dynamic updates. Let’s take a look at how that works:

To take advantage of dynamic updates for your custom slot, you setup a simple data pipeline to

1) Specify the frequency of the catalog update, and
2) Link the catalog updated with a referenced entity (a shared slot ID and/or the skill ID of your skill).

Data pipelines for dynamic updates are managed through the following Alexa Skill Management API (`smapi`) interfaces:

• Create/Update CatalogAutoRefresh
• Read CatalogAutoRefresh
• Delete CatalogAutoRefresh
• Cancel CatalogAutoRefresh
• Disable CatalogAutoRefresh
• List jobs
• List job definitions

Each interface takes as input a job definition that determines the action the API will take. Let’s take a look at the step-by-step process for setting up dynamic updates, starting with the use of the the Create/Update CatalogAutoRefresh interface.

1. Create a Job Definition to specify the frequency of updates

First, define a job definition for your interaction model. The format for your job definition should be a JSON string or file. In this case, you’ll define your job definition in a file called “CatalogAutoRefresh.json”. First, set the vendorId value to your vendor ID. If you don’t know your vendor ID, visit https://developer.amazon.com/mycid.html. Specify the jobDefinition “type” to “CatalogAutoRefresh,” which supports time-based configurations for catalogs. We specify the catalog ID (as created in Step 1), specify and specify a trigger of type “Scheduled” that sets the hour and dayOfWeek for which the catalog will be automatically updated:

Note that:

• “hour” refers to the hour of the day (in US Pacific time) and can only be 0, 4, 8, 12, 16, 20
• “dayOfWeek” is optional. If it is unset, your catalog is refreshed each day. If you set this value, “dayOfWeek” refers to the day of the week where
  • 0 = Sunday
  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4= Thursday
  • 5 = Friday
  • 6 = Saturday

With your job definition defined, you can now use ask smapi to submit your CatalogAutoRefresh job via the following command:

2. Specify the interaction model that will be triggered for an update whenever a catalog is refreshed

Now, create a second job definition that will create a link between the schedule you just created and your skill. Call this file “ReferenceVersionUpdate.json”.

Note that:

• The “locale” must be the same locale in which you built your skill.
• You must specify your skill ID in your resource “id” value. You can find your skill ID for your skill by using ask smapi list-skills-for-vendor to retrieve your skill, or by visiting the Alexa Developer Console.
• The references array can specify multiple catalogs, but in this example, only one catalog (i.e., the ingredients catalog) is necessary.

With the job definition in place, submit it as before, using ask smapi to specify this latest JSON file:

Your catalog will now update, automatically, on the day and hour which you specified. When your catalog updates, your skill will update as well. In this particular example, at 4AM Pacific time every Wednesday, the catalog will be updated based on the contents of the ingredients.json file you created in Step 2 and uploaded to Amazon S3. If we added “mushrooms” to our ingredients list, it would be available to our skill after the scheduled update was complete.

You have now created an interaction model catalog for a sample recipe skill, seeded the catalog with ingredients, and specified a schedule for how often your skill should update the list of ingredients. We’re excited to see how you use these new tools to make your skill maintenance a breeze, and please let us know how we can make it even easier.

Jeff Nunn