VOGO Voice – Knowledge Base

Socrata: Stats by Date

Estimated reading time: 6 min

Socrata, a web-based data repository is a scalable, cloud-based integrated solution that offers a simple and intuitive method via its open data platform to deliver universal access to government data. This cloud-based service known for its built-in capability to create a classic visual representation of government domain-specific data through a web interface in the public interest thereby allows users the privilege to query, analyze and share information. 

This comprehensive tutorial serves the purpose of illustrating through a specific use case i.e. retrieve stats by date using a Socrata dataset. Let’s outline the process by citing an example of how to retrieve a resultset of the total number of Pierce County Military Veterans unemployed in the year 2017. To illustrate this example the data records retrieved will be that of the year 2017, the reason being the respective Socrata dataset called to action holds records of unemployed veterans from 2013 to 2017 and the information the dataset contains is indexed by year.

Prerequisites: 

  •  VOGO Voice account: https://www.vogovoice.com/
  • Access rights to the Intents section under Settings.
  • Access rights to Interaction builder platform.
  • 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 Datasite field, input the Base URL of the open data portal to which access is intended. Here the input Datasite 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 to retrieve data on the total number of veterans living in Pierce County who were unemployed during the year 2017 and provide a corresponding record of the resultset based on the user input date.

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 in the year {date}”, “Tell me the number of veterans 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/

Steps to Configure the Socrata connector instance

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 return a resultset of data representing the stats of veterans who were unemployed in the year 2017. To accomplish the aforementioned task the Add Variables component has to be implemented within the interaction flow alongside the response cards and the respective connector instance with the query formatted using the SoQL syntax.

  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 make use of a Socrata connector instance to attain the stats of the veterans unemployed. It will query a dataset holding a record of veterans living in Pierce County who are looking for work or waiting to return to work and are available to work in 2017, and provide a resultset based on the user input date.
  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 in the year 2017.
    The same message will be replicated in the Reprompt field which can be edited for brevity.
    Reprompt: How many veterans were unemployed in the year 2017
  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 during the year 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 field 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 accordingly based on the user input date value assigned in the Add Variables component.
Select Veterans_Unemployed WHERE Year = '{{var.tmpYear}}'

To learn how to write SoQL queries visit https://dev.socrata.com/docs/queries/query.html

9. Drag and drop another Response component onto the flow canvas. You can alternatively right click on the anchor icon and choose the response component.
10. Connect the Socrata connector instance to the Response card.
11. 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 data on the number of unemployed veterans based on the user input date.

     Say: The number of unemployed veterans in the year {{var.tmpYear}} 
                 is 
                {{connectors.c1.first.Veterans_Unemployed}}

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

  1. 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.
  2. Populate the required fields and click the Save button. 
    Title: Veterans Unemployed
    Display Message: The number of unemployed veterans in the year {{var.tmpYear}} 
    is 
    {{connectors.c1.first.Veterans_Unemployed}}

For further reference on how to populate the additional fields visit https://university.vogovoice.com/kb/guide-response-component/

The screenshot below captures the aforementioned interaction flow

Testing and Validation

1. 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 2017.  
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/

Congratulations! You have successfully created an interaction flow to retrieve data from  a Socrata dataset to attain the number of unemployed veterans based on a user input date.

👍 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.

Tags:
Was this article helpful?
Dislike 0
Previous: Learn More
Next: Socrata Show Chart Example