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

Clone the repository:

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

Create a virtual environment (optional but recommended):

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

Install the required packages:
```
pip install -r requirements.txt
```

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.

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

Usage

Prepare your CSV file:

Make sure your CSV in the Kimai (Timesheet / Export).
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
```
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.

Cuchulain / kimai-csv-to-jira

readme