Export and import threads

Save a page's, a site's or a project's threads as one file, delete them from the server once the file is safe, and put a file into a project. Experimental.

Move threads to another server, or take finished threads off a server and keep them in a file, by exporting them as one file and importing that file where they belong. Export and import are experimental: they may change or be removed in any release, with no notice first, and their screen on the options page carries an Experimental label.

Prerequisites

The extension installed and connected to a server. See Install a server.
A server that offers export and import, both where you export and where you import. On one that does not, the Export / Import screen’s controls are disabled under a notice that says whether to update the server or the extension. Learn more about how the extension and a server agree.
To delete what you export, an access key that holds can_admin. Learn more about what a key may do.

Export threads

An export reads threads from the project you choose, and writes them, with their comments, screenshots, drawings and attached files, into a file you save.

Open the extension’s options page: the gear in the header of the side panel.
Select Export / Import.
In the Project menu, choose the project to export from. It starts on the project you are working in.
Under Export, open the menu that shows The whole project, and choose what to export: The whole project for everything in the project, One site for every page on one of its domains, or One page. In a project with no sites, One site and One page are disabled.
If you chose One site or One page, choose the site in the menu that appears beside it.
If you chose One page, choose the page in the menu that appears after the site.
Decide whether the threads stay on the server. Delete what was exported from this server is checked by default. If you want the threads to stay, clear it. After a delete, the file is the only copy of those threads, and while export is experimental, a later version of Commentware may refuse to import a file an earlier one wrote. With a key that does not hold can_admin, the box is unchecked and cannot be checked.
Select Export…. Chrome’s save dialog opens with a name filled in that ends in .export.commentware, such as example.com.export.commentware for a site.
Choose where to save the file, and select Save. The screen counts the file’s entries as it writes them. If you cancel the dialog instead, nothing is read and nothing is deleted.
If the box was checked, the screen asks “Delete 4 threads from this server?”, with the number the file holds. Select Delete 4 threads to delete them, or Cancel to keep them. If somebody replied to, edited, moved or resolved one of the threads after the export, nothing is deleted and the screen names its page; export again to take the change too.

Threads on a document an AI agent opened for comment are never exported, at any scope, because they go when that review ends; learn more about opening a document for comment. A project too large to delete in one request saves its file and then deletes nothing; export it one site at a time instead.

The question comes only after the file is on disk and has been read back whole, so a file that did not save never leads to a delete, and Cancel still leaves you a good file. The screen then says how many threads it saved, to which file, and how many it deleted. An export with no threads in it, such as an export of an agent’s document, saves a file with no threads and deletes nothing.

The file holds every screenshot, drawing and attached file as a file of its own, which anybody who has it can open, and it is a zip, so what it holds stays readable by hand. Learn more about what an export file carries.

Export threads through an agent

This assumes an AI agent is connected to your server. If none is, start with Work with an AI agent.

An agent can export threads without the options page, and the file it gets is the same one the options page saves.

Ask the agent to export a page’s, a site’s or a project’s threads to a file, such as “Export the threads on example.com to a file”.
If the agent can run commands on its computer, it downloads the file itself. Otherwise it hands you a link. Open the link in your browser, and the browser saves the file. Either way the server tells the agent the file’s name, which ends in .export.commentware, and how many threads it holds.

The link opens once, and stops working ten minutes after the agent asked for it; after that the agent asks the server for a new one. It is on your server’s own address, so it opens only where the server can be reached: for a server only its own computer can reach, only on that computer. Anybody who has the link before it is used can download the file, screenshots included.

The agent can then delete the exported threads from the server, if its key holds can_admin. It sends the SHA-256 of the file it saved, and the server refuses a hash that is not the file it sent, so a download that did not finish never leads to a delete. Nothing proves the agent kept the file, so ask for the delete only once you know where the file is. The agent can delete them for an hour after the export; after that, or after the server restarts, it exports again first. If somebody changed one of the threads after the export, nothing is deleted. Otherwise the server tells the agent how many threads it deleted, and an import through an agent brings them back, with whoever imports the file as the author of every comment.

Import threads

An import puts every page in a file into the project you choose, on the server the extension is connected to. A page goes into that project even when its address would otherwise file it under a different one. Learn more about projects, sites and pages.

If the threads are going to another server, switch the extension to it. See Hold several servers.
Open the extension’s options page: the gear in the side panel’s header.
Select Export / Import.
In the Project menu, choose the project you want the threads in. The Import section names it.
Under Import, select Import….
Choose a file whose name ends in .export.commentware, and select Open.

The screen reads the file, uploads its screenshots, drawings and attached files, and then sends it one page at a time. When it is done, it says how many threads it imported and into which project, and names any page that failed.

What arrives is the threads as the file holds them, with these differences:

You are the author of every imported thread and comment. Each comment still shows the name it was signed with in the file, and holding the pointer over that name shows your account.
A resolved thread keeps the time it was resolved, and names nobody as the person who resolved it, because that person is not known to this server. The retention purge counts its window from the import, so a thread resolved long ago is not deleted soon after it arrives. A file written by an earlier version of Commentware holds no resolution time, and a resolved thread from it is resolved by you, at the moment of the import.
Times are kept. A time later than the moment of the import, which a clock on another machine can produce, is saved as that moment, and a resolution time earlier than the thread’s creation is saved as the creation time. The screen says how many threads either happened to.
Nobody is notified and nobody is mentioned, and the threads arrive read for you.
A thread already on the page in this project is skipped, so importing a file twice into one project, or bringing back threads you exported without deleting into the project they came from, adds nothing twice. The screen says how many it skipped. Imported into a different project, they arrive as new threads. The exception is a thread, or its first comment, whose creation time was later than the import and so was saved as that moment, as in “Times are kept”: importing the same file again can add a copy of that thread, which you can delete.
Where this server keeps no screenshots, none arrive. On a server, or a site, with screenshots switched off, threads arrive without their screenshots and drawings, which are never uploaded, and their pins lose the page text kept with them. Learn more about the screenshots setting.

A file the import cannot read, such as one written by an earlier version of Commentware in a form this one no longer reads, is refused whole before anything is sent, with a message that opens “This file cannot be imported”. A screenshot, drawing or attached file missing from the zip, or not matching what the file says it holds, stops the import before any thread is written.

Import threads through an agent

This assumes an AI agent is connected to your server. If none is, start with Work with an AI agent.

An agent can import a file too, into the project you name or, if you name none, the project its access key is set to. What arrives is what the options page’s import above gives.

Ask the agent to import the file, such as “Import threads.export.commentware into the Design project”.
If the agent can run commands on the computer that holds the file, it sends the file itself. Otherwise it hands you a link. Open the link in your browser, select the file, and select Import.

The server answers with what the import did, as the options page says it: how many threads it imported and into which project, and how many it skipped. A damaged file imports nothing. If a page fails while the file is being written, the pages before it stay, and the answer names the page that failed.

The link takes one file, and a file that is refused uses it too; ask the agent for a new one. It stops working ten minutes after the agent asked for it, and it is on your server’s own address, so it opens only where the server can be reached: for a server only its own computer can reach, only on that computer. Anybody who has the link before it is used can import a file into that project as the person whose agent asked for it.

Check that it worked

After an export, the file is where you saved it, and the screen says “Saved”, with the number of threads and the file’s name. If you deleted them, they are gone from the side panel’s list on each of their pages. After an import, the imported threads are listed in the side panel on each of their pages, in the project you imported into.

Next steps

Find a comment: open an imported thread from the side panel.
What Commentware stores: what the file carries, and who can open it.