Internal Data JSON Methods

Objectives

This guide will help you to quickly use your JSON data file (.json) as a data source on the VoiceWorx platform and start using with various skills, you need to perform few steps on the VoiceWorx platform, this document will help you how to do it in a correct way.

Pre-requisites

A VoiceWorx Account

For steps to create a VoiceWorx account, follow the steps at https://docs.voiceworx.ai/general/voiceworx-create-account

A valid JSON data file

You need a valid json file containing some data. If you do not have this, to get started, you can also create a new with sample data provided below. Open notepad, paste the following sample data and save the file as “Sample.json”.

Sample JSON Data:

{

"Contacts": [

{

"name": "Martin",

"contactnumber": "0123456789",

"country": "US"

{

"name": "Bob",

"contactnumber": "1230456789",

"country": "US"

{

"name": "James",

"contactnumber": "1230456789",

"country": "Canada"

}

]

}

This guide is going to use this sample data in demonstration.

Steps

To proceed with these steps, you should have all the pre-requisites satisfied. If you are missing something, please go back and make sure you satisfy all of them.

Once done, you are ready to get started using VoiceWorx platform using Internal Data and the JSON data file.

Step 1 Create a content using JSON file

From the left menu, Navigate to the Content > Content. You should see a page with a list of contents (if any) and a button to add a new content as shown in below screenshot.

Let’s create a new content by clicking on the “ADD NEW CONTENT” button. Once clicked, you should see a screen to provide new content details. Fill the required information as shown in below screenshot and then click on “ADD” button.

Make sure you are selecting Type = JSON, and Source = Upload file so you can upload the JSON file. The file you use must be a valid JSON file with JSON contents else the VoiceWorx platform will not allow you to upload it.

If you do not have JSON file, please refer to the pre-requisites #2

Once uploaded, you should see a success notification and added contents as shown below.

Step 2 Create a new connection for the Internal Data

From the left menu, navigate to the Integration > Connect System. You should see a list of all the connections that you have already created.
Now to initiate creating a new connection, click on the “Connect External Systems” button at the bottom or you can also click on the Plus icon at the bottom right corner

You should see a small popup screen as shown below.

1. Select Custom for the Integration Category
2. Select Internal Content for the System Type
3. Give any name of your choice for the system Instance Name.
4. Click on Connect System button and this should quickly create a connection for the internal Content for you.

You should see a newly created connection as shown in below screenshot.

Now the connection is ready to use with the skill.

Step 3 Create an App to utilize internal data

To create a skill, browse to Custom Apps > Manage Apps and click on Create New Custom App button, you should see a small popup screen as shown below.

Input

Information

Name

You can give any value of your choice.

Custom App Type

Select Search

Step 4 Create a Data Source

A Data Source connects the app with the integration. Once you have an app created, you can go to Data Sources either by clicking on “Setup Data Source” button (as shown in the previous screenshot) or by clicking on “Data Sources” tab.

To create a data source, click on ‘Create New Data Source’ button and you should see a popup screen as shown below

Give a name of your choice and make sure you select the same connection that you have created in Step 2. In this example, it is “My Contacts”. If you want to make this connection as private to you, select the available option “Consider as a Personalized Data Source”. If selected, other users in your organization will not be able to use it.

Now click on Save. Once a data source is created, you are ready to start creating various methods and use JSON Data.

Step 5 Create Methods

By using method, you will be able to access JSON data as well as add new data to the same JSON so you can use new date for various purposes. To access the methods, click on the “Methods” tab which is next to the “Data Sources” tab.

As of the publication date of this document, the VoiceWorx platform supports following methods for the JSON Data,

GetJSONContents
AddRecord
AddRecordToNode

Method: GetJSONContents

You can use this method to pull the contents of your JSON file. The method requires just one parameter as explained below.

Parameters:

Parameter

Sample Value

Info

ContentID

Contacts01

This parameter is used to uniquely identify the content (JSON file) used in Internal Data

Other than these two parameters, you need to provide following standard inputs

Parameter

Info

Method Name

You can give any name. This name will be displayed in the methods list.

Request Type

GetJSONContents

This is the method that you are using

Parameters

As explained in the previous table

Record Limit

Numeric value (e.g. 10)

If Method is returning larger number of records, then you can limit this result by providing this value.

Record JsonPath

Each method returns data in json format and to pick any specific information from the json, we need to specify the Record JsonPath so Voice Worx platform will pick that data in consideration while displaying results.

Example: $.[*]

This selects all the records that is returned.

Record Template

Let’s assume that the following json represents one record.

{

"attributes": {

"type": "Contact",

"url": "/services/data/v47.0/sobjects/Contact/0032w000002GFOVAA4"

"Id": "0032w000002GFOVAA4",

"FirstName": "John",

"LastName": "Bond",

"Phone": "(312) 596-1000"

}

In this example, Phone is at root level and can be accessed by {{Phone}}

So record template can be written as

Phone number of {{FirstName}} {{LastName}} is {{Phone}}

So, when a method is executed, this will be displayed as,

Phone number of John Bond is (312) 596-1000

Note:

Anything written in between {{ }} is represented as a json field and it’s case-sensitive.

{{Phone}} is not same as {{phone}}

Result Template

This indicates how method results should be represented.

Here you go, {{Records}}

Here, {{Records}} represents one or more records separated by a separator.

Sample Response:

{

"Contacts": [

{

"name": "Martin",

"contactnumber": "(678)345 6789",

"country": "US"

{

"name": "Bob",

"contactnumber": "(678) 045 6789",

"country": "US"

{

"name": "James",

"contactnumber": "(678) 123 0456",

"country": "Canada"

}

]

}

Method: AddRecordToNode

This method is useful for adding new records in existing JSON that you have uploaded in the Contents section on the VoiceWorx platform.

This method requires following parameters:

Parameter

Sample Value

Info

ContentID

Contacts01

This parameter is used to uniquely identify the content (JSON file) used in Internal Data

NodePath

$.Contacts

NodePath determines the path or location within the JSON to insert the record.

Record

{

"name": "Joe",

"contactnumber": "(678) 000 6789",

"country": "US"

}

The record in valid JSON format

RecordPosition

First

Last

You can select value for dropdown.

It determines the position of the newly inserted record in the original JSON.

Sample Response:

{"result":"success"}

Method: AddRecord

This method is useful for adding new records in existing JSON that you have uploaded in the Contents section on the VoiceWorx platform. The method is like the previous one with a difference that, it does not require NodePath. It is useful when you have a very simple JSON (just key value pairs).

This method requires following parameters:

Parameter

Sample Value

Info

ContentID

Contacts01

This parameter is used to uniquely identify the content (JSON file) used in Internal Data

Record

{

"name": "Joe",

"contactnumber": "(678) 000 6789",

"country": "US"