Peace Portal Hub
Onboarding

Preparing your data for migration

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.

What we can migrate

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.

  1. Programs The programs and teams the agency runs. Download CSV template
    What goes in each column

    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
  2. Staff identifiers Ties the source system's staff identifiers to staff accounts that already exist in Peace Portal Hub. Creates no accounts.

    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 template
    What goes in each column

    One 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
  3. Participants The people the agency serves, with their demographics and contact information. Download CSV template
    What goes in each column

    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 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
  4. Program enrollments Which program each participant is on, and between which dates. Download CSV template
    What goes in each column

    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
  5. Case assignments Which member of staff carries each case. Download CSV template
    What goes in each column

    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
  6. Support plans Current support plans. Download CSV template
    What goes in each column

    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
  7. Plan goals The goals on those support plans. Download CSV template
    What goes in each column

    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
  8. Open referrals Referrals received and not yet screened or assigned. Download CSV template
    What goes in each column

    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
  9. Appointments Scheduled appointments. Download CSV template
    What goes in each column

    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
  10. Case notes Recent case notes, with their original dates and authors. Download CSV template
    What goes in each column

    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
  11. Documents A list of the documents held in the old system. Reconciliation only — no files are created.

    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 template
    What goes in each column

    Reconciliation 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

About the templates

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.

What to send

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.

Keep your original identifiers

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.

Include the reference for

  • Participants
  • Programs
  • Staff members
  • Program enrollments
  • Support plans
  • Referrals
  • Appointments
  • Case notes

And keep them as they are

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.

Keep your original dates

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.

Your column names do not need to match ours

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.

Every file is checked before anything is written

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.

The dry run looks for

  • Required information that is missing
  • Dates that cannot be read
  • Values the field does not accept
  • The same reference used twice in one file
  • Records pointing at something not yet brought across
  • People who may already be in Peace Portal Hub
  • Records that have already been imported

Possible duplicate participants

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.

The order to send your files

Send them in this order, or send them together and we will work through them in it.

  1. Programs
  2. Staff identifiers
  3. Participants
  4. Program enrollments
  5. Case assignments
  6. Support plans
  7. Plan goals
  8. Open referrals
  9. Appointments
  10. Case notes
  11. Documents

Before you send your files

Please do not:

  • Invent a date you cannot find
  • Replace a historical date with the migration date
  • Assign a case to a worker who did not carry it
  • Record consent that was not given
  • Add a signature that was not signed
  • Mark something verified that was not verified
  • Combine two people because their names look similar

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.

Sending your files safely

These files hold sensitive information

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.

What happens once we have your files

  1. Source system identified. We record which system the files came from, so references are matched within it.
  2. Secure upload. Files are placed in private storage. Uploading creates no records.
  3. Field mapping. Each of your columns is matched to a Peace Portal Hub field.
  4. Dry run. Every file is read in full and nothing is written.
  5. Review. Possible duplicates and rejected rows are worked through with you.
  6. Reconciliation. Every line is accounted for: to be created, already present, needing a decision, deliberately left out, or rejected.
  7. Approval. Nothing is imported until somebody approves that reconciliation.
  8. Import. The same file is read again, writing records this time.
  9. Verification. We check what arrived against what was promised, and report it back to you.

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.

Keep your original export

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.

Before migration begins

We will ask the following at the start of onboarding. Having the answers ready shortens the work considerably.

  • The name of the system you are moving from
  • Which of the datasets above you want brought across
  • Roughly how many participants are in your records
  • Whether your staff already have Peace Portal Hub accounts
  • Whether document files need to be transferred separately
  • Whether you hold other historical records that must be preserved

Questions about any of this: support@peaceportalhub.net.