Metisara - JIRA Project Management Automation

🏛️ Wisdom and planning for your project management

Metisara is an automated JIRA project management workflow tool that streamlines the creation of project tickets through CSV processing and template-based configuration.

Features

• 📋 CSV Template Processing: Convert project templates to JIRA tickets
• 🎯 Intelligent Placeholder Replacement: Dynamic configuration with placeholders
• 👥 Team Management: Automated resource allocation and conception review tickets
• 🔄 Epic Linking: Automatic epic creation and ticket linking
• 🔍 Dry-Run Mode: Preview changes before creating actual JIRA tickets
• ⚙️ Flexible Configuration: JSON and INI-based configuration management
• 📦 Issue Reporting: Built-in diagnostics and issue reporting

Quick Start

1. Installation

Supported Platforms: macOS, Fedora Linux

git clone https://github.com/your-org/metisara.git
cd metisara

Platform-specific setup:

macOS:

# Install Python 3.7+ if needed (using Homebrew)
brew install python

Fedora:

# Install Python 3.7+ if needed
sudo dnf install python3 python3-pip

2. Configuration

Copy the example configuration file and customize it:

cp examples/metisara.conf.example metisara.conf

Edit metisara.conf with your JIRA settings:

[jira]
url = https://your-jira-instance.com/
username = your.email@company.com

[files]
csv_file_input = workspace/input/Metisara Template - Import.csv
csv_file_output = workspace/output/project-tickets-processed.csv

[project]
default_project = PROJ

3. Environment Setup

Create a .env file with your JIRA API token:

echo "JIRA_API_TOKEN=your_jira_api_token_here" > .env

4. Basic Usage

# Dry run (preview mode) - recommended for first use
./metis --dry-run

# Generate configuration from CSV template
./metis --generate-config

# Create actual JIRA tickets in your JIRA
./metis

# Test with verbose debug output
./metis --dry-run --verbose

# Download from Google Sheets (requires gcloud auth)
./metis --google-sheets "https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit?gid=0#gid=0" --dry-run

5. Google Sheets Integration (Optional)

For corporate environments, you can use Google Sheets as your CSV source:

# 1. Set up Google Cloud authentication
gcloud auth application-default login

# 2. Use Google Sheets URL directly (include gid for specific sheet)
./metis --google-sheets "https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit?gid=0#gid=0" --dry-run

# 3. Or configure in metisara.conf for automatic use
echo -e '\n[google_sheets]\nurl = https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit?gid=0#gid=0' >> metisara.conf

Important Notes:

• Google Sheets must be accessible by your authenticated Google account
• Include the gid parameter in the URL to specify which sheet tab to use (gid=0 is the first tab)
• You can get the full URL with gid by opening the specific sheet tab in your browser and copying the URL

Workflow Overview

Metisara follows a structured 3-phase workflow:

Phase 1: CSV Processing

1. File Detection: Automatically detects CSV files from multiple sources (Google Sheets, Downloads folder, or existing workspace files)
2. Configuration Generation: Extracts configuration from CSV template sections
3. Placeholder Replacement: Replaces placeholders with actual values

Phase 2: JIRA Ticket Creation

1. Project Issues: Creates top-level project issues first
2. Epic Issues: Creates epic issues with proper naming and linking
3. Story/Tracker Issues: Creates detailed work items linked to epics

Phase 3: Team Integration

• Resource Allocation: Auto-generates team assignment tickets
• Conception Reviews: Creates review tickets for stakeholders
• Epic Linking: Automatically links related tickets

Command Line Options

./metis [OPTIONS] [API_TOKEN]

Options:
  --version             Show version information
  --dry-run, --pretend  Simulate ticket creation without creating actual JIRA tickets
  --generate-config     Generate placeholder configuration from CSV file
  --report-issue        Create a zip file with workspace contents for issue reporting
  --clean               Clean all project generated files
  --google-sheets URL   Download CSV from Google Sheets URL (requires gcloud authentication)
  --verbose, --debug    Show detailed debug information including subprocess commands

Arguments:
  API_TOKEN             JIRA API token (optional if using .env file)

Project Structure

metisara/
├── metis                           # Main executable script
├── metisara.conf                   # Configuration file
├── .env                           # Environment variables (API tokens)
├── src/metisara/                  # Source code
│   ├── __init__.py               # Package initialization
│   ├── cli.py                    # Command-line interface
│   ├── config/                   # Configuration management
│   │   ├── manager.py           # Config file handling
│   ├── processors/              # CSV processing
│   │   ├── csv_processor.py     # Main CSV processing logic
│   ├── jira/                    # JIRA integration
│   │   ├── ticket_creator.py    # JIRA ticket creation
│   │   ├── field_finder.py      # JIRA field discovery
│   └── utils/                   # Utility functions
│       ├── file_manager.py      # File management utilities
├── workspace/                   # Working directory (auto-created)
│   ├── input/                  # Input CSV templates
│   ├── output/                 # Processed CSV files
│   ├── config/                 # Generated configuration files
│   └── temp/                   # Temporary files and logs
└── examples/                   # Example configuration files
    └── metisara.conf.example   # Example configuration

CSV Template Format

Metisara processes CSV templates with the following sections: (no need to create CSV manually, just download CSV from Google Sheets)

1. Ticket Definitions

Standard CSV format with columns:

• Milestone, Issue Type, Summary, Description, Priority
• Epic Link, Epic Name, Reporter, Assignee, Parent Link
• Target Start, Due Date, Component, Story Points

2. General Configuration Section

Milestone,Issue Type,Summary,Description,...
General Configuration,,,,...
<project_key>,PROJ,,,
<project_name>,My Project,,,
<program_manager>,manager@company.com,,,
<project_target_start>,2025-09-05,,,
<project_due_date>,2025-12-31,,,

3. Resource Allocation Teams

Milestone,Issue Type,Summary,Description,...
Resource Allocation Tickets,,,,...
Team A,Developer,John Doe,john@company.com,...
Team B,Designer,Jane Smith,jane@company.com,...

4. Conception Teams

Milestone,Issue Type,Summary,Description,...
Conception Tickets,,,,...
Architecture,Lead Architect,Bob Wilson,bob@company.com,...
QA,QA Lead,Alice Johnson,alice@company.com,...

Configuration Management

Automatic Configuration Generation

# Generate fresh configuration from CSV template
./metis --generate-config

This creates workspace/config/csv_replacements.json with:

• Extracted placeholder mappings
• Team member information
• JIRA project settings
• File path configurations

Manual Configuration

Edit workspace/config/csv_replacements.json for custom replacements:

{
  "_ai_disclaimer": "AI-Generated file - Review before production use",
  "replacements": {
    "<project_key>": "MYPROJ",
    "<project_name>": "My Amazing Project",
    "<program_manager>": "manager@company.com"
  },
  "jira_settings": {
    "target_project": "MYPROJ"
  }
}

Error Handling & Troubleshooting

Common Issues

1. Missing API Token

   # Solution: Set environment variable or use .env file
   export JIRA_API_TOKEN=your_token
   # Or create .env file with JIRA_API_TOKEN=your_token

2. CSV File Not Found

   # Solution: Place file in workspace/input/ directory
   mkdir -p workspace/input && mv "your-file.csv" workspace/input/

3. Configuration Errors

   # Solution: Regenerate configuration
   ./metis --generate-config

Issue Reporting

# Create diagnostic package (WARNING: may contain sensitive data)
./metis --report-issue

Cleaning Up

# Remove all generated files
./metis --clean

Container Testing

For testing Metisara in clean environments (simulating fresh installations):

# Quick test in Fedora container
./podman-scripts.sh build
./podman-scripts.sh start
./podman-scripts.sh exec metisara-fedora

# Inside container
source venv/bin/activate
./metis --version
./metis --dry-run

See TESTING.md for complete container testing documentation.

Development

Project Structure

• CLI Module (cli.py): Main command-line interface and workflow orchestration
• CSV Processor (csv_processor.py): Template processing and placeholder replacement
• JIRA Integration (ticket_creator.py): JIRA API integration and ticket creation
• Configuration (manager.py): Configuration file management
• Utilities (file_manager.py): File operations and workspace management

Key Components

1. JiraBulkCreator: Main class for JIRA ticket creation with support for:

   • Hierarchical ticket creation (Project → Epic → Story)
   • Epic placeholder resolution
   • Dry-run simulation
   • Error handling and reporting

2. CSV Processing: Advanced CSV processing with:

   • Comment line filtering
   • Configuration section extraction
   • Dynamic team ticket generation
   • Placeholder replacement

3. Configuration Management: Flexible configuration with:

   • JSON-based replacement mappings
   • INI-based system configuration
   • Environment variable support

Dependencies

• Python 3.7+
• jira: JIRA Python API client
• python-dotenv: Environment variable management
• configparser: INI file configuration

Security Considerations

• API tokens are stored in .env files (add to .gitignore)
• Issue reports may contain sensitive information (names, emails)
• Always review generated configurations before production use
• Use dry-run mode to preview changes

License

This project is licensed under the MIT License. See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For issues and questions:

1. Check the troubleshooting section above
2. Use ./metis --report-issue to create diagnostic information
3. Open an issue on GitHub with the diagnostic information (remove all PII/sensitive information before upload!)

---

🏛️ Metis - Named after the Greek goddess of wisdom and planning, Metisara brings methodical wisdom to your project management workflows.