Kimai CSV to Jira Worklog Importer

This Python script allows you to import worklogs from a CSV file exported from Kimai to Jira. The script parses the CSV generated by Kimai, extracts the relevant task details, and adds the worklogs to the corresponding Jira tasks via the Jira API.

Features

• Extracts task ID and description using a customizable regular expression.
• Supports time zone conversion for accurate time logging.
• Configurable column names for flexibility with different CSV formats or languages.
• Dry-run option to preview the actions without modifying Jira.

Requirements

• Python 3.7+
• Jira API access with a valid API token
• Python packages: requests, python-dotenv, pytz

Installation

1. Clone the repository:

   git clone https://github.com/Cuchulain/kimai-csv-to-jira.git
   cd kimai-csv-to-jira

2. Create a virtual environment (optional but recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\\Scripts\\activate`

3. Install the required packages:

   pip install -r requirements.txt

4. Create a .env file in the root of the project with the following content:

   JIRA_URL=https://your-jira-instance.atlassian.net
   JIRA_USERNAME=your.email@example.com
   JIRA_API_TOKEN=your_api_token
   
   TIMEZONE=GMT
   
   COLUMN_DESCRIPTION=Description
   COLUMN_DURATION=Duration
   COLUMN_DATE=Date
   COLUMN_TIME=From
   
   TASK_REGEX=([A-Z]+-\\d+)(:?\\s+)(.*)

   You can copy the .env.dist file to the .env and modify it to suit your needs.

5. Replace the placeholders with your actual Jira details and the column names used in your CSV file.

Usage

1. Prepare your CSV file:

   Make sure your CSV in the Kimai (Timesheet / Export).

2. Run the script:

   To execute the script, use the following command:

   python kimai_to_jira.py /path/to/your/csvfile.csv

   If you want to perform a dry-run without actually sending data to Jira, use the --dry-run option:

   python kimai_to_jira.py /path/to/your/csvfile.csv --dry-run

3. Optional:

   If you need to set a visibility group for the worklogs, you can use the --visibility option:

   python kimai_to_jira.py /path/to/your/csvfile.csv --visibility your-group-id

Customization

Regular Expression for Task Extraction

The regular expression for extracting the task ID and description can be customized in the .env file using the TASK_REGEX variable. The default pattern is:

TASK_REGEX=([A-Z]+-\\d+)(:?\\s+)(.*)

This pattern assumes that the task ID is followed by a colon (optionally) and space and then the task description.

Column Names

You can customize the column names that the script uses by modifying the corresponding variables in the .env file.

This is necessary if you are using a language other than English.

• COLUMN_DESCRIPTION: The column that contains the task description.
• COLUMN_DURATION: The column that contains the time spent (in seconds).
• COLUMN_DATE: The column that contains the date of the worklog.
• COLUMN_TIME: The column that contains the start time of the worklog.

License

This project is licensed under the MIT License. See the LICENSE file for details.