Creating Integration Scripts

  1. Home
  2. Docs
  3. Help & Support
  4. Integration
  5. Creating Integration Scripts

You can write or edit scripts to control how Hook behaves with different applications. For example, you could modify how Hook handles Things to link whole projects instead of individual TODOs, or you could change how Hook integrates with DevonThink, to behave more like Evernote.

The other reason to write your own Hook scripts is to create Hook integration for an application from scratch.

Integration scripting is done through the Script Editor pane. It is strongly suggested that users write and test the scripts in a dedicated Applescript editing application like Script or the (highly recommended) Script Debugger and copy/paste them to the Hook Script Editor fields.

Integration scripts

There are four integration scripts:

  • Get Address
  • Get Name
  • Open Item
  • Link to New Item

Get Address

Returns a URL to identify and retrieve the document or resource or context with.


  • The URL must be unique to each document. Different documents cannot share the same URL.
  • A document must always produce the same URL, even if the document is moved, renamed, or edited.
  • URL must be formed “scheme://document-identifier”
  • Either the URL must open the document or else the Open Item script for the application must be able to parse the URL to open the document

Storing values in the clipboard

  • Hook will save and restore the contents of your clipboard if this script writes over it.

Get Name

Returns the title of the linked resource.

  • If this script doesn’t exist or doesn’t return a value Hook will use the URL from Get URL as the title of the link.
  • Hook will save and restore the contents of your clipboard if this script writes over it.

Open Item

Parses a URL to open the linked item.

Default behaviour

By default, if there is no Open Item script, Hook will pass the URL to macOS to open. If the URL retrieved by Get Address can be opened without assistance, an Open Item script is not required.

For example, links to websites and files are opened with the default web browser or the application assigned to the file type. Many applications, such as Omnifocus, Evernote, and Bear have their own scheme and can handle links to open documents without a custom Open Item script.


Any application which has a custom Open Item script requires a scheme.

The scheme is part of the URL. It identifies the type of resource being opened and the app needed to open it. Hook uses the URL’s scheme to select which Open Item script to handle the link with.

Parse the URL to open the document

The Open Item script should either reformulate the URL into a valid URL and open it, or use the document-idenitifer portion of the URL to locate the document and open it.

Any instance of the string “$0” in the script will be replaced with the URL.

The URL is the same as is returned by Get Address and is formed scheme://document-identifier.

Link to New Item

Creates a new document with the application and links it to the current context.

Link to New Item runs when you select Link to New in the Hook window. This script is entirely optional and not necessary for the core Hook functionality of linking documents and resources.

The Link to New Item script should

  • create a new document
  • name it after the current context
  • open it
  • return the URL of the new item

Any instance of “$title” will be replaced in the script by the title of the current document, to be used to name the new item

Applications which create files don’t need a Link to New Item script, it is easier and better just to put a file in the template folder.

Was this article helpful to you? Yes No

How can we help?