Document and Data Export

OmniFocus supports the export of documents and data to files of various formats. This section examines how to create File Wrappers in preparation for the export of documents and content.

Documentation regarding the other classes involved in the saving and export of OmniFocus documents can be found in FileTypes and FileSavers.


If you think of an outline as a set of data, then it’s easy to understand that an outline’s data can be packaged in a variety of ways. Each “data package” has a set of parameters that determine how the outline data is stored or presented.

For example, one package may store the data as tabbed data, while another may store the outline data in XML format. Each of the supported file packaging formats has its own set of parameters. In terms of Omni Automation, these file packages are referred to as instances of the FileWrapper class.

Each instance of the FileWrapper class has a unique type identifier that identifies that wrapper. To get a list of the export types supported by OmniOmniFocus, write a simple script to access the value of the writableTypes property of the Document class. The result will be an array of the identifiers for the FileWrapper types supported in OmniFocus.

For documentation of both readable and writable file types in OmniFocus, visit the FileType shared topic.

The following example script generates an array of the identifiers that comprise the value for the writableTypes property:

OmniFocus FileWrapper Writable Types

var types = document.writableTypes.map(type => { return "\"" + type + "\"" }) types = "[" + types.join(",\n") + "]" console.log(types) //--> ["com.omnigroup.omnifocus.filetype.ofocus", "com.omnigroup.omnifocus2.export-filetype.plain-text", "com.omnigroup.omnifocus2.export-filetype.html", "com.omnigroup.omnifocus2.export-filetype.comma-separated-values", "com.omnigroup.omnifocus2.export-filetype.comma-separated-values-unicode", "com.omnigroup.omnifocus.filetype.ofocus-backup"]

A writable type identifier is used with the makeFileWrapper() function when creating a new file wrapper instance:

New FileWrapper Instance

var fileTypeID = "com.omnigroup.omnifocus.filetype.ofocus" var baseName = "OF Backup" var wrapperPromise = document.makeFileWrapper(baseName, fileTypeID) wrapperPromise.then(wrapper => { console.log(wrapper) }) wrapperPromise.catch(err => { console.error(err.message) })

Instance Properties

Each FileWrapper instance has a set of supported properties, most of which have values that are read-only, with the exception of the preferredFilename property whose value can be set in a script.

The value of the contents property is a representation of the outline data, which can be manipulated using class and instance functions from the Data class:

Base 64 Encode New File Wrapper Instance

var fileTypeID = "com.omnigroup.omnifocus.filetype.ofocus" var baseName = "OF Backup" var wrapperPromise = document.makeFileWrapper(baseName, fileTypeID) wrapperPromise.then(function(wrapper){ encodedData = wrapper.contents.toBase64() console.log(encodedData) }) wrapperPromise.catch(function(err){ console.error(err.message) })

Class Functions

The class functions for the FileWrapper class:

Instance Functions

The instance functions for the FileWrapper class:


The class properties of a FileWrapper.Type:

Export Types

Here are the various export formats with their corresponding file type identifiers:

OmniFocus Document (.ofocus)
This is an ordinary OmniFocus document, like the one that you use as your database. If you open such a file in OmniFocus, it appears in its own window and you can work with it normally, but settings specific to your database (such as custom perspectives and View options) don’t come along with it.
Plain Text (.txt)
This is a lightweight plain-text representation of your data, able to be opened in the text editor of your choice. OmniFocus’s plain text export is inspired by TaskPaper, the light to-do application from Hog Bay Software. As such the output should be roughly compatible and able to be imported to TaskPaper with a minimum of fuss.
Simple HTML (.html)
This is a single-file HTML representation of your data; the stylesheet and even the icons are embedded in the HTML. If you are proficient with CSS, you should be able to restyle the result however you like.
Comma Separated Values (.csv)
CSV is a common syntax for applications old and new on all platforms: all of your data in a plain text file with its columns separated by commas. Once you have your data in CSV format, it’s easy to run scripts on it, convert it to some other format, or open it in applications that understand it (like OmniPlan). If you’re having trouble persuading other applications to read the non-ASCII characters in your CSV file, such as accented letters or non-Roman characters, try exporting with the UTF–16 CSV option.
Backup Document (.ofocus-backup)
This export option creates a file in a format (.ofocus-backup) that is essentially the same as the standard OmniFocus database format, with one key difference.
Unlike a standard OmniFocus database file, when you open a backup in OmniFocus, the option to Revert to This Backup appears in a notice bar beneath the toolbar. Click this button to replace your local default database with the database contained in the backup.

Saving/Exporting a Specific Document Type

The following Omni Automation script demonstrates how to save a backup OmniFocus document to file. Similar procedures are used by all Omni applications to export data and documents to file.

Detailed documentation regarding the FileType class, and its use to generate application-specific FileWrappers, can be found in the FileType topic.

Save OmniFocus Backup Document

var fmtr = Formatter.Date.withFormat('eee-MMM-dd-yyyy') var defaultName = "OF Backup " + fmtr.stringFromDate(new Date()) var fileTypeID = 'com.omnigroup.omnifocus.filetype.ofocus-backup' var wrapperPromise = document.makeFileWrapper(defaultName, fileTypeID) wrapperPromise.then(wrapper => { var filesaver = new FileSaver() var filetype = new FileType(fileTypeID) filesaver.types = [filetype] filesaver.show(wrapper) })

(01) Create a Date Formatter from generating a date slug to use in the file name.

(02) Append the date slug to the name for the saved file.

(03) The FileType identifier string of the file type to be saved or exported to file.

(04) A file wrapper is created using the makeFileWrapper(…) function, which is passed the stored file type identifier and the default file name as parameters. The function returns an instance of the JavaScript Promise class, which when resolved will provide the created file wrapper instance. The generated promise is stored in the variable: wrapperPromise

(06-24) The stored promise is resolved by calling the then(…) function on the stored instance. If the wrapper creation is successful, the method’s call-back function will be passed a reference to the created file wrapper.

(07) With the file wrapper created, the script can now display the file saver dialog to the user so they may provide the file name and saving location. A new instance of the FileSaver class is created and stored in the variable: filesaver

(08-10) On macOS, file saver dialogs can be customized to the include a user prompt and an approval button title. These FileSaver properties will be ignored should the script be executed on a device running iOS or iPadOS, both of which do not offer the ability to customize saving dialogs.

(11) Create and store an instance of the FileType class using the previously stored file type identifier.

(12) The value of the types property of the FileSaver class is an array of file types to be exported. In this example the property value will be an array containing a single file type instance.

(13) The saving dialog is displayed by calling the show(…) function and passing in the stored file wrapper instance as the parameter. The result of the function call is a JavaScript Promise instance, which is stored in the variable: fileSaverPromise

(15-17) When the user completes the saver dialog, the stored fileSaverPromise will be resolved by calling the then(…) function will automatically be passed a URL object referencing the saved file. The passed url can be used to perform any follow-up processing with the created file.

(19-21) Should the user cancel the saving dialog or should a problem occur during the processing of writing the file, the defining error will be passed into the catch(…) function, allowing the script to deal with the issue.

(22-24) The catch(…) is appended to the wrapper promise resolution call, so that any problem in creating the file wrapper can be dealt with by the script.

AirDrop OmniFocus Database Backup

Here is an example script that use the SharePanel class to AirDrop a backup copy of the OmniFocus document:

AirDrop Backup of OmniFocus Document

var fileTypeID = 'com.omnigroup.omnifocus.filetype.ofocus-backup' var defaultName = "OmniFocus DB Backup" var wrapperPromise = document.makeFileWrapper(defaultName, fileTypeID) wrapperPromise.then(wrapper => { new SharePanel([wrapper]).show() })

When the script is run, the share sheet appears from which you can select the option to AirDrop the exported file:

share-sheet airdrop-dialog  

Share Task Attachments

Here’s a plug-in variation of the previous script example, that displays share sheet for the attachments of the selected task:

Share Task Attachements

/*{ "author": "Otto Automator", "targets": ["omnifocus"], "type": "action", "identifier": "com.omni-automation.of.share-attachments", "version": "1.0", "description": "Displays a share sheet for sharing the task attachments.", "label": "Share Attachments", "mediumLabel": "Share Attachments", "paletteLabel": "Share Attachments", "image": "square.and.arrow.up.on.square" }*/ (() => { var action = new PlugIn.Action(function(selection, sender){ var task = selection.tasks[0] new SharePanel(task.attachments).show() }); action.validate = function(selection, sender){ return ( selection.tasks.length === 1 && selection.tasks[0].attachments.length !== 0 ) }; return action; })();