Office365 Exchange - Custom App

Objective

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

Pre-requisites

The first and foremost prerequisite for a Microsoft Office365 Exchange App is to get an Azure Subscription. Please follow this document for MicrosofitOffice365 Integration.

1. In Azure, For Office 365 exchange permissions, you will need to have following delegated permissions: “Calendars.ReadWrite.Shared, People.Read, Mail.ReadWrite, Notes.ReadWrite.All, Notes.Create & offline_access”. To give these permissions, click on “Add a permission” button, then click on “Microsoft Graph” button option at top and finally click on “Delegated permissions” button option and you will be able to see the list of permissions that you can give to your registered application. Find all the permissions stated above and check them and finally click on “Add permissions” button to complete the permission as shown in picture below:

1. For authentication, you have to provide redirect URL, where Office 365 can he next step is configuring the Authentication. Click on “Authentication” in the left menu. Then click “Add a platform”, Select Web in Configure platforms section. Provide the following URL to VoiceWorx as Redirect URL, so that Office365 can redirect to VoiceWorx after the authentication is done

2. Follow the subsequent screenshots as shown below

Add a platform as shown below:

Once the platform is added, you should see redirect URIs as below:

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

Now you have successfully configured App on Azure. You 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 Exchange.

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 Exchange

6. Create a custom skill in Voiceworx.

7. Publish the skill

8. Test the Alexa skill.

Setup connection to Office 365 Exchange

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 Exchange, browse to: Integration > Connect System as shown below. Click on Add New Connection.

1. Provide the following details.

Integration Category: Custom

System Type: Microsoft Office365 Exchange.

Click on Connect System.

1. Read the instructions and Click on Connect to Office365.

1. You will be redirected to the Microsoft login screen. Enter your Microsoft Office 365 login credentials.

1. Microsoft Office 365 will confirm your acceptance to allow SmartOffice connect to your Microsoft Office 365 Platform. Click “Allow”.

2. You will be redirected to the SmartOffice integration confirmation page

You have successfully configured SmartOffice integration to Microsoft Office 365. Now, you have successfully integrated Office 365 Exchange with the VoiceWorx platform. Now, you may click on “Return to Integration Configuration” button to come back to the connections page. You should see Microsoft Office 365 Exchange in the list as shown below.

Create a custom app in Voiceworx

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

Provide following details in the pop-up form.

Name: VoiceWorx Exchange 2021

Custom Skill Type: Search

Category: None

Click: Save.

You should see a screen as shown below:

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 “Data Sources” button (in the Home Tab) 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

Add DataSoure by doing the following:

Name: Office Exchange DS

Integration Configuration: Select Microsoft Office365 Exchange: VoiceWorx Sharepoint Portal (created in Step 4)

Create Methods to fetch the data from Office 365 Exchange

Methods allows you to interact with Office 365 Exchange data.

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

1. Read Emails

2. Read Emails from Email Addresses

3. Send Email

4. Search Messages

5. Get All Calendars

6. Get Calendar by Date Range

7. Search Contact by Name

8. Get my Notebook

9. Create Notebook

Depending on your requirement, you will have to use an appropriate method. This document will explain one methods with an example and rest of methods will be on the appendix section.

Let’s start with a use case.

Scenario/ Use Case (Read Emails):

You want to fetch emails from your Office 365 inbox. For this, you can use ReadEmails method as explained below.

To access the methods, click on the “Methods” tab which is next to the “Data Sources” tab.

Click “Create New Methods”.Then select or enter the following in Method Inputs, Method Output and Method Result tab respectively.

1. Name: ReadEmailMethod

2. Request Type: ReadEmails

3. Result Type: ListOfRecords

4. Record Limit: 10

5. Record JsonPath: $.value[*]

6. Empty Result Template: I could not find any emails in your inbox

7. Record Template: {{subject}}

8. Result Template: Here are your last few emails in your inbox: {{Records}}

Click on Save after filling the above details.

After you have created the method, you want to test if the method is functioning properly before proceeding any further with the App building.

Click on Test button of the newly created Method.

You have to check the Test Result section to confirm if the integration with Office365 Exchange is successful and if the method build is correct.

Following screens demonstrate a successful method. If you are not getting the following results, there might be something missing in your app build. You might also want to test your integration configuration first.

Create Intents

In the top menu tabs, select “Intents” and “Create New Intent”.

Provide the following details and Click on Save.

Name: ReadEmailIntent

Intent Type: Search

Intent Action: Execute Method

DataSource: VoiceWorx Exchange DS

DataSource Method: ReadEmailMethod

Create Slots

Slots are required when methods have parameters. Since, this method does not have any parameter, we can skip this step.

Create Utterance

In the top menu tabs, select “Utterance” and select “Create New Utterance”. Make sure that the selected Intent is the one we created in previous step. We are creating utterance to invoke the particular intent. Hence, we need to make sure that the correct intent is being selected.

Utterance are words spoken to launch specific intents. Now input or select the following:

Value: read my email

Custom App: VoiceWorx Exchange 2021

Intent: ReadEmailIntent

Click: Save

Create Input

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

Then input or select the following:

Name: ReadEmailInput

Custom App: VoiceWorx Exchange 2021

Custom Intent: ReadEmailIntent

Data Source: VoiceWorx Exchange DS

Data Source Method: ReadEmailMethod

Publish to Alexa

VoiceWorx supports publishing to number of channels like Amazon Alexa, Amazon Lex, Teams, Slack etc. We will be publishing to Amazon Alexa for this document. To publish to Alexa,select “Publish” in the top menu tabs then click “Add App Publishing”. Then input or select the following:

External Skill Name: VoiceWorx Exchange 2021. (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

Publishing Locale: Your region.

Skill Invocation Name: office exchange. (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.)

Messages: These fields shall be automatically populated and are used to greet and guide the user. You can modify it as per your interest as well

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.

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

Selected Skill: VoiceWorx Exchange 2021

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

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.

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

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

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

No type “read my email” and Alexa developer console should read few email subjects from your inbox.

Congratulations!

You have successfully completed building a Custom Skill and publishing to Alexa.