SalesForce Custom App

Objective

This document will demonstrate how easy it is to integrate SalesForce to the VoiceWorx platform and create methods to pull data.

Pre-requisites

• An active Salesforce Account

An active Salesforce account is required for this integration. The skill will require the user to log into their Salesforce account.

If an account needs to be created, please follow the steps below:

1. Visit https://www.salesforce.com and click “TRY FOR FREE”.

1. This will take the user to the screen below. Fill out the relevant details and complete the registration process.

1. Once the registration is complete, the screen below will appear.

1. The user will receive an email from SalesForce regarding account verification as in the screen below:

1. Click on “Verify Account” button and it will take you to change your password interface. After you change your password, you will be redirected to home page as shown in point no 3.

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 with SalesForce.

The following shows the general steps/activities that will be carried out in setting up this integration. Note: It is advisable to use same email for signup across the 3 channels below. Step 1 -3 below are compulsory.

1. Sign up for Alexa account

2. Sign up for Alexa developer account.

3. Sign up for VoiceWorx platform

4. Ensure you Login With Amazon (LWA) https://developer.amazon.com/alexa/console/ask account is setup by your admin. If you are the account admin, you can follow this instruction to set it up.

5. Set up connection to Salesforce

6. Create a custom skill in Voiceworx.

7. Publish the skill

8. Test the Alexa skill.

Setup connection to Salesforce

1. Login to the VoiceWorx portal at https://portal.voiceworx.ai. The first step to create a Salesforce Custom Skill is : connecting VoiceWorx to your Salesforce account. On the left navigation, under Integration menu, click on Connect System. Click on Add New Connection.

1. On the resulting Connect External System form, fill out the following details, and click on ‘Connect System’.

Integration Category: Custom

System Type: SalesforceCustom

System Instance Name : Salesforce Demo

Note: If a SalesForce Account is running on customer domain tick “Use Custom Domain” checkbox and provide the custom domain URL. Also, if Sandbox account is used then tick “Sandbox” checkbox.

Once you click on “Connect System” button, you will be redirected to the SalesForce login page as shown below. Enter your username and password and click on “Login” button.

Once you are logged in, Salesforce might show a screen with permissions options, allow it. You will be redirected to the VoiceWorx platform with a success screen as shown below.

Now, you have successfully integrated Salesforce with the VoiceWorx platform.

1. Now Salesforce has been successfully integrated with the VoiceWorx platform. Now, click “Return to Integration Configuration” to return to the connections page. SalesforceCustom will appear in the list as shown below.

Create a custom App in Voiceworx

1. To create an app, use the left navigation menu and select “Custom Apps” and then select “Manage Apps”. On the resulting screen, click “Create New Custom App”.

1. Fill following details in the Add Custom Skill window, and click ‘Save’.

Name: Salesforce Custom Skill

Custom Skill Type: Search

Category: None

1. The Custom app gets created. Now we have to create components of the app. Starting from the Data Source.

Create a Data Source

A Data Source connects the app with the integration. On the Data Sources tab, “Create New Data Source”.

1. The following popup screen will appear, add following details and click on Save.

Name: Salesforce DataSource

Integration Configuration:Select Salesforce Integration Config created in Step 2.

Create Methods to fetch the data from Salesforce

1. Next step is to create Methods. Methods allows you to fetch data from Salesforce. The salesforce supported custom queries can be used to define the data to be fetched from the linked Salesforce account.

2. VoiceWorx platform currently supports following Salesforce methods:

3. Get All Objects

4. Get Object Fields

5. Get Object ById

6. Get Object All Records

7. Get SOQL Query Results

8. Create Object

9. Update Object

10. Delete Object

11. For this document, we’ll create only one method. Users can refer to the appendix to explore all other supported methods.

Scenario/ Use Case (Contact Finder):

1. To access the methods, using the top tabs click on “Methods”. Next select the drop down under “Select Data Sources”. Select “Salesforce DataSource”.

1. The method we are going to create is ‘GetContactMethod’. Before actually building the skill, let us run through the scenario of the method. GetContactMethod will be used to get the contact detail of your friends, family or team member stored in Salesforce. This method will be using ‘GetSOQLQueryResult’ method supported by Salesforce.

.

Method: GetSOQLQueryResult

This method requires just one parameter. Please review the information below.

Parameters:

Parameter	Sample Value	Info
SOQLQuery	SELECT Id, FirstName, LastName,Phone FROM Contact WHERE FirstName='John' and LastName='Bond'	This is a standard Salesforce Object Search language (SOQL) query which you can use in different ways

1. Other than these two parameters, provide following standard inputs:

Parameter	Info
Method Name	You can give any name. This name will be displayed in the methods list.
Request Type	GetItems This is the method that you are using
Parameters	As explained in the previous table
Result Type	ListOfRecords (Auto Selected) It indicates that the method can return one or more records
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.
Empty Result Template	When the method does not return any data, this response will be generated. So we can specify something like: “Sorry, I could not find the contact details”
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": "[phone]" } 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 [phone] 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:

[

{

"attributes": {

"type": "Contact",

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

},

"Id": "0032w000002GFOVAA4",

"FirstName": "John",

"LastName": "Bond",

"Phone": "[phone]"

}

]

1. Now let’s us proceed back to method building in VoiceWorx. Click on ‘Create New Method’, and fill out following details in the Create New Method pop up.

Name: GetContactMethod

Request Type: GetSOQLQueryResult

SOQL Query: SELECT Id, Name,Phone FROM Contact WHERE Name='{{ContactName}}'

Result Type: ListOfRecords

Record Limit: 1

Record JsonPath: $.[*]

Empty Result Template: Sorry I could not find phone number for requested name

Record Template: Phone number for {{Name}} is {{Phone}}.

Result Template: {{Records}}

Click: Save

1. Before moving further, you want to test whether the method build is success and the method is able to extract correct data from Salesforce or not. Click on ‘Test’ to test the created method.

1. Now, to test the method, let us go back to the Salesforce portal and create a Contact.

Note: “You can skip this process if you have already created contacts in your Salesforce account”.

Login to login.salesforce.com, enter your credentials. On the Sales section, find Contacts menu. Click on ‘New’. Note the First Name and Last Name you enter here for your test purpose.

1. Let’s continue on our method test from Step 16, click on test and you shall see the test screen below.

On the Parameters section, provide full name of the contact you created in Salesforce in Step 17. Click on Method Test. Then the Result Tab, click Results Test. A correctly build method shall provide you a response similar to the screen shown below. If not, you may want to go through your method to check out the discrepancies between the user guide and your method.

Create Intents

1. In the top menu tabs, select “Intents” and “Create New Intent”. Then select or enter the following:

Fill following details and click on Save

Name: SearchContactIntent

Intent Type: Search

Intent Action: Executive Method

DataSource: Salesforce DataSource

DataSource Method: GetPhoneNumberByName

Create Slots

1. In next step, we have to create Slots. Slots correspond to the parameters in SOQL query that we defined in the method screen. In the top menu tabs, select “Slots” and select “Create New Slot”.

1. Fill the following details.

Note: The Reprompt message is what Alexa will ask if it can’t fill/resolve the person slot. Then select or enter the following:

Name: ContactName

Slot Order: Blank

Reprompt Message: What is the name

Type: Full name

Custom Skill: Salesforce Custom Skill

Intent: SearchContactIntent

Click: Save

Create Utterance

1. Utterance are words spoken to launch specific intents. In the top menu tabs, select “Utterance” and select “Create New Utterance”. Now input or select the following:

Value: What is the phone number of {ContactName}

Custom Skill: Salesforce Custom Skill

Intent: SearchContactIntent

Create Input

1. In the top menu tabs, select “Input” and select “Create New Input”.

Fill the following details:

Name: SearchContactInput

Custom Skill: Salesforce Custom Skill

Custom Intent: SearchContactIntent

Data Source: Salesforce DS

Data Source Method: GetContactMethod

Once the Input is created, click on ManageParameters. You need to follow this step if you have defined Slot.

1. On the resulting screen, click on Input Parameter and add the following details.

Input Parameter Name: ContactName

Parameter: ContactName

Data Type: Text

Publish to Alexa

1. The next step is to Publish the app. Here, we are going to publish to Amazon Alexa.

2. To publish to Alexa, select “Publish” in the top menu tabs then click “Add Skill Publishing”. Then input or select the following:

External Skill Name: SalesForce CRM Demo Skill. (This will be the name of the skill in Alexa. Therefore, make it unique and different from the names of your other skills in Alexa.)

Skill Type: Search

Channel: Alexa

Skill Invocation Name: Salesforce CRM. (This will be what users say to launch your skill in Alexa. It must be in lower case alphabets cannot contain START, BEGIN, STOP, EXIT, LAUNCH and cannot contain number or special characters.)

Uncheck the following: Require account linking, Auto Publish

Optional: Replace all placeholder values in all “Message”. Uncheck all the settings shown in the second image below.

Click: Save.

1. In the top menu tabs select “Publish” then click “Publish to Alexa”.

1. Once in Publish Skill to Amazon Alexa select and do the following:

Selected Skill: Salesforce Custom Skill

Select Amazon Account: LWA Config

Select the LWA account setup by your admin or the one you set up in step 4 above.

Click: Publish To Alexa

1. On the resulting screen, ensure that a success message shows for the publishing steps before clicking the “Go To Alexa Skill”. If success message not shown, click “Go To Skill Publishing” to fix any issue shown in publishing result.

Graphical user interface, text, application Description automatically generated

1. On the Alexa skill page, ensure “Full Build Successful” message is shown in bottom right corner before starting to test skill.

1. Go to “test” tab in the top menu, then below “test” tab change the skill test status from “Off” to “Development”.

1. Invoke skill by typing the invocation name (Salesforce CRM) inserted in the publishing step in Voiceworx. If the invocation is successful, your configured welcome message will be displayed in the developer console.

Congratulations!

You have successfully completed building a SalesForce-Custom Skill.

Appendix

Salesforce Methods

Method: GetAllObjects

This method returns all the objects you have in your salesforce account and it does not require any parameter.

Parameters:

Not Required

Sample Response:

[

{

"activateable": false,

"createable": false,

"custom": false,

"customSetting": false,

"deepCloneable": false,

"deletable": false,

"deprecatedAndHidden": false,

"feedEnabled": false,

"hasSubtypes": false,

"isInterface": false,

"isSubtype": false,

"keyPrefix": null,

"label": "Accepted Event Relation",

"labelPlural": "Accepted Event Relations",

"layoutable": false,

"mergeable": false,

"mruEnabled": false,

"name": "AcceptedEventRelation",

"queryable": true,

"replicateable": false,

"retrieveable": true,

"searchable": false,

"triggerable": false,

"undeletable": false,

"updateable": false,

"urls": {

"rowTemplate": "/services/data/v47.0/sobjects/AcceptedEventRelation/{ID}",

"defaultValues": "/services/data/v47.0/sobjects/AcceptedEventRelation/defaultValues?recordTypeId&fields",

"describe": "/services/data/v47.0/sobjects/AcceptedEventRelation/describe",

"sobject": "/services/data/v47.0/sobjects/AcceptedEventRelation"

}

},

{another record},

{another record},

]

Method: GetObjectFields

This method is used to fetch all the available fields for the specific Salesforce Object.

Parameters:

Parameter	Sample Value	Info
ObjectName	Contact	Salesforce Object name

Sample Response:

Contact object has approximately 61 fields. This method will return those records, one record represents one field.

[

{

"aggregatable": true,

"aiPredictionField": false,

"autoNumber": false,

"byteLength": 120,

"calculated": false,

"calculatedFormula": null,

"cascadeDelete": false,

"caseSensitive": false,

"compoundFieldName": "Name",

"controllerName": null,

"createable": true,

"custom": false,

"defaultValue": null,

"defaultValueFormula": null,

"defaultedOnCreate": false,

"dependentPicklist": false,

"deprecatedAndHidden": false,

"digits": 0,

"displayLocationInDecimal": false,

"encrypted": false,

"externalId": false,

"extraTypeInfo": "personname",

"filterable": true,

"filteredLookupInfo": null,

"formulaTreatNullNumberAsZero": false,

"groupable": true,

"highScaleNumber": false,

"htmlFormatted": false,

"idLookup": false,

"inlineHelpText": null,

"label": "First Name",

"length": 40,

"mask": null,

"maskType": null,

"name": "FirstName",

"nameField": false,

"namePointing": false,

"nillable": true,

"permissionable": false,

"picklistValues": [],

"polymorphicForeignKey": false,

"precision": 0,

"queryByDistance": false,

"referenceTargetField": null,

"referenceTo": [],

"relationshipName": null,

"relationshipOrder": null,

"restrictedDelete": false,

"restrictedPicklist": false,

"scale": 0,

"searchPrefilterable": false,

"soapType": "xsd:string",

"sortable": true,

"type": "string",

"unique": false,

"updateable": true,

"writeRequiresMasterRead": false

},

{record for another field},

{record for another field},…

]

Method: GetObjectAllRecords

This method is used to fetch all the records for the specific Salesforce Object like Contact or Opportunity.

Parameters:

Parameter	Sample Value	Info
ObjectName	Contact	Salesforce Object name
FieldNames	Id, FirstName, LastName,Phone	One or more fields separated by comma

Sample Response:

[

{

"attributes": {

"type": "Contact",

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

},

"Id": "0032w000002GFOPAA4",

"FirstName": "Rose",

"LastName": "Gonzalez",

"Phone": "[phone]"

},

{

"attributes": {

"type": "Contact",

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

},

"Id": "0032w000002GFOQAA4",

"FirstName": "Sean",

"LastName": "Forbes",

"Phone": "[phone]"

}

]

Method: CreateObject

This method is used to create a new record for the Salesforce Object like Contact or Opportunity

Parameters:

Parameter	Sample Value	Info
ObjectName	Contact	Salesforce Object name
RecordJson	{"FirstName": "John", "LastName": "Green", "Phone": "[phone]" }	A valid json with valid field names of the Salesforce Object.

Sample Response:

{

"id": "0032w00000FIZCxAAP",

"success": true,

"errors": []

}

Method: UpdateObject

This method is used to create a new record for the Salesforce Object like Contact or Opportunity

Parameters:

Parameter	Sample Value	Info
ObjectName	Contact	Salesforce Object name
RecordId	0032w00000FIZCxAAP	Salesforce Object Id
RecordJson	{"FirstName": "John", "LastName": "Green", "Phone": "[phone]" }	A valid json with valid field names of the Salesforce Object.

Sample Response:

{

"id": "",

"success": true,

"errors": ""

}

Method: DeleteObject

This method is used to Delete any specific record of Salesforce Object like Contact

Parameters:

Parameter	Sample Value	Info
ObjectName	Contact	Salesforce Object name
RecordId	0032w00000FIZCxAAP	A valid record id

Sample Response:

{

"success": true

}

Method: GetObjectById

This method is used to fetch one specific record for the specific Salesforce Object like Contact or Opportunity

Parameters:

Parameter	Sample Value	Info
ObjectName	Contact	Salesforce Object name
Id	0032w000002GFOPAA4	Salesforce Object Id
FieldNames	Id, FirstName, LastName,Phone	One or more fields separated by comma

Sample Response:

[

{

"Id": "0032w000002GFOPAA4",

"FirstName": "Rose",

"LastName": "Gonzalez",

"Phone": "[phone]"

}

]