Appearance

Intro to Plane Scripts ​

Video Placeholder Duration: 4-6 minutes Topics covered: What are scripts, automation use cases, writing scripts, scheduling

What are Plane Scripts? ​

Plane Scripts are automated programs that interact with Plane via the API. They can be scheduled, triggered, or run manually to automate repetitive tasks.

Use Cases ​

Data Management ​

  • Bulk create work items
  • Update properties en masse
  • Clean up old items
  • Archive completed work

Reporting ​

  • Generate custom reports
  • Export data regularly
  • Create dashboards
  • Track metrics

Integration ​

  • Sync with external systems
  • Import from other tools
  • Push updates elsewhere
  • Bridge systems

Workflow Automation ​

  • Auto-assign based on rules
  • Escalate overdue items
  • Notify on conditions
  • Create recurring tasks

Script Architecture ​

Components ​

  • Script: Your automation code
  • API Access: Authenticated API calls
  • Trigger: What starts the script
  • Output: What the script produces

Getting Started ​

Prerequisites ​

  • Programming language (Python, JavaScript, etc.)
  • Plane API token
  • Development environment

Basic Setup (Python) ​

python
import requests

PLANE_TOKEN = "your-api-token"
BASE_URL = "https://api.plane.so/v1"
WORKSPACE = "your-workspace"

headers = {
    "Authorization": f"Bearer {PLANE_TOKEN}",
    "Content-Type": "application/json"
}

def get_issues(project_id):
    url = f"{BASE_URL}/workspaces/{WORKSPACE}/projects/{project_id}/issues/"
    response = requests.get(url, headers=headers)
    return response.json()

Script Examples ​

Bulk Create Issues ​

python
def create_issues(project_id, issues):
    url = f"{BASE_URL}/workspaces/{WORKSPACE}/projects/{project_id}/issues/"

    created = []
    for issue in issues:
        response = requests.post(url, headers=headers, json=issue)
        created.append(response.json())

    return created

# Usage
new_issues = [
    {"name": "Task 1", "description": "Description 1"},
    {"name": "Task 2", "description": "Description 2"},
    {"name": "Task 3", "description": "Description 3"},
]
create_issues("project-id", new_issues)

Find Overdue Items ​

python
from datetime import datetime

def find_overdue(project_id):
    issues = get_issues(project_id)
    today = datetime.now().date()

    overdue = []
    for issue in issues:
        if issue.get('target_date'):
            due = datetime.fromisoformat(issue['target_date']).date()
            if due < today and issue['state'] != 'done':
                overdue.append(issue)

    return overdue

Weekly Report Generator ​

python
def weekly_report(project_id):
    issues = get_issues(project_id)

    completed = [i for i in issues if i['state'] == 'done']
    in_progress = [i for i in issues if i['state'] == 'in-progress']
    backlog = [i for i in issues if i['state'] == 'backlog']

    report = f"""
    Weekly Report
    =============
    Completed: {len(completed)}
    In Progress: {len(in_progress)}
    Backlog: {len(backlog)}

    Completed Items:
    {[i['name'] for i in completed]}
    """

    return report

Running Scripts ​

Manual Execution ​

bash
python your_script.py

Scheduled Execution ​

Using Cron (Linux/Mac)

bash
# Run daily at 9am
0 9 * * * /usr/bin/python /path/to/script.py

Using Task Scheduler (Windows) Create a scheduled task to run your script.

Using Cloud Functions

  • AWS Lambda
  • Google Cloud Functions
  • Azure Functions

CI/CD Integration ​

Run scripts as part of your pipeline:

yaml
# GitHub Actions example
- name: Run Plane Script
  run: python scripts/sync_issues.py
  env:
    PLANE_TOKEN: ${{ secrets.PLANE_TOKEN }}

Best Practices ​

Error Handling ​

python
try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")
    # Handle gracefully

Rate Limiting ​

python
import time

def rate_limited_request(url):
    response = requests.get(url, headers=headers)

    # Check rate limit headers
    remaining = int(response.headers.get('X-RateLimit-Remaining', 100))
    if remaining < 10:
        time.sleep(1)  # Slow down

    return response

Logging ​

python
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def my_script():
    logger.info("Script started")
    # ... do work ...
    logger.info("Script completed")

Secrets Management ​

python
import os

# Don't hardcode tokens!
PLANE_TOKEN = os.environ.get('PLANE_TOKEN')

if not PLANE_TOKEN:
    raise ValueError("PLANE_TOKEN environment variable not set")

Script Organization ​

Project Structure ​

plane-scripts/
├── config.py           # Configuration
├── api_client.py       # API wrapper
├── scripts/
│   ├── weekly_report.py
│   ├── cleanup_old.py
│   └── sync_external.py
├── requirements.txt    # Dependencies
└── README.md          # Documentation

Key Takeaways ​

  • Scripts automate Plane interactions via the API
  • Use for bulk operations, reporting, and integrations
  • Any programming language that makes HTTP requests works
  • Schedule with cron, cloud functions, or CI/CD
  • Handle errors, rate limits, and logging properly
  • Keep secrets secure
  • Document and organize your scripts

Next Steps ​

Share your projects publicly with Plane Publish.

Next Lesson: Intro to Plane Publish

Plane University

Made with love by Plane