Development Toolkit

Interested in writing an add-on for Clockify? Don’t know where to start? In this guide we’ll cover basic concepts and walk you through the initial setup and running a simple add-on.

What do I need to follow this guide?

While Clockify add-ons are language agnostic and can be written using any stack capable of handling HTTP requests and serving web pages, this guide will focus on running an add-on written in Java.

All you need to run the example is docker-compose and ngrok.

Providing a public URL

First you need to create free account at ngrok and follow their guideline for installing & running app docs. After you’ve setup ngrok, run the following command:

ngrok http 8080

This will generate tunnel to your app running on port 8080.

Note the public URL in the output:

https://7ba8-188-246-34-133.eu.ngrok.io

Running a docker container

Visit https://github.com/clockify/add-on-examples and clone the repository. Inside, you’ll find a project named ‘hello-world-java’.

Update docker-compose.yml file by changing the PUBLIC_URL to an address that ngrok gave you.

Next, we will build the image by passing GitHub username and it’s access token. These are only used in order to pull the add-on SDK dependency from GitHub packages. The container will expose the following port for the add-on: 8080. Run the following commands to build an image and start the docker container.

docker-compose build --build-arg GITHUB_USERNAME="{username}" --build-arg GITHUB_TOKEN="{token}"

docker-compose up

Once the container starts, it’s time to install it in Clockify.

Developer account

In order to get access to a test environment in which you can freely install and test your add-ons, you need to create a CAKE.com developer account. Navigate to https://developer.marketplace.cake.com/signup and continue with the registration. Once you have an account, go to “Test accounts” in the sidebar, and choose “Login as” next to the workspace owner.

This will log you in to a test Clockify instance, from where you can go to “Workspace settings”, then “Integrations” where you can find a section named “Add-ons” on the bottom of the page. 

Installing the add-on

In order to install add-on, you must paste link to Add-on manifest file. In this example, link to the manifest file is: PUBLIC_URL + /manifest. This is equivalent to:

https://7ba8-188-246-34-133.eu.ngrok.io/manifest

Simply paste your manifest URL into the box, and click “Install”. The installation should be very quick, and you should be able to see the add-on on the table below. To verify that its working, open a widget container on the bottom right of the screen, and a message should pop up:

This text is actually rendered by the add-on running on your computer!

OK, so what just happened?

You might be asking yourself – this makes no sense, how this cryptic series of events led to embedding an add-on in Clockify? Let’s break it down a bit.

Add-ons are a code that runs on your hardware. In this example, it physically runs on your computer. That works well for development and testing, but before publishing you’ll need to provide the hosting and a public URL. In order for Clockify to be able to reach your computer we used ngrok to provide a public tunnel. 

Clockify integrates your add-on by parsing its manifest file. It contains a list of functionalities your add-on is capable of handling. 

You can read more about manifest files in the documentation https://dev-docs.marketplace.cake.com/development-toolkit/manifest

You can see your add-ons manifest by navigating to the “/manifest”, relative to the base URL. In this case it registers a UI component:

Components are HTML pages rendered by the add-on and embedded in the Clockify’s UI via an iframe. The location of the iframe is determined by add-ons type. In this example it’s a “WIDGET” and it floats in the bottom right corner of the page. The source of the page is “/ui”, which is a path relative to the add-ons base URL.

You can read more about UI locations in the documentation https://dev-docs.marketplace.cake.com/development-toolkit/ui-locations

Other than rendering the UI through components, add-ons can also register to Clockify webhooks, and make full use of public REST API: https://docs.developer.clockify.me/

Alright, what next?

We’re just scratching the surface of possibilities provided by the add-on architecture. After following this guide you should have a basic understanding of how to run and register a trivial add-on. For more complex use cases follow other examples in the example repository. You might also be interested in a fully serverless add-on example that shows how to make a functional add-on with no server-side code.

The Java example that you ran is based on the Clockify Add-on Java SDK . Its Github page contains useful information about the add-on development https://github.com/clockify/addon-java-sdk

See further documentation at https://dev-docs.marketplace.cake.com/development-toolkit/development-basics

You can reach us and ask questions directly on CAKE.com development forum https://dev-forum.marketplace.cake.com