secure-file-sharing-office-addin v1.2.4
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
npmcommands. 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.xmldefines 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: