Skip to content

Commit eb5bff3

Browse files
fspeirsfspeirs
committed
Add documentation - CSM guide and example CSV template
1 parent bd01501 commit eb5bff3

File tree

2 files changed

+253
-0
lines changed

2 files changed

+253
-0
lines changed

‎docs/import/school_import_csm_guide.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# School Import Quick Reference for Customer Success Managers
2+
3+
## Prerequisites
4+
5+
1. You must have the `experience-cs-admin` or `profile-admin` role
6+
2. School owners must have existing Code Editor for Education accounts
7+
3. School owners must be unique within the CSV, and in the existing database.
8+
4. CSV file must be properly formatted (see template)
9+
10+
## Step-by-Step Process
11+
12+
### 1. Prepare the CSV File
13+
14+
Download the template: `docs/school_import_template.csv`
15+
16+
Required columns:
17+
- `name` - School name
18+
- `website` - School website URL (e.g., https://example.edu)
19+
- `address_line_1` - Street address
20+
- `municipality` - City/town
21+
- `country_code` - 2-letter code (US, GB, CA, etc.)
22+
- `owner_email` - Email of school owner (must exist in system)
23+
24+
Optional columns:
25+
- `address_line_2` - Additional address info
26+
- `administrative_area` - State/province
27+
- `postal_code` - ZIP/postal code
28+
- `reference` - School reference number (must be unique)
29+
30+
### 2. Validate Owner Emails
31+
32+
Before importing, verify that all owner emails in your CSV correspond to existing accounts in Code Editor for Education. Owners without accounts will cause those schools to fail during import.
33+
34+
### 3. Upload the CSV
35+
36+
**Via API:**
37+
38+
```bash
39+
curl -X POST https://editor-api.raspberrypi.org/api/schools/import \
40+
-H "Authorization: YOUR_TOKEN" \
41+
-F "csv_file=@path/to/schools.csv"
42+
```
43+
44+
**Response:**
45+
```json
46+
{
47+
"job_id": "550e8400-e29b-41d4-a716-446655440000",
48+
"total_schools": 150,
49+
"message": "Import job started successfully"
50+
}
51+
```
52+
53+
### 4. Track Progress
54+
55+
Use the job_id from the response:
56+
57+
```bash
58+
curl https://editor-api.raspberrypi.org/api/school_import_jobs/550e8400-e29b-41d4-a716-446655440000 \
59+
-H "Authorization: YOUR_TOKEN"
60+
```
61+
62+
**Response while running:**
63+
```json
64+
{
65+
"id": "550e8400-e29b-41d4-a716-446655440000",
66+
"status": "running",
67+
"created_at": "2024-01-15T10:00:00Z",
68+
"finished_at": null,
69+
"job_class": "SchoolImportJob"
70+
}
71+
```
72+
73+
**Response when completed:**
74+
```json
75+
{
76+
"id": "550e8400-e29b-41d4-a716-446655440000",
77+
"status": "completed",
78+
"created_at": "2024-01-15T10:00:00Z",
79+
"finished_at": "2024-01-15T10:05:00Z",
80+
"job_class": "SchoolImportJob",
81+
"results": {
82+
"successful": [...],
83+
"failed": [...]
84+
}
85+
}
86+
```
87+
88+
### 5. Review Results
89+
90+
Once the job completes, the results will show:
91+
92+
```
93+
Job ID: 8a24adf7-c705-451a-8bb3-051ec5d8fdd8
94+
Status: completed
95+
Job Type: SchoolImportJob
96+
Created: 2025-11-20T15:44:52.925Z
97+
Finished: 2025-11-20T15:44:53.316Z
98+
99+
════════════════════════════════════════════════════════════════
100+
Summary
101+
════════════════════════════════════════════════════════════════
102+
103+
Total Schools: 3
104+
✓ Successful: 3
105+
✗ Failed: 0
106+
107+
════════════════════════════════════════════════════════════════
108+
Successful Schools
109+
════════════════════════════════════════════════════════════════
110+
111+
NAME CODE OWNER EMAIL
112+
────────────────────────────────────────────────────────────────
113+
Springfield Elementary School 85-59-21 [email protected]
114+
Shelbyville High School 76-79-30 [email protected]
115+
Capital City Academy 32-91-93 [email protected]
116+
117+
════════════════════════════════════════════════════════════════
118+
```
119+
120+
### 6. Handle Failures
121+
122+
Common failure reasons and solutions:
123+
124+
| Error Code | Error Message | Solution |
125+
|------------|---------------|----------|
126+
| `OWNER_NOT_FOUND` | Owner not found: [email protected] | Verify owner has CEfE account, create if needed |
127+
| `OWNER_ALREADY_CREATOR` | Owner is already the creator of school 'X' | Each person can only create one school; use different owner |
128+
| `SCHOOL_VALIDATION_FAILED` | Validation errors | Check country code, website format, required fields |
129+
| `CSV_VALIDATION_FAILED` | CSV validation failed | Check error details for specific row and field errors |
130+
| `DUPLICATE_OWNER_EMAIL` | Duplicate owner emails found in CSV | Same owner email appears multiple times - only one school per owner allowed |
131+
132+
For failed schools, you can either:
133+
1. Fix the issues and re-import (only failed schools)
134+
2. Create them manually through the standard process
135+
136+
## Important Notes
137+
138+
- **Automatic Verification**: Imported schools are automatically verified and receive school codes
139+
- **Owner Roles**: Owner roles are automatically created
140+
- **One Owner Per School**: Each owner can only create one school (enforced at database level)
141+
- **No Duplicate Owners in CSV**: The CSV cannot contain the same owner email multiple times
142+
- **No Teacher Creation**: Teachers are NOT created during import - they must be invited separately
143+
- **Country Codes**: Use ISO 3166-1 alpha-2 codes (find at https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
144+
- **Structured Errors**: All errors include error codes for programmatic handling
145+
146+
## Common Country Codes
147+
148+
| Country | Code |
149+
|---------|------|
150+
| United States | US |
151+
| United Kingdom | GB |
152+
| Canada | CA |
153+
| Mexico | MX |
154+
155+
## Troubleshooting
156+
157+
### CSV Validation Fails Immediately
158+
159+
The system validates the entire CSV before starting the import. If validation fails, you'll receive a structured error response:
160+
161+
**Example Error Response:**
162+
```json
163+
{
164+
"error_code": "CSV_VALIDATION_FAILED",
165+
"message": "CSV validation failed",
166+
"details": {
167+
"row_errors": [
168+
{
169+
"row": 2,
170+
"errors": [
171+
{"field": "country_code", "message": "invalid code: USA"}
172+
]
173+
},
174+
{
175+
"row": 5,
176+
"errors": [
177+
{"field": "website", "message": "invalid format"}
178+
]
179+
}
180+
]
181+
}
182+
}
183+
```
184+
185+
To fix:
186+
1. Check that all required headers are present (case-sensitive)
187+
2. Verify all required fields have values for every row
188+
3. Check country codes are valid 2-letter codes (US not USA)
189+
4. Verify website URLs are properly formatted (must include https://)
190+
5. Look for the row number in the error details
191+
192+
### Import Succeeds But Some Schools Failed
193+
194+
This is normal - the system processes all schools it can. Review the failed list and address issues individually.
195+
196+
### Duplicate Owner Emails in CSV
197+
198+
If your CSV contains the same owner email more than once, the import will be rejected before processing:
199+
200+
**Error Response:**
201+
```json
202+
{
203+
"error_code": "DUPLICATE_OWNER_EMAIL",
204+
"message": "Duplicate owner emails found in CSV",
205+
"details": {
206+
"duplicate_emails": ["[email protected]"]
207+
}
208+
}
209+
```
210+
211+
**Solution**: Each owner can only create one school. Either:
212+
- Use different owner emails for each school
213+
- Have one owner create their school first, then import the rest
214+
- Remove duplicate entries and import in batches
215+
216+
### All Schools Failed
217+
218+
Common causes:
219+
- Owner emails don't match any accounts
220+
- CSV formatting issues
221+
- Network/system errors (check with technical team)
222+
223+
## Getting Help
224+
225+
If you encounter issues:
226+
227+
1. Check the error message and error_code for specific details
228+
2. Verify your CSV matches the template format
229+
3. Confirm all owner emails are valid accounts
230+
4. Ensure no duplicate owner emails in your CSV
231+
5. Contact the technical team with:
232+
- The job_id
233+
- The CSV file (or sample rows)
234+
- Error codes and messages received
235+
236+
## Example Workflow
237+
238+
**Scenario**: Import 150 schools for Springfield School District
239+
240+
1. District admin provides school information
241+
2. You create CSV with all 150 schools
242+
3. Verify all 150 owners have accounts (or help them create accounts)
243+
4. Upload CSV via API
244+
5. Wait for job to complete (~2-5 minutes for 150 schools)
245+
6. Review results: 148 succeeded, 2 failed
246+
7. Fix issues with 2 failed schools (duplicate references)
247+
8. Create those 2 schools manually or re-import
248+
9. Notify district admin that all schools are ready
249+
10. District admin can now invite teachers to their schools

‎docs/import/school_import_template.csv‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
name,website,address_line_1,address_line_2,municipality,administrative_area,postal_code,country_code,reference,owner_email
2+
Springfield Elementary School,https://springfield-elem.edu,123 Main Street,,Springfield,IL,62701,US,SPE-001,[email protected]
3+
Shelbyville High School,https://shelbyville-high.edu,456 Oak Avenue,Suite 100,Shelbyville,IL,62565,US,SHS-002,[email protected]
4+
Capital City Academy,https://capital-city-academy.edu,789 State Road,,Capital City,IL,62702,US,CCA-003,[email protected]

0 commit comments

Comments
 (0)