Skip to content

Commit b8c4ab9

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

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

‎docs/import/school_import_csm_guide.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
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": "ImportSchoolsJob"
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": "ImportSchoolsJob",
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+
```json
93+
{
94+
"successful": [
95+
{
96+
"name": "Springfield Elementary",
97+
"id": "123e4567-e89b-12d3-a456-426614174000",
98+
"code": "12-34-56",
99+
"owner_email": "[email protected]"
100+
}
101+
],
102+
"failed": [
103+
{
104+
"name": "Shelbyville High",
105+
"error_code": "OWNER_NOT_FOUND",
106+
"error": "Owner not found: [email protected]",
107+
"owner_email": "[email protected]"
108+
}
109+
]
110+
}
111+
```
112+
113+
### 6. Handle Failures
114+
115+
Common failure reasons and solutions:
116+
117+
| Error Code | Error Message | Solution |
118+
|------------|---------------|----------|
119+
| `OWNER_NOT_FOUND` | Owner not found: [email protected] | Verify owner has CEfE account, create if needed |
120+
| `OWNER_ALREADY_CREATOR` | Owner is already the creator of school 'X' | Each person can only create one school; use different owner |
121+
| `SCHOOL_VALIDATION_FAILED` | Validation errors | Check country code, website format, required fields |
122+
| `CSV_VALIDATION_FAILED` | CSV validation failed | Check error details for specific row and field errors |
123+
| `DUPLICATE_OWNER_EMAIL` | Duplicate owner emails found in CSV | Same owner email appears multiple times - only one school per owner allowed |
124+
125+
For failed schools, you can either:
126+
1. Fix the issues and re-import (only failed schools)
127+
2. Create them manually through the standard process
128+
129+
## Important Notes
130+
131+
- **Automatic Verification**: Imported schools are automatically verified and receive school codes
132+
- **Owner Roles**: Owner roles are automatically created
133+
- **One Owner Per School**: Each owner can only create one school (enforced at database level)
134+
- **No Duplicate Owners in CSV**: The CSV cannot contain the same owner email multiple times
135+
- **No Teacher Creation**: Teachers are NOT created during import - they must be invited separately
136+
- **Country Codes**: Use ISO 3166-1 alpha-2 codes (find at https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
137+
- **Structured Errors**: All errors include error codes for programmatic handling
138+
139+
## Common Country Codes
140+
141+
| Country | Code |
142+
|---------|------|
143+
| United States | US |
144+
| United Kingdom | GB |
145+
| Canada | CA |
146+
| Mexico | MX |
147+
148+
## Troubleshooting
149+
150+
### CSV Validation Fails Immediately
151+
152+
The system validates the entire CSV before starting the import. If validation fails, you'll receive a structured error response:
153+
154+
**Example Error Response:**
155+
```json
156+
{
157+
"error_code": "CSV_VALIDATION_FAILED",
158+
"message": "CSV validation failed",
159+
"details": {
160+
"row_errors": [
161+
{
162+
"row": 2,
163+
"errors": [
164+
{"field": "country_code", "message": "invalid code: USA"}
165+
]
166+
},
167+
{
168+
"row": 5,
169+
"errors": [
170+
{"field": "website", "message": "invalid format"}
171+
]
172+
}
173+
]
174+
}
175+
}
176+
```
177+
178+
To fix:
179+
1. Check that all required headers are present (case-sensitive)
180+
2. Verify all required fields have values for every row
181+
3. Check country codes are valid 2-letter codes (US not USA)
182+
4. Verify website URLs are properly formatted (must include https://)
183+
5. Look for the row number in the error details
184+
185+
### Import Succeeds But Some Schools Failed
186+
187+
This is normal - the system processes all schools it can. Review the failed list and address issues individually.
188+
189+
### Duplicate Owner Emails in CSV
190+
191+
If your CSV contains the same owner email more than once, the import will be rejected before processing:
192+
193+
**Error Response:**
194+
```json
195+
{
196+
"error_code": "DUPLICATE_OWNER_EMAIL",
197+
"message": "Duplicate owner emails found in CSV",
198+
"details": {
199+
"duplicate_emails": ["[email protected]"]
200+
}
201+
}
202+
```
203+
204+
**Solution**: Each owner can only create one school. Either:
205+
- Use different owner emails for each school
206+
- Have one owner create their school first, then import the rest
207+
- Remove duplicate entries and import in batches
208+
209+
### All Schools Failed
210+
211+
Common causes:
212+
- Owner emails don't match any accounts
213+
- CSV formatting issues
214+
- Network/system errors (check with technical team)
215+
216+
## Getting Help
217+
218+
If you encounter issues:
219+
220+
1. Check the error message and error_code for specific details
221+
2. Verify your CSV matches the template format
222+
3. Confirm all owner emails are valid accounts
223+
4. Ensure no duplicate owner emails in your CSV
224+
5. Contact the technical team with:
225+
- The job_id
226+
- The CSV file (or sample rows)
227+
- Error codes and messages received
228+
229+
## Example Workflow
230+
231+
**Scenario**: Import 150 schools for Springfield School District
232+
233+
1. District admin provides school information
234+
2. You create CSV with all 150 schools
235+
3. Verify all 150 owners have accounts (or help them create accounts)
236+
4. Upload CSV via API
237+
5. Wait for job to complete (~2-5 minutes for 150 schools)
238+
6. Review results: 148 succeeded, 2 failed
239+
7. Fix issues with 2 failed schools (duplicate references)
240+
8. Create those 2 schools manually or re-import
241+
9. Notify district admin that all schools are ready
242+
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)