Импорт из CSV

Документ описывает инструкцию по переносу проекта из CSV в TeamStorm.

Исходные данные

Для переноса проекта из CSV потребуются:

архив со скриптами импорта
URL сервера TeamStorm
токен аутентификации пользователя TeamStorm
файл с исходными данными для импорта в формате CSV
конфигурационный файл импорта

Подготовка запуска

Установите среду выполнения Python 3.11 (или версию выше).

Установите следующие модули:

    pip install \
        Markdown==3.4.4
        requests==2.31.0
        jira2markdown==0.3.4
        dataclasses-json==0.5.7
        future==0.18.2
        pytz==2023.3
        jsonpickle==3.0.2

Распакуйте архив со скриптами миграции
Добавьте пользователей в TeamStorm перед запусĸом импорта. Отображаемое имя пользователей TeamStorm должны совпадать с пользователями в CSV для автоматического маппинга.

Получение токена аутентификации TeamStorm

Для аутентификации в API TeamStorm необходимо выбрать учетную запись пользователя, у которого есть системные роли "Администратор Core" и "Пользователь TeamStorm".

Авторизуйтесь в TeamStorm в браузере с выбранной учетной записью.
Откройте веб-инспектор браузера.
Откройте любой запрос TeamStorm.
Скопируйте из заголовка запроса Authorization токен авторизации (символы без "Bearer").

Основные параметры скрипта

- URL сервера TeamStorm
```
"https:\\source.teamstorm.io"
```
- тоĸен аутентифиĸации пользователя TeamStorm
```
"EzLCJzaWQiOiJh...jzSZHNHP3Jw"
```
- ключ пространства, в которое будет импортированы задачи
```
"KEY"
```
- путь к CSV-файлу с выгрузкой
```
"issues.csv"
```
- путь к JSON-файлу с конфигурацией импорта
```
    "config.json"
```

Дополнительные параметры скрипта

Выбор пространства

По умолчанию задачи импортируются в существующее пространство, указанное в параметре .

Для того, чтобы создать новое пространство, необходимо уĸазать ключ нового пространства в параметре и указать название через параметр:

    --space_name "Название нового пространства"

Если в TeamStorm уже существует пространство с указанным ключом, данные будут импортированы в него.

Подготовка файла конфигурации

Файл конфигурации позволяет задать параметры импорта (маппинг полей, форматы разделителей, кодировку, значения по умолчанию, форматы дат и текста и т.п.).

Файл конфигурации состоит из двух блоков:

    {
    "columns": [],
    "params": {}
    }

columns – описывает поля выгрузки CSV и маппинг их на системные и пользовательские атрибуты TeamStorm. params – задает общие параметры импорта.

Общие параметры импорта

Список общих параметров:

    "params": {
    "task_id_col_name": "#",
    "ext_id_col_name": "#",
    "root_folder_name": "Импорт",
    "date_format": "%d.%m.%Y",
    "csv_delimiter": ";",
            "options_delimiter": ",",
    "text_format": "txt",
    "ignore_missing_links": false,
    "workflow_name": "Импортированный процесс",
    "default_task_type": "Задача",
    "default_workflow_name": "Процесс по умолчанию",
    "csv_encoding": "utf-8-sig",
    "status_category_mapping": {
        "New": "К выполнению",
        "Confirmed": "В работе",
        "Needs feedback": "В работе",
        "Resolved": "Выполнено"
        }
    }

Описание параметров приведено ниже:

task_id_col_name Название колонки в CSV, которая используется для идентификации задачи в других колонках (например, идентификатор связанной, дочерней или родительской задачи)
```
    "task_id_col_name": "#"
```
ext_id_col_name Название колонки в CSV, в которой указан идентификатор задачи
```
    "ext_id_col_name": "Task ID"
```
root_folder_name Имя корневой папки внутри пространства, в которую будут импортированы задачи
```
    "root_folder_name": "Пример проекта"
```
date_format Описание формата даты, которая используется в выгрузке. Описание формата
```
   "date_format": "%Y-%m-%d"
```
csv_delimiter Формат разделител CSV-файла
options_delimiter Формат разделителя опций значений в CSV-файле

json "options_delimiter": ","
text_format Формат текста (txt – plain text, md – markdown, html – формат гипертекста)
```
"text_format": "txt"
```
ignore_missing_links Возможность продолжить импорт, если связанная задача не найдена в выгрузке (true – игнорирование ошибок связывания, false – остановка скрипта при возникновении ошибок связывания)

json "ignore_missing_links": false
workflow_name Название создаваемого процесса

json "workflow_name": "Импортированный процесс"
default_task_type Название типа, созданного в пространстве по умолчанию

json "default_task_type": "Задача"
default_workflow_name Название процесса, созданного в пространстве по умолчанию
```
    "default_workflow_name": "Процесс по умолчанию"
```
csv_encoding Кодировка CSV-файла
```
    "csv_encoding": "utf-8-sig"
```
status_category_mapping Маппинг категорий статусов в формате { "название статуса": "категория статуса" }
```
    "status_category_mapping":
    { "К исполнению": "К выполнению" }
```

Категория статуса должна соответствовать одной из категорий:

"К выполнению" - категория, обозначающая задачи, не взятые в работу
"В работе" - категория, обозначающий задачи, которые выполняются
"Выполнено" - категория, обозначающая задачи, которые завершены
"Отменено" - категория, обозначающая задачи, которые не будут завершены

Описание полей выгрузки

Поля, которые необходимо импортировать, необходимо добавить в конфигурацию. Для каждого поля необходимо указать название колонки и тип.

{
    "columns": [
        {
            "col_name": название колонки,
            "col_type": тип колонки
        }
    ]
}

Возможные типы колонок:

Тип	Описание
system	Системный атрибут
custom	Пользовательский атрибут
portfolio	Портфель
link	Связь
folder	Папка

Системные поля

Для заполнения системного атрибута необходимо добавить запись:

    {
        "col_name": "Название колонки",
        "col_type": "system",
        "field_name": "Тип системного атрибута"
    }

Возможные типы системных атрибутов:

Тип	Описание	Пример
title	Название задачи	`json "field_name": "title"`
status_name	Название статуса	`json "field_name": "status_name"`
assignee_email	Email пользователя	`json "field_name": "assignee_email"`
assignee_name	Имя пользователя	`json "field_name": "assignee_name"`
start_date	Планируемая дата начала задачи	`json "field_name": "start_date"`
due_date	Планируемая дата выполнения	`json "field_name": "due_date"`
description	Описание задачи	`json "field_name": "description"`
type	Тип задачи	`json "field_name": "type"`

Пользовательские атрибуты

Для создания пользовательского атрибута необходимо добавить запись:

{
    "col_name": "Название колонки",
    "col_type": "custom",
    "attr_type": тип пользовательского атрибута,
    "attr_name": "Название атрибута в TeamStorm"
}

Возможные типы пользовательских атрибутов:

Тип	Формат	Пример
UniString	строка	`json "attr_type": "UniString"`
Number	число	`json "attr_type": "Number"`
Date	дата	`json "attr_type": "Date"`
UniSelect	выбор из списка	`json "attr_type": "UniSelect"`
Tag	тег	`json "attr_type": "Tag"`
User	пользователь	`json "attr_type": "User"`
TimeDuration	время (в секундах)	`json "attr_type": "TimeDuration"`

Портфель

Для создания портфеля необходимо добавить запись:

    {
    "col_name": "Название колонки",
    "col_type": "portfolio",
    "portfolio_name": "Название портфеля"
    }

В результате будет создан портфель с указанным названием, в который будут добавлены элементы, соответствующие значениям в колонке.

Связь

Для колонок, которые задают отношение между задачами, необходимо добавить запись:

    {
        "col_name": "Название колонки",
        "col_type": "link",
        "link_type": тип связи
    }

Возможные типы связей: | Тип | Формат | |------------|------------------------| | relates | Связь многие ко многим | | blocks | Блокирует задачу | | blocked_by | Заблокирована задачей | | duplicates | Дублирование | | parent | Родительская задача |

Запуск скрипта

Перейдите в папку со скриптами

Выполните команду c необходимыми параметрами

    python3 csv_import.py <teamstorm_url> \
                        <teamstorm_token> \
                        <teamstorm_space_key> \
                        <csv_file_path> \
                        <config_file_path> \
                        [дополнительные параметры скрипта]

Пример вызова скрипта:

    python3 csv_import.py "http://teamstorm.ru" \
                        "EzLCJzaWQiOiJh...jzSZHNHP3Jw" \
                        "KEY" "issues.csv" "config.json"

Дождитесь выполнения скрипта и проверьте импортированные данные

В случае возниĸновения ошибоĸ соединения сĸрипт можно перезапустить c теми же параметрами, продолжится импорт оставшихся задач.

Результат переноса

В результате в указанном пространстве будут созданы задачи и выполнены настройки типов, атрибутов и процессов для этих задач, в соответствии с конфигурацией и данными выгрузки.