Writing a docly file to the drive is an import not an edit

What you'll see

A document you changed one word in comes back missing things you never touched.

• The tags are gone. docly.getTags returns an empty array, a tag filter that used to match the document no longer finds it, and the Tags array in the envelope on disk has emptied itself.
• Created shows today where it used to show the year the document was written.
• You write the old Tags or Created values back into the file, save, read it again — and they are blank once more.

Nothing reports an error. The edit you intended is applied correctly. Only the envelope fields around it are lost.

What's actually happening

Reading and writing a .docly file over the drive are not symmetric operations, and that asymmetry is the whole of this entry.

Reading serializes the document out of the database. The Tags array you see on disk is generated from the document's tag rows, and Created from its stored creation date — which is why the envelope always looks complete and authoritative.

Writing does not reverse that. The drive parses the file, recognises a valid .docly wrapper and hands it to document import — the same path that brings a document in from outside. Import is a replacement, not a patch. It carries over the identifying Guid, the Schema, the Document payload and any EmbeddedFiles. It never reads Tags, and it never reads Created. Both are simply absent from the new document: tags because no tag rows are recreated, Created because the import stamps the row as it writes it.

So the envelope is written on export and only partly honoured on import. A field can round-trip through your editor perfectly, be visible in the file the whole time, and still be discarded on save.

The repair loop follows from the same fact. Writing the correct Tags back into the file is itself a save, which is another import, which ignores Tags — the second attempt fails exactly like the first, and so does the tenth.

The two losses are not equally serious. Tags are recoverable, because docly.addTag writes tag rows through a path that has nothing to do with the drive. Created is not: no API writes it, and once the original date is overwritten there is nothing left to read it back from.

What to do

Treat a drive edit as costing the document its tags and its creation date. For most content neither matters. Both matter on documents that are tagged for filtering or search, and on anything a template sorts or displays by creation date.

Read the tags before you edit, and put them back afterwards. A short API script restores them, and it is idempotent, so running it twice is harmless:

// #/API/RestoreTags.js
export default () => {
    let path = "/Invoices/Invoice 1001";
    docly.addTag(path, "invoice");
    return docly.addTag(path, "paid");
}

Note the path form: a schema-bound document is addressed without its .docly extension, exactly as it is in a link. See Omit file extensions in links.

Where the creation date is content, keep it in a field of your own. A schema field is written by you and never restamped, so it survives any number of drive edits, while the envelope's Created does not:

"Published": "2024-11-03"

Sort and display on that field — the same reasoning as Sort folder contents by a custom field.

Before editing a batch of documents, record what you are about to lose. One pass with listFiles captures every tag in the folder, and it is the only chance you get:

#{ docly.setMime("text/plain"); }#
#{
    for (let f of docly.listFiles("/Invoices", "*", true))
        write(f.Name + " = " + JSON.stringify(f.Tags) + chr(13));
}#

Do not try to repair either field by editing the file. That save is an import too. Tags go back through addTag; the creation date does not go back at all.

When you are creating a document rather than editing one, none of this applies — but note that a new document's envelope Tags are not imported either, so tag it with addTag after it registers. See Creating new docly files.