What you can import
A package carries any of 32 entities, and every one is optional. This page lists what you can import on its own and the minimum set of entities each kind of data needs. Every minimum below was built from the full example, checked against the schemas and compiled, so it is a package that works.
- Minimum lists the entities to put in the package. A row that starts with + adds entities to the minimum of the row it names.
- A record that refers to another record needs it in the package, so the entities of a minimum come along with what they require. A reference that is optional is simply left out when the record it points at is not there.
- Each entity has a page with its fields, rules and an example record: see the Entities group in the menu. The format of the package is described in Bundle format, and the ready packages are on the Examples page.
Spaces, folders and documents
| I want to import | Minimum entities | What to know |
|---|---|---|
| Document comments | Document comments, Documents, Spaces | A comment without a parent starts a thread; a reply names its parent comment. A thread can be resolved. |
| Documents | Documents, Spaces | A document needs a parent: a space, a folder or another document. Add the folders when the parent is a folder. |
| Documents with attachments | Attachments, Documents, Folders, Spaces | The document sits in a folder or a space; add the folders when the parent is a folder. The bytes go under files/, and the data of the document shows a file with its link. |
| Folders | Folders, Spaces | A folder needs a parent, which is a space, another folder or a document. A folder can hold documents and other folders. |
| Space keys | Spaces | A space or a folder issues card keys when it has a key. A key is unique within the company. When the company already uses a prefix of the package, Convertinator gives the space a new key and reports it. Keep the prefix as it is in the source. |
| Spaces | Spaces | A space without a parent is created inside the target space you pick, and you become its administrator. Spaces can be nested. |
Boards and cards
| I want to import | Minimum entities | What to know |
|---|---|---|
| A board with cards | Boards, Card types, Cards, Columns, Users | Every card needs a type, an owner from users, a board and a column of that board. Lanes and tags are optional: a card without a lane goes to the first lane of its board. Reference example: kpi-cards.zip. |
| Spaces with boards | Boards, Columns, Space boards, Spaces | A board needs columns. A board without lanes gets one default lane. A board that is not placed in a space goes into the target space you pick. |
| … with attachments | + Attachments and the minimum of A board with cards | A file is two things: an attachment record and its bytes under files/, or a link to a file in the cloud. The same bytes can serve several records. |
| … with blockers | + Card blockers and the minimum of A board with cards | Both cards must be in the package. Give only blocks that are active now. |
| … with card history | + Activities, Card history, Lanes, Users and the minimum of A board with cards | Set timeline_mode to explicit. Every card has its actions, with one card_add first, and a snapshot of every state except the current one, and the places they name must exist, so the lanes and the users they mention come along. Without history, leave the entities out and use current_state_only. |
| … with card keys | + Spaces and the minimum of A board with cards | The key of a card is a prefix and a number, and the prefix is the key of the space or folder that issues it, so the space comes along. |
| … with checklists | + Checklist items, Checklists and the minimum of A board with cards | A checklist belongs to one card (card_ref) and holds its items in checklist_items. The checklists of a card are shown in the order of their records. |
| … with comments | + Comments and the minimum of A board with cards | Reactions are the emojis of a comment, one item per user and emoji. A reply names its parent comment of the same card. A comment without an author is the exception: it is shown as written by the system AI user, with author_name, when given, on its first line. Links in a text to cards and documents of the package are rewritten to their new addresses. |
| … with custom properties | + Custom properties and the minimum of A board with cards | The values are the properties of a card, each shaped by the type of its property. A select property carries its options. A value that names a user or a directory record needs those entities too, or it is left out. |
| … with external links | + Card links and the minimum of A board with cards | Each record is one link shown on one card: a page outside, another card of the package or a document of the package. The same address on two cards is two records. A link to a card or a document needs that card or document in the package, otherwise it is left out. |
| … with files in custom properties | + Attachments, Custom properties and the minimum of A board with cards | A property of type attachment has no value in the properties of a card. Its files are attachments of the card with property_ref naming the property; the bytes go under files/. |
| … with iterations (sprints) | + Iteration cards, Iterations, Space boards, Spaces and the minimum of A board with cards | An iteration belongs to a space, and it takes the cards of the boards that are placed in that space as the primary board, so the placement of the board comes along. The cards are listed separately, including the cards of iterations that are already closed. |
| … with members | + Card members, Users and the minimum of A board with cards | A card has at most one responsible user. A user who is both a member and responsible is stored as responsible. |
| … with parent and child cards | + Card children and the minimum of A board with cards | Every pair is written once, and the relations contain no cycle. |
| … with planned relations | + Card planned relations and the minimum of A board with cards | Both cards need planned_start and planned_end. A gap and its gap_type are given together, and the chain is shorter than 256 links. |
| … with subscriptions | + Users and the minimum of A board with cards | The cards list the users who follow them in subscriber_refs. |
| … with tags | + Tags and the minimum of A board with cards | A tag with the same name as one the company has is reused. The cards list their tags in tag_refs. |
| … with time tracking | + Card time logs, Users and the minimum of A board with cards | A time log needs the user. It is logged under the built-in role Employee. |
Company data outside boards
| I want to import | Minimum entities | What to know |
|---|---|---|
| Access roles | Roles | A role is built on a template of the target: reader, writer or admin. Only the roles of the package travel; arbitrary permissions are not accepted. Members and groups get a role by naming it in role_refs of tree_entity_roles; the built-in names reader, writer and admin need no role record, so a role cannot use them as its external_id. |
| Card types | Card types | A type with the same name as one the company has is reused, ignoring case. |
| Custom properties | Custom properties | Values of a property live on cards, so they come with cards. A select property lists its options in options; a property of type directory needs the directory. |
| Directories | Custom directories, Custom directory records, Custom properties, Users | The fields of a directory are listed in its fields; those of type select, user or directory link point at a custom property or another directory. The cell values are the values of each record. To pick a record on a card, add a property of type directory, and the cards. |
| Group access to nodes | Roles, Spaces, Tree entity roles, User groups, Users | A group has at most one tree_entity_roles record per space, folder or document (member_ref names the group), with one or more roles in role_refs: the built-in names reader, writer and admin, or the external_id of a role of the package. |
| Role and member access to nodes | Roles, Spaces, Tree entity roles, Users | A tree_entity_roles record gives a user (member_ref) one or more roles in a node (tree_entity_ref) through role_refs: the built-in names reader, writer and admin, or the external_id of a role of the package. Without any access record a node still imports: the user who runs the import is its administrator. |
| Tags | Tags | A tag with the same name as one the company has is reused. Colors are snapped to the supported ones. |
| User groups with members | User groups, Users | The groups list their members in user_refs and their administrators in admin_refs. A group with the same name as one the company has is reused, ignoring case, and keeps its own members and administrators. An administrator does not have to be a member. Importing groups needs the Members management permission and a tariff with groups. |
| Users | Users | A user is looked up in the target company by email and added to the target space, without an invitation email, where you may. Only email and full name are used. A user is never created from the package with a password. |
What you cannot do
| Not possible | Why |
|---|---|
| Create a company, or change its plan, its settings or its owner | An import always goes into a company you are signed in to, into a space you pick. Nobody gets rights of the company from a package. |
| Update or delete what the company already has | An import only adds. What is matched to existing data is matched by name or by email, as the notes above say, and never replaced. |
| Include an entity or a field that the format does not define | The package is refused before anything is sent. |
