Skip to content

Commit

Permalink
Added entity resolution and dynamo docs
Browse files Browse the repository at this point in the history
  • Loading branch information
John Kelvie committed May 16, 2018
1 parent 08dcacd commit fa22e51
Show file tree
Hide file tree
Showing 3 changed files with 190 additions and 4 deletions.
8 changes: 6 additions & 2 deletions README.md
View file
Expand Up @@ -147,12 +147,16 @@ We also support the Display Interface! [Read more here](https://github.com/bespo
## Dialog Interface
**NEW** We also support the Dialog Interface. [Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/Dialog.md).

## External Calls
**NEW** We also support mocking external calls, such as ones made to the Address API.
## Mocking External Calls (Dynamo and Address API)
**NEW** We also support mocking external calls, such as ones made to the Address API and Dynamo.
[Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/Externals.md).

This allows for testing without relying on the actual calls, which are difficult if not impossible to configure for unit tests.

## Entity Resolution
**NEW** We support the entity resolution request payloads.
[Read more here](https://github.com/bespoken/virtual-alexa/blob/master/docs/EntityResolution.md).

## How Do I Talk To You?
Easy, you can open [an issue here](https://github.com/bespoken/virtual-alexa/issues), or find us on [our Gitter](https://gitter.im/bespoken/virtual-alexa).

Expand Down
145 changes: 145 additions & 0 deletions docs/EntityResolution.md
View file
@@ -0,0 +1,145 @@
# Virtual Alexa and Entity Resolution
Virtual Alexa now supports Entity Resolution. To take advantage of it, just use Virtual Alexa as normal -
it will now automatically add the correct resolution information to your request payloads, like so:

```
{
"request": {
"locale": "en-US",
"requestId": "amzn1.echo-external.request.c89fbf6b-59be-468f-acc5-0e7d3da091d3",
"timestamp": "2018-05-16T16:36:05Z",
"type": "IntentRequest",
"intent": {
"name": "CountryCode",
"slots": {
"countryCodeSlot": {
"name": "countryCodeSlot",
"value": "England",
"confirmationStatus": "NONE",
"resolutions": {
"resolutionsPerAuthority": [
{
"authority": "amzn1.er-authority.echo-sdk.amzn1.echo-sdk-ams.app.ad9e4502-4b6e-4060-b601-1fd680eb0d81.COUNTRY_CODE",
"values": [
{
"value": {
"id": "UK",
"name": "UK"
}
}
],
"status": {
"code": "ER_SUCCESS_MATCH"
}
}
]
}
}
}
}
}
}
```

This is generated by calling:
```
virtualAlexa.utter("I live in England")
```

## What Is Supported?
### Multiple synonym matches
When multiple synonyms match a a slot value, more than one resolution will be sent, like in the example below:

```
{
"name": "countryCodeSlot",
"value": "Europe",
"confirmationStatus": "NONE",
"resolutions": {
"resolutionsPerAuthority": [
{
"authority": "amzn1.er-authority.echo-sdk.amzn1.echo-sdk-ams.app.0fd9931c-4d0f-4e70-ae4b-1244216010fa.COUNTRY_CODE",
"values": [
{
"value": {
"id": "DE",
"name": "DE"
}
}
],
"status": {
"code": "ER_SUCCESS_MATCH"
}
},
{
"authority": "amzn1.er-authority.echo-sdk.amzn1.echo-sdk-ams.app.0fd9931c-4d0f-4e70-ae4b-1244216010fa.COUNTRY_CODE",
"values": [
{
"value": {
"id": "UK",
"name": "UK"
}
}
],
"status": {
"code": "ER_SUCCESS_MATCH"
}
}
]
}
}
```

### Builtin Slot Extensions
When extending builtin slots, the status code will be set correctly based on whether an extension is matched, like so:

```
{
"name": "citySlot",
"value": "city by the bay",
"confirmationStatus": "NONE",
"resolutions": {
"resolutionsPerAuthority": [
{
"authority": "amzn1.er-authority.echo-sdk.amzn1.echo-sdk-ams.app.e768a0d1-d59c-4fb9-aa7e-84f285315a94.AMAZON.Cities",
"values": [
{
"value": {
"id": "San Francisco",
"name": "San Francisco, CA"
}
}
],
"status": {
"code": "ER_SUCCESS_MATCH"
}
}
]
}
}
```

And if there is no match for the custom slot value, that will also be indicated:

```
{
"citySlot": {
"name": "citySlot",
"value": "Chicago",
"confirmationStatus": "NONE",
"resolutions": {
"resolutionsPerAuthority": [
{
"authority": "amzn1.er-authority.echo-sdk.amzn1.echo-sdk-ams.app.ef3fc3cd-03d7-414e-ab84-ca08730413ce.AMAZON.Cities",
"values": [],
"status": {
"code": "ER_SUCCESS_NO_MATCH"
}
}
]
}
}
}
```

Happy testing!
41 changes: 39 additions & 2 deletions docs/Externals.md
View file
Expand Up @@ -3,8 +3,8 @@ Virtual Alexa can mock external calls easily.

It handles:
* Address API
* Dynamo (Coming Soon)
* List API
* Dynamo
* List API (Coming Soon)

## Why Mocks?
We use mocks because it is either difficult or impossible to write unit tests with the **real** services.
Expand All @@ -23,6 +23,43 @@ For other calls, such as the Address API, it is essentially impossible to do wit
This is because the Address API relies on a unique security token from Amazon,
and the only way to get it is to be running inside Alexa. An emulator like Virtual Alexa just cannot do it.

## DynamoDB
To mock calls to DynamoDB, simply enable our DynamoDB mock service.

Example:

```javascript
const virtualAlexa = VirtualAlexa.Builder()
.handler("index.handler")
.interactionModelFile("models/en-US.json")
.create();

virtualAlexa.dynamo().mock();
```

The Dynamo DB mock will be called automatically for get and put requests to Dynamo, without hitting the service itself.

Records will be stored locally in memory instead of in Dynamo.

Dynamo can be used in the tests by simply calling the Dynamo SDK in the normal way:

```
const getParams = {
Key: {
ID: {
S: "The Beatles",
},
},
TableName: "Musicians",
};
const dynamo = new AWS.DynamoDB();
dynamo.getItem(getParams, function(error, data) {
assert.equal(data.Item.Genre.S, "Rock");
});
```

Complete information on [AWS SDK for Node.js is here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html).

## Address API
To mock the Address API with Virtual Alexa, simply supply the a desired return value to the [AddressAPI object](https://bespoken.github.io/virtual-alexa/api/classes/addressapi.html).

Expand Down

0 comments on commit fa22e51

Please sign in to comment.