Most agencies arrive with years of records in another system. This page explains what Peace Portal Hub can bring across, how to export it, and what to leave exactly as it is. Read it before you export anything — a few decisions made now save a great deal of checking later.
Nothing on this page requires an account, and nothing here moves any data. The migration itself is carried out by Peace Portal Hub staff with your organization's agreement.
These are the datasets Peace Portal Hub currently brings across, listed in the order they must be sent. Each one can depend on the ones above it, so a file cannot be brought in before the records it refers to exist.
One row per program or team. Bring the identifier the old system used, so enrollments can point at it.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
name |
Program name | Required |
description |
Description | Optional |
status |
Status Left blank, the program arrives active. One of: active, inactive, archived | Optional |
This file creates no accounts. It ties your current system's worker identifiers to Peace Portal Hub accounts that already exist. Set those accounts up first, the ordinary way; a row matching nobody is reported back to you rather than guessed at.
Download CSV templateOne row per worker: their identifier in the old system, and the email address of their Peace Portal Hub account. Create the accounts first, the ordinary way, under People & access. This file creates nobody and changes nothing about an account.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
email |
Peace Portal Hub email address Must already belong to an active account in this organization. A row that matches nobody is rejected. | Required |
source_display_name |
Name in the old system Kept as provenance. Nothing is matched on it. | Optional |
One row per person. Status and the date that status began are both required: an agency's live caseload arriving as "intake pending", or dated the day of the migration, would be wrong on every screen that counts it.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
first_name |
First name | Required |
last_name |
Last name | Optional |
nickname |
Preferred name | Optional |
date_of_birth |
Date of birth | Optional |
gender |
Gender One of: male, female, non_binary, transgender_male, transgender_female, other, decline_to_state | Optional |
race_ethnicity |
Race / ethnicity One of: black_african_american, hispanic_latino, white, asian, native_american, pacific_islander, mena, two_or_more, other, decline_to_state | Optional |
primary_language |
Primary language | Optional |
needs_language_support |
Needs language support | Optional |
phone |
Phone | Optional |
email |
Optional | |
address_line |
Address | Optional |
city |
City | Optional |
state |
State Two letters. | Optional |
zip |
ZIP | Optional |
guardian_first_name |
Guardian first name | Optional |
guardian_last_name |
Guardian last name | Optional |
guardian_phone |
Guardian phone | Optional |
emergency_contact_name |
Emergency contact | Optional |
emergency_contact_phone |
Emergency contact phone | Optional |
status |
Status Required. The old system's own words have to be mapped to one of these before the file will load. One of: engagement, assigned_intake_pending, active, active_low_intensity, suspended, inactive, discharged | Required |
status_changed_at |
Date this status began Required, and never the date of the migration: it is what the engagement review and the time-in-status figures are counted from. | Required |
last_contact_at |
Last contact The real date of the last contact, where the old system holds it. | Optional |
One row per enrollment. A person on two programs has two rows.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_participant_id |
Participant identifier The participants identifier from the source system. | Points at another file |
source_program_id |
Program identifier The programs identifier from the source system. | Points at another file |
enrolled_at |
Enrolled on | Required |
exited_at |
Exited on | Optional |
status |
Status Left blank, the enrollment arrives active. One of: active, completed, withdrawn, inactive | Optional |
is_primary |
Primary program | Optional |
One row per worker on a case. Bring the current assignments; the history of who carried it before is not imported.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_participant_id |
Participant identifier The participants identifier from the source system. | Points at another file |
source_staff_id |
Worker identifier The staff identifiers identifier from the source system. | Points at another file |
role_key |
Discipline What this worker does on the case. One of: case_manager, street_outreach_worker, victim_advocate, therapist | Required |
effective_date |
Assigned on | Required |
is_primary |
Primary worker | Optional |
Current plans only. Signatures are never imported: a signed plan is a record of somebody signing, and a CSV is not evidence of that.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_participant_id |
Participant identifier The participants identifier from the source system. | Points at another file |
plan_date |
Plan date | Required |
review_due_on |
Review due | Optional |
status |
Status Left blank, the plan arrives as a draft. One of: draft, active, superseded, closed | Optional |
strengths |
Strengths | Optional |
resources |
Resources | Optional |
One row per goal, pointing at the plan it belongs to.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_support_plan_id |
Support plan identifier The support plans identifier from the source system. | Points at another file |
description |
Goal | Required |
status |
Status Left blank, the goal arrives as not started. One of: not_started, in_progress, achieved, partially_achieved, no_longer_relevant | Optional |
target_date |
Target date | Optional |
measure |
How progress is measured | Optional |
participant_role |
What the participant will do | Optional |
staff_role |
What the worker will do | Optional |
sort_order |
Order | Optional |
Open referrals only - the ones not yet screened or assigned. A referral that already became a participant should come in as a participant instead, or it will be counted twice.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_type |
Referral source One of: street_outreach, community_activity, cbo, police, justice_system, mayors_office, school, hospital, victim_services, self_referral, other | Required |
referral_date |
Referral date | Required |
first_name |
First name | Required |
last_name |
Last name | Optional |
date_of_birth |
Date of birth | Optional |
phone |
Phone | Optional |
address_line |
Address | Optional |
city |
City | Optional |
state |
State | Optional |
zip |
ZIP | Optional |
referrer_name |
Referrer | Optional |
referrer_organization |
Referrer organization | Optional |
referrer_phone |
Referrer phone | Optional |
presenting_concern |
Reason for referral | Optional |
Upcoming appointments. The worker named has to be in the staff identifiers file already.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_participant_id |
Participant identifier The participants identifier from the source system. | Points at another file |
source_staff_id |
Worker identifier The staff identifiers identifier from the source system. | Points at another file |
starts_at |
Starts at The appointment's own date and time, in the agency's local time. | Required |
purpose |
Purpose | Required |
duration_minutes |
Duration (minutes) | Optional |
kind |
Kind Left blank, the appointment arrives as in person. One of: in_person, phone, video, court, home_visit | Optional |
location |
Location | Optional |
internal_note |
Internal note Staff-facing. Nothing imported here is shown to the participant. | Optional |
Recent notes. Every note needs its real date and a real author: a note whose worker is not in the staff identifiers file is rejected rather than attributed to somebody else.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_participant_id |
Participant identifier The participants identifier from the source system. | Points at another file |
source_author_id |
Author identifier The worker who wrote the note in the old system. Required, and never substituted: these notes are read in disputed cases, and a note under the wrong name is worse than no note. | Points at another file |
contacted_at |
Date of contact When the contact happened, not when it was written up or imported. A date, because few old systems kept the time of day. | Required |
summary |
Note | Required |
contact_type |
Contact type One of: individual_session, group_session, street_engagement, home_visit, phone_call, text_message, hospital_response, court_accompaniment, crisis_counseling, mediation, case_conference, collateral_contact, attempted_contact, administrative | Required |
category |
Category Left blank, the note arrives as a progress note. One of: progress, safety_concern, imminent_risk, service_delivery, referral, incident, collateral | Optional |
visibility |
Visibility Left blank, the note is visible to the care team. Clinical notes are a separate permission in this product - map them to "clinical" or they will be readable by people the old system kept them from. One of: care_team, private, clinical | Optional |
location |
Location | Optional |
duration_minutes |
Duration (minutes) | Optional |
participant_present |
Participant present | Optional |
This file creates nothing. It is a list of what your current system holds, so we can agree together what still has to be carried across. Naming a file here does not send that file — moving the documents themselves is arranged separately during onboarding.
Download CSV templateReconciliation only. This file is read and reported on, and no document record is created by it: a document row needs a file behind it, and a CSV has none. Bringing the files themselves across is arranged separately during onboarding.
| Column | What it is | Needed? |
|---|---|---|
source_id |
This record's own identifier in your current system. Every file needs one. It is what later files point at, and what lets us run a file twice without duplicating anything. | Required |
source_participant_id |
Participant identifier The participants identifier from the source system. | Points at another file |
title |
Title | Required |
original_name |
File name The name the file has in the old system. Naming it here does not send it - this file is a list of what you hold, and the documents themselves are carried across separately. | Required |
document_type |
Type One of: release_of_information, protective_order, court_document, identification, consent_form, medical_record, school_record, housing_document, referral_paperwork, assessment, correspondence, photograph, other | Required |
size_bytes |
Size in bytes | Optional |
uploaded_at |
Date held from | Optional |
Templates are examples, not a requirement to rename your existing exports. If your current system uses different column names, Peace Portal Hub can map them during migration.
Each one has a header row and a single made-up record so you can see the shape of it. The names, telephone numbers and addresses in that row are invented — delete it before you send the file.
If you hold historical information outside this list, tell us during onboarding. We will say plainly whether it can be brought across, rather than leaving you to find out after go-live.
Export your records from your current system as comma-separated values (CSV) files. Most case-management systems offer this under an export, download or reporting option.
Send each dataset as its own file where your system allows it. One file of participants, one file of appointments, and so on. A single combined export is harder to check and harder to correct.
Your current system gives each record a reference of its own. Keep those references in the export. They are how Peace Portal Hub connects related records to each other — an appointment to the right participant, a goal to the right support plan — rather than matching on names, which repeat.
Do not renumber, tidy or shorten them. A reference only has to be consistent within your own files: the same participant reference on the participant row and on every appointment, note and plan that belongs to them.
These references are used during the migration and are not shown to your staff afterwards.
Every date in the export should be the date the thing actually happened — the date of the referral, the enrollment, the note, the appointment. Do not replace historical dates with today's date, and do not use the migration date as a stand-in for one you cannot find.
Dates are what your reporting is built on. A year of case notes carrying the date they were imported shows a year of work that never happened, and it cannot be put right afterwards.
If a date is genuinely unknown, leave the field empty and say so. An empty field is an honest gap. A filled one is a wrong answer.
Call your columns whatever your current system calls them. Before anything is brought in, a member of our team maps each of your columns to the matching Peace Portal Hub field, one at a time, and you see that mapping.
Nothing is guessed. A column that has not been mapped is not imported, and a column we cannot place is raised with you rather than assumed.
Each file is read all the way through once without creating a single record. This is the dry run, and it is not optional. It reports what would happen, line by line, so that problems are found while they are still easy to fix.
Where an incoming person resembles somebody already on your caseload, the row is held and shown to a person to decide. Nobody is merged automatically, and the import will not run while any of these are unanswered.
You decide whether it is the same person or a different one. Two people with the same name are common, and the cost of guessing wrong is somebody's record.
Send them in this order, or send them together and we will work through them in it.
Please do not:
A record that is incomplete can be completed later by the worker who knows the answer. A record that is wrong looks complete, and it will be relied on — in a case review, a funder report, or a court file.
A participant export contains names, dates of birth, contact details and case history.
Do not email files containing participant data. Do not place them in a shared drive or folder accessible to people outside the approved migration process. Your Peace Portal Hub onboarding contact will provide the approved secure transfer method.
A batch can be reversed afterwards if something is wrong, provided nothing has been built on top of it. That is a safety net, not a plan — the dry run is where mistakes are meant to be caught.
Before you send anything, keep an untouched copy of exactly what came out of your current system, and do not edit it. If a question comes up months later about what a record said before it moved, that copy is the answer.
Work on a duplicate if you need to adjust anything, and tell us what you changed.
We will ask the following at the start of onboarding. Having the answers ready shortens the work considerably.
Questions about any of this: support@peaceportalhub.net.