# Importers

# Importers

Codecks offers two types of Importers. A generic CSV importer as well as importers for specific services (Trello and HacknPlan at the moment).

## CSV Importer

The CSV Importer is the most flexible solution and comes with smart heuristics to make the experience as smooth as possible.

You can find it towards the bottom of the Organzation Settings. You start the flow by picking or dragging a csv file into file picker. The file can be at most 10MB.

![CSV Importer](https://manual.codecks.io/_astro/csv-1.CDwneCN0_Z29rsWh.webp)

> ### What properties can be imported?
>
> - **Title & Content:** if only **Content** is passed, the first line will be turned into the card's title.
> - **Owner:** Will make a best guess based on user name, full name and email-address of users on Codecks.
> - **Effort:** Allows to specify a factor to turn any number into an effort.
> - **Priority:** Allows to map any value into one of the 3 priority levels or `None`.
> - **Status:** Allows to map any value to `Default`, `Started`, `Done`, `Doc Card` or `Archived`. `Default` will become either `Unassigned` or `Assigned` depending on whether a Owner is present.
> - **Tags:** Maps a column to [Project Tags](https://manual.codecks.io/tags/). Separate multiple tags within a cell with commas. You can leave out individual tags before importing. Tags that don't exist yet are created in the target project.

Once imported you can go through each of the card properties above and decide which column in your CSV should be considered. Based on some heuristics based on column name and content type some columns will already be selected.

Here's what these heuristics look like:

- **Title:**

  The column title contains `summary`, `title`, `description` or `content` and every row has a value.

- **Content:**

  There's at least one row that contains a new line

- **Owner:**

  The column title contains `creator`, `assignee` or `owner`.

- **Effort:**

  The content consists of numbers and the column title contains `estimate`, `effort`.

- **Priority:**

  The content consists of numbers or values that are reused at least once. And the column title contains `priority`.

- **Status:**

  The column title contains `status` or `state`.

- **Tags:**

  The column title contains `tag` or `label`. Columns whose cells hold comma-separated values that repeat across rows are preferred, and so are several columns sharing the same title, whose values are combined.

> Does your tool have an output that doesn't match these heuristics? Feel free to reach out to <hello@codecks.io>.

Once you've mapped the columns to the card properties you may have one of two choices, depending on what type of csv you're using:

### Importing new Cards

This option is availabl for any csv. You can define an output deck and export all your cards there.

There currently is no support to use a single csv to import into multiple decks.

### Re-Importing existing Cards

If you exported a csv from Codecks (By selecting cards and looking for the `Export cards` option), you notice that the csv also includes a `Card id` column. If this column is present and all rows contain a valid id, another option is shown: `Update cards`.

This allows to update the cards in place. One use case could be to change the effort of all cards by a factor of 2.

If you map a Tags column, it replaces the project tags of each card. Leave it unmapped to keep the current tags.

You'll export these cards and load them into a spreadsheet tool. There you can bulk update the contents to your liking.

You can then export the results as csv and re-import them using the CSV Importer.

## Trello Importer

This tool can be found towards the bottom of the Organzation Settings as well. The importer allows you to map most Trello properties to their Codecks counterparts:

> - **Lists** ➡️ **Decks**
> - **Cards** ➡️ **Cards**
> - **Labels** ➡️ **[Project Tags](https://manual.codecks.io/tags/)**
> - **Attachments** ➡️ **[Attachments](https://manual.codecks.io/attachments/)** (up to 500MB in total, and no more than your organization's free storage. If the attachments add up to more, the largest ones are left out)
> - **Card members** ➡️ **[Card Owner](https://manual.codecks.io/owner/)** (note that Codecks only supports at most one [Owner](https://manual.codecks.io/owner/) per card)
> - **Checklists** ➡️ **[Checklist](https://manual.codecks.io/text-editor/#checklists) within the card content**
> - **Due Dates** ➡️ **[Due Dates](https://manual.codecks.io/due-dates/)** (will be imported, but they'll only be usable in the Pro plan)

Most notably comments, any power-up content or the activity history won't be imported.

A board can have at most 5000 cards. The import of a larger board stops with an error.

Once you start the flow, you'll be asked to give read-only access to your organizations. You may then pick the Board to be imported.

![Trello Importer](https://manual.codecks.io/_astro/trello-1.3pOTAnUM_1N7FqO.webp)

You get a high-level overview of the project to be imported and can decide whether new decks will be created in an existing project or whether a new project should be created.

The next screen allows you to decide whether or not to import attachments and how the existing trello users should be mapped. If the users are not on Codecks yet, you might want to invite them first before starting the importer. Otherwise you'd have to manually assign the tasks once they are on Codecks.

## HacknPlan Importer

Just like the Trello Importer, this tool can be found towards the bottom of the Organzation Settings as well. The importer allows you to map most HacknPlan properties to their Codecks counterparts:

> ### Option 1: Boards as Decks
>
> - **Boards** ➡️ **Decks** (Tasks without a board will end up in a "Backlog" Deck
> - **Categories** ➡️ **Project Tags**
> - **Milestones** ➡️ **Milestones**
> - **Tags** ➡️ **Project Tags**
>
> ### Option 2: Categories as Decks
>
> - **Categories** ➡️ **Decks**
> - **Boards** (if they have a due date) ➡️ **Milestones**
> - **Milestones** ➡️ **Milestones**
> - **Tags** ➡️ **Project Tags**
>
> ### Shared for both options
>
> - **Tasks** ➡️ **Cards**
> - **Attachments** ➡️ **[Attachments](https://manual.codecks.io/attachments/)** (up to 500MB in total, and no more than your organization's free storage. Attachments are imported task by task, and the import of attachments stops once they reach that limit)
> - **Assignees** ➡️ **[Card Owner](https://manual.codecks.io/owner/)** (note that Codecks only supports at most one [Owner](https://manual.codecks.io/owner/) per card)
> - **Subtasks for Tasks** ➡️ **[Checklist](https://manual.codecks.io/text-editor/#checklists) within the card content**
> - **Subtasks for User Stories** ➡️ **[Hero Cards](https://manual.codecks.io/hero-cards/) the order of the sub cards might be different due to API limitations**
> - **Cover Image** ➡️ **Cover Image**
> - **Importance Level** ➡️ **Priority** (You can define a mapping before importing)
> - **Estimated cost** ➡️ **Effort** (You can define a scaling factor before importing)
> - **Due Dates** ➡️ **[Due Dates](https://manual.codecks.io/due-dates/)** (will be imported, but they'll only be usable in the Pro plan)
> - **Dependencies** ➡️ **[Dependencies](https://manual.codecks.io/dependencies/)** (will be imported, but they'll only be usable in the Pro plan)

Most notably comments, the start date and the work logs won't be imported.

A project can have at most 5000 tasks. Closed tasks and tasks on closed boards only count if you choose to import them. The import of a larger project stops with an error.

To start the flow you first need to generate a read-only API key within the HacknPlan [Api Settings](https://app.hacknplan.com/settings?section=api).

To create an Api Key within the settings screen:

1. Click the "Create" Button.
2. Create an Api Key with a name like `Codecks`. It needs `Projects Read` and `Work Items Read` access.
3. Copy the Api key and paste it into the Codecks importer. The key won't be stored, so if you plan to import multiple times, make sure to store the Api key somewhere safe.

The next step allows to pick the HacknPlan project of your choice.
You may then decide whether to import the tasks into an existing project or a new one.

You'll then see an overview of the project to be imported and can make a few decsions:

![HacknPlan Importer](https://manual.codecks.io/_astro/hnp-1.D3j1pr___Zd1wJM.webp)

- **Deck Strategy:** as you can see in the box above, there's two options for how to import decks. They can either based on boards or on categories.
- **Import closed Tasks:** allows you to import closed tasks as archived Codecks cards.
- **Import closed Boards:** will consider closed boards when importing. The resulting decks or milestones (depending on the Deck Strategy) won't look different than non-closed boards.
- **Import attachments**
- **Effort scaling:** the effort is based on the `Estimated cost` within HacknPlan. This field allows to convert hours into an effort value. The value you enter corresponds to "effort points per hour".
- **Importance Level Mapping:** Pick how to map to the 4 Codecks priority options
- **User Mapping:** Pick which HacknPlan user corresponds to which Codecks user. If the users are not on Codecks yet, you might want to invite them first before starting the importer. Otherwise you'd have to manually assign the tasks once they are on Codecks.