Survey Solutions Integration

This page documents the integration between PCH-SIG and Survey Solutions for field data collection.

Overview

Survey Solutions is a World Bank data collection tool. The integration allows you to:

• Synchronize households collected in the field
• Import survey data
• Update existing household information

Architecture

┌─────────────────┐         ┌─────────────────┐         ┌──────────────┐
│  Survey         │  Sync   │    PCH-SIG      │  Store  │   Database   │
│  Solutions      │ ------> │    API          │ ------> │   PostgreSQL │
│  (Tablets)      │         │                 │         │              │
└─────────────────┘         └─────────────────┘         └──────────────┘

Endpoints

Endpoint	Method	Description
/api/collecte/sync	POST	Synchronize Survey Solutions data
/api/collecte/menages	POST	Import a new household
/api/collecte/menages/{id}	PUT	Update a household
/api/collecte/status	GET	Last synchronization status

---

Synchronization

Endpoint

POST /api/collecte/sync

Request Body

{
  "source": "survey_solutions",
  "questionnaireId": "abc123",
  "data": [
    {
      "interview__id": "int-001",
      "menage_code": "MEN-OIO-001",
      "region": "Oio",
      "secteur": "Farim",
      "localite": "Farim Centro",
      "chef_nom": "Mamadou Diallo",
      "chef_sexe": "M",
      "taille_menage": 5,
      "nb_enfants_0_4": 1,
      "nb_enfants_5_14": 2,
      "latitude": 12.3456,
      "longitude": -15.6789,
      "distance_ecole": 1.5,
      "distance_sante": 2.3
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "processed": 150,
    "created": 120,
    "updated": 25,
    "errors": 5,
    "errorDetails": [
      {
        "interview__id": "int-045",
        "error": "Region not found: Unknown"
      }
    ]
  }
}

---

Field Mapping

Household

Survey Solutions	PCH-SIG	Description
interview__id	collecteId	Unique interview ID
menage_code	code	Household code
region	region.nom	Region name
secteur	secteur.nom	Sector name
localite	localite.nom	Locality name
gps__Latitude	latitude	GPS latitude
gps__Longitude	longitude	GPS longitude
gps__Accuracy	precisionGps	Accuracy in meters
taille_menage	tailleMenage	Household size
nb_enfants_0_4	nbEnfants04	Children 0-4 years
nb_enfants_5_14	nbEnfants514	Children 5-14 years
distance_ecole	distanceEcole	Distance to school (km)
distance_sante	distanceSante	Distance to health center (km)

Head of Household

Survey Solutions	PCH-SIG	Description
chef_nom	chefMenage.nomComplet	Full name
chef_sexe	chefMenage.sexe	Gender (M/F)
chef_age	chefMenage.age	Age
chef_telephone	chefMenage.telephone	Phone
chef_education	chefMenage.niveauEducation	Education level

Housing

Survey Solutions	PCH-SIG	Description
type_logement	logement.typeLogement	Housing type
statut_occupation	logement.statutOccupation	Occupancy status
nb_pieces	logement.nbPieces	Number of rooms
materiau_mur	logement.materiauMur	Wall material
materiau_toit	logement.materiauToit	Roof material
source_eau	logement.sourceEau	Water source
type_toilette	logement.typeToilette	Toilet type

---

New Fields

Distance to Services

Distance to social services fields have been added:

Field	Type	Description
distanceEcole	decimal	Distance to nearest school (km)
distanceSante	decimal	Distance to health center (km)
distanceMarche	decimal	Distance to market (km)
distanceEauPotable	decimal	Distance to water point (km)

These fields are used for:

• PMT score calculation
• Vulnerability analysis
• Geographic targeting

---

Conflict Management

Update Strategy

By default, synchronization uses the "last update wins" strategy:

• If collecteId exists: update fields
• If collecteId doesn't exist: create

Protected Fields

Some fields are not updated after initial collection:

• code (household code)
• dateEnregistrement
• createdAt

---

Data Validation

Validation Rules

Field	Rule	Error Message
region	Must exist	"Region not found"
tailleMenage	> 0	"Invalid household size"
latitude	-90 to 90	"Latitude out of bounds"
longitude	-180 to 180	"Longitude out of bounds"

Error Handling

Errors are returned in errorDetails:

{
  "errorDetails": [
    {
      "interview__id": "int-045",
      "field": "region",
      "value": "Unknown",
      "error": "Region not found"
    }
  ]
}

---

Synchronization Status

Endpoint

GET /api/collecte/status

Response

{
  "success": true,
  "data": {
    "lastSync": "2026-06-12T08:30:00+00:00",
    "lastSyncStatus": "success",
    "totalProcessed": 150,
    "totalErrors": 0,
    "pendingSync": 0,
    "nextScheduledSync": "2026-06-12T20:00:00+00:00"
  }
}

---

Configuration

Environment Variables

SURVEY_SOLUTIONS_URL=https://survey.example.com
SURVEY_SOLUTIONS_API_USER=api_user
SURVEY_SOLUTIONS_API_KEY=secret_key
SURVEY_SOLUTIONS_WORKSPACE=pch_gb

Scheduling

Synchronization can be scheduled via cron:

# Daily synchronization at 8pm
0 20 * * * /usr/bin/php /app/bin/console app:sync-survey-solutions

---

Permissions

Action	Permission
Synchronize	registre.collecte_sync
View status	registre.collecte_view

---

Best Practices

:::tip Recommendations

1. Test in preprod: Validate the mapping before production
2. Verify GPS: Check coordinate quality
3. Monitoring: Monitor synchronization errors
4. Backup: Export Survey Solutions data regularly :::