Suralink Secure File Sharing Add-in for Outlook

Installation on Windows

Install NodeJS for Windows

Install Git for Windows

• The Git GUI is used for Git commands but will not run npm commands. The Git Gui provides a limited terminal like a *nix environment.

Running the app

Copy config/.env.example as config/.env and update any values for your local env.

Navigate to the project root and install npm dependencies:

npm install

Validate manifest.xml if formatted correctly:

npm run validate

Create or update local env files (run this any time you add to or change your .env values). This should be run in GitBash on your VM if .env values are updated. This must be run for .env or UI changes on your Host machine:

npm run build:dev

Run the app to side-load the add-in in Outlook in the VM (this spawns a new NodeJS window instance and new Outlook window):

npm start

NOTE: Changes to manifest.xml are not hot-reloaded like React components. To load a change made in manifest.xml you need to close the current instance of Outlook and open Node.js console and then run npm start again.

NOTE: Sometimes the dev server process will stay running for whatever reason. Why you try to npm start a new one you'll see a message: "The dev server is already running on port 3000" and a new server won't start and the React components won't load to the Outlook view. This usually seems to happen if you close Outlook before the NodeJS terminal or if you restart the server before the previous process has time to terminate. Run this command to kill any running process on port 3000:

npx kill-port 3000

Sometimes you need to close the terminal window (GitBash) if running that command doesn't solve the issue.

Auth

Outlook prevents loading Google Recaptcha's js files. Enable OUTLOOK_RECAPTCHA_TOKEN in both filesharing_outlook and auth_server .env files with the same value in both repos.

VM certs

The default expiration time for local certs is 30 days. As a result, your local cert might expire and you will see an error in the yellow box iin the sidebar that the add-in refuses to load. If the node service doesn't recreate the cert by itself you can recreate it manually.

After stopping the node service, delete the existing cert(s):

npx office-addin-dev-certs uninstall

Create a new cert:

npx office-addin-dev-certs install --days 365

Restart the server (npm start)

Using local samurai components

In the samurai repo, run npm install or maybe npm install --legacy-peer-deps if normal install doesn't work In the samurai repo, run npm link In this outlook repo, run npm link @suralink/samurai In the samurai repo, run npm link ../filesharing_outlook/node_modules/@material-ui/core In the samurai repo, run npm link ../filesharing_outlook/node_modules/react

Code overview

• ./manifest.xml defines the settings and capabilities of the add-in.

Initial yeoman installation notes

npm install -g yo generator-office

npx office-addin-usage-data off

yo office

selected Office Add-in Task Pane project using React framework but considered Office Add-in Task Pane project supporting single sign-on maybe in the future

option Office Add-in project containing the manifest only might end up being the best option depending on integration with existing projects

typescript

named the project "Suralink Secure File Sharing Add-in for Outlook"

outlook

versioning

The package.json patch version gets auto-incremented on git commit with a husky pre-commit rule. The version of manifest.xml gets rewritten during build with the version from package.json so there is no reason to update the <Version> element in manifest.xml since the prod copy will get written with the latest version of package.json.

Feature flags

Outlook feature flags are currently managed in the filesharing_api gitlab feature flags https://gitlab.com/theRealSuralink/suralink_repos/filesharing_api/-/feature_flags

Semantic release

Semantic release will auto-increment the repo version based on the merge request title

Merge request titles should follow semantic-release patterns:

Fix/patch release 0.0.x

fix(APP-1234): fix this pattern regex

Minor/feature release 0.x.0

feat(APP-1234): add list to component

Major/breaking release x.0.0

perf(APP-1234): change fetch to new endpoint

If this patterns is not followed, the script will attempt to parse the ticket number from the branch name and append the proper semantic-release pattern in the commit message.

Example:

A commit message my horrible commit message on branch feature/APP-1234-branch-name creates a new patch commit message fix(APP-1234): my horrible commit message

If you really need to bypass this pattern for some reason, the frowned-upon method is to add the --no-verify flag when committing

More info about semantic release:

https://www.npmjs.com/package/semantic-release