Document Export

OmniPlan supports the export of documents 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 OmniPlan documents can be found in FileTypes and FileSavers.

FileWrappers

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

For example, one package may store the data as tabbed data, while another may store the project 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 FileWrappers.

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 OmniPlan, 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 FileWrappers supported in OmniPlan:

OmniPlan Writable Types Identifiers
Copy

document.writableTypes
//--> ["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"]

A variation of the previous script that returns the types as a multi-line text block:

OmniPlan Writable Types Identifiers
Copy

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

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

• makeFileWrapper(baseName:String, type:String or null) → (Promise r/o) • 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.

Make File Wrapper of Specified Type
Copy

var fileName = "My File Name"
var typeID = "public.comma-separated-values-text"
var wrapperPromise = document.makeFileWrapper(fileName, typeID)

wrapperPromise.then(wrapper => {
	console.log(wrapper)
	//--> [object FileWrapper: file, 682 bytes]
})

wrapperPromise.catch(err => {
	console.error(err.message)
})

NOTE: If the document identifier parameter is omitted from the makeFileWrapper(…) function, the default document type (OmniPlan Document (.oplx)) is automatically used.

Make Default File Wrapper
Copy

var wrapperPromise = document.makeFileWrapper("My File Name")
wrapperPromise.then(wrapper => {
	console.log(wrapper)
	//--> [object FileWrapper: file, 682 bytes]
})

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.

• children (Array of FileWrapper r/o) • Returns an Array of child FileWrappers, if this represents a directory. Otherwise, an empty array is returned.

• contents (String or nil r/o Data) • Returns the regular file contents of the wrapper, if this represents a regular file. Otherwise, null is returned.

• destination (URL or nil r/o) • Returns the destination if this represents a symbolic link. Otherwise, null is returned.

• filename (String or nil) • Returns the actual file name that was last read for this file wrapper. Depending on the names of other sibling wrappers, this may not be what file name will be written.

• preferredFilename (String or nil) • Returns the preferred file name that should be used when writing the file wrapper if no other file in the same parent directory wrapper is in use.

• type (FileWrapper.Type r/o) • Returns the type of this FileWrapper

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

For example, here’s an example of exporting the current data view to a new OmniFocus task as a PNG image:

Add OmniPlan Snap to New OmniFocus Task
Copy

docName = document.name
wrapperPromise = document.makeFileWrapper(docName, "public.png")
wrapperPromise.then(wrapper => {
	encodedData = wrapper.contents.toBase64()
	taskName = encodeURIComponent(docName)
	attachmentName = taskName + ".png"
	urlStr = "omnifocus://localhost/add?name=" + taskName + "&attachment=" + encodedData + "&attachment-name=" + attachmentName
	URL.fromString(urlStr).call(result => {
		console.log(result)
		//--> "omnifocus:///task/eb1BMyUGr2F"
	})
})

NOTE: To create the new task without returning a result to OmniPlan, use the open() function of the URL class instead of the call() function:

OmniPlan Snap to New OmniFocus Task (no return result)
Copy

docName = document.name
wrapperPromise = document.makeFileWrapper(docName, "public.png")
wrapperPromise.then(wrapper => {
	encodedData = wrapper.contents.toBase64()
	taskName = encodeURIComponent(docName)
	attachmentName = taskName + ".png"
	urlStr = "omnifocus://localhost/add?name=" + taskName + "&attachment=" + encodedData + "&attachment-name=" + attachmentName
	URL.fromString(urlStr).open()
})

Class Functions

The class functions for the FileWrapper class:

• withContents(name:String or null, contents:Data or null) --> FileWrapper • Returns a new FileWrapper that represents a flat file containing the given data.

• withChildren(name:String or null, children:Array of FileWrapper) --> FileWrapper • Returns a new FileWrapper that represents a directory with the given child file wrappers. Each child file wrapper must have a unique name specified.

Instance Functions

The instance functions for the FileWrapper class:

• filenameForChild(child:FileWrapper) --> String or null • Returns the unique file name that will be used for the given child FileWrapper, or null if this file wrapper is not a child of the receiver.

The following example uses the FileWrapper.withChildren(…) function to generate a new folder containing mutliple image export files. Note the use of the Promise.all() function to handle mutliple instances of file wrapper promises:

Multiple Exports
Copy

var docName = document.name

PNGwrapperPromise = document.makeFileWrapper(docName, "public.png")
JPGwrapperPromise = document.makeFileWrapper(docName, "public.jpeg")
promises = [PNGwrapperPromise, JPGwrapperPromise]

Promise.all(promises).then(fileWrappers => {
	filesaver = new FileSaver()
	folderType = new FileType("public.folder")
	filesaver.types = [folderType, FileType.png, FileType.jpeg]
	fldrwrapper = FileWrapper.withChildren("Export Folder", fileWrappers)
	fileSaverPromise = filesaver.show(fldrwrapper)

	fileSaverPromise.then(urlObj => ){
		console.log(urlObj.string) // file url to directory
		urlObj.open() // on macOS open the directory
	})

	fileSaverPromise.catch(function(err){
		console.error("Error", err.message)
	})
}).catch(function(err){
	console.error("Error", err.message)
})

PRO TIP: For those with a more advanced knowledge of JavaScript, here is the previous multiple export types script written using await statements within an asynchronous function wrapper as an alternative to explicit Promise blocks:

Asynchronous Export
Copy Run Script

(async () => {
	try {
		docName = document.name
		PNGwrapper = await document.makeFileWrapper(docName, "public.png")
		JPGwrapper = await document.makeFileWrapper(docName, "public.jpeg")
		filesaver = new FileSaver()
		folderType = new FileType("public.folder")
		filesaver.types = [folderType, FileType.png, FileType.jpeg]
		fldrwrapper = FileWrapper.withChildren("Export Folder", [PNGwrapper, JPGwrapper])
		savedURL = await filesaver.show(fldrwrapper)
		savedURL.open()
	}
	catch(err){console.error(err)}
})();

FileWrapper.Type

The class properties of a FileWrapper.Type:

• Directory --> (FileWrapper.Type r/o) • A FileWrapper that represents a directory with zero or more child wrappers.

• File --> (FileWrapper.Type r/o) • A FileWrapper that represents a regular file with data contents.

• Link --> (FileWrapper.Type r/o) • A FileWrapper that represents a symbolic link to another location.

Here are descriptions of the FileWrapper.Types supported by OmniPlan:

OmniPlan Document (.oplx)

Of course, OmniPlan can export to its own format. This is useful when you want to use the filtering feature to make a new OmniPlan file of tasks matching certain criteria—just filter the tasks and make sure that Only Filtered Contents is checked when you go to export the project.

com.omnigroup.omniplan2.planfile

com.omnigroup.omniplan2.planfile-zip (New in OP 4.x)

iCalendar (.ics)

This is the calendar format used by Apple iCal, Apple Calendar, and many other calendar applications. You can choose to export the tasks as calendar events or as items on a to-do list. If you export calendar events, you can also choose whether each task should become to a single event, regardless of how long it may be (One event per task), or whether tasks should be broken into chunks when they span working and non-working hours (One event per work period).

com.apple.ical.ics

Comma Separated Values (.csv)

CSV is a common, plain-text format that can be read by many different applications. 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 one of the other encoding options. This makes it easier for some applications to detect the correct encoding and interpret your characters properly.

public.comma-separated-values-text

Image Export (.png, .pdf, .tiff, .jpg)

You can export a picture of the task view or the resource view, whichever one is open in the main window. In the Export panel, you can choose whether the image should include the outline, the chart, or both.

public.png, public.tiff, public.jpeg

OmniOutliner (.oo3)

The task outline is exported as an OmniOutliner file (supported by OmniOutliner 3 and 4), with row hierarchy that corresponds to OmniPlan’s task groupings and columns corresponding to those available in OmniPlan’s Task View.

com.omnigroup.omnioutliner.oo3

OmniGraffle

There are several types of OmniGraffle export available across an array of diagram types and style. Available diagram types for export include:

Work Breakdown Structure—Tasks and groups are represented by a tree of objects. The connection lines in this diagram type represent the hierarchy of the task outline; dependency lines are not represented.

Activity-on-Node Network Diagram—Tasks are represented by objects, connected by dependency lines. While a Gantt chart emphasizes durations, this type of chart emphasizes the path of dependencies.

Activity-on-Arrow Network Diagram—Tasks are represented as lines between objects, with the title and duration of the task as a label on each line. Like the Activity-on-Node network diagram, this diagram type emphasizes dependencies.

When exporting to a Work Breakdown Structure or an Activity-on-Node network diagram, you can choose between two different node Styles: nodes that represent tasks as basic objects (which just show the task name) or as tables (which show the task name, assigned resources, start date and end date).

com.omnigroup.OmniPlan.graffle

Adobe PDF

Export to standard Adobe PDF file.

com.adobe.pdf

Microsoft Project Support (Pro)

Exports a .ooutline file, containing the textual data from the OmniGraffle canvas. Exporting to OmniOutliner works best for diagrams that adhere to a tree-like structure. OmniGraffle uses the connection lines between shapes to create the outline hierarchy.

com.microsoft.mpp, com.microsoft.project.mspdi

If you’re ever called upon to reach across the aisle and use OmniPlan in tandem with Microsoft Project, there’s good news—OmniPlan Pro supports both export to and import from the vast majority of Project file formats.

Documents in the Microsoft Project XML or MPP formats created with Microsoft Project versions 2003 through 2016 can be opened by OmniPlan Pro.

Along with importing from the most-used MS Project formats, OmniPlan Pro can output to them as well. The following Microsoft Project formats are supported:

Extensible Markup Language (XML) and Microsoft Project Plan (MPP) Microsoft Project 2003 to 2016 can read and write these formats. MPP is the preferred format for most interactions with modern versions of Microsoft Project; as an open standard, XML is useful for interaction with other applications as well.

NOTE: OmniPlan’s Microsoft Project MPP export is updated to be most highly compatible with the newest MPP format we support (that used by Microsoft Project 2016). MPP files generated by OmniPlan will still open in older versions of Microsoft Project, but may not be as fully readable to them. Older versions of Microsoft Project may prompt you to download an update or converter from Microsoft to support the newer file format exported by OmniPlan.

See the built-in OmniPlan Help documentation for details concerning Microsoft Project exports.

Example: Export to Microsoft Project

Here’s a script demonstrating the export of the current document in Microsoft Project format.

Export to Microsoft Project Format
Copy Run Script

docName = document.name 
wrapperPromise = document.makeFileWrapper(docName, 'com.microsoft.mpp')

wrapperPromise.then(function(wrapper){
	filesaver = new FileSaver()
	filetype = new FileType('com.microsoft.mpp')
	filesaver.types = [filetype]
	fileSaverPromise = filesaver.show(wrapper)

	fileSaverPromise.then(function(urlObj){
		console.log(urlObj.string) // url to saved file
	})

	fileSaverPromise.catch(err => {
		console.error(err.message)
	})
}).catch(err => {
	console.error(err.message)
})

PRO TIP: And here is the previous export script written using await statements within an asynchronous function wrapper as an alternative to explicit Promise blocks:

Export to Microsoft Project Format (asynchronous)
Copy Run Script

(async () => {
	try {
		docName = document.name 
		wrapper = await document.makeFileWrapper(docName, 'com.microsoft.mpp')
		filesaver = new FileSaver()
		filetype = new FileType('com.microsoft.mpp')
		filesaver.types = [filetype]
		urlObj = await filesaver.show(wrapper)
		console.log(urlObj.string)
	}
	catch(err){console.error(err)}
})();