Know Your MSP

The Idea

With the recent Brexit referendum and general election, people are taking a bigger interest in politics. 1 element of politics that I personally had neglected to investigate had been the Scottish Parliament. Being a resident in Scotland the Scottish government plays an important role in many of the decisions that has an effect on my day to day life.

To this end I initially started work on the Know Your MSP website (currently a working progress). The aim of the site is to make details about Scottish politics easy to obtain and understand, as well as to present data provided as part of the Open Data initiative from the Scottish Government in unique ways and mashed with data from other sources.

To help provide the information that I already have in a way that is accessible to the general public I felt that an Alexa skill is a perfect addition.

Considerations and Concerns

Location API

Initially I had planned to use the location API (specifically the postcode) that Amazon had recently released however, upon investigation I found a couple of issues. For example, if the user does not specify the postcode I wanted to prompt the user to read it out. Unfortunately, this appears impractical as there are no built-in slots that cover postcodes, attempting to create 1 is no mean feat, simply creating a slot with a list of postcodes just does not work at present. This is something I still wish to include but a short-term solution might be to use the postcode and if this does not exist to prompt for their city or constituency.

To Call the API Directly?

I had also considered using the API from the Scottish Government directly however this would have potentially caused a large number of API calls for simple queries. As I am already obtaining the details for the Know Your MSP site I have decided to start developing an API (very basic so far, and being developed as and when needed).

Lambda or HTTPs?

The last consideration is whether to use Lambda or HTTPs. Lambda is a much more appealing proposition at the moment due to the fact you can now receive rebates for usage related to skills. HTTPs would have also been beneficial as the data could be served directly from the server that hosts the information. Upon considering the best option I have opted for a hybrid solution at present. Any data that is fairly static (for example region names and constituency names) are hosted and checked upon using Lambda, when more dynamic data is required Lambda carries out an API call from Know Your MSP, this allows instant updates.

Moving forward using an AWS storage mechanism to house a cache may help improve latency.

The Features

As a starting point the following features are required:

• Ability to list regions.

• Ability to list constituencies.

• Ability to list constituencies in a region.

• Ability to list regional MSP's for a specified region.

• Ability to list constituency MSP's for a specified constituency.

• Ability to find out more information about a specified MSP

Moving forward there are quite a few possible features that I am envisaging adding for example:

• Giving more detailed information about an MSP (stats about the MSP activity, expenses, a bio for the MSP and how long they have been elected for).

• Giving information about how MSP's voted in Holyrood.

• Details regarding past MSP's (data already exists).

• Implement the location API and use the postcode to identify the constituency the user is in (postcode database is already available and stored on Know Your MSP).

Creating the Skill

Prior to continuing I shall make a couple of assumptions. Firstly, I shall assume that you already have an Amazon developer account as well as an AWS account.

Creating the Initial Skill

Firstly, login on the Amazon Developer site. Click on the "Alexa" tab, then click "Get Started", lastly click "Add A New Skill"

We are now in the meat of the skill. I will go through each option in turn. If I do not mention a setting this means that I am leaving it to the default value.

We are currently in the "Skill Information" section. Let's go through the options on this tab.

Skill Type

This allows us to choose what type of skill we are creating. For this skill, we are creating a "Custom Interaction Model".

Language

At present the skills kit supports US English, UK English and German. As this skill is directed towards the UK store I am going to select "English (U.K.)"

Name

This is the name the skill will have in the store and in the Alexa app. For my version of the skill I chose "Know Your MSP" as it matches the name of my site.

Invocation Name

The invocation name is the term used by the user when interacting with your skill. For example, in the phrase "Alexa, open Spotify" Spotify would be the invocation name. The invocation name should be something that is not easily confused with another term. A poor choice of an invocation name can make it difficult for users to interact with your skill. I have chosen "Holyrood Information"

Click on save. Prior to continuing take a note of the Skill App ID. as we will need this shortly. Once the page has saved this is located near the top of the page situated below the skill name. The ID will start with "amzn1.ask.skill.".

Now let's move onto the "Interaction Model" tab. Amazon have recently started a beta for a new Skill Builder that replaces the interaction model tab but you have to enable it for the skill. To enable it click on the black button titled "Enable Skill Builder" and click discard in the popup (the popup is a bug and is displaced regardless upon whether there is anything to save).

Once the page loads click onto the "Code Editor" tab.

You will see a text box that already contains some json, we will replace this.

I have already created the required json and will not fully go through this. To obtain the required json copy the text from THIS link (direct link to the json file hosted on GitHub) into the textbox replacing the content there already. The advantage of this editor is that you can now create the json file using your own tools rather than making the slots and sample utterances within the builder although the new builder does make this job easier in some instances.

Once you have entered the new json you should click on the "Apply Changes" button on the top right

then click "Save Model" then "Build Model" on the top left. The build process can take a little while to complete.

Once complete click on "Configuration".

For the moment, we will stop here and create our Lambda function.

Creating the Lambda Function

In a new tab or window log into the AWS Console. Prior to making our function ensure that our region shows as "Ireland" (this shows at the top right to the right of your name). If it does not ensure to change this. Only certain regions currently support creating Lambda functions that support Alexa.

Now that we have checked that the region is set correctly let's create the function. In the main page type Lambda into the search box and click on the first response.

We are now in the Lambda interface. Click on the blue button called "Create a Lambda function". If you have never used Lambda you may see a "Get Started Now" button instead.

We will now have the option of which blueprint we would like to use. This skill uses numerous files, therefore we will need to upload a zipped file so the blueprint is inconsequential therefore select "Blank Function".

Now that we have selected the blueprint we will be presented with a page that has an empty white outlined box that has an arrow pointing to Lambda. Click on the white box and select "Alexa Skills Kit" and click next.

On this page, we have the following options we need to complete:

Name

This is the name that we will give out function. This can be anything but of course it makes sense to name this something related to the skill. Therefore, I will name this "HolyroodSkill"

Description

This is not required however handy to enter something meaningful that will help identify what the function is for.

Runtime

Lambda works with numerous languages, we are using Node.Js. It is wise to ensure that we are using the latest version available, this will ensure that the version does not become deprecated anytime soon. Therefore, I have chosen "Node.js 6.10".

Code Entry Type

This is initially set to "Edit Code Inline" however this does not allow you to use more than 1 file, this skill relies upon multiple files (such as the json files) therefore we will choose "Upload A Zip File". Once this has been selected we will have the option of uploading a file. Prior to doing this we have 2 things to do.

Firstly, we need to obtain the code for the skill. This is located on Github, this will download the content of the repository but we are really only interested in the content of the src folder. Secondly, when creating our skill, we took a note of the Skill App ID. We now need that ID. Extract the content of the zip file we just downloaded. Go into the src folder and locate index.js and open this in a notepad and locate the following line (line 11):

const APP_ID = '';

The App ID that we obtained earlier should be placed within the quotation marks.

Once you have edited and saved the file compress the content of the src folder and use the "Upload button" to upload this into your Lambda function.

Handler

Although we are not changing this option it is important to point out that if this is incorrect the function will not work. If for example I had named index.js in the src folder as something else this option would need updating to reflect.

Role

The role is quite an important option. This is the option that allows the Alexa Skill to communicate with the Lambda function. If you have not done so already you will need to create a new one. To create one, select "Create A New Role From Template(s)". This will open two further boxes.

Role Name

The role name can be anything of your choosing but as per usual enter something meaningful such as "AlexaSkillRole"

Policy Templates

For policy templates select "Simple Microservice Permissions"

We can ignore the rest of the settings, scroll to the bottom and click next. We will be presented with a summary page, ensure everything is correct and click "Create Function".

We have now finished creating our function however prior to leaving AWS we need to get the ARN for our function. This is displayed on the top right-hand side of the page, copy everything after "ARN - ", it should start with "arn:aws" and end with the name you gave the function.

Finishing the Skill

Now that we have completed the function we can now finish the skill. We left off entering the "Configuration" tab earlier. We will now go through the settings on this tab:

Service Endpoint Type

We have the option of AWS Lambda arn or HTTPs, it should be fairly obvious that we will be choosing Lambda. We would use HTTPs if we were calling a HTTP accessible URL hosted elsewhere.

Once you select Lambda 1 further option opens asking us the region. As we created our function in Ireland we will have to choose Europe, conceivably we could have also created a function in the US and we could specify a function for each region. As this is a UK based function however there is no need to have a US function, if the skill was intended for US audiences as well creating a US endpoint could help reduce latency. Once Europe has been selected 1 further option opens, enter the ARN we copied when we finished creating our function.

The remainder of the options on this page will remain the same. Therefore, we will click "Save" (if you receive an error when trying to save advising the information is out of date, do not worry the page simply timed out, come out and go back into the skill page) then "Next".

We now find ourselves in the "Testing" tab. For the time being we will bypass this tab and click "next" again.

We are now on our penultimate screen, the "Publishing Information" tab:

Category

This is the category that you would like the skill to appear on in the Alexa app and the Alexa store. For this skill, I chose "Education and Reference"

Testing Instructions

All skills go through a certification process. These are the instructions to give the Amazon certification staff to help using the skill. For example, if your skill required account linking you should give them test account details to use for the certification process.

Countries & regions

This helps limit what countries people can use your skill from. I am going to leave this at the default.

Short Skill Description

This is a short description (150 characters or less) that tells a user what the skill does from search pages on the store.

Full Skill Description

When you look at a skill in the Alexa app and read the full details you are reading the content that the creator put into this box. This should give the user a good idea on what the skill does and how to use it. You do not have to give sample phrases they should use, that comes in a moment.

Example Phrases

These are the phrases that you see when you look at a skills description. You can either use a conversation such as:

• Alexa, open Holyrood Information.

• List all regions.

• Tell me about Dundee East.

Or alternatively standalone example phrases such as:

• Alexa, ask skill name what time it is.

• Alexa, ask skill name what temperature it is in London.

If you choose to post a conversational list of phrases only the first should have the wake work (Alexa) and invocation name (Holyrood Information). Each phrase should end with a punctuation mark such as a "?" or a ".".

Keywords

These are keywords that you expect users to search for that your skill may be handy for.

Images

The skill requires 2 images. 1 which is 108px x 108px and another which is 512px x 512px. Some people make the mistake of placing a logo into a speech bubble as they see all the icons in the Skill store having this format. This is not necessary as Amazon add these. There is a tool hosted by Alexa Bible that can be handy to have an idea how your logo may appear. Once everything has been completed on this page click on "Save" then "Next".

We are now on our final tab. The Privacy and Compliance tab. I will not go through each of these, it is important that you read through these options as failure to do so can result in the skill being rejected or even potentially breaking privacy laws dependent upon which country you are in.

The skill is now ready to be submitted for certification. Prior to doing so however read the next section.

Testing Prior to Certification

Of course, prior to releasing any software or services it is important to carry out testing to ensure that it functions as expected. There are a few tools that are useful for this very purpose.

Testing Tab

The testing tab allows you to enter phrases to ensure that your skill responds as expected. This should always be the first port of call for testing.

EchoSim.io

EchoSim.io is a handy service that allows you to use voice commands similar to the way you would a normal echo. If you do not have an Echo available this is a good compromise. Ensure you link the account that you used to create the Alexa Skill.

Testing on A Device

Although EchoSim.io is a good compromise it is no substitute for the real thing. Interacting with the skill on a supported device can alert you to problems other testing may not highlight. As long as the Echo (or any Alexa device) is linked to the same account that created the skill you will be able to interact with it without the need to install the skill.

Beta Testing

Beta testing is a valuable way to test services and products. When creating the skill, you may have noticed a tab entitled "Skills Beta Testing". As long as the skill is ready for certification (i.e. all tabs are completed) you can start a beta testing campaign and invite people by email. Once the recipient receives the invite email they will be able to install the skill and interact with it like any other skill. In an ideal world, you would be able to view them interfacing with the skill (be sure not to guide them) so that you can see how people try to use the skill. If this is not feasible you can request feedback from users within the Beta Testing interface.

Skill Validator Plugin

Amazon have released a plugin that is quite handy for identifying issues with the skill. At present for those that use Firefox you currently need to use the Developer Edition of Firefox. Once you have the developer edition download the plugin from HERE. Be sure to read the instructions after install otherwise the plugin will not work. A nuisance to install but useful nonetheless.

Where Can I Find the Skill?

The skill was submitted for certification on Sunday 25th of June and passed certification on Tuesday 27th of June. This is an extremely good turnaround time. Amazon really are certificating fast these days.

The skill can be found on the Amazon Skill Store.