Document

By default, OmniFocus is designed to use a single data source whose content is synced across your devices and is even accessible using a web-based HTML interface (browser) on non-Apple hardware.

In OmniFocus, a “document” provides a visual interface to the synced database that manages all of your projects, tasks, schedules, and information.

Document Properties

Here are the scripting properties of a document:

• canRedo (Boolean r/o) • Whether there are currently any actions that can be redone.

• canUndo (Boolean) • Whether there are currently any actions that can be undone.

• fileType (String or null r/o) • The file type identifier the document uses when saving, if set.

• name (String or null r/o) • Document name.

• windows (Array of DocumentWindow r/o) • The windows for this document.

• writableTypes (Array of String r/o) • A list of all of the file types that this document can be written as.

Get the Writable Types
Copy

document.writableTypes.join('\n')
//--> "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"

New Documents

Omni Automation scripts have the ability to create and manipulate new documents using the class and instance functions of the Document class. As OmniFocus is optimized for use with a single data source, the following functions are provided for theoretical and archival purposes.

Class Functions

• makeNew(resultFunction:Function) • Create a new document, which can be populated with data and then presented. On iOS, if the document is not presented by the time the resultFunction returns, it will be closed. On macOS, the document will be left around and accessible to the running script. The resultFunction will be passed either the new document or an Error if there was a problem creating the document.

• makeNewAndShow(resultFunction:Function) • Create a new document and presents it. The resultFunction will be passed either the new document or an Error if there was a problem creating the document.

Show New Document
Copy Run Script

Document.makeNewAndShow(function(newDoc){
	newDoc.windows[0].perspective = Perspective.BuiltIn.Inbox
	var db = newDoc.windows[0].selection.database
	var tsk = new Task("NEW TASK",db.inbox.beginning)
})

Instance Functions

The supportive functions that can be called on an instance of the Document class.

• close(didCancel:Function or null) • Close this document. If for some reason the document cannot be closed, the didCancel function may be called at some point in the future, with the original document as the single argument. For example, on the Mac the user may review unsaved changes and may cancel the close operation. If the document is closed, the didCancel function will not be called at all.

• save() • If the document has saved before, this function will save the document. If the document has not been previously saved, the display of a Save Sheet will be triggered in the application interface.

• fileWrapper(type:String or null) → (FileWrapper) • (DEPRICATED) Returns a new FileWrapper representing the contents of the document formatted as the specified type, or its current fileType if a null is passed for the type.

• makeFileWrapper(baseName:String, type:String or null) → (Promise) • Generates a FileWrapper representing the contents of the document formatted as the specified type, or its current fileType if a null is passed for the type. Returns a JavaScript Promise that will yield the file wrapper or an error. The returned file wrapper will have a name based off the given baseName and the default path extension for the requested file type.

• undo() • Undo the last done action.

• redo() • Redo the last done action.

• show(resultFunction:Function or null) • Presents the document, ordering the window forward on macOS, and possibly closing the existing document and opening the new on on iOS.

Undo and Redo
Copy Run Script

if(document.canUndo){document.undo()}
if(document.canRedo){document.redo()}

Opening an OmniFocus Document

Existing OmniFocus documents are opened using the openDocument(…) function of the Application class.

• openDocument(from:Document or null, url:URL, completed:Function) • Attempts to open the specified document and return a reference to it asynchronously. If the document is already open, the reference is passed along. Note that due to platform sandboxing restrictions, opening the document may fail if the application doesn’t have currently permission to access the given URL. The document, if any, that is associated with the calling script can be passed along to help grant permission to open the new document. The passed in function will be passed two arguments. The first will be either either the Document or an Error. On success, the second argument is a Boolean specifying whether the document was already open.

The following example script uses the FilePicker and FileType classes to display a file picker dialog to the user, allowing them to choose the OmniFocus document to open and process.

Open Document and Process InBox Tasks
Copy

var picker = new FilePicker()
picker.folders = false
picker.multiple = false
aFileType = new FileType("com.omnigroup.omnifocus.filetype.ofocus")
picker.types = [aFileType]
var pickerPromise = picker.show()

pickerPromise.then(urlsArray => {
	fileURL = urlsArray[0]
	app.openDocument(
		document,
		fileURL,
		function(doc,wasOpen){
			if(doc instanceof Document){
				console.log("opened")
				var db = doc.windows[0].selection.database
				db.inbox.forEach((tsk)=>{
					// task processing goes here
				})
			} else {console.error(doc)}
		}
	)			
})