Office 365 SharePoint - Custom App

Objective

This document will demonstrate how easy it is to integrate Office 365 SharePoint to the VoiceWorx platform, create methods to pull data and publish to alexa to test the skills.

Pre-requisites

1. An active Office 365 Account

User should have an active Microsoft Office 365 Account. If user does not have an active account the user can create one at: https://signup.live.com/signup?lic=1&uaid=dcccc7d3501844919762928e146c9308

1. At least one App Registration

If user does not have any App Registration, one can be created quickly by using the below link and following the steps: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

1. Click on New Registration button as shown below:

C:\Users\sandeep\Desktop\365screenshots\app_registration_1.png

1. Fill-up the details as shown below and click on register:

Application (Client) ID, Tenant ID, Client Secret, Permissions & Authentication

1. To be able to connect to Office365 from the VoiceWorx platform, one application registration is required and user should have permissions to view and execute Office365 functions. Once the application registration is successful, you can copy the information as described in the steps below:

2. User will need to visit the newly created application and note the following information as highlighted with red marker. The user can find Application ID and Tenant ID market inside red contour.

1. On the left navigation menu click “Certificates & Secrets” and click on “New client secret” button as shown in picture below:

1. A popup will appear and fill-in the necessary information as shown in the picture below:

1. After user clicks “Add” button, the application secret will appear as shown below. Copy the value and store it in a safe location. This information can only be seen once and it will be necessary to create a new secret if information is lost.

1. User should now have Client ID, Tenant ID and client secret.

2. User will now need to create app permission. On left navigation menu, click “API permissions”, then click “Add a permission” button as shown below:

1. For Office 365 SharePoint permissions, the user will need to have the following delegated permissions: “Sites.ReadWrite.All & offline_access”. To obtain these permissions, do the following:

Click: “Add a permission”

Click: “Microsoft Graph” option at top

Click: “Delegated permissions” option

User will then be able to see the list of permissions that are offered to registered application. Find all the permissions stated above and check them. Finally click on “Add permissions” button to complete the permission as shown in picture below:

1. For authentication, the user has to provide redirect URL. This is where Office 365 can redirect after authentication is complete. To setup the redirect URL, click “Authentication” on the left navigation menu and then click “Add URL” on the body and add the URL. Follow the subsequent screenshots as shown below:

Add a platform as shown below:

1. Once the platform is added, user should see redirect URIs as below:

“https://portal.voiceworx.ai/OAuthCode/Redirect”

1. Now you have successfully configured App on Azure. User can now follow the steps below to connect VoiceWorx with Office 365.

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 Office 365 SharePoint.

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 Office 365 SharePoint

6. Create a custom skill in Voiceworx.

7. Publish the skill

8. Test the Alexa skill.

Setup connection to Office 365 SharePoint

1. Login to the VoiceWorx portal at https://portal.voiceworx.ai.

After login you will land on VoiceWorx portal home page as shown below:

1. To Configure Office 365 SharePoint, browse to: Integration > Connect System as shown below:

1. The user will be redirected to “Connect to External Systems” interface as shown below:

1. Next, click “CONNECT EXTERNAL SYSTEMS” and a popup will appear.

Click “Select Integration Category” dropdown, choose “Custom”. Then click “Select System Type” dropdown, choose “Microsoft Office365. Click “CONNECT SYSTEM” button as shown below:

1. Once you click on “CONNECT SYSTEM”, you will be redirected to “Microsoft Office365 Instance Configuration” page as shown below:

If you do not have this information ready, please refer to the pre requisites section.

1. The table below explains each of the inputs shown on this screen.

Input	Information
Service Instance Name	You can give any value of your choice.
Client ID	This is your Office 365 Application ID
Client Secret	This is your Application secret
Tenant Id	This is the directory ID in Office 365.

1. Fill the required information and click “GO TO CONNECT SYSTEM”. This will validate the details and if it is correct, integration will be saved, and user will be redirected to the connection page as shown below:

1. Once user is logged in, user will be asked to accept permissions, click “Accept” and user will be redirected to the VoiceWorx platform with a success screen as shown below:

1. Now, the user has successfully integrated Office 365 SharePoint with the VoiceWorx platform. User will now need to click “Return to Integration Configuration” to return to the connections page. The user should see Microsoft Office 365 SharePoint in the list as shown below.

Create a Custom Skill in Voiceworx

1. To create a skill, use left navigation menu and click Custom Skills > Manage Skills and then click “Create New Custom Skill.” The user will see the popup screen as shown below:

1. Add Custom Skill by doing the following:

Name: Microsoft SharePoint Skill

Custom Skill Type: Search

Category: None

Click: Save.

Once complete the user should see a screen as shown below:

Create a Data Source

1. A Data Source connects the Skill with the integration. Once you have a skill created, the user can go to Data Sources either by clicking on “Setup Data Source” (as shown in the previous screenshot) or by clicking “Data Sources” tab in the top tabs.

1. To create a data source, click “Create New Data Source” and a popup screen will appear as shown below:

1. Add DataSoure by doing the following:

Name: SharePoint DS

Integration Configuration: Select Microsoft Office365: Office365

Click: Save.

Create Methods to fetch the data from Office 365 SharePoint

1. Methods allow the user to interact with Office 365 SharePoint data.

As of the publication of this document, the VoiceWorx platform supports following Office 365 methods:

GetAllSites

GetSite

SearchSites

GetAllLists

GetList

SearchList

GetAllListItems

GetListItem

SearchListItem

PostListItem

PutListItem

DeleteListItem

1. Depending on the users requirements, the user will need to choose the appropriate Methods. This document will explain one Methods with an example and the rest of Methods will be on the appendix section. Let’s start with a use case.

Scenario/ Use Case (Read Emails):

1. The user will want to find a contact stored in SharePoint. For this, you can use SearchListItem Methods as explained below.

2. To access the Methods, click on “Methods” tab at the top as seen below.

1. Click “Create New Methods”. Then select or enter the following:

Name: FindContactMethod

Request Type: SearchListItem

SiteId: Select your SharePoint site

ListId: Contacts

ListItemSearchCondition: Title={{ContactName}}

Result Type: ListOfRecords

Record Limit: 10

Record JsonPath: $.value[*].fields

Empty Result Template: Sorry, I could not find the contact details

Record Template: Phone number of {{Title}} is {{Phone}}

Result Template: {{Records}}

Click: Save

Create Intents

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

Name: FindContactIntent

Intent Type: Search

Intent Action: Execute Method

DataSource: SharePoint DS

DataSource Method: FindContactMethod

Click: Save

Create Slots

1. In the top menu tabs, select “Slots” and select “Create New Slot”. Now input or select the following:

Name: ContactName

Slot Order: 0

Reprompt Message: What's the contact name?

Type: FullName

Click: Save

Create Utterance

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

Value: find a phone number

Custom Skill: Microsoft SharePoint Skill

Intent: FindContactIntent

Click: Save

Create Input

1. In the top menu tabs, select “Input” and select “Create New Input”. Then input or select the following:

Name: FindContactInput

Custom Skill: Microsoft SharePoint Skill

Custom Intent: FindContactIntent

Data Source: SharePoint DS

Data Source Method: FindContactMethod

Click: Save

1. On the input page, once input is created, click on “Manage Parameters”.

1. On Manage Parameters page inside Input, click “Add New Input Parameter”. Then input or select the following:

Input Parameter Name: ContactName

Parameter: ContactName

Data Type: Text

Click: Save

Publish to Alexa

1. 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: Microsoft SharePoint 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: office SharePoint. (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. Once in Publish Skill to Amazon Alexa select and do the following:

Selected Skill: Microsoft SharePoint 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 “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 (open office SharePoint) inserted in the publishing step in Voiceworx. If the invocation is successful, your configured welcome message will be displayed in the developer console.

1. Now type “find a contact number” and Alexa developer console should ask for contact name. Enter the contact you created in SharePoint. Here, the sample contact name is Sam. Once the contact name is entered, the user should see the response as below:

Congratulations!

You have successfully completed building Office 365 Custom Skill.