When exporting is done from within a sequence set to Optionally or Never show dialogs, Helix must be instructed on how to respond when a file about to be exported would replace an existing file at the target location. This issue can arise for the text file being exported (aka: the control file) as well as for documents stored in fields of the document data type.

In Helix 7.0.2 and earlier, the If document exists property was used to determine how to handle all such situations (text files and documents). The options available are:

• Ask: display a dialog prompting the user to decide how to handle the situation.
• Replace: replace the existing file without asking the user.
• Skip: do not replace the existing file — do not export this data at all.
• Stop: return an error, potentially stopping the sequence entirely.

In Helix 7.0.3 and later, If document exists is obsolete and has been removed entirely. Control is now split into two distinct properties:

1. If control file exists: determine handling of the text file that exports data directly from a view.
2. If documents exist: determine handling of documents stored within fields o the view being exported.

All of the options formerly available to the If document exists property are now available to each of the new properties. Allowing each function to have its own option provides greater flexibility when exporting documents via a sequence.

When a collection is updated to Helix 7.0.3, both of the new properties are initialized with the value that was stored in the obsolete If document exists property, providing for a smooth transition. That is, behavior of existing collections should be unchanged until the collection designer changes one or both of the new properties.

Note the grammatical shift from If document exists to If documents exist: this was done deliberately to draw a distinction between the old property — which was applied to all export functions — and the new one — which applies specifically to documents stored in records.

Existing AppleScripts that use the existing document property are automatically converted to the existing documents property. Scripts can now also read/write the existing control file property using the same set of document export options: {ask, replace, skip, stop}.

Document management within a sequence is a complicated subject, owing to four factors:

1. The document field’s “Internal” vs. “External” storage type
2. The view’s “If documents exist” options; { ask, replace, skip, stop }
3. The sequence’s “Show dialogs” options; { always, optionally, never }
4. The sequence’s “On error” options; { continue, return, stop }

When a sequence is showing dialogs (always or optionally when the Option key is down) the process is straightforward: all dialogs are shown. But when a sequence is not showing dialogs (optionally without the Option key down ornever) and the “If documents exist” property is set to ask, dialogs asking whether or not to replace the document will be displayed. That is, the view’s ask option takes precedence over the sequence’s option to not display dialogs. It may help to understand this if you consider that the option to ask before replacing a document is actually a function of the Export… command, not of the sequence itself. Stated the other way: a seuqence’s “Show dialogs” option applies to the steps in the sequence, not to the actions those steps perform.

When the user is prompted to deal with a duplicate and chooses to ‘stop’ the export process, the export is immediately stopped and control is returned to the sequence, where the “On error” property determines whether the sequence will continue with the next step, return control to the parent sequence (if one exists) or stop entirely. It is important to understand that the Export… command was stopped and control returned to the sequence.

When a sequence is set to continue on error, it proceeds with the next step in that sequence. When a sequence is set to stop on error, the entire sequence chain is stopped. When a sequence is set to return on error, the user is prompted to stop or continue the sequence itself. This “slightly anomalous” specification was implemented to give collection designers access to all three potential options (continue, stop, or let the user decide) when a sequence is interrupted by a stop within a command.

An externally stored document being exported “on stored path” is always skipped: exporting a file to itself is pointless.

An externally stored document being exported “with control file” is skipped if the stored path is the same as the control file location: exporting a file to itself is pointless.

Helix has a facility for automatically renaming a document when exporting would replace an existing document, but this is not implemented in any version of Helix. (It is used for other purposes when the ‘Keep Versions’ property is true.) If you have suggestions for how this may be incorporated in a feature update, we invite your feedback.

Although this facility is not currently used, it has been improved in the following ways:

• Previously, Helix appended a character to the end of the file name. Helix now more closely follows the macOS model of putting a space between the filename and the unique identifier. That is, a duplicate of a file named “sunset.jpg” now becomes “sunset 2.jpg” instead of “sunset.jpg0” as it would have before.
• Like the Finder, Helix now starts numbering duplicated documents at 2, instead of 0. Unlike the Finder, after 2–9 comes A–Z. (The Finder uses 10, 11 …)