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.
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:
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"
}
)
})
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.
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:
canRedo (boolean r/o) • Whether there are currently any actions that can be redone.
canUndo (boolean r/o) • Whether there are currently any actions that can be undone.
name (String r/o) • Name of the document.
writableTypes (Array of Strings r/o) • A list of the identifiers for all of the possible document types for writing the document to file.
fileType (String r/o) • The file type identifier the document uses when saving, if set.
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:
project (Project r/o) • The value of this property is a reference to the OmniPlan project object contained by the document.
windows (Array of NSWindows r/o) • An array of references to the windows that display the OmniPlan document content.
Class Functions
Here are the functions for the Document class of objects:
makeNew(resultFunction: Function) → (PlanDocument) • 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) → (PlanDocument) • 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.
Instance Functions
Here are the functions for 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( ) → ( ) • Save the document into its source file, if the document has been saved before. If the document has not been already saved once, summon the Save sheet.
fileWrapper(String or null) → (FileWrapper) • Deprecated: Please use makeFileWrapper() instead. 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 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 undone action.
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.
- com.omnigroup.omniplan2.planfile-zip
- com.omnigroup.omniplan2.planfile
- com.apple.ical.ics
- public.comma-separated-values-text
- com.microsoft.mpp
- com.microsoft.project.mspdi
- public.png
- com.adobe.pdf
- public.tiff
- public.jpeg
- com.omnigroup.omnioutliner.xmlooutline
- com.omnigroup.foreign-types.graphviz-gv
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.
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"
})
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.
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.
Close Document
document.close()
Create a new document and close the previous docuemnt.
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.
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()
})