×

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){})
Open Document


app.openDocument(document, fileURL, function(result, wasOpen){ // action to perform on opened document }))

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 and edit the chosen document:

omniplan://localhost/omnijs-run?script=try%7Bvar%20picker%20%3D%20new%20FilePicker%28%29%0Apicker%2Efolders%20%3D%20false%0Apicker%2Emultiple%20%3D%20false%0AfileType1%20%3D%20new%20FileType%28%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%22%29%0AfileType2%20%3D%20new%20FileType%28%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%2Dzip%22%29%0Apicker%2Etypes%20%3D%20%5BfileType1%2C%20fileType2%5D%0ApickerPromise%20%3D%20picker%2Eshow%28%29%0A%0ApickerPromise%2Ethen%28urlsArray%20%3D%3E%20%7B%0A%09fileURL%20%3D%20urlsArray%5B0%5D%0A%09app%2EopenDocument%28%0A%09%09document%2C%0A%09%09fileURL%2C%0A%09%09function%28doc%2C%20wasOpen%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
Open and Edit Document
 

var picker = new FilePicker() picker.folders = false picker.multiple = false var fileType1 = new FileType("com.omnigroup.omniplan2.planfile") var fileType2 = new FileType("com.omnigroup.omniplan2.planfile-zip") picker.types = [fileType1, fileType2] var pickerPromise = picker.show() pickerPromise.then(urlsArray => { var fileURL = urlsArray[0] app.openDocument( document, fileURL, (doc, wasOpen) => { var task = doc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" } ) })

 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-05  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.

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

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

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

 10  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.

Readable/Editable Types

You can get a full list of the names and identifiers of the file types for files that are either readable or editable by OmniPlan, by using the readableTypes and editableTypes properties of the TypeIdentifer class for OmniPlan.

TIP: When presenting a picker dialog to a script user, only enable the selection of the file types that the script is designed to process.

omniplan://localhost/omnijs-run?script=types%20%3D%20TypeIdentifier%2EreadableTypes%2Emap%28type%20%3D%3E%20type%2Eidentifier%29%0Aconsole%2Elog%28%22READABLETYPES%3A%5Cn%5Ct%22%2C%20types%2Ejoin%28%22%5Cn%5Ct%22%29%29%0A%2F%2F%2D%2D%3E%20%5B%22public%2Exml%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eomnijs%2Ecompressed%2Dplugin%22%2C%20%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%22%2C%20%22com%2Emicrosoft%2Empp%22%2C%20%22public%2Etab%2Dseparated%2Dvalues%2Dtext%22%2C%20%22com%2Eomnigroup%2Eomnioutliner%2Exmlooutline%22%2C%20%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%2Dzip%22%2C%20%22com%2Eomnigroup%2Eomniplan3%2Edashboard%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eomnijs%2Esimple%2Dplugin%22%2C%20%22com%2Eomnigroup%2Eframeworks%2Eomnijs%2Esimple%2Dplugin%22%2C%20%22public%2Ecomma%2Dseparated%2Dvalues%2Dtext%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eomnijs%2Eplugin%22%2C%20%22com%2Eomnigroup%2Estatusboard%22%2C%20%22com%2Eomnigroup%2Eomnioutliner%2Eoo3%2Dpackage%22%2C%20%22com%2Eomnigroup%2Eomnioutliner%2Exmlooutline%2Dpackage%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eplanfile%22%2C%20%22com%2Eomnigroup%2Eframeworks%2Eomnijs%2Ecompressed%2Dsimple%2Dplugin%22%2C%20%22com%2Eomnigroup%2Eomnioutliner%2Eoo3%22%5D%0A%0Atypes%20%3D%20TypeIdentifier%2EeditableTypes%2Emap%28type%20%3D%3E%20type%2Eidentifier%29%0Aconsole%2Elog%28%22EDITABLETYPES%3A%5Cn%5Ct%22%2C%20types%2Ejoin%28%22%5Cn%5Ct%22%29%29%0A%2F%2F%2D%2D%3E%20%5B%22com%2Eomnigroup%2Eomniplan3%2Edashboard%22%2C%20%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%2Dzip%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eomnijs%2Esimple%2Dplugin%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eomnijs%2Ecompressed%2Dplugin%22%2C%20%22com%2Eomnigroup%2Eomniplan2%2Eplanfile%22%2C%20%22com%2Eomnigroup%2Eomniplan%2Eomnijs%2Eplugin%22%5D
Readable/Editable File Types for OmniPlan
 

types = TypeIdentifier.readableTypes.map(type => type.identifier) console.log("READABLETYPES:\n\t", types.join("\n\t")) //--> ["public.xml", "com.omnigroup.omniplan.omnijs.compressed-plugin", "com.omnigroup.omniplan2.planfile", "com.microsoft.mpp", "public.tab-separated-values-text", "com.omnigroup.omnioutliner.xmlooutline", "com.omnigroup.omniplan2.planfile-zip", "com.omnigroup.omniplan3.dashboard", "com.omnigroup.omniplan.omnijs.simple-plugin", "com.omnigroup.frameworks.omnijs.simple-plugin", "public.comma-separated-values-text", "com.omnigroup.omniplan.omnijs.plugin", "com.omnigroup.statusboard", "com.omnigroup.omnioutliner.oo3-package", "com.omnigroup.omnioutliner.xmlooutline-package", "com.omnigroup.omniplan.planfile", "com.omnigroup.frameworks.omnijs.compressed-simple-plugin", "com.omnigroup.omnioutliner.oo3"] types = TypeIdentifier.editableTypes.map(type => type.identifier) console.log("EDITABLETYPES:\n\t", types.join("\n\t")) //--> ["com.omnigroup.omniplan3.dashboard", "com.omnigroup.omniplan2.planfile-zip", "com.omnigroup.omniplan.omnijs.simple-plugin", "com.omnigroup.omniplan.omnijs.compressed-plugin", "com.omnigroup.omniplan2.planfile", "com.omnigroup.omniplan.omnijs.plugin"]

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

Property: 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.

Name Property


document.name //--> "Construction Project"

Property: writableTypes

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.

An example plug-in that uses the writableType for a Microsoft Project file type to export the OmniPlan Project as a Microsoft Project file: com.microsoft.project.mspdi

Export as Microsoft Project
 

/*{ "type": "action", "targets": ["omniplan"], "author": "Otto Automator", "identifier": "com.omni-automation.op.export-document", "version": "1.0", "description": "Exports the current document as a Microsoft Project.", "label": "Export as Microsoft Project", "shortLabel": "Export to Microsoft" }*/ (() => { const action = new PlugIn.Action(function(selection, sender){ // action code // Create File Wrapper and File Type let fileTypeID = "com.microsoft.project.mspdi" var filetype = new FileType(fileTypeID) let baseName = document.name let wrapperPromise = document.makeFileWrapper(baseName, fileTypeID) wrapperPromise.then(function(wrapper){ // Create and Show File Saver let filesaver = new FileSaver() filesaver.message = "Choose the location for the saved file:" // macOS filesaver.nameLabel = "Name:" // macOS filesaver.prompt = "Continue" // macOS filesaver.types = [filetype] var fileSaverPromise = filesaver.show(wrapper) // Process File Saver Result fileSaverPromise.then(function(urlObj){ console.log(urlObj.string) // CODE FOR PROCESSING RESULTING FILE URL }) fileSaverPromise.catch(function(err){ console.log(err.message) }) }) wrapperPromise.catch(function(err){ console.error(err.message) }) }); action.validate = function(selection, sender){ // validation code // selection options: project, tasks, resources return true }; return action; })();

Property: fileType

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

File Type


document.fileType //--> "com.omnigroup.omniplan2.planfile-zip"

Function: 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.

Undo Command


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

Function: 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.

Redo Command


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

Functions: makeNew() and makeNewAndShow()

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

In the following example, note the names of the current and new documents are logged to the console. Also note how the newDoc variable containing a reference to the new document is used to create a new task in the new document.

omniplan://localhost/omnijs-run?script=var%20currentDoc%20%3D%20document%0Aconsole%2Elog%28currentDoc%2Ename%29%0ADocument%2EmakeNew%28newDoc%20%3D%3E%20%7B%0A%09console%2Elog%28newDoc%2Ename%29%0A%09var%20task%20%3D%20newDoc%2Eproject%2Eactual%2ErootTask%2EaddSubtask%28%29%0A%09task%2Etitle%20%3D%20%22NEW%20TASK%22%0A%7D%29
New Document
 

var currentDoc = document console.log(currentDoc.name) Document.makeNew(newDoc => { console.log(newDoc.name) var task = newDoc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" })

 1  (optional) Store a reference to the current document in the variable: currentDoc

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

 3  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: newDoc

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

 5  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

 6  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.

omniplan://localhost/omnijs-run?script=try%20%7B%0A%09%2F%2F%20check%20for%20existing%20document%0A%09var%20currentDoc%20%3D%20document%0A%09%2F%2F%20execute%20the%20script%0A%09Document%2EmakeNewAndShow%28newDoc%20%3D%3E%20%7B%0A%09var%20task%20%3D%20newDoc%2Eproject%2Eactual%2ErootTask%2EaddSubtask%28%29%0A%09task%2Etitle%20%3D%20%22NEW%20TASK%22%0A%09newDoc%2Esave%28%29%0A%7D%29%0A%7D%0Acatch%20%28err%29%7B%0A%09console%2Elog%28err%29%0A%7D
Create & Save New Document (makeNewAndShow)
 

Document.makeNewAndShow(newDoc => { var task = newDoc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" newDoc.save() })

Function: close()

Close the current host document.

omniplan://localhost/omnijs-run?script=document%2Eclose%28%29
Close Document
 

document.close()

Create a new document and close the previous docuemnt.

omniplan://localhost/omnijs-run?script=var%20oldDoc%20%3D%20document%0ADocument%2EmakeNewAndShow%28function%28newDoc%29%7B%0A%09oldDoc%2Eclose%28%29%0A%7D%29
New Document Closing Current Document
 

var oldDoc = document Document.makeNewAndShow(function(newDoc){ oldDoc.close() })

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.

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
New Document, Add Task, Close Previous Document
 

var oldDoc = document Document.makeNewAndShow(newDoc => { var task = newDoc.project.actual.rootTask.addSubtask() task.title = "NEW TASK" oldDoc.close() })