Migrating from projects v1 to v2

Timekit's new project model was released in May 2018 and improves on our previous approach in multiple ways.

Fetching availability is faster and more powerful, the admin UI is easier to work with and full API access is now available for creating and managing projects. Projects will also reflect availability constraints configured on each resource,, making it more manageable if you deal with a large number of projects.

This guide is targeted at customers that integrate and customize Timekit by manually configuring booking.js widget, using the JavaScript SDK or are making server-to-server API integrations with projects.

🚧

Only using our admin panel?

If you're not interested in API access and have few existing projects, you can simply re-create your legacy projects through our admin panel. Your new links to the hosted page will be https://book.timekit.io/YYY (instead of https://my.timekit.io/XXX)

Prerequisites

When you should migrate

Basically everybody will benefit from migrating to projects and there are some very obvious case:

• If you don't want the project owner/creator to be bookable.
• If you use team availability, where you query availability on a team of resources instead of a single resource (much improved performance)
• If you need resource-specific availability rules that are applied across all projects.
• If you're want programmatic access to projects through our API in a server-to-server setup.

When not to migrate (yet)

• If you depend calendar granularity by querying availability on specific calendars and/or saving bookings to a specific calendar for each project. The new projects uses the same calendar preferences specified on the resource-level for all projects.

API access

Projects is now properly supported as a backend entity as opposed to our legacy projects, which were mainly a frontend configuration for booking.js stored on Timekit' backend.

There are a few naming changes that you should be aware of:

• findtime is now availability
• filters are now availability_constraints and do not have the notion of "and" and "or", we take care of and'ing and or'ing the different block and allow constraints that you define, so that the result is as expected.

You can also refer to the project_id when requesting availability with POST /availability and when creating bookings with POST /booking where the settings from the project will be taken into account.

Head on over to API reference for the full run-down.

Booking.js widget

Along with projects we released a new version of booking.js.

The biggest conceptual change in version 2 is that we go from personal credentials/authentication (Resource Widget Key) to app wide authentication (App Widget Key), so you should use the App Widget Key instead of previously the resource's token.

The second biggest thing is that version2 supports projects, so configuring a booking.js widget to use the settings from a project is super simple: just provide the project_id and the app_key and you're ready to receive bookings.

Configuration wise, version 2 of the booking.js widget is a bit different from version 1, but we also think that it is much easier to configure, since we have removed a lot of duplicate settings, this is most apparent in that there is no timekitConfig setting, all those settings are set in the root of the config.

Changed settings

• The setting timekitFindTime is now split into the resources (which resources should be queried for availability), availability (time-slot length, time-space etc.) and availability_constraints (previously called filters). The biggest change is from "filters" to "availability_constraints" in that there is no longer a notion of "and" and "or", we take care of and'ing and or'ing behind the scenes. Please refer to the documentation for a full overview.
• The setting timekitCreateBooking is now called booking.
• localization remains but is now placed under the new ui object.
• fullCalendar is called fullcalendar (notice the lower-case C)
• bookingFields is now called customer_fields
• callbacks is still called callbacks.

New settings

• reminders. Previously reminders were setup as event_notifications under the timekitCreateBooking setting but now have their own top-level key.
• ui. Different UI settings were previously placed in the root configuration, this includes settings like avatar, name now called display_name and availability_view previously availabilityView

JavaScript SDK

A new minor version of our JavaScript SDK was released with the following new methods to create, list, update and delete projects:

timekit.getProjects()
timekit.getProject({ id })
timekit.getHostedProject({ slug })
timekit.getEmbedProject({ id })
timekit.createProject({ ... })
timekit.updateProject({ id, ... })
timekit.deleteProject({ id })
timekit.addProjectResource({ id, ... })
timekit.setProjectResources({ id, resources })
timekit.removeProjectResource({ id, resourceId })