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…
Get started
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:
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:
https://app.getbusy.com?create=todo&title=Try+the+Hyperlink+API
And finally, attach a public web document:
Create a task 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
https://app.getbusy.com?create=signature
https://app.getbusy.com?create=note
URL protocol and platform targeting
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.
Character stripping
Please note that you will have to strip out the following special characters from any values (for example from within the title of a to-do) as they are used to structure the API
Colon :
Semicolon ;
The api does not currently support
en dash –
em dash —
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.
Navigation
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…
Action
The thing that’s going to happen in GetBusy.
🚨 Before you declare an action, remember to add a question mark [?] to your URL after the navigation path.
https://app.getbusy.com?{action}
Parameters
The properties of the things that’s going to happen in GetBusy.
Separate action parameters with an ampersand [&]
https://app.getbusy.com?create=todo&{parameter1}&{parameter2}
Open and create connections
Opens an existing connection or populates the add connection screen with connection details if a connection does not already exist.
https://app.getbusy.com
?open=connection
&email={emailaddress}
&firstname={firstname}&lastname={lastname}
Parameters
Required.
The email address of the connection to be opened or created.
firstname
Optional.
The first name of the connection, to be used to create the connection if it does not already exist.
lastname
Optional.
The last name of the connection, to be used to create the connection if it does not already exist.
Create threads
Triggers creation of a new thread in GetBusy.
getbusy://app.getbusy.com
?create=todo
&title=My+title
&extra=My+extra+information
&participants=person1@domain1.com,person2@domain2.com;assignee:true
&file=Users%2Fme%2FDesktop%2FSample%20.pdf;name:Sample%20document.pdf;source:local
Parameters
participants
Optional.
Adds participants to the new thread
🚨 Optional additional parameter of assignee.
🚨 New GetBusy connections will automatically be created for participants that do not already exist as connections for the current user.
The current user will always be added as a participant on new threads and does not need to be specified.
Multiple participants can be separated with a comma.
Parameter syntax
https://app.getbusy.com?create=todo
&participants=person1@domain1.com,person2@domain2.com
assignee
Optional.
Sets as specific participant as the assignee (if creating a to-do).
Parameter syntax
https://app.getbusy.com?create=todo
&participants=person1@domain1.com,person2@domain2.com;assignee:true
title
Optional.
Populates the title field in the create thread screen.
https://app.getbusy.com?create=todo&title=My+title
extra
Optional.
Populates the extra information field in the create thread screen.
https://app.getbusy.com?create=todo&extra=My+extra+information
file
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.
🚨 Must be used with additional parameters of source
🚨 Upload of local files on the users device is only supported using the getbusy:// protocol with the desktop app installed on a Windows or Mac device.
Parameter syntax:
{filepath} {name}(optional) {source}
file={filepath}; name:{filename}; source:{local|web};
source
Specifies whether GetBusy should look for the file on the web or on the users Windows or Mac device device.
Parameter values:
-
web
-
local
name
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
multiple files
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
Comments
0 comments
Article is closed for comments.