Skip to content

Data Import

Country Workspace supports importing beneficiary data from multiple sources. Every import runs within the selected Program and creates a Batch that groups the imported records.

This section explains how to prepare a Program, choose and configure a data source, review imported records, reprocess existing Batches, and resolve common import issues.

Import workflow

flowchart LR
    A[Select Program]
        --> B[Choose data source]
        --> C[Configure import]
        --> D[Import data]
        --> E[Review imported records]

Before you import

Before importing beneficiary data, make sure that the selected Program is configured for the required beneficiary structure and validation rules.

Depending on the selected source, additional preparation may be required. Source-specific requirements and instructions are described in Data sources.

Optional field mappings and value transformations are described in Mapping and transformation.

What happens during import

Although each data source has its own preparation and processing rules, all imports follow the same general lifecycle.

flowchart LR
    A[Create Batch and read source data]
        --> B[Prepare beneficiary fields]
        --> C[Create beneficiary records]
        --> D[Create and resolve relationships]
        --> E[Apply Transformers and source-specific checks]
        --> F[Schedule validation if enabled]
        --> G[Complete Batch]

Create Batch and read source data creates a Batch in Loading status and reads records from the uploaded workbook or selected external source.

Prepare beneficiary fields applies source-specific preparation, normalizes field names, applies selected Mapping Importers, processes supported document fields, applies Program defaults, and removes ignored fields.

Create beneficiary records creates Households and Individuals, or People, according to the Program structure. The source data used to create each record is stored for later Batch reprocessing.

Create and resolve relationships creates the Household membership, Household roles, and cross-record references supported by the selected source.

Apply Transformers and source-specific checks applies selected Transformers after beneficiary records and supported relationships have been created. Additional checks, such as RDI duplicate identity detection, are performed when configured and supported by the source.

Schedule validation if enabled creates background validation jobs using the Program's validation configuration. Validation can report unexpected fields as Alien Fields.

Complete Batch marks the Batch as Complete after source-specific processing has finished and any enabled validation jobs have been scheduled. Validation results may continue to appear after the Batch becomes Complete.

Source-specific preparation, relationships, checks, and failure behavior are described under Data sources.

Validation after import

Validate after import is enabled by default and can be disabled when configuring the import. When enabled, validation is scheduled after all source-specific processing has finished.

Import results

After source-specific processing finishes, open the created Batch to review the imported records and processing status.

If processing stops before finalization, the Batch can remain Loading.

Validation results may continue to appear as background validation jobs finish.

If the Program processing configuration, Mapping Importers, or Transformers change later, the Batch can be reprocessed without requesting or uploading the original source again.

See Batches for Batch review, status, reprocessing, picture import, and cleanup.

Supported data sources

Country Workspace currently supports importing beneficiary data from:

An overview of the available sources and their requirements is provided in Data sources.

Troubleshooting

If an import cannot be started, does not complete, or produces unexpected records, see Troubleshooting.