kt-outlook v0.0.1

KnowledgeTree for Outlook

A Microsoft add-in for creating shares from recommended content within Outlook (365 and desktop clients).

See kt-manager repo for the API service.

Structure

The application structure is split between an Angular2 thick-client, a NodeJS backend, and a Microsoft add-in.

Most of the application code lives in the client. The backend is used primarily as a mechanism for serving the Angular2 client.

 +- kt-outlook
    +- client           // The Angular2 client code
       +- app           // Source and test code
    +- dist             // Distributable version of client-side code (git ignored)
    +- server           // NodeJS server-side code
    +- tasks            // Gulp (build) tasks
       +- config        // Karma and webpack configuration
    +- reports          // Unit test coverage reports (git ignored)
    +- node_modules     // All dependencies (git-ignored)

Prerequisites

• NodeJS >= 4.2.3 (brew install nodejs)
• Gulp >= 4.0.0 (npm install gulpjs/gulp-cli -g)

Develop

Most development should take place when running the client-only app while running the KT Manager service and the Outlook add-in.

# Install all Dependencies
$ npm install
# Run a local server for development (with watchers)
$ npm start
# Package for distribution
$ npm run-script dist
# Run production server
$ npm run-script start-dist OR node server/index.js

The Node server serves HTTP on port 7003 and HTTPS on 7004.

Third-party Dependencies

Add a new third-party JavaScript dependency:

1. Run npm install -D <package-name>
2. Remove semantic versioning (tildes and carets) so that version is locked
3. Add import <package-name> to vendor.js

Webpack will create a separate file with all of the dependencies concatenated.

Lodash and rxjs

These two libraries in particular are, in a word, large, and pulling them in wholesale would increase the size of our distributed vendor file considerably. Therefore, all new lodash and rxjs methods used should be added into lodash-operators.js and rxjs-operators.js, respectively.

Configuring Secure Local Development

In order for Outlook to serve the add-in, it must be served securely over HTTPS. In production, this is handled by GCP, but in development we use a self-signed certificate served by Express/NodeJS.

For reference, the certificate and key were generated using the following command:

openssl req -newkey rsa:2048 -x509 -nodes -keyout localhost.key -new -out localhost.crt -subj /CN=localhost -reqexts SAN -extensions SAN -config <(cat /System/Library/OpenSSL/openssl.cnf <(printf '[SAN]\nsubjectAltName=DNS:localhost')) -sha256 -days 3650

Accept the certificate on your host machine (Mac)

1. Open the “Keychain Access” application, in Finder > Applications > Utilities
2. In the lefthand window, select "System" and "Certificates" in the Keychains and Category sections, respectively
3. Drag and drop the cert file (localhost.crt found in the server directory) into the application window
4. Double click on the certificate with the name localhost
5. In the dialog box that appears, expand the "Trust" section and select “Always Trust”
6. Restart your browser and open up https://localhost:7004/manifest to see your trusted, SSL localhost setup in action

Running the App / Add-In

1. Sign up for an account at outlook.live.com if you are without credentials and login
2. Click the gear in the top right corner then select "Manage add-ins"
3. Click the text "Click here to add a custom add in." Pro tip: This text doesn't look like a link but it is
4. Select "Add from file..."
5. Find and select manifest-dev.xml located in the root of this project
6. Make sure you have followed the steps in Configuring Secure Local Development
7. Compose a new email
   • In the web client, the KT logo will appear at the bottom of the compose window.
   • In the desktop client, the KT logo will appear on the far left in the task pane. If the logo is nowhere to be seen, restart the client and try again.
8. Profit.

The manifest file loads the Angular app, which is hosted remotely, and configures how the add-in is displayed in Outlook (both web and desktop clients).

Running the Add-In in a Windows VM

1. On the host machine (Pro tip: Save this configuration in a git stash for later use):
   1. Replace the hostnames in config/default.json with ktoutlook-dev.com
   2. Replace the https server creation in server/index.js (line 57) with

      https.createServer(options, app).listen(serverConfig.port.https, 'www.ktoutlook-dev.com');

2. On the VM:
   1. Set up this project's directory as a shared folder.
   2. Add the following to the C:\Windows\System32\drivers\etc\hosts file:

      10.0.2.2	ktoutlook-dev.com
      10.0.2.2	www.ktoutlook-dev.com

3. Follow the steps in the section above for your Outlook Windows client, but use manifest-dev-windows.xml as your manifest
4. Debug the application using the Windows 10 F12 developer tools

Environment Configuration

In non-development environments, the manifest file is hosted at https://<hostname>/manifest.

To change the environment that you are using, follow the steps above except in step 4 you will Select "Add from URL..." and use the URL above replacing the hostname with the environment you want from the table below. The Node server returns the correct API hostname based on the NODE_ENV environment variable used to start the server through the /config route.

Microsoft Store

Dashboard

https://knowledgetree.atlassian.net/wiki/spaces/engineering/pages/126746626/KnowledgeTree+for+Outlook

Listing

https://store.office.com/en-us/app.aspx?assetid=WA104381163&sourcecorrid=aa9adf16-d53b-4a26-827c-e92ed9c4e5e5&searchapppos=0&ui=en-US&rs=en-US&ad=US&appredirect=false