Skip to content

Latest commit

 

History

History
203 lines (132 loc) · 15.4 KB

README.md

File metadata and controls

203 lines (132 loc) · 15.4 KB
Raw
page_type description products languages extensions urlFragment
sample
Sample Outlook add-in and Teams tab app.
office-teams
office
office-365
typescript
nodejs
contentType createdDate
samples
09/19/2023 01:00:00 PM
officedev-microsoft-teams-samples-multiple-capability-discounts-ts

Discount Offers

This sample combines, into a single app with a single manifest, an Outlook Add-in with a Teams Tab to make and manage discounts offers. The Outlook add-in is used to insert discount offers into e-mails. These offers are recorded in a mock customer relation management (CRM) system that is implemented with a simple JSON database. The aggregated data from the CRM is viewed in a Teams tab.

The sample illustrates a prime use case for combining a Teams Tab and an Office Add-in: Users take discrete actions on an Office document and analyze data about these discrete actions in a Teams tab.

Note: As of 6/20/2023, Teams apps that include an Office Add-in capability are in preview and can run only on a Windows computer. You should be working on a Windows computer to run this sample.

Included Features

  • Tabs
  • Office Add-ins

Interaction with app

Interaction with the add-in:

Animated gif shows a discount offer being inserted into an email with the Discounts add-in

Interaction with the tab:

Animated gif shows a discount offer being inserted into an email with the Discounts add-in

Try it yourself - experience the App in your Microsoft Teams client

Please find below demo manifest which is deployed on Microsoft Azure and you can try it yourself by uploading the app package (.zip file link below) to your teams and/or as a personal app. (Sideloading must be enabled for your tenant, see steps here).

Tab-add-in-combined: Manifest

Prerequisites

  • NodeJS, version 16.x.x or 18.x.x.

  • npm (installed with NodeJS)

    Note: This sample was developed with NodeJS version 16.13.2 and npm version 8.1.2. It should work with most NodeJS versions in the 16.x.x or 18.x.x ranges, but there are some exceptions to this. It does not work on NodeJS 16.16.0.

  • Teams Microsoft Teams is installed and you have an account.

  • Visual Studio Code

  • Teams Toolkit extension for Visual Studio Code

  • M365 developer account or access to a Teams account with the appropriate permissions to install an app.

  • Microsoft Office for Windows

    Note: The add-in capability in a Teams app is only supported on Windows computers.

  • Your Microsoft 365 account has been added as an account in desktop Outlook. See Add an email account to Outlook

  • Mockoon or another database that can accept HTTP GET and POST requests with JSON payloads.

Setup

  1. Setup the project.

    • Clone the repository:
    git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git
    • In a terminal, navigate to samples/tab-add-in-combined/nodejs.
    • Install modules:
    npm install
    • In a terminal, navigate to samples/tab-add-in-combined/nodejs/add-in.
    • Install modules:
    npm install
    • In a terminal, navigate to samples/tab-add-in-combined/nodejs/tab.
    • Install modules:
    npm install

  2. Install a mock customer relations management (CRM) system.

    • Instructions for installing and configuring a local Mockoon database are in: Setup Mockoon Database.

    • If you prefer, you can use any database, either on localhost or remotely, that can (1) send a JSON payload in response to a GET request and (2) update in response to a POST request that contains a JSON payload. Read the article that is linked to in the preceding bullet to find out what CORS headers and starter data should be used. You can use any domain and port you like (except ports 3000 and 53000 which are used by other parts of the sample), but if you use anything other than localhost:3001, you will need to edit the calls of fetch in the following two files to pass the correct domain and/or port:

      • samples/tab-add-in-combined/nodejs/add-in/src/taskpane/components/App.tsx
      • samples/tab-add-in-combined/nodejs/tab/src/components/App.tsx

Build for production

npm run build

Running the sample

Be sure your mock CRM server is running.

Before running the Teams tab and Outlook add-in at the same time, it is best to run each separately so that certain "first run only" tasks are carried out.

Run the Outlook add-in for the first time

  1. Open the folder samples/tab-add-in-combined/nodejs in Visual Studio Code.

  2. First, make sure Outlook desktop is closed.

  3. In Visual Studio Code, open the Teams Toolkit.

  4. In the ACCOUNTS section, verify that you're signed into Microsoft 365.

  5. Select View | Run in Visual Studio Code. In the RUN AND DEBUG drop down menu, select the option Launch Add-in Outlook Desktop (Edge Chromium) and then press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then Outlook desktop opens.

  6. You can now work with your add-in. If your Outlook application has more than one account, be sure you're working in the Inbox of your Microsoft 365 account identity.

  7. Open an Outlook message compose window by either starting a new message or selecting Reply on a message.

  8. Be sure there is an email address in the To and From lines.

  9. Find the Offer Discount button on the ribbon and select it.

    Blue Yonder control group on the Outlook ribbon with a single button named Offer Discount

    If this is the first time that you've developed an Office add-in on your computer, or the first time in more than a month, you may see one or both of the following prompts. Select Yes for both. Doing so ensures that there is an SSL certificate for the localhost domain that hosts the add-in. You won't see these prompts again for another month.

    A dialog with Yes and No buttons titled Root Certificate Store. The text is the question "Do you want to DELETE the following certificate from the Root Store?" This is followed by data about a security certificate.

    A dialog with Yes and No buttons titled Security Warning. The text is data about a security certificate. This is followed by the question "Do you want to install this certificate?"

    You will next see the following prompt. Select OK This prompt appears whenever the add-in is run in debugging mode.

    Dialog titled "WebView Stop On Load" with text reading "To debug the webview, attach VS Code to the webview instance using the Microsoft Debugger for Edge extension, and click OK to continue. To prevent this dialog from appearing in the future, click Cancel." Below the text are buttons labelled OK and Cancel.

    A Discounts task pane opens.

    A task pane styled to match the Office Colorful theme. The title bar is "Discounts". A text box labelled "Discount %" with default number 15 in it. A text box labelled "Offer text" with default text "We are delighted to offer you a discount of" in it. A button labelled "Insert Offer". A footer bar containing text "Blue Yonder Airlines".

  10. Optionally, edit the discount percentage and offer text. (The percentage will be appended to the end of the offer text.)

  11. Click anywhere in the message body and then select the Make Offer button.

  12. The offer text and discount percentage are entered in the email body. They are also added to a mock CRM database (see below).

    An email message with the text "We are delighted to offer you a discount of 15%".

  13. To see the task pane match the current Office theme, change the Office theme and then open a new message compose window and start the add-in. It will open in the new theme. The following shows the task pane in the Office dark gray theme.

    Note: There isn't currently an API in the Office JavaScript Library to detect the theme changed event in Office, so the task pane cannot dynamically change to the new theme.

    A task pane styled to match the Office Dark Gray theme. The title bar is "Discounts". A text box labelled "Discount %" with default number 15 in it. A text box labelled "Offer text" with default text "We are delighted to offer you a discount of" in it. A button labelled "Insert Offer". A footer bar containing text "Blue Yonder Airlines".

IMPORTANT: To end a localhost session with the add-in, open a command prompt, bash shell, or Visual Studio Code TERMINAL, and run the commamd npm stop. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

Run the Teams tab for the first time

  1. In Visual Studio Code, open the Teams Toolkit.

  2. In the ACCOUNTS section, verify that you're signed into Microsoft 365 and that sideloading is enabled.

  3. Select View | Run in Visual Studio Code.

  4. In the RUN AND DEBUG drop down menu, select the option, Launch App Debug (Edge), and then press F5. The project will build and run. This process may take a couple of minutes. Eventually, Teams opens in a browser with a prompt to add the tab app.

    A standard Teams prompt to add an app with an Add button. App title is "Discounts". Author name is "OP Developer Content Team". The Overview subtab has the title "Insert discount offers in Outlook email and view data about the offers in Teams." The same sentence is the text below the title.

  5. Select Add

  6. When the tab opens, data about discounts that have already been offered is fetched from the mock CRM database and displayed.

    The Discounts app open in Team, formatted with the standard Teams "light" theme. It has the app logo and name "Discounts". There are subtabs named "Discount History" and "About". The first of these is open. It has a title "Discount Offers". Below that is a button named "Refresh data". Below that is a grid with columns labelled "Customer", "Salesperson", "Discount Percentage", and "Offer Text". There are two data rows in the grid with fictional email addresses for customer and salesperson. The top row has 15 in the "Discount Percentage" column and "We are pleased to offer you a discount of" in the "Offer Text" column. The second row has 20 in the "Discount Percentage" column and "As a perferred customer, your discount is" in the "Offer Text" column. At the bottom of the tab is a footer bar containing the name "Blue Yonder Airlines".

  7. If the Outlook add-in is open in Outlook desktop, create another discount in a message.

  8. On the Teams tab, select the Refresh Data button. The new discount you created appears at the end of the grid.

  9. To see the tab match the current Teams theme, change the Teams theme. The tab appearance will automatically change to match. The following image shows the app in the Teams high contrast theme.

    The Discounts app open in Team, formatted with the high contrast Teams theme. It has the app logo and name "Discounts". There are subtabs named "Discount History" and "About". The first of these is open. It has a title "Discount Offers". Below that is a button named "Refresh data". Below that is a grid with columns labelled "Customer", "Salesperson", "Discount Percentage", and "Offer Text". There are two data rows in the grid with fictional email addresses for customer and salesperson. The top row has 15 in the "Discount Percentage" column and "We are pleased to offer you a discount of" in the "Offer Text" column. The second row has 20 in the "Discount Percentage" column and "As a perferred customer, your discount is" in the "Offer Text" column. At the bottom of the tab is a footer bar containing the name "Blue Yonder Airlines".

IMPORTANT: To stop debugging and uninstall the app, select Run | Stop Debugging in Visual Studio Code.

Run both the Teams tab and the Outlook add-in at the same time

  1. First, make sure Outlook desktop is closed.

  2. In Visual Studio Code, open the Teams Toolkit.

  3. In the ACCOUNTS section, verify that you're signed into Microsoft 365.

  4. Select View | Run in Visual Studio Code. In the RUN AND DEBUG drop down menu, select the option Launch App and Add-in Outlook Desktop (Edge Chromium) and then press F5. The project builds and a Node dev-server window opens to host the add-in. The tab app is hosted in the Visual Studio Code terminal. This process may take a couple of minutes. Eventually, both of the following will happen:

    • Teams opens in a browser with a prompt to add your tab app. If Teams has not opened by the time Outlook desktop opens, then automatic sideloading has failed. You can manually sideload it to see both the app and the add-in running at the same time. For sideloading instructions, see Upload your app in Teams.
    • Outlook desktop opens.

  5. In the Teams prompt, select Add and the tab will open.

  6. In Outlook, open an Outlook message compose window by either starting a new message or selecting Reply on a message.

  7. Be sure there is an email address in the To and From lines.

  8. Find the Offer Discount button on the ribbon and select it. You will next see the following prompt. Select OK. This prompt appears whenever the add-in is run in debugging mode.

    Dialog titled "WebView Stop On Load" with text reading "To debug the webview, attach VS Code to the webview instance using the Microsoft Debugger for Edge extension, and click OK to continue. To prevent this dialog from appearing in the future, click Cancel." Below the text are buttons labelled OK and Cancel.

    A Discounts task pane opens.

  9. Create another discount in a message.

  10. On the Teams tab, select the Refresh data button. The new discount you created appears at the end of the grid.

Further Reading