Migrate from Harvest to Kimai

Take it out

1. 1

   Step 1

   Export the time while the account still opens

   In Harvest, an administrator can use Settings, then Import/Export, then Export all time. Harvest's help says that downloads a CSV of company time, or emails a link when the file is large. Anyone who can see a time report can also export from Reports, then Time, or from Reports, then New report, then Detailed time. Those reports export to CSV. Save the files on a disk you control before you cancel. That export is the rollback.

2. 2

   Step 2

   Export the clients and the projects

   Harvest's help says an administrator or a manager who can create and edit clients uses Manage, then Clients, to export clients and client contacts. CSV is one of the formats. An administrator or a manager who manages projects exports project data from the main Projects section. CSV is one of the formats. The help says not every plan has every export, and the export you see depends on your permissions. Use the labels on your account.

3. 3

   Step 3

   Keep a small sample aside

   Copy a few time rows, one client, and one project into a second file. Import that sample first. Leave the full files untouched.

Put it in

1. 1

   Step 1

   Install the Importer plugin

   The Importer store page says to unzip the plugin into var/plugins/ImportBundle/ on the Kimai install, with ImportBundle.php inside that folder. From the Kimai folder, run bin/console kimai:reload --env=prod so Kimai rebuilds its cache and finds the plugin. The same page says the web server must be allowed to write in the var folder, and it shows sample permission commands for Debian and Ubuntu. The plugin list says plugins are for on-premises customers. Cloud users can use plugins labelled Cloud. The store data for the Importer lists the price as 0 and includes a cloud tag. This guide did not click through a cloud install.

2. 2

   Step 2

   Line the headings up with the docs

   The Importer docs say you can load CSV and JSON. The heading must use the same letters, including capitals. Fields the docs mark as required have to be in the file. The plugin includes examples, and you can download them from the importer screen. The docs say the importer permission opens System, then Importer. That permission starts on the role ROLE_SUPER_ADMIN. The docs point to the permission documentation if another role needs it. For clients, use the Customer table. Customer is required. Name is the other heading for that same field. A row updates a customer when that name already exists. Otherwise Kimai creates the customer. For projects, use the Project table. Project and Customer are required. Name can stand in for Project. A project updates when that name already exists for that customer. Otherwise Kimai creates the project, and it creates the customer when that name is new. For time, use the Timesheet table. The required headings are Date, From, To, Email, User, Project, Customer, and Activity. Date looks like YYYY-MM-DD. The docs give 2020-05-04. From and To are 24-hour times like HH:MM:SS. The docs give 15:50:00 and 17:21:44. Email is matched first. User is the user identifier used when Email does not match. If the Harvest file uses other headings or another date shape, change them on the copy.

3. 3

   Step 3

   Import the sample, then the rest

   If Kimai will create users during the import, set the default timezone for new users at System, then Settings, before you load the file. The docs say that timezone is what the timesheet import uses. When the people are in different timezones, the docs say to create those users by hand first. Then load the sample at System, then Importer. Stop if the hours, the client names, or the project names are wrong. If the sample matches, import the remaining files. A timesheet import creates a missing customer, project, activity, tag, or user as it goes.

4. 4

   Step 4

   Check the rows

   Open the customers, the projects, and a few timesheets. A matching customer name should be an update. A matching project name under that customer should be an update. Duration is seconds, and the docs say Kimai calculates it from the start and end when you leave it out. Billable uses 1 or 0. Visible uses 1 or 0. Exported uses 1 for exported and 0 for new.

What you lose

• What the Importer docs leave out

  The docs list Timesheet, a Clockify timesheet, a Toggl Track timesheet, Project, Customer, a Grandtotal customer, and Kimai v1. A Harvest file has to use the Timesheet, Customer, or Project headings. The tables do not include invoices, card-payment links, timesheet approvals, or Harvest logins. Harvest's help still lets an administrator export all invoices as a ZIP of PDFs from Settings, then Import/Export. Keep that ZIP with the CSV files.

• Users in more than one timezone

  The docs say a timesheet import can create a missing user. That new user gets the default timezone from System, then Settings. The docs say that timezone is what the timesheet import uses. When the people are in different timezones, create those users by hand before the import.