(help-jira_download_attachments)=

# jira_download_attachments.py - Download attachments from Jira issues

::::{warning}

This documentation was AI-generated by Claude Code and should be reviewed for accuracy. Please report any errors or inconsistencies.

::::

## Description

Downloads all attachments from a Jira issue and saves them with their original filenames to a specified directory. Supports filtering by filename pattern and list-only mode for previewing attachments. Designed for downloading manuscript PDFs and submission forms from AEA Data Editor Jira tickets.

## Usage

```bash
python3 tools/jira_download_attachments.py <issue-key> [OPTIONS]
```

### Arguments

- **issue-key** (required) - Jira issue key (e.g., AEAREP-9354, aearep-9354, case-insensitive)

### Options

- `--output-dir DIR`, `-o DIR` - Directory to save attachments (default: current directory)
- `--filter PATTERN`, `-f PATTERN` - Only download files matching this pattern (case-insensitive substring match)
- `--list`, `-l` - List attachments without downloading
- `--verbose`, `-v` - Print detailed progress information

### Examples

```bash
# Download all attachments to current directory
python3 tools/jira_download_attachments.py AEAREP-9354

# Download to specific directory
python3 tools/jira_download_attachments.py AEAREP-9354 --output-dir ./attachments

# Download only PDF files
python3 tools/jira_download_attachments.py AEAREP-9354 --filter ".pdf"

# Download only manuscripts
python3 tools/jira_download_attachments.py AEAREP-9354 --filter "manuscript"

# Download only forms
python3 tools/jira_download_attachments.py AEAREP-9354 --filter "form"

# List attachments without downloading
python3 tools/jira_download_attachments.py AEAREP-9354 --list

# Verbose mode
python3 tools/jira_download_attachments.py AEAREP-9354 --verbose
```

## Automation Script

A convenient wrapper script is available that automatically reads the Jira ticket from `config.yml`:

```bash
# Download all attachments from ticket in config.yml
bash automations/30_download_jira_attachments.sh

# List attachments first
bash automations/30_download_jira_attachments.sh --list

# Download only manuscripts
bash automations/30_download_jira_attachments.sh --filter manuscript

# Download only forms
bash automations/30_download_jira_attachments.sh --filter form
```

## Requirements

- Python >= 3.6
- `jira`: Python Jira library (already in requirements.txt)

### Environment Variables Required

- `JIRA_USERNAME` - Your Jira email address
- `JIRA_API_KEY` - API token from https://id.atlassian.com/manage-profile/security/api-tokens

To obtain a Jira API token:
1. Visit https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the token and set it as `JIRA_API_KEY` environment variable

## Output

- **On success**: Downloads attachments with their original filenames; prints each filename to stdout
- **No attachments**: Prints warning to stderr and exits with code 0
- **Missing credentials**: Prints error message with instructions and exits with code 1
- **Invalid issue key**: Prints error and exits with code 1
- **Download failure**: Prints error for failed files but continues with remaining files

## Typical Workflow

For AEA replication packages, each Jira ticket typically has two attachments:
1. A manuscript (PDF)
2. A submission form (PDF or Word document)

Recommended workflow:

```bash
# 1. Check what attachments are available
bash automations/30_download_jira_attachments.sh --list

# 2. Download all attachments to repository root
bash automations/30_download_jira_attachments.sh
```

Or download selectively:

```bash
# Download manuscript only
bash automations/30_download_jira_attachments.sh --filter manuscript

# Download form only
bash automations/30_download_jira_attachments.sh --filter form
```

## Behavior

- Attachments are saved with their original filenames from Jira
- Existing files with the same name will be overwritten without warning
- Downloads are performed over HTTPS using the Jira REST API
- The tool respects Jira API rate limits
- Requires active internet connection and valid Jira credentials

## See Also

- [jira_get_info.py](help-jira_get_info) - Retrieve Jira issue information
- [jira_add_comment.py](help-jira_add_comment) - Post comments to Jira issues
- [jira_find_task_by_icpsr.py](help-jira_find_task_by_icpsr) - Find Jira tasks by openICPSR ID
- [30_download_jira_attachments.sh](https://github.com/aeaDataEditor/replication-template/blob/master/automations/30_download_jira_attachments.sh) - Automation wrapper script