# Global Keywords Database (SeedKeyword) - Import Guide

## Overview

The Global Keywords Database stores canonical keyword suggestions that can be imported into account-specific keywords. These are organized by Industry and Sector.

**Admin URL:** `https://api.igny8.com/admin/igny8_core_auth/seedkeyword/`

---

## Import Functionality

### CSV Format

The import expects a CSV file with the following columns:

| Column | Type | Required | Description | Example |
|--------|------|----------|-------------|---------|
| `keyword` | String | **Yes** | The keyword phrase | "best massage chairs" |
| `industry` | String | **Yes** | Industry name (must exist) | "Health & Wellness" |
| `sector` | String | **Yes** | Sector name (must exist) | "Massage Products" |
| `volume` | Integer | No | Monthly search volume | 5400 |
| `difficulty` | Integer | No | Keyword difficulty (0-100) | 45 |
| `country` | String | No | Country code (US, CA, GB, etc.) | "US" |
| `is_active` | Boolean | No | Active status | True |

### Sample CSV

```csv
keyword,industry,sector,volume,difficulty,country,is_active
best massage chairs,Health & Wellness,Massage Products,5400,45,US,True
deep tissue massage chair,Health & Wellness,Massage Products,720,52,US,True
shiatsu massage chair,Health & Wellness,Massage Products,1200,48,US,True
```

**Template file available:** `/data/app/igny8/backend/seed_keywords_import_template.csv`

---

## How to Import

### Step 1: Prepare Your CSV File

1. Download the template: `seed_keywords_import_template.csv`
2. Add your keywords (one per row)
3. Ensure Industry and Sector names **exactly match** existing records
4. Save as CSV (UTF-8 encoding)

### Step 2: Import via Django Admin

1. Go to: `https://api.igny8.com/admin/igny8_core_auth/seedkeyword/`
2. Click **"Import"** button (top right)
3. Click **"Choose File"** and select your CSV
4. Click **"Submit"**
5. Review the preview:
   - ✅ Green = New records to be created
   - 🔵 Blue = Existing records to be updated
   - ❌ Red = Errors (fix and re-import)
6. If preview looks good, click **"Confirm import"**

### Step 3: Verify Import

- Check the list to see your imported keywords
- Use filters to find specific industries/sectors
- Edit any records if needed

---

## Data Validation

The import process automatically:

✅ **Validates volume:** Ensures it's a positive integer (defaults to 0 if invalid)  
✅ **Validates difficulty:** Clamps to 0-100 range  
✅ **Validates country:** Must be one of: US, CA, GB, AE, AU, IN, PK (defaults to US)  
✅ **Handles duplicates:** Uses `(keyword, industry, sector)` as unique key  
✅ **Skip unchanged:** If keyword already exists with same data, it's skipped  

---

## Bulk Delete

### How to Delete Keywords

1. Select keywords using checkboxes (or "Select all")
2. Choose **"Delete selected keywords"** from the action dropdown
3. Click **"Go"**
4. Review the confirmation page showing all related objects
5. Click **"Yes, I'm sure"** to confirm deletion

**Note:** Only superusers and developers can delete seed keywords.

---

## Export Functionality

### Export to CSV/Excel

1. Go to: `https://api.igny8.com/admin/igny8_core_auth/seedkeyword/`
2. (Optional) Use filters to narrow down results
3. Click **"Export"** button (top right)
4. Choose format: CSV, Excel, JSON, etc.
5. File downloads with all selected fields

**Export includes:**
- All keyword data
- Related industry/sector names
- SEO metrics (volume, difficulty)
- Metadata (created date, active status)

---

## Common Issues & Solutions

### Issue: "Industry not found" error during import

**Solution:** 
- Ensure the industry name in your CSV **exactly matches** an existing Industry record
- Check spelling, capitalization, and spacing
- View existing industries: `/admin/igny8_core_auth/industry/`

### Issue: "Sector not found" error during import

**Solution:**
- Ensure the sector name in your CSV **exactly matches** an existing IndustrySector record
- The sector must belong to the specified industry
- View existing sectors: `/admin/igny8_core_auth/industrysector/`

### Issue: Import shows errors for all rows

**Solution:**
- Check CSV encoding (must be UTF-8)
- Ensure column headers match exactly: `keyword,industry,sector,volume,difficulty,country,is_active`
- Remove any extra columns or spaces in headers
- Verify there are no special characters causing parsing issues

### Issue: Duplicate keyword error

**Solution:**
- Keywords are unique per `(keyword, industry, sector)` combination
- If importing a keyword that already exists, it will be updated (not duplicated)
- Use `skip_unchanged = True` to avoid unnecessary updates

### Issue: Delete confirmation page has no "Delete" button

**Solution:** ✅ **FIXED** - Custom bulk delete action now includes proper delete button on confirmation page

---

## Permissions

| Action | Permission Required |
|--------|-------------------|
| View | Staff users |
| Add | Superuser |
| Edit | Superuser |
| Delete | Superuser or Developer |
| Import | Superuser |
| Export | Staff users |

---

## Technical Details

### Model Location
- **Model:** `backend/igny8_core/auth/models.py` - `SeedKeyword`
- **Admin:** `backend/igny8_core/auth/admin.py` - `SeedKeywordAdmin`
- **Resource:** `backend/igny8_core/auth/admin.py` - `SeedKeywordResource`

### Database Table
- **Table name:** `igny8_seed_keywords`
- **Unique constraint:** `(keyword, industry, sector)`
- **Indexes:** 
  - `keyword`
  - `industry, sector`
  - `industry, sector, is_active`
  - `country`

### API Access (Read-Only)
- **Endpoint:** `/api/v1/auth/seed-keywords/`
- **ViewSet:** `SeedKeywordViewSet` (ReadOnlyModelViewSet)
- **Filters:** industry, sector, country, is_active

---

## Related Documentation

- [Django Admin Guide](../../docs/90-REFERENCE/DJANGO-ADMIN-ACCESS-GUIDE.md)
- [Models Reference](../../docs/90-REFERENCE/MODELS.md)
- [Planner Module](../../docs/10-MODULES/PLANNER.md)

---

**Last Updated:** January 11, 2026  
**Maintainer:** IGNY8 Team