Hyperlink API

Introduction

The Hyperlink API is the simplest and easiest way to integrate with and automate tasks in GetBusy.

It allows you to launch the GetBusy web, desktop and mobile apps from anywhere and trigger actions and navigation using parameters within a URL.

Whilst you can write scripts and code to use the Hyperlink API in powerful ways, you don’t have to - you don’t have to worry about connecting to services, managing authentication tokens, callbacks, overrides and a whole bunch of other complicated things that only developers know how to do…

Before you go any further, make sure you have created a GetBusy account at https://app.getbusy.com.

Once you’ve created an account, you’ll be able to use the following link to trigger creation of a new to-do:

Create new to-do

The link we use to create a new to-do is pretty simple:

https://app.getbusy.com/?create=todo

You can give the to-do a title:

Create new to-do with a title

https://app.getbusy.com/?create=todo&title=Try+the+Hyperlink+API

And finally, attach a public web document:

Create a to-do with a title and attachment

https://app.getbusy.com/?create=todo&title=Try+the+Hyperlink+API&file=file-examples.com/wp-content/uploads/2017/10/file-sample_150kB.pdf;name:Sample+web+document.pdf;source:web

Tips

The GetBusy Hyperlink API is designed to work with all of the GetBusy apps on web, desktop (Windows & Mac) and native mobile (iOS & Android).

Most users spend the majority of their time in the desktop and native mobile apps and rarely use the web application. The Hyperlink API can be specifically targeted to these platforms.

The GetBusy Hyperlink API supports two URL protocols (the bit at the beginning of the URL).

• https:// - always opens a new browser tab in your default browser . If you’ve downloaded and installed a GetBusy desktop or native mobile app on your device, the browser will ask if you want to open the link in the app (every time you click or tap an API link).

• getbusy:// - opens or brings the GetBusy desktop or native mobile apps into focus and executes the link within them, bypassing the browser for a much more streamlined experience.

In deciding which URL protocol to use, determine whether the audience is going to want a new browser tab to open for everything they do, or for the desktop or mobile apps to pop into focus.

It’s also worth noting that uploading local files to GetBusy via the Hyperlink API only works with the getbusy:// protocol via the desktop apps.

In the majority of cases, the best solution is to use getbusy://, but feel free to give us a shout if you’re in any doubt.

URL encoding

🚨All of the URLs you create for the GetBusy Hyperlink API need to be encoded.

If you haven’t heard about URL Encoding, it’s the process of converting characters into an interpretable format on the web. There are certain characters that can’t be used in URLs, like spaces, which get encoded as %20.

So if you want the title of your to-do to be My to-do, you can’t use &title=My to-do, but instead use:

&title=My%20to-do

If you aren’t generating your URLs using code (in which case, encoding is straight forward) and you need some help to understand what your encoded link should look like, you’ll find https://www.urlencoder.org/ as useful resource.

URL Schema

The URL schema for the Hyperlink API is made up of four parts:

Protocol - Navigation - Action - Parameters

{protocol}    {navigation}        {action}        {parameters}
https://      app.getbusy.com     ?create=todo    &title=My+new+todo

Protocol

Controls the GetBusy application in which the link will open.

Required.

See the URL protocol and platform targeting section for further information.

Controls where in the GetBusy application the action will be performed.

Required.

You must provide a navigation path when using the Hyperlink API with the https:// protocol. If you are using the getbusy:// protocol exclusively, then a navigation path isn’t really required but we’d recommend using it to avoid any future compatibility issues.

At a minimum, you must specify app.getbusy.com

Generally, we don’t recommend navigating the user any further unless there is good reason - you could be changing the state of the users session unexpectedly. If no further navigation options are provided, the action will be executed for the user without switching theirAction current view.

You can further navigate the user to key screens within the app before any action is performed. Supported navigation screens:

• mytasks (known in the app as 'Assigned to me')

• catchup

• focus

• more coming soon…

The thing that’s going to happen in GetBusy.

https://app.getbusy.com?{action}

The properties of the things that’s going to happen in GetBusy.

https://app.getbusy.com?create=todo&{paramter1}&{parementer2}

Triggers creation of something new in GetBusy.

Action values:

• todo - opens the create to-do screen

• coming soon: thread

• coming soon: note

• coming soon: connection

Parameters

Participants

Adds participants to the new thread

Parameter syntax:

&participants={participant1-emailaddress},{participant2-emailaddress}

https://app.getbusy.com?create=todo&participants=person1@domain1.com,person2@domain2.com

Title

Populates the title field in the create to-do screen.

https://app.getbusy.com?create=todo&title=My+title

File(s)

Path to a public file stored on the web or a private file on the users device to be uploaded to GetBusy and added as an attachment in the create to-do screen.

Parameter syntax:

{filepath}         {name}(optional)     {source}
file={filepath};   name:{filename};     source:{local|web};

Specifies whether GetBusy should look for the file on the web or on the users Windows or Mac device device.

Parameter values:

• web

• local

The optional name given to the attachment in the create to-do screen. If name is not specified, the attachment will be named using the filename from the filepath.

WEB FILE EXAMPLE
https://app.getbusy.com/?create=todo&file=file-examples.com/wp-content/uploads/2017/10/file-sample_150kB.pdf;name:Sample+web+document.pdf;source:web 

LOCAL FILE EXAMPLE
getbusy://app.getbusy.com/?create=todo&file=Users%2Fme%2FDesktop%2FSample%20.pdf;name:Sample%20document.pdf;source:local

It is possible to pass multiple instances of the file parameter to upload multiple files to GetBusy, including multiple files from difference sources.

getbusy://app.getbusy.com/?create=todo&file=Users%2Fme%2FDesktop%2FSample%201.pdf;name:Sample+document+1.pdf;source:local&file=Users%2Fme%2FDesktop%2FSample%202.pdf;name:Sample+document+2.pdf;source:local

When passing multiple files to the Hyperlink API, it is possible to omit the source:{local|web} command from each file and instead pass the global parameter filesource if the source of all the files is the same

getbusy://app.getbusy.com/?create=todo&file=Users%2Fme%2FDesktop%2FSample%201.pdf;name:Sample+document+1.pdf&file=Users%2Fme%2FDesktop%2FSample%202.pdf;name:Sample+document+2.pdf&filesource:local