Task Linked Files

A task Linked File is a file reference in URL format for a file that is linked to a task. Omni Automation in OmniFocus (v3.8+) provides the ability to add and remove file links to/from tasks.

File links are often used in place of task attachments in order to minimize the size of the data added to the OmniFocus database. The inclusion of large files in a synced OmniFocus database can compromise performance across devices.

Task Linked File Properties

There is one property regarding Linked Files for the Task class:

• linkedFileURLs (Array of URL r/o) • The list of file URLs linked to this task. The files at these URLs are not present in the database, rather the database holds bookmarks leading to these files. These links can be read on iOS, but not written to.

Task Linked Files Functions

The functions of the Task class dealing with the management of file links.

• addLinkedFileURL(url:URL) • Links a file URL to this task. In order to be considered a file URL, url must have the file scheme. That is, url must be of the form file://path-to-file. The file at url will not be added to database, rather a bookmark leading to it will be added. In order to add files to a task, use the addAttachment function. Linking files is especially useful for large files, as including large files in the database can degrade app performance.

• removeLinkedFileWithURL(url:URL) • Removes the first link to a file with the given url. This removes the bookmark that leads to the file at url. If the file itself is present in the database, use the removeAttachmentAtIndex function instead.

Adding File Links

Task File Links are instances of the URL class with each instance representing a file.

The following example plug-in demonstrates how create File Link instances from chosen files and add them to a selected task.

Add Chosen Files to Task as Links
Copy Download Plug-In Install Plug-In

/*{
	"type": "action",
	"targets": ["omnifocus"],
	"author": "Otto Automaator",
	"identifier": "com.omni-automation.of.add-linked-files-to-task",
	"version": "1.1",
	"description": "This action will add chosen files as file links to the selected task.",
	"label": "Add File Links to Task",
	"shortLabel": "Add File Links",
	"paletteLabel": "Add File Links",
	"image": "doc.on.doc"
}*/
(() => {
	const action = new PlugIn.Action(async function(selection, sender){
		task = selection.tasks[0]
		
		picker = new FilePicker()
		picker.folders = false
		picker.multiple = true
		picker.types = null // any file type
		urlsArray = await picker.show()
		urlsArray.forEach(url =>{
			task.addLinkedFileURL(url)
		})
	});

	action.validate = function(selection, sender){
		return (selection.tasks.length === 1)
	};
	
	return action;
})();

Deleting File Links

Should you wish to remove file links from their assigned task, Omni Automation provides two mechanisms for deleting existing file links:

Deleting All File Links of Selected Tasks
Copy Run Script

tasks = document.windows[0].selection.tasks
tasks.forEach(task =>{
	urls = task.linkedFileURLs
	console.log(urls)
	urls.forEach(url => {
		task.removeLinkedFileWithURL(url)
	})
})