Gratona
Data & imports

How do I import data into my account?

Updated 3 weeks ago

.

  1. TROUBLESHOOTING

  2. FAQs

How do I import data into my account?

Welcome to Gratona! 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 Gratona 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 Gratona:

    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

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

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 Gratona 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 Gratona 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 Gratona 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 Gratona 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

Gratona 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.

Bulk photo imports are available in the data import wizard: select Profile Photos as the import type, choose Recipients or donors, and name each file after a value that identifies the record. For the full recipient photo workflow, see How do I import recipient photos?

Best Practices

  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

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:

  • Contact Gratona support for help.

Was this helpful?
Was this helpful?