Control & Reviews
Word and PDF Files as Artifacts
Add Word documents and PDFs to a project as Artifacts, review and comment on their pages, keep every version, and free storage by removing old versions' files.
On this page
A Word document or a PDF can live in your project as an Artifact. Reviewers read it in Holarch, comment on its pages and approve it like any other item. Each new upload of the same document becomes a new version, and earlier versions stay readable.
On the hosted service, Word files are turned into PDF when you add them, and PDFs are compressed. The PDF is what everyone reads, downloads and comments on.
Concepts
- File Artifact: an Artifact that holds a file. Its page has a File section at the top with the viewer, the versions and the file tools.
- Version: one upload of the document. Each version keeps its PDF, who uploaded it, the date and an optional note. The newest version is shown by default.
- Conversion: turning a Word file into PDF and compressing PDFs. One file is converted at a time for everyone; files from different accounts take turns, so one large batch does not hold others up.
- Pinned comment: a comment that belongs to a spot of one version: selected words, a point, a box or a whole page (or, in the Word view, a paragraph). Discussion shows where it sits, for example "on version 2, page 3".
How to use it
When and why
Use a file Artifact when a deliverable is written outside Holarch: a design review package, a supplier's interface control document, a test report. Keeping it in the project puts it next to the requirements and items it covers. Reviewers comment in one place, and baselines record which version was approved.
Add Word or PDF files
- Open the Database of an LML project.
- Click + New Item, then Artifact from a Word or PDF File… under the Name field. When the Database shows Artifacts only, the button is + New Artifact and the dialog's button reads From a Word or PDF File…. The dialog closes and the file chooser opens.
The same button is in the New Item dialog everywhere it opens, for example ⌘K / Ctrl+K → New Item…. You can also drag .docx and .pdf files onto the Database table, or press ⌘K / Ctrl+K and run Artifact from File… on any page of the project.
- Choose one or more files.
You see Files being added above the table, with each file's status: "Waiting (2 ahead)", Converting…, Compressing… or Storing….
- Wait, or keep working. You may close the tab.
When a file is done, Holarch tells you: "Design Review.docx is ready as an Artifact." If no Holarch tab of yours is open, the message comes by email.
Each file becomes one Artifact, named after the file without its extension. The notice states the stored size, for example "Stored as 2.1 MB, compressed from 15 MB."
Upload a new version
- Open the Artifact.
- In the File section, click Upload New Version… and choose the file.
- Optionally enter a Note for the new version, for example "Comments from the design review addressed", and click Upload as New Version.
You see "New version Design Review.docx: Converting…" on the page until it is ready.
When you add a file whose name matches an Artifact already made from a file of that name, File Already in the Project asks what to do:
- Upload as New Version (the default): the file becomes the next version of that Artifact.
- Keep Both: a separate Artifact, whose name gets " (2)".
- Cancel: nothing is added.
Review and comment
- Open the Artifact. Pages shows the PDF in the document viewer: a toolbar, the pages and a Comments panel beside them.
- Move through the document with the toolbar: Page 3 of 12 (type a page number and press Enter), the previous and next page buttons, Thumbnails, zoom (Fit Width, Fit Page or a fixed size) and Find (⌘F / Ctrl+F). Keys: ← and → turn pages, Home and End go to the first and last page, + and − zoom.
- Comment in one of four ways:
- Select Text: select words on the page (you can also copy them), then click Comment on Selection. The words are highlighted.
- Point: click the spot on the page where the comment belongs.
- Box: drag a box around an area, for example a figure or a table.
- Comment on Page: a comment on the page shown, as a whole.
Type the comment in the panel and click Add Comment (⌘Enter / Ctrl+Enter). Type @ and a name to mention someone.
- The Comments panel lists the threads in page order, numbered like their markers on the page. Click a thread to go to its spot; click a marker or highlight to open its thread. Reply, Resolve and Reopen work as in Discussion; Show resolved shows resolved threads.
- For more room, click Review View (the version across the whole window) or Pop Out (a separate window, for example on a second screen). Both stay up to date as people comment.
Each comment belongs to the version it was made on, and Discussion shows it too, for example "on version 2, page 3". Commenting never changes the file: a signed PDF keeps its signature.
Comments on later versions
When a new version is added, open threads move to it, so a review continues across versions:
- Holarch finds each thread's words in the new version, also when they moved to another page or the text around them reflowed. The thread shows there labelled From version 1 (the version it was made on).
- When the words were edited, the thread is also marked Text changed since and shows what the earlier version said, for example "Version 1 said: “reject 40 W”".
- When the words are gone, the thread is listed under Earlier versions at the end of the Comments panel, with its quoted words and Show on Version 1 (the last version that has them).
- A Point or Box follows the nearest line of text. On a page without text (a drawing or a scan) it stays where it was when the page looks the same in the new version; otherwise it goes under Earlier versions.
- Resolved threads stay on the versions they were on. Reopen one to have it move to the newer versions.
- Made on (above the threads, once there are threads from more than one version) shows only the threads made on one version, or all of them.
- Threads from Word follow the same rules.
This happens when the new version is added. Projects with comments from before this feature get the same treatment the first time a newer version is shown. In Discussion, a comment from an older version says where it is now, for example "On version 1, page 2, “radiator” · carried to version 3" or "· not in version 3".
Comments keep their quoted words, so they still read after an old version's file is removed. An edited comment keeps its earlier text: Earlier text under the comment lists each earlier wording with who wrote it and when.
A baseline records the file version and its comment threads as they were then. Click the baseline's name under In baselines to see them.
Comments and tracked changes from Word
On the hosted service, a Word file's own review markup comes over when you add it:
- Its comments become comment threads on the PDF, on the words they were made on, with their replies. Each keeps the author and date from Word and is marked From Word. A comment Word marked done arrives resolved.
- Its tracked changes are listed as suggestions: "Suggested insertion: …" or "Suggested deletion: …", by the person who made them.
- The PDF shows the comments in the margin and the tracked changes as redline.
The notice after the upload says what came over, for example "3 comments and 2 tracked changes came over from Word." You own the imported threads, so you can resolve or delete them. People watching the item are not notified about each imported comment.
Compare two versions
- Open the Artifact. In the File section, click Compare Versions… (shown when the Artifact has two versions or more).
- Choose the Older and Newer version. By default the version shown is compared with the one before it.
The two versions appear side by side, page by page:
- Inserted words are green on the newer version.
- Deleted words are red on the older version.
- Moved sentences and paragraphs are violet in both places. A moved block that was also edited shows its word changes too. The change list names both pages, for example "Page 2 → page 5".
- Pages without text (drawings, scans) are compared as pictures. A changed one is outlined; on the newer page, Differences shows red where only the older version has ink and green where only the newer one has.
- Select a change in the list, or click Previous and Next (F7 and Shift+F7), to show it on both sides. Sync scrolling keeps the same text side by side while you scroll.
The text is compared across the whole document, so text that moved to another page, or reflowed onto other lines, is still matched. A Word file kept without conversion is compared as text, without pages. Long documents show a progress bar while they are read.
The same comparison marks text changes elsewhere: change-request review, item History, document changes and library differences show moved sentences as moved, with a Moved to / Moved from link between the two places.
Worked example: a design review on the CubeSat EO-1 demo
- In the CubeSat EO-1 demo, open the Database, click + New Item and add "EO-1 CDR Package.docx" with Artifact from a Word or PDF File….
- When it is ready, open EO-1 CDR Package and relate it to the requirements it covers.
- Reviewers open it and use Comment on Page… for page 12: "Thermal margin table is missing the eclipse case."
- After the fixes, upload "EO-1 CDR Package.docx" again and choose Upload as New Version, with the note "CDR comments addressed".
- Create a baseline. The Artifact page shows In baselines with the baseline's name for version 2.
Tips and good practice
- Upload each new version under the same file name. One Artifact then holds the whole history.
- Upload a PDF instead of a Word file when the layout must match Word exactly: conversion can move line breaks.
- Signed PDFs, PDF forms, PDF/A files and encrypted PDFs are kept exactly as uploaded. Compressing them would break the signature, the form or the conformance.
Common mistakes
- A second Artifact appeared: you chose Keep Both. Delete it, then upload the file again and choose Upload as New Version.
- A Word file over 100 MB was refused: in Word, choose File → Save As → PDF, then upload the PDF.
How it connects
- Comments and reviews: pinned comments are ordinary comments; replies, mentions and approvals work as for any item. See Comments and Reviews.
- Baselines: a baseline records the version each file Artifact had. See Change Requests.
- Storage: every version's PDF counts toward the project's and your storage. See Attachments, Storage and Limits.
The File section
| Control | What it does |
|---|---|
| Version | Shows a version: "Version 3 (latest) · date · uploader". Versions whose file was removed say "file removed". |
| Download (PDF) | Saves the PDF of the version shown. A Word file shown without conversion offers Download (.docx). |
| Restore as Newest | Makes the version shown the newest again, as a new version. Nothing is overwritten. Editors only, not on the latest version. |
| Upload New Version… | Adds the next version. Editors only. |
| Compare Versions… | Two versions side by side with inserted, deleted and moved text marked. See "Compare two versions". |
| Remove Old Versions' Files… | Deletes the files of chosen old versions. See below. |
| Pages / PDF Viewer | The document viewer (pages, Find, comments); or the browser's own PDF viewer (print). |
| Review View / Pop Out | The document viewer across the whole window, or in a separate window. |
| Comment on Page… / Pin a Comment | In the Word view (a Word file kept without conversion): a comment on a page by its number, or on the paragraph you click. Click Stop Pinning to end. PDFs use the viewer's own tools (see Review and comment). |
Below the tools, the facts of the version: Uploaded (who and when), Uploaded file (its original name), Note, Stored (the size and the saving), and In baselines (click a baseline's name to see the comment threads it recorded).
Remove old versions' files
Old versions' PDFs take storage. Remove the ones nobody needs:
- On the Artifact, click Remove Old Versions' Files….
- Select the versions.
You see "Removes the files of version 2 permanently. The version stays in the history."
- Click Remove Files.
You see "Removed the files of 1 version (12.4 MB freed)."
- Who may remove: the account holder on a personal plan (the project owner), an organization admin on the Team plan. An organization admin needs no edit access to the project; the removal carries the admin's name.
- The latest version can't be removed this way. To remove it, delete the Artifact.
- The version stays in the list, marked "File removed by name on date". Its comments stay in Discussion as text.
- Removal is recorded in the audit log, with the versions and the space freed.
Files being added
The Database shows Files being added while your uploads are on their way.
- Uploading…: the file is being sent. Cancel stops it, and nothing is added.
- Waiting (n ahead) or Waiting (next): the file waits its turn. Cancel removes it from the queue.
- Converting…, Compressing…, Storing…: the file is being processed.
- A file that could not be added stays in the list with its message until you click Dismiss.
If the server restarts during a conversion, the file goes back into the queue and is tried once more.
Without conversion
When the server has no converter, files are stored as uploaded:
- PDFs are stored without compression.
- Word files are shown read-only in the browser: "Shown read-only in the browser (no PDF conversion on this server). Layout may differ from Word." Pin a Comment then pins comments to paragraphs.
Messages
| Message | What to do |
|---|---|
| "file is 140 MB. Word files over 100 MB can't be converted. In Word, choose File → Save As → PDF, then upload the PDF." | Save the document as PDF in Word and upload the PDF. |
| "Couldn't convert file: the file is password-protected. Remove the password and upload it again." | Open the file in Word, remove the password to open, save, and upload again. |
| "Couldn't convert file: the file is damaged or not a Word document." | Open and save the file in Word, or upload a PDF. |
| "Couldn't convert file: it took longer than 5 minutes (very large or complex). Split it or save it as PDF and upload the PDF." | Split the document, or save it as PDF in Word and upload the PDF. |
| "Couldn't convert file: it needs more memory than the converter has (many large images). Reduce the images or upload a PDF." | Compress the pictures in Word (Picture Format → Compress Pictures), or upload a PDF. |
| "Couldn't store file: the file is damaged or not a PDF." | Save the PDF again from the program that made it. |
| "Only Word documents (.docx) and PDFs become Artifacts. Not added: files." | Save other formats as .docx or PDF first. |
| A per-file limit message | The file is over your plan's per-file limit. A Word file also gets the advice to save it as PDF. |
When a file can't be added, nothing is kept: no Artifact, no version, and the upload is deleted.
Limits
| Plan | Per file |
|---|---|
| Free / Academic | 10 MB |
| Individual | 25 MB |
| Team | 100 MB |
- Word files over 100 MB can't be converted on any plan.
- The per-file limit applies to the file you upload. The stored PDF counts toward the project's and your storage.
- Word and PDF Artifacts are available in LML projects.