How do I import data into my account?

Welcome to HelpYouSponsor! This comprehensive guide walks you through the process of importing data into the system. The platform supports importing:

• Recipients (also called Entities)

• Donors (also called Sponsors)

• Sponsorship Relationships

• Payments

• Photos and additional files

This documentation combines both UI instructions and technical details to provide a complete reference for data migration.

Note: Before importing any data, ensure you've prepared properly

Import Strategy

1. Identify Data Sources

   Determine where your data currently resides (e.g., spreadsheets, another CRM, etc.)

2. Define Data Mappings

   Map fields from your source data to HYS fields

3. Establish Import Order

   Always follow this sequence:

   1. First: Recipients (Entities)

   2. Second: Donors (Sponsors)

   3. Third: Relationships (connections between recipients and sponsors)

   4. Fourth: Payments (if applicable)

4. Set Import Timeline

   Plan for adequate testing time before final import

5. Assign Responsibilities

   Identify who will prepare data, perform imports, and verify results

Data Preparation Requirements

1. CSV Format: Organize your data in CSV format

2. Required Fields: Include all required fields for each data type

3. File Size: Ensure CSV files are under 10MB

4. Headers: Include appropriate headers matching the required field names

5. Encoding: Save files as UTF-8 encoded CSVs

6. Delimiters: Use comma (,) as the field separator

7. First Row: First row must contain column headers

System Preparation

1. Form Configuration:

   Ensure all necessary forms are configured in HYS:

   1. Recipient profile forms with required fields.

   2. Sponsor profile forms with required fields.

2. Program Setup:

   Verify program settings:

   1. Sponsorship amounts.

   2. Number of sponsors per recipient.

   3. Program type (one-time, recurring, etc)

3. User Access: Confirm admin users have appropriate import permissions

Import Types and Required Fields

Recipient Import

Recipients are individuals who receive sponsorships from donors through your programs. They are referred to as "Entities" in some parts of the system.

Required CSV Format for Recipients

Field Name	Description	Required	Format	Notes
First name	First name of recipient	Yes	Text
Last name	Last name of recipient	Yes	Text
DOB	Date of birth	Yes	YYYY-MM-DD
Gender	Gender	Yes	M/F
Program id	ID of the program	Yes	Number
Recipient id	Unique ID (if existing)	No	Text/Number	Used for reference
Bio	Biographical information	No	Text
Location	Location/address	No	Text
Status	Availability status	No	Number	0=Available, 1=Not Available
SP_NUM	Number of sponsors needed	No	Number	Defaults to 1 if not specified
SP_AMOUNT	Sponsorship amount	No	Number (decimal)	Defaults to program amount if not specified

Special Fields for Recipients

• SP_NUM: Indicates how many sponsors are needed for full sponsorship

• SP_AMOUNT: Sets the monthly sponsorship amount (defaults to program setting if not specified)

Donor Import

Donors are individuals or organizations that sponsor recipients. They are referred to as "Sponsors" in some parts of the system.

Required CSV Format for Donors

Field Name	Description	Required	Format	Notes
First name	First name of donor	Yes	Text
Last name	Last name of donor	Yes	Text
Email	Email address	Yes	Email format	Used as username if not specified
Phone	Phone number	No	Text
Address	Physical address	No	Text
Donor id	Unique ID (if existing)	No	Text/Number	Used for reference
Donor status	Status	No	Text	Active/Inactive
Notes	Additional notes	No	Text
Username	Login username	No	Text	Defaults to email if not specified
Password	Account password	No	Tex	System generates if not specified

Special Fields for Donors

• username: If not specified, the system uses the email address as the username.

• password: If not specified, the system generates a random password.

Sponsorship Relationship Import

Sponsorship relationships connect donors to recipients and define sponsorship details.

Required CSV Format for Sponsorships

For sponsorships, we require a field in the CSV for the entities that will act as an association between the donor and child. for example, child id in the csv which is related to the child id in the donors record that the donor is sponsoring. Then for the donors we only want the field that carries the donor id from the csv. Next field is the sponsorship amount, so in the CSV you indicate which column contains the sponsorship amounts. Finally, the date when the sponsorship started.

Special Considerations for Relationships

• Donors and recipients must already exist in the system.

• The system will update recipient availability based on sponsorship totals.

• If a recipient is fully sponsored, their status will automatically change to "Not Available".

Payment Import

Payments record financial transactions from donors, optionally linked to specific recipients.

Required CSV Format for Payments

For the importation of the payments. We'll require the child id from the csv which will be associated with the child id the donor sponsors. Then we'll require the donor id field in the csv so that we are able to map the payments to the appropriate donor.

For payment details, We'll require amounts column, payment date (the date when payments were made), results or notes written on that payment (can be empty if no notes), Payment method (options are provided like cash, credit card), the payment type (this can be one time payment, recurring payment). default payment method (this will be the payment method that the system will use to track the sponsorship)

Step-by-Step Import Process

Import Recipients

1. Navigate to Import Tool:

   • Log in as administrator

   • Navigate to Campaigns & Programs > Manage Programs

   • Find the program you want to import recipients to

   • Click the three dots (⋮) menu on the right side of the program

   • Select Import from the dropdown menu

2. Upload and Configure:

   • Select your prepared CSV file

   • Choose "Recipients" as the import type

   • Click "Begin Import"

3. Map Fields:

   • For each column in your CSV, select the corresponding HYS field

   • If a column should be ignored, select "Do Not Import"

   • Special fields require specific mapping (e.g., SP_NUM, SP_AMOUNT, status)

4. Configure Import Settings:

   • Select Field for Matching: Typically Internal ID or recipient_id

   • Specify Default Values: For any required fields not in your CSV

   • Set Custom ID Field: If applicable for your organization

5. Review and Validate:

   • Preview how data will be imported

   • Check for any validation warnings

6. Execute Import:

   • Click "Import Data" to begin

   • Monitor progress indicator

7. Receive Confirmation:

   • System will notify when import completes

   • Summary report shows records imported, skipped, or with errors

Managing Recipient Availability

The system manages recipient availability based on their sponsorship status:

• Status 0: Available/Unsponsored - Recipient is available for sponsorship

• Status 1: Not Available/Fully Sponsored - Recipient has all needed sponsors

• Status 2: Processing/Checked Out - Recipient is temporarily unavailable (in checkout process)

Import Donors

1. Navigate to Import Tool:

   • Log in as administrator

   • Navigate to Campaigns & Program > Manage Programs

   • Find the program you want to import donors to

   • Click the three dots (⋮) menu on the right side of the program

   • Select Import from the dropdown menu

2. Upload and Configure:

   • Select your prepared CSV file

   • Choose "Donors" as the import type

   • Click "Begin Import"

3. Map Fields:

   • For each column in your CSV, select the corresponding HYS field

   • If a column should be ignored, select "Do Not Import"

   • Map username and password fields if you have them, otherwise system defaults apply

4. Configure Import Settings:

   • Select Field for Matching: Typically email address or donor_id

   • Specify Default Values: For any required fields not in your CSV

5. Review and Validate:

   • Preview how data will be imported

   • Check for any validation warnings

6. Execute Import:

   • Click "Import Data" to begin

   • Monitor progress indicator

7. Receive Confirmation:

   • System will notify when import completes

   • Summary report shows records imported, skipped, or with errors

Import Sponsorship Relationships

1. Navigate to Import Tool:

   • Log in as administrator

   • Navigate to Campaigns & Program > Manage Programs

   • Find the program you want to import sponsorship relationships to

   • Click the three dots (⋮) menu on the right side of the program

   • Select Import from the dropdown menu

2. Upload and Configure:

   • Select your prepared CSV file

   • Choose "Sponsorship Relationship" as the import type

   • Click "Begin Import"

3. Map Fields:

   • For each column in your CSV, select the corresponding HYS field

   • If a column should be ignored, select "Do Not Import"

   • Ensure donor_id and recipient_id are properly mapped

4. Configure Import Settings:

   • Verify ID Matching: Confirm how donor and recipient IDs should be matched

   • Specify Default Values: For any required fields not in your CSV

5. Review and Validate:

   • Preview how data will be imported

   • Check for any validation warnings

6. Execute Import:

   • Click "Import Data" to begin

   • Monitor progress indicator

7. Receive Confirmation:

   • System will notify when import completes

   • Summary report shows records imported, skipped, or with errors

Import Payments

1. Navigate to Import Tool:

   • Log in as administrator

   • Navigate to Campaign & Program > Manage Programs

   • Find the program you want to import payments to

   • Click the three dots (⋮) menu on the right side of the program

   • Select Import from the dropdown menu

2. Upload and Configure:

   • Select your prepared CSV file

   • Choose "Payments" as the import type

   • Click "Begin Import"

3. Map Fields:

   • For each column in your CSV, select the corresponding HYS field

   • If a column should be ignored, select "Do Not Import"

   • Ensure donor_id is properly mapped, and recipient_id if relevant

4. Configure Import Settings:

   • Verify ID Matching: Confirm how donor and recipient IDs should be matched

   • Specify Default Values: For any required fields not in your CSV

5. Review and Validate:

   • Preview how data will be imported

   • Check for any validation warnings

6. Execute Import:

   • Click "Import Data" to begin

   • Monitor progress indicator

7. Receive Confirmation:

   • System will notify when import completes

   • Summary report shows records imported, skipped, or with errors

Photo Import Methods

HYS offers multiple methods for importing photos for your recipients and donors.

Method 1: Individual Upload (Web Interface)

1. Navigate to Profile:

   • Find and select the recipient or donor

   • Click "Files" or "Upload Photo" option

2. Select and Upload Photo:

   • Choose file from your computer

   • Optionally crop/resize

   • Click "Upload"

3. Set as Profile Picture:

   • If uploading multiple photos, select which one to use as the profile picture

   • Save changes

Method 2: This can only be donoor by our developers.

1. Organize children Images:

   • Have the images to contain the children id for example (1200.png)

   • Place them in a folder to be shared with HYS

2. Uploading done by HYS developers:

• Once we have received the folder containing images, we'll upload them according to the child id provided in HYS. Please ensure the filenames match with the children ids in the imported data.

Best Practices

Recommended Import Order

1. Recipients first

2. Donors second

3. Sponsorship relationships third

4. Payments fourth

This order ensures that all necessary relationships can be established properly.

Data Preparation Tips

• Clean your data before importing

• Validate required fields are present

• Check for formatting issues

• Remove duplicates

• Use consistent date formats (YYYY-MM-DD)

• Save as UTF-8 encoded CSV files

Testing Your Import

1. Create a test sample with 5-10 records

2. Import the sample

3. Verify the data appears correctly

4. Proceed with the full import once verified

Data Backup

• Keep backups of original data

• Save copies of all CSV files

• Take screenshots of import confirmations

Data Validation Tips

• Ensure recipient IDs are unique

• Verify donor emails are valid format

• Confirm relationships reference valid IDs

• Check that dates follow YYYY-MM-DD format

• Verify numeric fields contain only number

Troubleshooting Common Issues

Issue	Solution
CSV format errors	Verify the file is properly formatted with headers in the first row
Missing required fields	Check the error report to identify and add missing data
Duplicate records	Remove duplicates from your import file
Date format issues	Ensure all dates follow YYYY-MM-DD format
Relationship failures	Verify that referenced IDs exist in the system before importing relationships
UTF-8 encoding issues	Resave your file with UTF-8 encoding
File size too large	Split large files into multiple smaller files under 10MB
Sponsorship status not updating	Verify that relationship data is correctly formatted with valid amounts
Photo linking failures	Ensure filenames exactly match recipient IDs
Import timeout	Break large imports into smaller batches

Sample CSV Templates

Recipients Sample

first_name,last_name,dob,gender,program_id,recipient_id,bio,location,status,SP_NUM,SP_AMOUNT
John,Doe,2010-05-15,M,1,R1001,"John is a bright student who enjoys math.",Nairobi,0,1,35.00
Jane,Smith,2012-03-20,F,1,R1002,"Jane loves reading and wants to become a doctor.",Lagos,0,2,35.00

Donors Sample

first_name,last_name,email,phone,address,donor_id,donation_status,notes,username,password
Robert,Johnson,[email protected],555-123-4567,"123 Main St, Anytown",D2001,Active,"Monthly donor since 2022",,
Sarah,Williams,[email protected],555-987-6543,"456 Oak Ave, Somewhere",D2002,Active,"Prefers email communication",,

Sponsorships Sample

donor_id,recipient_id,start_date,sponsorship_amount,frequency,program_id,end_date,status
D2001,R1001,2023-01-15,35.00,Monthly,1,,Active
D2002,R1002,2023-02-20,35.00,Monthly,1,,Active

Payments Sample

donor_id,recipient_id,amount,payment_date,payment_method,transaction_id,notes
D2001,R1001,35.00,2023-01-15,Credit Card,TX100123,"Initial payment"
D2002,R1002,105.00,2023-02-20,Bank Transfer,TX100124,"Quarterly payment"

Support

If you encounter issues during the import process, please contact our support team:

• Email: [email protected]