Escribal
Back to Docs

Text Doc

Comments & tracked changes

This group of instructions is used to add comments to a document and to manage tracked changes (the revisions a word processor shows when someone edits with “Track Changes” enabled): turning it on, accepting or rejecting changes, and setting the revision author.

Prerequisite: before using any of these instructions, the workflow must already have a DOCX document created or opened (with Create text doc), which these instructions will act upon.

These concepts recur across several instructions; they are explained here once.

  • Document: indicates which document in the workflow the instruction applies to. If left empty, the current document is used.

  • Dynamic values (@name): in any text field you can type @ followed by the name of a value saved earlier in the workflow, and it will be replaced by that value. For example, if you saved the author in revisionAuthor, you can type @revisionAuthor in the Author field.

  • Saving a result: some instructions offer a field to save a value they produce (for example, the identifier of the created comment or the number of changes processed) under a name, so you can reuse it in later steps. If left empty, nothing is saved.

  • The value -1 means “all”: instructions that act on a specific element by its identification number accept -1 (the default) to act on all elements at once.

  • “From variable” fields: the @name trick only works in text fields. So that a numeric field (like Comment Id) or a yes/no field (like Enable) can also take its value from a saved value, each one has a companion “from variable” field:

    • If you leave it empty, the value typed in the normal field is used.
    • If you fill it in with the name of a saved value, the engine ignores the normal field and uses that variable’s value.

    This is mainly for chaining instructions. For example, an Insert Comment instruction can save the identifier of the comment it creates; then a Delete Comment with the Comment Id (from variable) field pointing at that value will delete exactly that comment, without you having to know its number in advance. If you only work with fixed values, you can ignore these fields.

Accept All Tracked Changes .docx

Accepts all tracked changes in the document at once.

When to use it: to finalize the document by approving all marked edits, without going through them one by one.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Save number of changes Name under which to save how many changes were accepted (empty) No

Accept Tracked Change .docx

Accepts a specific tracked change by its identifier, or all changes. Accepting a change makes it a permanent part of the document.

When to use it: to approve edits marked with track changes (inserted text, deleted text, or formatting changes).

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Revision Id Identifier of the change to accept; -1 accepts all -1 (all) No
Revision Id (from variable) Reads the identifier from a saved value (empty) No

Important behavior: accepting keeps the inserted text, permanently removes the text marked as deleted, and keeps the formatting changes.

Delete Comment .docx

Deletes a specific comment by its identifier, or all comments in the document.

When to use it: to clean up comments before delivering the document, or to remove a specific annotation.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Comment Id Identifier of the comment to delete; -1 deletes all -1 (all) No
Comment Id (from variable) Reads the identifier from a saved value (empty) No

Important behavior: if the document has no comments, the instruction does nothing.

Insert Comment .docx

Inserts a comment into the document, anchored to a specific bookmark or, if no bookmark is given, to the last paragraph of the document.

When to use it: when you want to leave a note or annotation on part of the text, just like the “New Comment” button of a word processor.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Comment text Content of the comment. Supports @name Comment text. Yes
Author Name of the comment’s author. Supports @name Author No
Initials Author’s initials. Supports @name A No
Bookmark Name of the bookmark to anchor the comment to (empty) No
Save comment Id Name under which to save the identifier of the created comment (empty) No

Important behavior: if the Bookmark field is empty, or if the given bookmark does not exist, the comment is anchored to the last paragraph of the document.

Reject All Tracked Changes .docx

Rejects all tracked changes in the document at once, restoring the original content.

When to use it: to discard all marked edits and return the document to how it was before the revisions.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Save number of changes Name under which to save how many changes were rejected (empty) No

Reject Tracked Change .docx

Rejects a specific tracked change by its identifier, or all changes. Rejecting a change undoes the edit and restores the previous state.

When to use it: to discard edits marked with track changes and return to the original content.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Revision Id Identifier of the change to reject; -1 rejects all -1 (all) No
Revision Id (from variable) Reads the identifier from a saved value (empty) No

Important behavior: rejecting discards the inserted text, restores the text marked as deleted, and returns the formatting to its previous state.

Set Revision Author .docx

Saves the revision author’s name and initials so that subsequent Insert Comment instructions can reuse them.

When to use it: at the start of the workflow, to define once who signs the comments and avoid repeating the author on each one.

Parameter Meaning Default Required
Author name Name to save. Supports @name Author No
Initials Initials to save. Supports @name A No
Save name in Name under which the author is saved revisionAuthor No
Save initials in Name under which the initials are saved revisionInitials No

Important behavior: this instruction does not modify the document; it only saves values for later use. In a later Insert Comment instruction, type @revisionAuthor in the Author field and @revisionInitials in Initials to apply them.

Set Track Changes .docx

Enables or disables tracked changes for the document.

When to use it: enable it before making edits you want recorded as revisions; disable it so later edits are not tracked.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Enable Yes to enable tracked changes, No to disable them Yes (enabled) No
Enable (from variable) Reads the yes/no value from a saved value (empty) No

This documentation is the help of the application, and it comes underCreative Commons Attribution 4.0.