DocLock Outlook Add-in

The DocLock Outlook Add-in lets you archive email attachments straight into the DocLock Document Management System without leaving Outlook. While you're reading a message, you open the add-in, pick the attachments you want to keep, choose a destination workspace, and upload — the files land in that workspace's Inbox folder.

The add-in works in read mode: it activates when you are reading an email message (not while composing one), in both Outlook desktop and Outlook on the web.

---

How to open the add-in

1. Open an email message that has one or more file attachments.
2. On the Outlook ribbon, find the DocLock button (it appears in the default tab group for reading mail).
3. Click it. A task pane opens on the right-hand side of the message.

First time or session expired? You'll be asked to sign in before you can see your attachments — see Signing in below.

---

Signing in

The first time you open the add-in — or after your session expires — you'll see the Login screen.

1. Enter your Email / Username.
2. Enter your Password.
3. Click Sign In (or just press Enter).

If your credentials are wrong, an inline error message appears and you can try again. On success you're taken straight to the main screen, and you stay signed in until you sign out or close the add-in.

---

The main screen

Once you're signed in, the add-in shows a fixed header, a scrollable content area of cards, and a sticky footer with the upload button.

Header

• The DocLock logo.
• A Help button (the ? icon) that opens a short step-by-step usage guide.
• A Sign out button that ends your session and returns you to the login screen.

Card 1 — Mail subject

Shows the subject line of the email you currently have open, so you always know which message you're working with.

Card 2 — Email attachments

Lists every file attachment on the open email (inline images embedded in the message body are not shown). For each attachment you'll see:

• A checkbox to select or deselect it for upload.
• A colour-coded file-type icon — for example PDF (red), Word (blue), Excel (green), images (purple) and archives (brown).
• The file name and file size.
• A pencil (rename) button.

Selecting files

• Tick the box next to each file you want to archive.
• Use the Select all row at the top to tick or untick every attachment at once.
• A selection badge in the card header (for example 2 / 3 selected) shows how many files are currently selected.

The list scrolls when there are more than about three attachments, keeping the panel compact.

Renaming a file before upload

1. Click the pencil button next to a file.
2. The file name turns into a text box — type the new name.
3. Press Enter or click away to confirm, or press Escape to cancel.

The file is uploaded under the new name, and its icon updates to match if the extension changes.

Card 3 — Target workspace

Choose where the files should be archived. Start typing in the workspace box and pick a match from the suggestions list. The add-in loads the list of workspaces you have access to.

The Upload button stays disabled until you have both chosen a workspace and selected at least one attachment.

Card 4 — Upload progress

This card appears once you start an upload. It shows one row per file with live status:

Status	Meaning
Uploading… (blue)	The file is being sent.
✔ Done (green)	The file uploaded successfully.
✖ message (red)	The file failed, with a short reason.

If any file fails, a Retry failed button appears so you can re-attempt only the files that didn't succeed — the ones that already worked are left alone.

Footer

• Upload to DocLock — the main button. It starts the upload and shows a spinner while files are being sent.
• A status bar shows the final result, for example: "✔ 3 file(s) uploaded. You can find them in the Inbox folder of the Finance workspace."

---

Uploading attachments — step by step

1. Open an email with attachments and open the DocLock add-in.
2. Sign in if prompted.
3. In Email attachments, tick the files you want to archive (and rename any if you like).
4. In Target workspace, type and select the destination workspace.
5. Click Upload to DocLock.
6. Watch the Upload progress card; when it finishes, the status bar confirms success.
7. Open that workspace in DocLock and look in its Inbox folder to find the uploaded files.

---

The Help guide

Click the ? button in the header to open the in-app help. It's an overlay with five numbered steps:

1. Open an email with attachments.
2. Select one or more attachments.
3. Optionally rename files using the pencil icon.
4. Choose a target workspace.
5. Click Upload — files land in the workspace Inbox folder.

It also reminds you that failed uploads can be retried. Close it with the × button, by clicking outside it, or by pressing Escape.

---

Troubleshooting

Problem	What to do
The DocLock button isn't on the ribbon	Make sure you're reading a message (the add-in doesn't appear while composing) and that your administrator has deployed the add-in to your mailbox.
No attachments are listed	The email may only contain inline images embedded in the body, which aren't shown. Only real file attachments appear.
The Upload button is greyed out	You must select at least one attachment and choose a target workspace before it becomes active.
You're suddenly asked to sign in again	Your session expired. Sign in again — your token is cleared automatically when it expires or when you sign out.
A file shows ✖ with an error	Click Retry failed to re-attempt just the failed files. If it keeps failing, check the file size and your connection.

---

For administrators and IT

This section summarises how the add-in is built and configured, for the people who deploy and maintain it.

Technical stack

Layer	Technology
Platform	Microsoft Office Add-in (Manifest v1.1 / VersionOverrides v1.0)
Host	Microsoft Outlook — Desktop & Web (Mailbox requirement set 1.3)
Frontend	Vanilla JavaScript with HTML/CSS (no framework)
Build	Webpack, Babel
Office API	Office.js (office-addin-taskpane-js scaffold)
Auth	JWT bearer token, stored in sessionStorage
Backend	DocLock REST API
Dev server	localhost:3000 (webpack-dev-server)

Activation

The manifest registers the add-in on the MessageReadCommandSurface extension point, under the default TabDefault ribbon group, so the DocLock button appears when a user is reading a message. It requests ReadWriteItem permission, which is required to read attachment content via getAttachmentContentAsync.

API endpoints used

Method	Endpoint	Purpose
POST	/api/auth/login	Authenticate and receive a JWT.
GET	/api/workspaces	List the workspaces available to the user.
POST	/api/Documents/upload?source=outlook	Upload a single document.

The API base URL defaults to https://localhost:7148 and can be overridden at build time with the DOCLOCK_API_BASE environment variable.

Upload flow

1. For each selected attachment the add-in calls Office.context.mailbox.item.getAttachmentContentAsync() to retrieve the file as a Base64-encoded string.
2. The Base64 string is decoded into a binary Blob.
3. A multipart/form-data POST is sent to /api/Documents/upload?source=outlook containing:
   • File — the binary blob with the (possibly renamed) filename.
   • Metadata — JSON with workspaceId and name.
4. The upload request has a 60-second timeout; all other API calls use a 15-second timeout.
5. A 401 response at any point clears the token and returns the user to the login screen.
6. Successful files appear in the Inbox folder of the target workspace.

Session and authentication

• The JWT is stored in sessionStorage, so it is cleared automatically when the Outlook tab/add-in closes.
• Before every authenticated request the token's exp claim is checked client-side; if it has expired, the user is sent to login immediately, without a network round-trip.
• The login response may carry the token under any of these field names: token, accessToken, or access_token.