Migrate Trello Boards to Open Source Planka: A Step-by-Step API Guide

As a Senior DevOps Engineer and Technical Writer for TechResolve, I understand the challenges organizations face with proprietary SaaS solutions. While platforms like Trello are excellent for project management, the desire for greater control, data ownership, and cost efficiency often leads teams to explore open-source alternatives. Planka, a self-hosted, open-source project management tool, emerges as a compelling option. However, the thought of manually migrating years of Trello boards, lists, and cards can be daunting, consuming valuable time and introducing human error.

This comprehensive guide addresses that exact problem. Instead of laborious manual transfers, we will leverage the power of APIs to programmatically migrate your Trello boards to Planka. This tutorial is designed for SysAdmins, Developers, and DevOps Engineers looking to automate this process, gain deeper insight into API integrations, and transition seamlessly to a self-hosted solution.

Prerequisites

Before we dive into the migration, ensure you have the following:

• A running instance of Planka. If not, we will briefly cover setting it up with Docker.
• Admin access to your Planka instance to create boards and users.
• A Trello API Key and Token. You can obtain these by logging into your Trello account and visiting the developer API page.
• Python 3.x installed on your local machine.
• pip, Python’s package installer.
• Basic familiarity with JSON data structures and RESTful APIs.

Step-by-Step Guide

Step 1: Set Up Planka (If Not Already Running)

If you don’t have a Planka instance, the easiest way to get started is using Docker Compose. Create a docker-compose.yml file with the following content:

version: '3.8'

services:
  planka:
    image: planka/planka:latest
    container_name: planka
    restart: always
    ports:
      - "1337:80"
    environment:
      - NODE_ENV=production
      - MONGO_URL=mongodb://mongo:27017/planka
    depends_on:
      - mongo

  mongo:
    image: mongo:latest
    container_name: mongo
    restart: always
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:
    driver: local

Save this file and run docker-compose up -d in the same directory. Planka will be accessible at http://localhost:1337. Follow the initial setup to create your admin user.

Step 2: Extract Data from Trello

First, obtain your Trello API key and token. You can find these at https://trello.com/power-ups/admin. Keep them secure. Our Python script will use these to fetch your board data.

Install the requests library:

pip install requests

Here’s a Python script to extract your Trello data. It fetches boards, their lists, and the cards within those lists.

import requests
import json
import os

# --- Trello API Credentials ---
TRELLO_API_KEY = os.environ.get('TRELLO_API_KEY', 'YOUR_TRELLO_API_KEY')
TRELLO_TOKEN = os.environ.get('TRELLO_TOKEN', 'YOUR_TRELLO_TOKEN')

# --- Trello API Endpoints ---
TRELLO_BASE_URL = "https://api.trello.com/1"

def get_trello_data():
    all_data = []
    auth_params = {'key': TRELLO_API_KEY, 'token': TRELLO_TOKEN}

    print("Fetching Trello boards...")
    boards_url = f"{TRELLO_BASE_URL}/members/me/boards"
    boards_response = requests.get(boards_url, params={**auth_params, 'fields': 'id,name,desc'})
    boards_response.raise_for_status()
    boards = boards_response.json()

    for board in boards:
        board_data = {
            'id': board['id'],
            'name': board['name'],
            'description': board.get('desc', ''),
            'lists': []
        }
        print(f"  Fetching lists for board: {board['name']}")
        lists_url = f"{TRELLO_BASE_URL}/boards/{board['id']}/lists"
        lists_response = requests.get(lists_url, params={**auth_params, 'fields': 'id,name', 'cards': 'open'})
        lists_response.raise_for_status()
        trello_lists = lists_response.json()

        for trello_list in trello_lists:
            list_data = {
                'id': trello_list['id'],
                'name': trello_list['name'],
                'cards': []
            }
            print(f"    Fetching cards for list: {trello_list['name']}")
            cards_url = f"{TRELLO_BASE_URL}/lists/{trello_list['id']}/cards"
            cards_response = requests.get(cards_url, params={**auth_params, 'fields': 'id,name,desc,due,idMembers'})
            cards_response.raise_for_status()
            trello_cards = cards_response.json()

            for card in trello_cards:
                list_data['cards'].append({
                    'id': card['id'],
                    'name': card['name'],
                    'description': card.get('desc', ''),
                    'due': card.get('due'),
                    'idMembers': card.get('idMembers', []) # List of member IDs
                })
            board_data['lists'].append(list_data)
        all_data.append(board_data)
    
    with open('trello_data.json', 'w', encoding='utf-8') as f:
        json.dump(all_data, f, ensure_ascii=False, indent=4)
    print("Trello data successfully extracted to trello_data.json")
    return all_data

if __name__ == "__main__":
    # Ensure environment variables are set or replace placeholders
    if TRELLO_API_KEY == 'YOUR_TRELLO_API_KEY' or TRELLO_TOKEN == 'YOUR_TRELLO_TOKEN':
        print("WARNING: Please set TRELLO_API_KEY and TRELLO_TOKEN environment variables or replace placeholders in the script.")
        # exit(1) # Uncomment to force exit if credentials not set
    
    get_trello_data()

This script connects to the Trello API, retrieves all boards associated with your account, then for each board, fetches its lists and the cards within those lists. The data is saved to a trello_data.json file in a structured format, which will serve as our source for Planka.

Step 3: Transform Trello Data for Planka

Planka’s data model is similar but not identical to Trello’s. We need to map Trello boards to Planka projects, Trello lists to Planka lists, and Trello cards to Planka cards. A key consideration is user mapping. For this tutorial, we will simplify by assigning all cards to the Planka admin user. A more advanced script could attempt to create users in Planka based on Trello members and then map them.

The transformation logic will be embedded within the import script in the next step, as we’ll process data directly from the trello_data.json file and push it to Planka.

Step 4: Import Data into Planka

Now, let’s push the transformed data to your Planka instance. We’ll need to authenticate with Planka first to get a session token, then use that token for subsequent API calls.

First, get your Planka admin username and password. Then, modify the following Python script:

import requests
import json
import os
import time

# --- Planka API Credentials and Endpoint ---
PLANKA_BASE_URL = os.environ.get('PLANKA_BASE_URL', 'http://localhost:1337/api')
PLANKA_ADMIN_EMAIL = os.environ.get('PLANKA_ADMIN_EMAIL', 'admin@example.com') # Your Planka admin email
PLANKA_ADMIN_PASSWORD = os.environ.get('PLANKA_ADMIN_PASSWORD', 'adminpassword') # Your Planka admin password

# --- User Mapping (Simplified: Map all cards to Planka admin) ---
# In a real scenario, you'd fetch/create Planka users and map Trello idMembers to Planka user IDs.
# For this tutorial, we'll assign tasks to the Planka admin user.
# You might need to retrieve the admin user's ID from Planka after logging in.
PLANKA_ADMIN_ID = None # This will be set after successful login and fetching admin user data

def login_to_planka():
    global PLANKA_ADMIN_ID
    login_url = f"{PLANKA_BASE_URL}/users/login"
    login_payload = {
        'email': PLANKA_ADMIN_EMAIL,
        'password': PLANKA_ADMIN_PASSWORD
    }
    print("Attempting to log in to Planka...")
    try:
        response = requests.post(login_url, json=login_payload)
        response.raise_for_status()
        auth_token = response.headers.get('x-auth-token')
        user_data = response.json()
        PLANKA_ADMIN_ID = user_data['id']
        print(f"Successfully logged in as Planka user: {user_data['name']} (ID: {PLANKA_ADMIN_ID})")
        return auth_token
    except requests.exceptions.RequestException as e:
        print(f"Error logging into Planka: {e}")
        if e.response:
            print(f"Response: {e.response.text}")
        return None

def import_trello_to_planka(trello_data, auth_token):
    headers = {'x-auth-token': auth_token, 'Content-Type': 'application/json'}
    
    # Store mapping of old Trello IDs to new Planka IDs
    board_id_map = {}
    list_id_map = {}

    for trello_board in trello_data:
        print(f"Creating Planka board: {trello_board['name']}...")
        board_payload = {
            'name': trello_board['name'],
            'description': trello_board['description']
        }
        try:
            board_response = requests.post(f"{PLANKA_BASE_URL}/boards", headers=headers, json=board_payload)
            board_response.raise_for_status()
            planka_board = board_response.json()
            board_id_map[trello_board['id']] = planka_board['id']
            print(f"  Board '{planka_board['name']}' created with ID: {planka_board['id']}")

            for trello_list in trello_board['lists']:
                print(f"  Creating Planka list: {trello_list['name']} for board {planka_board['name']}...")
                list_payload = {
                    'boardId': planka_board['id'],
                    'name': trello_list['name']
                }
                list_response = requests.post(f"{PLANKA_BASE_URL}/lists", headers=headers, json=list_payload)
                list_response.raise_for_status()
                planka_list = list_response.json()
                list_id_map[trello_list['id']] = planka_list['id']
                print(f"    List '{planka_list['name']}' created with ID: {planka_list['id']}")

                for trello_card in trello_list['cards']:
                    print(f"      Creating Planka card: {trello_card['name']} for list {planka_list['name']}...")
                    card_payload = {
                        'listId': planka_list['id'],
                        'name': trello_card['name'],
                        'description': trello_card['description']
                    }
                    if trello_card['due']:
                        card_payload['dueDate'] = trello_card['due'] # Planka expects ISO 8601
                    
                    # Assign card to Planka admin
                    if PLANKA_ADMIN_ID:
                        card_payload['memberIds'] = [PLANKA_ADMIN_ID]

                    card_response = requests.post(f"{PLANKA_BASE_URL}/cards", headers=headers, json=card_payload)
                    card_response.raise_for_status()
                    planka_card = card_response.json()
                    print(f"        Card '{planka_card['name']}' created with ID: {planka_card['id']}")
                    time.sleep(0.1) # Small delay to avoid hammering API
        except requests.exceptions.RequestException as e:
            print(f"Error importing {trello_board.get('name', 'unknown board')}: {e}")
            if e.response:
                print(f"Response: {e.response.text}")
            continue # Continue with next board even if one fails
    print("Migration complete!")

if __name__ == "__main__":
    # Ensure environment variables are set or replace placeholders
    if PLANKA_ADMIN_EMAIL == 'admin@example.com' or PLANKA_ADMIN_PASSWORD == 'adminpassword':
        print("WARNING: Please set PLANKA_ADMIN_EMAIL and PLANKA_ADMIN_PASSWORD environment variables or replace placeholders in the script.")
        # exit(1) # Uncomment to force exit if credentials not set

    # Load Trello data
    try:
        with open('trello_data.json', 'r', encoding='utf-8') as f:
            trello_data_to_import = json.load(f)
    except FileNotFoundError:
        print("Error: trello_data.json not found. Please run the Trello extraction script first.")
        exit(1)

    # Login to Planka
    planka_auth_token = login_to_planka()

    if planka_auth_token:
        import_trello_to_planka(trello_data_to_import, planka_auth_token)
    else:
        print("Failed to obtain Planka authentication token. Aborting migration.")

This script first attempts to log into your Planka instance to obtain an authentication token. With this token, it iterates through the previously extracted Trello data, creating corresponding boards, lists, and cards in Planka. It also assigns all cards to the admin user identified during login. After execution, you should see your Trello boards and their contents reflected in your Planka instance.

Common Pitfalls

• API Rate Limits: Trello has rate limits. If you have an exceptionally large number of boards or cards, your Trello API calls might be temporarily blocked. The provided script includes small delays; for very large datasets, you might need to implement more sophisticated retry mechanisms with exponential backoff.
• Authentication Errors: Double-check your Trello API key/token and Planka admin credentials. Ensure there are no typos and that they have the necessary permissions. For Planka, verify your PLANKA_BASE_URL is correct (e.g., http://localhost:1337/api).
• Data Mapping Inconsistencies: This tutorial simplifies certain aspects, like user assignments and complex Trello features (checklists, labels, attachments). These might require custom logic to migrate accurately. Planka’s API might not support all granular features directly via simple REST calls, or their representation could differ significantly.
• Planka Instance Accessibility: Ensure your Planka instance is running and accessible from where you’re running the migration script. Firewall rules or incorrect container configurations can prevent API calls from reaching Planka.

Conclusion

Migrating from a proprietary SaaS solution like Trello to an open-source alternative such as Planka doesn’t have to be a manual, error-prone ordeal. By harnessing the power of their respective APIs, we’ve demonstrated a robust, automated method to transfer your project boards. This not only saves significant time and effort but also provides you with invaluable experience in API-driven automation.

The script provided here is a solid foundation. You can extend it further to:

• Implement more sophisticated user mapping, including creating Planka users from Trello members.
• Migrate additional card details like labels, checklists, and attachments (if supported by Planka’s API).
• Add robust error handling and logging for production environments.
• Schedule periodic synchronizations if you plan a gradual transition rather than a hard cut-over.

With your Trello data now comfortably residing in Planka, you have full control over your project management environment, paving the way for greater customization, data sovereignty, and cost efficiency. Happy self-hosting!

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions