199 lines
5.9 KiB
Markdown
199 lines
5.9 KiB
Markdown
# Global Keywords Database (SeedKeyword) - Import Guide
|
|
|
|
**Last Updated:** January 20, 2026
|
|
**Version:** 1.8.4
|
|
|
|
## 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
|