The None, One, Many modelling of solutions when implemented in an interaction flow emulates the principle made use of in programming languages while dealing with a variable that holds no object, one object or many objects. Similar is the underlying analytic idea brought into effect while determining whether an algebraic equation has one, infinite or no solutions.
This instructional tutorial aims at illustrating a specific use case on how to design a flow in order to generate a None, One, Many results/solutions oriented interaction. To accomplish this purpose a Socrata dataset that holds the records of the total number of Pierce County unemployed veterans indexed by the year 2013-2017 is put to use to build the desired interaction model. What’s unique about this tutorial is that it posits two variant options: Method 1 (using Check Variable component) and Method 2 (simplified version using {{#if}} {{else}} {{#if}} template condition to produce the same intended result but by addressing the three aforementioned expressions of possibilities respectively.
Checklist of Benefits for Method 1 vs Method 2
- More choices in pathing
- Less template using within fields
Prerequisites:
- VOGO Voice account: https://www.vogovoice.com/
- Access rights to the Intents section under Settings.
- Access rights to Interaction builder platform.
- Socrata 4×4 Dataset Identifier and Datasite URL.
- Understanding of how to write SoQL queries.
Setting up a Socrata connector instance
In order to create a Socrato connector instance
1. Log into your VOGO Voice account to be directed to VOGO Voice Management Console (https://account.vogovoice.com)
2. Navigate to Settings on the top right-hand corner of the Dashboard and select Integration from the list of tabs displayed.
Settings > Integration
3. Click on the Add Button on the top left-hand corner of the screen.
4. In the Select Account Type window, choose the Socrata icon from the list of connectors and click Create Connector button which opens up Add Socrata Connection window.
5. Populate the required fields in the Add Socrata Connection window.
Field values
Provide the Name assigned to the instance of the connector created.
In the Data site field, input the Base URL of the open data portal to which access is intended. Here the input Data site is internal.open.piercecountywa.gov
The additional parameters in the Add Socrata Connection window are optional fields that need to be populated depending on the requirements of the skill that demand access to private datasets.
To learn more about the additional parameters refer to the Add Socrata connector guide: https://university.vogovoice.com/kb/socrata/
6. After filling in the required fields click the Save button to set up and integrate the connector instance with the platform.
Create a custom intent
Create an appropriate intent to be invoked for executing an interaction flow mapped to it such that it will return records addressing the three probable solutions (i.e. none, one, many) by making use of the data containing the number of unemployed veterans living in Pierce County from 2013 to 2017.
Create an intent titled ‘Veterans Unemployed’ with a set of suitable sample utterances mapped to it. Let’s say the sample utterances are: “How many veterans were unemployed”, How many veterans were unemployed in {date}“How many veterans were unemployed in the year {date}” where ‘date’ is the slot name. Assign the slot type to ENVIRONMENT_Date, which is a global slot with predefined values.
To learn how to create custom intents refer the guide: https://university.vogovoice.com/kb/creating-intents/
Method 1 – Using Check Variable component
Once the Socrata connector has been created, navigate to Interactions and click on the Interaction button at the bottom right-hand corner of the screen. Select the ‘Veterans Unemployed’ intent to be directed into the Interaction builder platform.
Now let’s create an interaction flow to attain a resultset that will represent the three possible solutions i.e. none, one, many while querying a record of data representing the number of veterans who were unemployed from 2013-2017. To accomplish this task a Method 1 and Method 2 interaction model will be implemented wherein the former method would involve configuring the Check Variable and Add Variables components alongside its respective Connector instance and Response cards thereby allowing it the flexibility to create a continuation of pathing with the aid of expectations if needed. Whereas, the latter method would be a simplified version modeled using the {{#if}} {{else}} {{#if}} template condition within the Response card along with configuring an Add Variables component and a Connector instance thus limiting it to a listing of three different paths simulating an A, B, C order.
1. In the flow diagram area, you will be able to see the Start and Response component.
2.Roll the mouse over the Response component to see the voice, computer and camera icon on the top right-hand side of the component.
3.Clicking on the Voice icon opens a Speak pop-up window with a field titled Say wherein you need to type the voice action intended to be spoken to the user in regard to Veterans Unemployed intent.
Say: In this example we will look at how to query a dataset holding a record of unemployed veterans living in Pierce County from 2013-2017 to provide a resultset representing the three different possibilities of none, one, many solutions.
4. Check the checkmark box in the Expect Response and type in the suitable Prompt message to proceed with the flow.
Prompt: To know the total number of unemployed veterans, ask How many veterans were unemployed.
The same message will be replicated in the Reprompt field which can be edited for brevity.
Reprompt: How many veterans were unemployed.
5. Populate the field under Expectations by selecting the Global Intent Next from the drop-down list and then click the Save button at the bottom of the window.
👍 Note: Ensure to click the Save button to save the interaction flow as and when edits are made.
6. Drag and drop the Add Variables component onto the flow canvas and connect the anchor symbol of Next on the Response card to the Add Variables component
🖍Note: To interconnect the different components click on their respective Anchor symbols so as to chain and hold them in the interaction flow.
1. Configure the Add Variables component by adding the key-value pair as shown below. Set the data type as Function for the value dateGet and add the arguments inputs.date.end and year with its respective datatypes chosen as Path and String . The dateGet function is purposed to get the specified type from the date. Whereas, the two aforementioned arguments perform the task of attaining the end date for the user input date and then differentiates the type of date by date/month/year respectively. After the differentiation of the date type is carried out the year is separated from the user input date. The objective here is to produce the desired resultset of obtaining records of unemployed veterans in the instance of querying an array of data that holds records in the year range of 2013-2017.
🖍Note: The purpose of configuring the Add Variables card is to perform the task of calling to action the value assigned using the variable name in the subsequent response card within the interaction flow.
To know more about data types, visit https://university.vogovoice.com/kb/data-types-functions/
7. Connect the anchor symbol of Next on the Add Variables card to the Socrata connector instance.
8. Double click the Socrata component, or click the pencil to access the Configuration window and fill in the required fields to query and retrieve the desired data from the specific dataset.
Setting up the configuration fields for c1
Name: The name is provided by default and can be changed manually. It is used to identify the connector instance and how it is referenced throughout the flow.
Data Set: In this field provide the 4×4 Dataset Identifier, in this instance being n4tz-zswx for the respective dataset from the open data catalogs to which access is intended. It will be provided in the description column of the chosen dataset and the dataset identifier will also show up in the last part of the dataset URL as well.
To know more on how to locate the Dataset Identifier visit: https://university.vogovoice.com/kb/socrata/
Query: “Socrata Query Language” (SoQL) is the query language used to filter the datasets. Here a query is formulated to retrieve data representing the number of unemployed veterans from the Socrata dataset and return a resultset limited to a record of three sorted in descending order.
SELECT Veterans_Unemployed, Year
{{#if inputs.date}}
WHERE Year = '{{var.tmpYear}}'
{{/if}}
ORDER BY Year DESC
LIMIT 3
To learn how to write SoQL queries visit https://dev.socrata.com/docs/queries/query.html
9. Drag and drop the Check Variable component, a decision-making component onto the flow diagram area and connect the anchor symbol of Next on the Socrata connector instance to the Check Variable component.
10. Configure the Check Variable component with a test condition, here the general idea being to evaluate using the relational operator is equal to for the purpose of assessing and returning the resultset as 0, 1 or more than 1 records thereby presenting the three possibilities of none, one, many results based on the user-input value and also when the input value is not provided.
1. While configuring the first Check Variable component, define the test condition using the relational operator is equal to test if the length of the array of objects returns zero records.
2. Populate the left and right-hand side of the Configuration window as in the screenshot shown below. Set the data types accordingly based on the inputs.
Left-Hand side: connectors.c1.length (choose data type as Path).
Right-Hand side: 0 (choose data type as Number).
Upon testing the condition, the subsequent pathing will be modeled accordingly i.e. if the test condition returns true the flow should be linked to ‘Then’ and if it returns false, it needs to be linked to ’Otherwise’.
11. Drag and drop another Response component onto the flow canvas and connect the anchor symbol of this Response card to the ‘Then’ on the configured Check Variable component.
12. Click on the Voice icon of the Response card to open up the Speak pop-up window and type the voice action intended to be spoken to the user to provide a suitable response if the test condition returns ‘0’ records.
Say: Sorry there were no results found for {{var.tmpYear}}.
To learn about different template engines to be followed to run functions visit https://university.vogovoice.com/kb/template-engine/
To add a display message in a video-enabled voice-assisted device
- Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
- Populate the required fields and click the Save button.
Title: Veterans Unemployed
Display Message:Sorry there were no results found for {{var.tmpYear}}.
For further reference on how to populate the additional fields visit https://university.vogovoice.com/kb/guide-response-component/
13. Now drag and drop another Check Variable component onto the flow canvas and connect its anchor symbol to the ‘Otherwise’ of the already configured Check Variable component.
1.
- While configuring the second Check Variable component, define the test condition using the relational operator is equal to test if the length of the array of objects returns 1 record.
- Populate the left and right-hand side of the Configuration window as in the screenshot shown below. Set the data types accordingly based on the inputs.
Left-Hand side: connectors.c1.length (choose data type as Path).
Right-Hand side: 1 (choose data type as Number).
14. Drag and drop another Response component onto the flow canvas and connect the anchor symbol of the Response card to ‘Then’ on the second Check Variable component. This flow linked to ‘Then’ represents the test condition when returned true.
15. Now drag one more Response card onto the flow canvas and connect the anchor symbol of the Response card to ‘Otherwise’ on the second Check Variable component. This flow linked to ‘Otherwise’ represents the test condition when returned false.
16. Click on the Voice icon of the Response card linked to ‘Then’ of the Check Variable component to open up the Speak pop-up window and type the voice action intended to be spoken to the user to provide the response if the test condition returns true thereby returning a result of ‘1’ record.
Say: In the year {{var.tmpYear}} there were
{{connectors.c1.first.Veterans_Unemployed}} unemployed veterans.
To add a display message in a video-enabled voice-assisted device
- Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
- Populate the required fields and click the Save button.
Title: Veterans Unemployed
Display Message:In the year {{var.tmpYear}} there were
{{connectors.c1.first.Veterans_Unemployed}} unemployed veterans.
17. Click on the Voice icon of the Response card linked to ‘Otherwise’ of the Check Variable component to open up the Speak pop-up window and type the voice action intended to be spoken to the user to provide the response if the test condition returns false, thereby returning a record of more than 1 by looping through the list of results present in the database, thereby satisfying the condition of ‘Many’ results.
Say: {{#each connectors.c1}}
Veterans unemployed in {{Year}} were {{Veterans_Unemployed}}.
{{/each}}
To add a display message in a video-enabled voice-assisted device
- Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
- Populate the required fields and click the Save button.
Title: Veterans Unemployed
Display Message:{{#each connectors.c1}
Veterans unemployed in {{Year}} were {{Veterans_Unemployed}}
{{/each}}
The screenshot below captures the aforementioned interaction flow for Method 1
Method 2 – Using {#if}} {{else}} {{#if}} template condition
To accomplish Method 2 follow the instructional steps starting from the beginning of the tutorial until Step 8 .i.e up to the query part while configuring the Socrata connector instance.
9. Then drag and drop a Response component onto the flow canvas and connect the anchor symbol of the Response card to the ‘Next’ of the Socrata component.
10. Click on the Voice icon of the Response card to open up the Speak pop-up window and type the voice action intended to be spoken to the user to provide the three possible responses by employing the {{#if}} {{else}} {{#if}} template condition thereby satisfying the ‘None, One, Many’ condition in a single action.
Say: {{#if connectors.c1.length '=' 0 }}
Sorry there were no results found for {{var.tmpYear}}.
{{else if connectors.c1.length '=' 1 }}
In the year {{var.tmpYear}} there were {{connectors.c1.first.Veterans_Unemployed}} unemployed veterans.
{{else}}
{{#each connectors.c1}}
Veterans unemployed in {{Year}} were {{Veterans_Unemployed}}.
{{/each}}
{{/if}}
To add a display message in a video-enabled voice-assisted device
- Click on the Computer icon, and type in a condensed version of the voice message in the field titled Display Message of the Show pop-up window.
- Populate the required fields and click the Save button.
Title: Veterans Unemployed
Display Message:{{#if connectors.c1.length '=' 0 }}
Sorry there were no results found for {{var.tmpYear}}.
{{else if connectors.c1.length '=' 1 }}
In the year {{var.tmpYear}} there were {{connectors.c1.first.Veterans_Unemployed}} unemployed veterans.{{else}}
{{#each connectors.c1}}
Veterans unemployed in {{Year}} were {{Veterans_Unemployed}}
{{/each}}
{{/if}}
The screenshot below captures the aforementioned interaction flow for Method 2
Testing and Validation
a) Testing for None
When the connector instance is called to action it returns zero records (none) based on the user input date. Here the input date for testing is given as 2018 for which there are no records in the database as the year range for which it holds records is from 2013-2017.
- Click on the Test button next to the Flow Editor button on the interaction builder platform.
2. In the Tests pop-up window that appears click the + button on its top right-hand corner.
3. Fill the Name field of the Test Response window that shows up.
4. In the Conversation section of the Test Response, the intent ‘Veterans Unemployed’ will be auto-generated in the User invokes field as shown below.
1. Fill the ‘With slots’ field under Conversation with the input date as 2018.
5. Click the plus button within the Conversation Section to open up an additional field titled User Invokes. Ensure to populate this field by selecting the Next intent called to action within the interaction flow.
6. Finally, click the Save button to save the input and perform the test.
7. To validate the Test Response, click on the lightning symbol on the left-hand side of the test case.
8. On the resultant Test Response window, the blue chat bubbles will cumulatively present the previously input message within the Response component. The single lightning bolt symbol in yellow represents the Socrata connector instance.
9. Click on the chat bubble to see the details of the individual responses. To take a detailed look at the data fetching part of the connector instance, click on the lightning bolt icon highlighted in yellow.
To know more about testing an interaction refer https://university.vogovoice.com/kb/testings/
b) Testing for One
Repeat the same steps as carried out while performing Testing for None with the only exception being to populate the With slots field with any year from 2013 to 2017 as the database holds records only during the specified year range. When the connector instance is called to action it returns (1) one record based on the user input date.
c) Testing for Many
Repeat the same steps as carried out while performing Testing for None with the only exception being to leave the With slots field empty. When the connector instance is called to action it returns many records because it loops through a list of records ranging from 2013 -2017 since a specific user-input date has not been provided in the With slots field.
Congratulations! You have successfully created an interaction flow modeled on the ‘None, One, Many’ concept of returning results from an array of data using either methods or both in order to retrieve data from a Socrata dataset so as to attain the number of unemployed veterans by providing a user input date and without. The two uniquely variant methods are simple and unique as one uses the Check Variable component and the other makes use of the {{#if}} {{else}} {{#if}} template condition to help you recreate custom skills of your choice.
👍 Note: To test the functioning of the interactions on your device you have to deploy the custom skill to facilitate the skill with the new edits. To accomplish this, click on the Deploy button seen at the bottom of the Skill Settings pop-up window.
To know how to deploy a custom skill visit https://university.vogovoice.com/kb/deploying-a-skill/
To learn about Socrata connector, click here.