Importing with Convertinator

Convertinator is the desktop application that imports a package into Kaiten. It checks the package and compiles it on your computer, lets the server check it before anything is written, and starts the import. The labels below are the ones the application shows, in Russian.

• A package as a folder or a .zip archive whose meta-data.json names the profile external. See Bundle format and the Examples.
• An account that may import into the target Kaiten company, which has the new import enabled.
• Free space on your disk for the temporary files of the compilation. They are removed when the import has been queued, and your package is never changed.
• A database backup of the target, if it is an on-premises installation: the import screen reminds you to make one, so that you can restore it if the data does not come out as expected.

Choose Универсальный импорт on the start screen. Convertinator asks you to sign in first and offers two buttons: войти в облако and войти в свое решение.

Cloud

1. Choose войти в облако. Convertinator opens a sign-in window with the Kaiten sign-in page.
2. Sign in with your usual Kaiten account. The window closes by itself.
3. Convertinator is signed in. No address or domain is entered: the import goes to the company of the account you signed in with.

Your own installation

1. Choose войти в свое решение. The dialog Введите учётные данные has up to three steps; Далее goes to the next one.
2. The first step asks for the address of your installation, the address you open the application at, for example https://tasks.example.com.
3. The second step asks for a key from your profile. The dialog links straight to the page where a key is created.
4. The third step appears only when the key belongs to several companies: pick the one to import into, then choose Подтвердить.

Once signed in, Convertinator reads what the installation allows. On an installation that also offers cloning of a company, a choice appears: choose Импорт из JSON-файлов. If the import cannot run, Convertinator says so instead of offering it: the new import is switched off for the chosen company, the installation is too old to import into a chosen space, or the settings could not be read and you need to sign in again. The application menu has a sign-out item (in the application menu on macOS, under Settings on Windows and Linux).

Choose the field Выберите папку или .zip and select the package folder or the .zip archive. An archive is unpacked on your computer first, with a progress bar.

Convertinator recognizes a package of this format by its manifest. A manifest it cannot accept is reported and nothing is sent: a missing or damaged profile, or a manifest that mixes this format with another one. Such a package is never treated as another format.

A package of this format is always imported into one space of the target company, and you pick that space in the field Пространство для импорта; the package names none. A space without a parent, and every board that is not placed in a space, is created inside it. You become an administrator of each top-level space, document and folder that the import creates there.

You need the rights to update that space and to create boards, cards, documents and folders in it. Convertinator lists every space you can open; choose one where you have these rights, otherwise the import is refused. These rights are checked again during the import, so keep them until it finishes. If the import has to invite people and you no longer have them at that step, the import fails and what it has written is removed. Otherwise the import completes, but if you have lost the rights by its end, you do not get the administrator role on the top-level spaces, documents and folders it created.

The field Поведение при ошибке decides what happens when part of the data cannot be imported.

• Strict (Прерывать импорт при ошибке) is the default. The first error stops the import, and the rows it had inserted are removed again. Only those: it cannot restore a value the import overwrote, and the people it invited before the failure stay in the company and in the space. If you need a guaranteed way back, take a backup before importing.
• Non-strict (Импортировать, несмотря на ошибки) imports despite errors. A row the database refuses is skipped where the import can do that, and the rest continues; some errors still stop the whole import. Check the imported data afterwards. Use it when a partial result is better than none.

The mode applies after the package has been accepted. A package that is not valid is refused in both modes: the package must be valid, see Validation and errors.

There is no choice of identifiers to make. A package always runs with new identifiers. Importing the same package twice creates its boards, columns, cards and the rest twice; what is reused by name or by email, such as tags, card types and people, is matched again.

The server imports a package in its own prepared form, so Convertinator compiles your package into it on your computer. This happens when you start the check or the import, after Convertinator has read from the target what the compilation depends on.

• Once the package is chosen, the screen shows the block Рабочий каталог: the folder where the package is prepared and the free space on its disk. A large package needs a disk with enough room; change the folder with Изменить…. Your package folder is never changed.
• The compilation reads the files one record at a time, so a large package does not have to fit in memory. It validates every record against the schema of its entity, checks that every reference resolves, that identifiers and unique values are not repeated, that hierarchies have no cycles, that the history of every card is consistent and that every file matches its declared size and checksum.
• It runs apart from the window, which stays responsive. While it works the button shows Подготовка пакета…, and the block shows the stage (reading files, checking references, copying attachments, converting, writing pages), the entity and file being processed, the number of records, the bytes read, the size of the work folder and the number of errors found so far. Отмена under the progress stops it and removes the temporary files of that attempt; leaving the screen stops it as well.
• Nothing is sent before the compilation succeeds. When it finds mistakes, the screen says В пакете найдены ошибки and lists the first of them with the entity, the file, the number of the record and the field, with the count of the rest. Показать полный отчёт opens the full report on disk. Fix the JSON files and start again.
• The check and the import that follows it share one compiled result, as long as neither the package nor the target changed. Changing a file of the package compiles it again.

Preflight checks the compiled package on the server with nothing written to the company. It catches what can be judged before writing: the structure, every row against the schema of the server, and conflicts with data the company already has. It does not catch everything. A value the database itself rejects passes preflight and fails during the import. Passed means the package is well-formed, not that the import is guaranteed to succeed.

1. Choose Произвести проверку. Convertinator compiles the package, sends every file, counting them as it goes, and the server then checks it in the mode chosen above.
2. Wait for the result. A small package takes seconds; a very large one can take much longer.
3. Read the verdict, which ends in one of three outcomes:
   • Проверка пройдена — нарушений не найдено. Можно импортировать. The import can be started.
   • Найдены предупреждения. Можно импортировать всё равно. The package can be imported, but something will not be carried exactly as sent. Review the findings; the import button waits until you choose Импортировать всё равно.
   • Импорт заблокирован — устраните ошибки и попробуйте снова. The package has errors and cannot be imported. The first findings are listed. Fix them and run the check again.

The files sent for the check are reused by the import, so they are not sent twice. Changing the mode, the package or the target space clears the verdict. The check is optional, but an import started without it finds out about a failure only after it has run, on the screen and by email.

Space keys are unique within a company. Before the package is compiled, Convertinator asks the company which of the space keys of the package it already uses. Each such key is replaced: the new key is the first 7 characters of the old one, an underscore and 8 uppercase hexadecimal characters, and the package is compiled with it. Each replacement is listed on the screen, for example Ключ X уже занят в компании — пространство получит ключ Y, where X is the key of the package and Y the new one. The card keys under the key follow it.

Choose Импортировать. Convertinator compiles the package unless the check already did, sends whatever the check has not already sent and puts the job in the queue of the server. The temporary files of the compilation are removed then. The screen then shows the progress of the import on the server, stage by stage. When the import ends, the screen shows its outcome: Импорт завершён, Завершено с потерями (some data or attachments were not carried over) or Импорт прерван, with the reason. Скачать отчёт saves the report when there is one, and Назад returns to the start. The import runs on the server and does not depend on Convertinator: you can close it, you receive an email when the import finishes, and if you open Convertinator again while an import of the company is running, its progress screen comes back.

The screen names the cause when an import stops and says when a non-strict import left something out; the report has the details. The email says only whether the import succeeded or failed. Run preflight first to see where a problem is, and check the imported data in the target space afterwards.

No account is created from the package. Every user is looked up in the target company by email: a member who can already read the target space is used as they are, and anyone else is invited to that space when you may invite people. That invitation creates an account for an address the installation has never seen, with no password, and no email goes out, so tell those people yourself that they now have access. Where the company has run out of licences, the new member is added switched off.

Inviting takes two rights of yours: access control over the target space and, only for an address that is not a member of the company yet, the company right to invite people or to manage members. Without them, everyone who cannot already read the space stays unmatched: cards they own and files they attached go to you, their comments are kept with their name shown at the top of the text, their time logs are not imported, they are not added as members or as the responsible person of cards, and values of user fields that name them are dropped.

A company runs one universal import or export at a time. A second request is refused while the first is running. A preflight check holds the place while it runs, so a check of one package blocks an import of another until it is done or cancelled; a finished check holds nothing. Companies do not block each other. Convertinator also runs one compilation of a package at a time.

Kaiten

Addons terms of usePersonal data processing policy

If you have any questions or need help with integration feel free to write us at support@kaiten.ru