MyEdBC GDE to SpacesEDU Advanced CSV — How-to Guide

Introduction

• DistrictSync converts your MyEducation BC General Data Extracts (GDEs) into the Advanced CSV format for integration with SpacesEDU and myBlueprint+.
• It runs as a single executable file including a configuration interface, built-in SFTP upload, and support for automated daily scheduling.
• This article provides an overview of how to download and use the tool.

Step 1 — Download DistrictSync

Download the latest release for your platform:

Put the file anywhere convenient — a folder like C:\DistrictSync\, /opt/districtsync/, even a USB stick. Your settings, logs and run history are saved to your Windows user profile, not next to the program file, so where you keep the program doesn't matter.

On first launch, Windows may show a blue "Windows protected your PC" screen. This is normal for a new release that isn't yet code-signed — it doesn't mean anything is wrong. Click More info, then Run anyway. The first launch can take up to about 30 seconds while Windows unpacks the program; wait rather than double-clicking again.

For servers with no display (headless Linux, Docker, Windows Server Core), see Headless & Docker SFTP Setup — SFTP delivery can be configured entirely from the command line.

Step 2 — Open the DistrictSync app (Windows)

Double-clicking the program opens a native application window on the desktop.

Down the left side of the window is a fixed navigation menu, always in the same order:

Home · Convert · Run History · Setup · Mapping · Help

"Who looks after this sync?"

The very first thing you'll see is a short question: "Who looks after this sync?", asking for one work email address. This isn't a login or an account — there's no password, and nothing is "unlocked" by answering. It exists purely so DistrictSync can recognize your district's email domain and pre-select the right district for you further into setup.

• If your address matches a district DistrictSync already supports, it tells you which one and lets you continue or correct it.
• If it doesn't recognize the domain, it says so calmly and lets you carry on — you'll pick your district yourself in a moment.
• If you're not the person who manages this — or would rather skip the question — there's a plain link to move on without answering ("I'm not the person who looks after this sync"). Nothing is saved either way.

You can add, change or remove this address later from Setup → Settings.

Setup: a 5-step wizard

After the initial question, DistrictSync walks you through a five-step setup wizard on the Setup screen:

1. Choose your district — pick your district from a dropdown. If your email domain was recognized in the first step, your district may already be selected for you (a suggestion you can change, never a silent default) — otherwise nothing is pre-picked. If your district isn't listed, contact SpacesEDU support.
2. Choose your folders — the input folder where your MyEd BC GDE files land, and the output folder DistrictSync writes the converted CSV files to.
3. Set up delivery — enter the SFTP details SpacesEDU provided (host, username, password, remote path) and test the connection. This step is optional and can be set up later.
4. Set a nightly schedule — turn on an automatic daily run and pick a time (03:00 is a good default, after your overnight MyEd BC export finishes). This step is also optional — if you only plan to run conversions by hand from the Convert screen, you can skip it. This step also has an optional seasonal pause, so the sync can stop over summer break and resume on its own each fall.
5. Finish — a summary of what was actually set up (and what you skipped, so you know what's left). Finishing here is the one thing that marks setup complete.

Turning on the nightly schedule shows one Windows permission prompt. Registering a task that can run whether or not you're logged in needs administrator rights, so Windows asks you to approve that one step — click Yes. You don't need to run the whole program as administrator, and if you never turn on the schedule (ad-hoc runs only), you won't see this prompt at all.

Once you finish the wizard, the Setup screen (the rail item still says "Setup") turns into a flat Settings page where you can review or change your folders, district, schedule and delivery settings at any time, with a single Save that updates everything — including re-registering the nightly task if something that affects it changed.

The six screens

Home

A plain-language health check: is the sync working? A green banner means everything's fine, with the roster size for a quick sanity check. If something needs attention — a missing schedule, a failed run — Home names the problem in plain language and gives you a button to fix it. If setup hasn't been finished yet, Home shows the setup wizard itself instead of a dashboard.

Convert

Run a conversion by hand at any time — separate from any nightly schedule. Choose your district and input folder, click Convert now, and DistrictSync builds the CSV files into your configured output folder. If SFTP delivery is set up, you can send the files to SpacesEDU from here too, either right after a conversion or on their own from files already on disk. If a run's record counts drop sharply compared to the last one, Convert pauses and asks you to confirm before writing anything.

Run History

A read-only list of past runs — nightly, manual, and command-line — newest first, with plain-language status (not raw error text) and whether each run was delivered to SpacesEDU.

Setup

Covered above: the first-run wizard, then the ongoing Settings page for folders, district, schedule and delivery.

Mapping

Shows which pre-built district configuration is currently active and what it produces (which CSV files, from how many source files), and lets you switch to a different pre-built configuration — seeing what it would produce before you apply it. This is not a YAML editor: creating or adjusting a district's column mapping is done by the DistrictSync/SpacesEDU team, not in the app. Contact SpacesEDU support if your district needs a new or adjusted mapping.

Help

Links out to the SpacesEDU Help Centre and a one-click "email support" button (with the version number and your district name pre-filled in the subject line, so support doesn't have to ask). Both the Help Centre link and the support address are also shown as plain, selectable text, in case the "open" buttons don't do anything on a locked-down server without a browser or mail client configured.

Headless configuration (Linux)

On Linux or a server without a browser, configure SFTP from the command line:

# Interactive — prompts for each value (password input is hidden):
/opt/districtsync/DistrictSync --sftp-configure

# Or fully scripted:
export DISTRICTSYNC_SFTP_PASSWORD='your-password-here'
/opt/districtsync/DistrictSync --sftp-configure \
  --sftp-host sftp.ca.spacesedu.com \
  --sftp-user your_username \
  --sftp-remote /files
unset DISTRICTSYNC_SFTP_PASSWORD

# Verify credentials:
/opt/districtsync/DistrictSync --sftp-test

Then add a crontab entry to run daily:

(crontab -l 2>/dev/null; echo "0 3 * * * /opt/districtsync/DistrictSync --sis myedbc --input /data/gde/input --output /data/gde/output --sftp # DistrictSync managed entry") | crontab -

Step 3 — Place your GDE files

The GDE files required depend on which configuration (output tier) your district uses. See Configurations below for the full breakdown.

The tool expects exact filenames (e.g. Student Schedule.txt). If your district uses different filenames, advise SpacesEDU Support and we can generate a custom configuration for you.

Step 4 — Run the tool

If you set up a schedule and SFTP account, the tool will run automatically. You'll just need to ensure that new files are added to the input folder on the same schedule. You can also run the tool manually.

Ad-hoc run via the UI

Click Convert, review the selected configuration and input folder, then click Convert Now.

Manual run via command line

# Windows
C:\DistrictSync\DistrictSync-windows.exe --sis myedbc --input C:\DistrictSync\input --output C:\DistrictSync\output

# Linux
/opt/districtsync/DistrictSync --sis myedbc --input /data/gde/input --output /data/gde/output

Replace myedbc with mbp_all or mbp_core , along with folder names, as needed. Add --dry-run to preview record counts without writing files. Add --sftp to upload immediately after a successful run.

Output and SFTP upload

When SFTP upload is enabled, DistrictSync automatically zips all output CSVs into a single dated archive (districtsync_YYYY-MM-DD.zip) and uploads it to the SpacesEDU SFTP server after each run. You do not need to upload files manually.

If you need to upload manually, use an SFTP client such as FileZilla or Cyberduck to connect to sftp.ca.spacesedu.com and upload the zip to your assigned folder.

Configurations

DistrictSync supports three generic output tiers, selected via the --sis flag or the Setup Wizard district dropdown.

--sis myedbc — Standard rostering

Required GDE input files:

• StudentDemographicInformation.txt
• StaffInformationEnhanced.txt
• EmergencyContactInformation.txt
• StudentSchedule.txt
• CourseInformation.txt

Output CSVs:

--sis mbp_all — Full rostering & myBlueprint+ data

Produces all 5 standard rostering files plus 2 additional myBlueprint+ files.

Required GDE input files (everything in myedbc, plus):

• StudentCourseHistory.txt
• StudentCourseSelection.txt

Output CSVs:

--sis mbp_core — Core myBlueprint+ Data

For districts that only need to sync student and course data for myBlueprint+ — no family contacts or class enrollments.

Required GDE input files:

• StudentDemographicInformation.txt
• CourseInformation.txt
• StudentCourseHistory.txt
• StudentCourseSelection.txt

Output CSVs:

Field mapping reference

Students.csv — from Student Demographic Information

Only active students are exported. Students with an enrollment status of Inactive or a past withdrawal date are excluded automatically.

Staff.csv — from Staff Information - Enhanced

Family.csv — from Emergency Contact Information

Classes.csv — from Student Schedule + Course Information + Staff Information - Enhanced + Student Demographic Information

Classes are generated in two ways depending on grade level:

Homeroom classes (default for Grades K–7): One class is created per unique homeroom at a school. The Class ID is derived from the School Number and Homeroom Name; the class name is built from the Homeroom, Teacher Name, and Academic Year.

Subject classes (default for Grades 8–12): One class is created per course section in the student schedule. The Class ID is derived from the Master Timetable ID; the class name is built from the Teacher's Last Name, Course Title, Section, and Academic Year.

Enrollments.csv — from Student Schedule + Student Demographic Information

Homeroom enrollments: Students and teachers in StudentDemographicInformation.txt are enrolled in their corresponding homeroom class.

Subject enrollments: Students and teachers are enrolled in subject-based classes based on StudentSchedule.txt.

CourseInfo.csv — from Course Information (myBlueprint+ only)

StudentCourses.csv — from Course Information + Student Course History + Student Course Selection (myBlueprint+ only)

Automating GDE downloads from MyEdBC SFTP

MyEdBC can place your GDE exports on an SFTP server nightly. You can automate the download of those files into DistrictSync's input folder using WinSCP on Windows or lftp on Linux, then have DistrictSync run immediately after.

Prerequisites - Windows

• WinSCP installed on the same server as DistrictSync
• MyEdBC SFTP credentials (contact MyEdBC support)

Step 1 — Save your MyEdBC session in WinSCP

Storing credentials in a saved WinSCP session keeps them out of the script file entirely. WinSCP encrypts passwords using Windows Credential Manager.

1. Open WinSCP and click New Tab > New Site
2. Enter your MyEdBC SFTP connection details:

• File protocol: SFTP
• Host name: sftp.myeducation.gov.bc.ca
• User name / Password: your MyEdBC SFTP credentials
• If you don't have these credentials, contact MyEdBC support.

3. Click **Save, **check **Save Password, **and name the session MyEdBC
4. Click Login to connect and accept/verify the host key — WinSCP stores it with the session
5. Close the connection

The session name MyEdBC is what you'll reference in the script. No credentials appear in the script file itself.

Step 2 — Create the download script

Create a plain text file, e.g. C:\DistrictSync\download_gdes.txt, with the following content. Adjust the file list to match your configuration tier (see Configurations) and set INPUTDIR to your DistrictSync input folder.

# Download GDEs from MyEdBC SFTP
# Credentials are stored in the saved WinSCP session — not in this file.

open MyEdBC
cd /download/
lcd C:\DistrictSync\input

# --- myedbc (standard rostering) ---
get StudentDemographicInformation.txt
get StaffInformationEnhanced.txt
get EmergencyContactInformation.txt
get StudentSchedule.txt
get CourseInformation.txt

# --- optional: uncomment the lines below for mbp_all or mbp_core ---
# get StudentCourseHistory.txt
# get StudentCourseSelection.txt

close
exit

• Remove the # from the two optional lines if you are using the mbp_all or mbp_core configuration.
• Comment out the lines (add a #) for StaffInformationEnhanced.txt, EmergencyContactInformation.txt, and StudentSchedule.txt, if you are using the mbp_core configuration.

Step 3 — Test the script

Open Command Prompt and run:

"C:\Program Files (x86)\WinSCP\WinSCP.com" ^
  /log="C:\DistrictSync\winscp.log" ^
  /script="C:\DistrictSync\download_gdes.txt"

A successful run will show each file being downloaded. Check C:\DistrictSync\input (or your destination folder) to confirm the files arrived.

Step 4 — Schedule the download before DistrictSync

The download task should run before DistrictSync's daily run. If DistrictSync is scheduled at 3:00 AM, schedule the download at 2:00 AM.

1. Open Task Scheduler and click Create Basic Task
2. Name it DistrictSync_GDE_Download and set a daily trigger (e.g. 2:00 AM)
3. Action: Start a program

• Program/script: C:\Program Files (x86)\WinSCP\WinSCP.com
• Add arguments: /log="C:\DistrictSync\winscp.log" /script="C:\DistrictSync\download_gdes.txt"

4. Save the task

With this in place, you'll want to schedule the DistrictSync to run after the download task, so the nightly flow is (for example):

2:00 AM  WinSCP downloads GDE files from MyEdBC SFTP → C:\DistrictSync\input\
3:00 AM  DistrictSync reads input\, converts to CSV, uploads zip to SpacesEDU SFTP

Scheduling Downloads - Linux

On Linux, use lftp with credentials stored in ~/.netrc — a standard file that keeps passwords out of your scripts, readable only by your user account.

1. Store credentials in ~/.netrc:

echo "machine sftp.myeducation.gov.bc.ca login your_username password your_password" >> ~/.netrc
chmod 600 ~/.netrc

2. Create the download script at e.g. /opt/districtsync/download_gdes.sh:

#!/bin/bash
INPUT_DIR="/data/gde/input"

lftp -u your_username, sftp://sftp.myeducation.gov.bc.ca <<EOF
set sftp:auto-confirm yes
set net:max-retries 3
lcd $INPUT_DIR
cd /download
get StudentDemographicInformation.txt
get StaffInformationEnhanced.txt
get EmergencyContactInformation.txt
get StudentSchedule.txt
get CourseInformation.txt
# get StudentCourseHistory.txt
# get StudentCourseSelection.txt
bye
EOF

The password is read automatically from ~/.netrc — it does not appear in the script. Uncomment the last two get lines for mbp_all or mbp_core. Make the script executable:

chmod +x /opt/districtsync/download_gdes.sh

3. Add to crontab, scheduled before the DistrictSync run:

crontab -e

0 2 * * * /opt/districtsync/download_gdes.sh >> /opt/districtsync/download.log 2>&1
0 3 * * * /opt/districtsync/DistrictSync --sis myedbc --input /data/gde/input --output /data/gde/output --sftp

Troubleshooting

The tool runs but produces no output

Possible causes:

1. Wrong district config — The config expects different filenames than what's in the input directory.

• Check the log for messages like Primary source file 'X.txt' is empty.
• Try a different config (e.g., sd48myedbc instead of myedbc).

2. GDE files not in the input directory — Verify the files are present:

C:\DistrictSync\input\
     your Student Demographic file     ← must be here
     your Student Schedule file
     your Staff Information file
     your Course Information file
     your Emergency Contact file

3. All students are inactive — Only Active enrollment status is exported.

• Run with --quality to get a breakdown: DistrictSync-windows.exe --sis myedbc --input ... --output ... --quality

SFTP upload fails

Error: "No password found"

• The OS credential store was cleared (e.g., after a password change or server reinstall).
• Re-enter credentials via the Setup Wizard → Step 4.

Error: "Connection failed: Connection refused"

• Verify the SFTP host and port are correct.
• Check that the server firewall allows outbound connections on port 22.

Error: "Authentication failed"

• The username or password is incorrect.
• Contact SpacesEDU to confirm your credentials.

Task Scheduler does not run the task

First — is a seasonal pause switched on?

• If you enabled the seasonal pause (Setup → Schedule), DistrictSync intentionally does nothing outside your school-year window. The task still wakes each night; it checks the date and exits cleanly.
• Confirm by opening DistrictSync: Home reads a green "Paused for the summer — resumes <date>". That is the pause working, not a fault, and it will resume on its own on that date.
• If you need a one-off run while paused, use the Convert page — manual conversions always run, regardless of the window.

Task does not run after a reboot / server restart

• The Setup Wizard (schedule step) automatically registers the task to run whether the user is logged on or not with Highest Privileges, using the Windows account password you enter during setup.
• If the task still doesn't run after a reboot, the Windows password entered at setup was likely incorrect. A wrong password causes Windows to report an error in the wizard — if you dismissed the error, re-run the Setup Wizard to re-register the task with the correct password.
• If you left the password blank during setup, the task was registered for logged-on-only operation (the wizard warns you at that point). Enter the password to enable unattended runs.

The Windows permission prompt (UAC) when activating the schedule

• Registering an unattended task (runs whether or not you are logged on, with highest privileges) requires administrator rights. DistrictSync requests them with one Windows permission prompt as it registers the task — click Yes. You do not need to launch the whole app as administrator.
• "You declined the Windows permission prompt — nothing was changed." The prompt was answered No / Cancel. Re-run the schedule step and click Yes.
• "The permission prompt ran as a different account…" The prompt was approved with a different administrator account than the one you're logged in as. Log in as an administrator yourself, or use the no-password (logged-on-only) schedule.
• "Access is denied" even after approving the prompt: the Windows password was likely rejected. Enter your Windows account password — not your Windows Hello PIN, and for a Microsoft Account your microsoft.com password — on the schedule step. If it still fails, the account may not be permitted to "Log on as a batch job" (check with your IT administrator).

Task shows a non-zero "Last Run Result" (e.g. code 3 / 0x3)

• Exit code 3 means the ETL conversion succeeded and the output files were written, but the SFTP delivery to SpacesEDU failed. The CSV files are intact in your output folder.
• Open the Run History page in the DistrictSync wizard or check etl_tool.log in your DistrictSync data folder (see Where DistrictSync stores its data) for an ERROR line beginning SFTP upload FAILED — to find the cause (network, credentials, host).
• Re-run --sftp-test (or Setup Wizard → Step 4) to verify your SFTP credentials are still valid.

Task runs but nothing happens

• Open the Run History page in the DistrictSync app. Scheduled, manual,

and CLI runs are all recorded in the run-history database (history.db) in
your DistrictSync data folder, so a run that started should appear there,
tagged by how it was triggered.

• For the why behind a failed run, open the diagnostic log (etl_tool.log

in the same folder) and look for Pipeline failed: lines. Run History tells
you that a run failed; the log carries the detailed cause.

• The task's Start in field does not matter — both history.db and the

log always live in your DistrictSync data folder regardless of the working
directory (see
Where DistrictSync stores its data).

I ran the .exe from a terminal and saw nothing

On Windows the released .exe is a windowed application, so double-clicking
it never flashes a black console box. The trade-off is that it only prints when
there is a terminal to print to:

Because the app is windowed, your shell does not wait for it: the prompt
returns immediately and the output appears after it. Use start /wait if you
want the prompt to wait for the run to finish.

When nothing is printed, the run still leaves two signals: the diagnostic log
(etl_tool.log in your DistrictSync data folder) and the exit code below.
On Linux and macOS output goes to the terminal as usual.

Exit codes

Every run ends with one of four codes. Task Scheduler shows it as **Last Run
Result**; in Command Prompt read it with echo %ERRORLEVEL%, in PowerShell with
$LASTEXITCODE.

A code 1 and a code 3 mean very different things: 1 means no files were
produced, 3 means the files exist locally but SpacesEDU did not receive them.

Encoding errors in log

WARNING - Could not decode your Student Demographic file with utf-8, trying latin1

This is normal. The tool automatically tries UTF-8, Latin-1, and CP1252 in sequence. If all three fail, check that the file is a valid text file (not corrupt or binary).

"Mapping file not found" error

ERROR - Mapping file not found: config/mappings/myedbc_mapping.yaml

The tool cannot find its configuration files. This happens when:

• The executable was moved without the config/ directory.
• The tool is invoked from a different working directory.

Fix: The config is embedded in the executable (PyInstaller bundle). If you see this error from the bundled .exe, contact SpacesEDU — it may indicate a corrupted download.

Partial output files

If the tool crashes mid-run, you may find an incomplete output directory. Since v1.4+, DistrictSync uses atomic (transactional) writes — all CSVs are staged in a temporary directory first and only committed together on success. A failed run leaves the previous output intact.

If you find a .tmp_* directory in your output folder, it means the tool was interrupted during a write. Delete it and re-run.

SFTP Host Rejected

DistrictSync only allows SFTP uploads to SpacesEDU servers (sftp.ca.spacesedu.com, sftp.app.spacesedu.com, sftp.myblueprint.ca). If you see 'SFTP host not allowed', verify you're using the correct SpacesEDU host.

Record Count Drop Warning

If a run produces significantly fewer records than the previous run (>20% decrease), a warning is logged. This usually means the GDE export was incomplete. Re-export the files from MyEdBC and run again.

Wrong file extension (.csv vs .txt)

Some districts (e.g., SD40 – New Westminster) export GDE files as .csv instead of .txt. If the tool cannot find the expected file, check whether your district's files have a .csv extension and contact SpacesEDU to ensure the correct district config (e.g., sd40myedbc) is configured for your installation.

Records missing after SpacesEDU import

If DistrictSync completed successfully but records are missing in SpacesEDU, the issue is on the import side — not DistrictSync. Common causes:

• Email domain mismatch — student or staff email doesn't match the district's configured domain in SpacesEDU.
• Missing required field — a record was skipped because a required field (User ID, Name, etc.) was blank.
• Orphaned enrollment — an enrollment references a Class ID or User ID that doesn't exist in the corresponding file.
• Family without student — a family record references a student not in Students.csv.

Check the SpacesEDU import report for details. See also FAQ — What happens after upload.

A student appears in the wrong class

A student shows up in an old or incorrect class in SpacesEDU even though MyEdBC was updated.

The fix depends on the student's grade, because different GDE files drive placement for different grades:

DistrictSync rebuilds every class and enrollment from scratch on each run — it never remembers a previous run. So if the output still places a student in the wrong class, the current input file named above still contains that placement. The fix is always the same shape: correct it in MyEdBC → re-export that GDE → re-run.

Homeroom-grade students (K–7) are the common surprise. Their class is named <Homeroom> - <Teacher name> (<year>) (e.g. 10 Eng6/7 - Bali-Kainth, P. (2026)), taken straight from the Student Demographic Homeroom and Teacher name columns — not from who teaches their courses. If a student was moved to a new homeroom but still appears in the old one, the **Homeroom field on their demographic record was never updated in MyEdBC**. Moving them in the schedule (their course teachers) will not fix it — and re-exporting only the Student Schedule will not fix it. Update the homeroom assignment in MyEdBC, then re-export the Student Demographic file.

A stale GDE cannot be auto-detected. DistrictSync faithfully transforms whatever it is handed; it has no way to know an export is out of date. The only built-in guard is the >20 % record-drop warning (above), which won't catch scattered individual changes. Keeping exports current — especially the Student Schedule at semester rollover, when secondary timetables change wholesale — is an operational responsibility.

A student isn't getting the expected homeroom class

Homeroom classes are only created for grades listed in the config's homeroom_grades (compared after CEDS normalization). DistrictSync maps several MyEdBC grade codes onto a homeroom grade automatically — for example KF and EL both normalize to KG.

Any grade code the tool doesn't recognize falls through to UG (ungraded) and is treated as a non-homeroom grade, so that student is routed through the subject-class (schedule) path and gets no homeroom. If a district introduces a new grade code and its students unexpectedly have no homeroom, the code is likely missing from the grade map — contact SpacesEDU to have it added.

Where DistrictSync stores its data (config, logs, run history)

DistrictSync keeps all of its data — your saved settings (config.json), the diagnostic log (etl_tool.log), and the run-history database — in the standard per-user application-data folder for your operating system. Nothing is ever written next to the .exe, so moving or re-downloading the program never loses your settings or history:

Two things track your runs, side by side in that folder:

• history.db — the run-history database the Run History surface reads. Every run (wizard, scheduled task, and CLI) is recorded here, tagged by how it was triggered.
• etl_tool.log — the diagnostic log: the detailed, human-readable messages for troubleshooting a specific run. It rotates automatically at 5 MB and keeps 3 backups (etl_tool.log.1, .2, .3).

Both are written regardless of where the .exe lives or what working directory the task runs from.

Run History looks empty after updating? This version records history in history.db rather than parsing it back out of the log, so history starts fresh with this update — earlier log-derived runs aren't carried over (the old log mixed real runs with internal test entries). Run History fills in again from your next conversion; your previous etl_tool.log is untouched.

Upgrading from an older version? Earlier releases stored this data in a .districtsync folder in your home directory (e.g. C:\Users\<username>\.districtsync\). The first time you run a newer version, DistrictSync automatically copies your settings, logs, and history into the new location above and leaves a small MOVED.txt note in the old folder pointing at the new one. The move is safe and one-time: if anything prevents it, DistrictSync simply keeps using the old folder (you are never left half-moved). Once you have confirmed everything still works, the old .districtsync folder is safe to delete.

Still need help?

1. Review ~/.districtsync/etl_tool.log for error details
2. Contact SpacesEDU support at hello@spacesedu.com with the log file attached

Updated on: 18/08/2026