OmniPlan: Document

A Document is the top-level object in Omni Automation. For security reasons, scripts can only address the frontmost document, they cannot query for or address other documents that may be open. Unlike other classes of objects, such as graphics, that can be addressed by index, the “current document” is simply referenced as document instead of app.documents[0] in your scripts.

The following documentation describes how open, create, save, and close documents, as well as how to access a document’s properties.

Open Document

To open an OmniPlan file, a file URL is passed to the openDocument application method. This handler attempts to open the specified document and to return a reference to it asynchronously. If the document is already open, the reference to the open document 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 file 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 return two arguments: the first (result) will be either either the Document reference or an Error. On success, the second argument (wasOpen) is a Boolean value specifying whether the document was already open.

app.openDocument(document,fileURL,function(result,wasOpen){}

A an example, here is a script that uses the FilePicker class to prompt the user to locate and select an OmniPlan document (in either file or package format) and then open the chosen document:

var picker = new FilePicker() picker.folders = false picker.multiple = false aFileType = new FileType("com.omnigroup.omniplan2.planfile","com.omnigroup.omniplan2.planfile-zip") picker.types = [aFileType] pickerPromise = picker.show() pickerPromise.then(function(urlsArray){ fileURL = urlsArray[0] app.openDocument( document, fileURL, function(doc,wasOpen){ task = doc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" } ) })
omniplan://localhost/omnijs-run?script=try%7Bvar%20picker%20%3D%20new%20FilePicker%28%29%0Apicker%2Efolders%20%3D%20false%0Apicker%2Emultiple%20%3D%20false%0AaFileType%20%3D%20new%20FileType%28%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%22%2C%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%2Dzip%22%29%0Apicker%2Etypes%20%3D%20%5BaFileType%5D%0ApickerPromise%20%3D%20picker%2Eshow%28%29%0A%0ApickerPromise%2Ethen%28function%28urlsArray%29%7B%0A%09fileURL%20%3D%20urlsArray%5B0%5D%0A%09app%2EopenDocument%28%0A%09%09document%2C%0A%09%09fileURL%2C%0A%09%09function%28doc%2CwasOpen%29%7B%0A%09%09%09task%20%3D%20doc%2Eproject%2Eactual%2ErootTask%2EaddSubtask%28%29%0A%09%09%09task%2Etitle%20%3D%20%22NEW%20TASK%22%0A%09%09%7D%0A%09%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

 01  Create a new instance of the FilePicker class and store a reference to it in the variable: picker

 02-03  Set the properties of the file picker to select a single document file.

 04  Indicate the file types that can be selected within the file picker. In this case, the bundle and single-file version of the standard OmniPlan document format.

 05  Set the file types for the file picker to the stored list of file types.

 06  Use the show() function to display the file picker. The resulting JavaScript promise object is stored in the variable: pickerPromise

 08-18  Use the then() method with the stored promise object to process the array of URLs chosen in the file picker.

 09  Since multiple selections were not allowed, the resulting file URL will be the first in the array of one.

 10-17  The OmniPlan openDocument(…) is called on the application object, passing in the chosen file URL to the then(…) callback function.

 13-16  The callback function of the openDocument(…) command will pass-in a reference to the newly created document, and a boolean value indicating if it was already open.

 14  Create a new task in the new project document. note the use of the project object in the reference chain to the rootTask of the new project.

 15  Set the title of the newly created task.

Instance Properties

Here are the properties of the Document class:

Instance Properties: PlanDocument

The PlanDocument class is a subclass of the Document class used to represent properties that are specific to OmniPlan documents. Here are the properties of the PlanDocument class:

Class Functions

Here are the functions for the Document class of objects:

Instance Functions

Here are the functions for an instance of the Document class:

Examples

Name

The read-only name property has a value that is the name of the OmniPlan document as it appears in the title bar of the document window. On macOS, this value will reflect the value of the Finder’s file extension visibility setting, set in the file’s Information window.

Writable Types

The value of the writableTypes property of the document class is an array (list) of all of the file types that this document can be written as.

File Type

The value of the fieType property of the document class is the default file type that this document is set to be saved as.

Document Undo

If the value of the document’s canUndo property is true, then the undo() method can be used to undo the previous user or script action.

if(document.canUndo){document.undo()}
omnigraffle:///omnijs-run?script=if%28document%2EcanUndo%29%7Bdocument%2Eundo%28%29%7D

Document Redo

If the value of the document’s canRedo property is true, then the redo() method can be used to re-apply the previous user or script action.

if(document.canRedo){document.redo()}
omnigraffle:///omnijs-run?script=if%28document%2EcanRedo%29%7Bdocument%2Eredo%28%29%7D

New Document

The makeNew(…) and makeNewAndShow(…) instance functions of the Document class are used to create and display a new OmniPlan document.

cDoc = document console.log(cDoc.name) Document.makeNew((nDoc)=>{ console.log(nDoc.name) task = nDoc.project.actual.rootTask.addSubtask() task.title = "NEW RESOURCE" })
omniplan://localhost/omnijs-run?script=try%7BcDoc%20%3D%20document%0Aconsole%2Elog%28cDoc%2Ename%29%0ADocument%2EmakeNew%28%28nDoc%29%3D%3E%7B%0A%09console%2Elog%28nDoc%2Ename%29%0A%09task%20%3D%20nDoc%2Eproject%2Eactual%2ErootTask%2EaddSubtask%28%29%0A%09task%2Etitle%20%3D%20%22NEW%20RESOURCE%22%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D

 01  (optional) Store a reference to the current document in the variable: cDoc

 02  (optional) Log the name of the current document in the Automation Console.

 03  Call the makeNew(…) function on the Document class to generate a new instance (document). The passed-parameter of the function is a callback function that is passed either an error or a reference to the newly created document in the parameter variable: nDoc

 04  (optional) Log the name of the newly created document in the Automation Console.

 05  Create a new top-level task in the new document. Note that a reference chain to the actual scenario, including the specified project property of the PlanDocument class, is used when calling the newSubtask(…) function. This is done to avoid inadvertently referencing the previous document. The resulting reference to the created task is stored in the variable: task

 06  Set the value of the title property of the new task object.

And a version of the previous script that uses the makeNewAndShow(…) function to create, display, and triggers a saving sheet for a new document that contains a new task.

Document.makeNewAndShow((nDoc)=>{ task = nDoc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" nDoc.save() })
omniplan://localhost/omnijs-run?script=try%7BDocument%2EmakeNewAndShow%28%28nDoc%29%3D%3E%7B%0A%09task%20%3D%20nDoc%2Eproject%2Eactual%2ErootTask%2EaddSubtask%28%29%0A%09task%2Etitle%20%3D%20%22NEW%20TASK%22%0A%09nDoc%2Esave%28%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
new-and-save-doc

Document Close

Close the current host document.

document.close()
omniplan://localhost/omnijs-run?script=document%2Eclose%28%29

Create a new document and close the previous docuemnt.

var oldDoc = document Document.makeNewAndShow(function(newDoc){ oldDoc.close() })
omniplan://localhost/omnijs-run?script=var%20oldDoc%20%3D%20document%0ADocument%2EmakeNewAndShow%28function%28newDoc%29%7B%0A%09oldDoc%2Eclose%28%29%0A%7D%29

Create a new document, edit the new document, and then close the previous docuemnt.

IMPORTANT: Do not attempt to close the original document until the end of the script. Scripts are run within the context of a document. The script creating a new document is run in context of the document running the script. Closing the document owning the script will halt the script’s execution.

var oldDoc = document Document.makeNewAndShow(function(newDoc){ task = newDoc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" oldDoc.close() })
omniplan://localhost/omnijs-run?script=try%7Bvar%20oldDoc%20%3D%20document%0ADocument%2EmakeNewAndShow%28function%28newDoc%29%7B%0A%09task%20%3D%20newDoc%2Eproject%2Eactual%2ErootTask%2EaddSubtask%28%29%0A%09task%2Etitle%20%3D%20%22NEW%20TASK%22%0A%09oldDoc%2Eclose%28%29%0A%7D%29%7Dcatch%28err%29%7Bconsole%2Elog%28err%29%7D
UNDER CONSTRUCTION

This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.

DISCLAIMER