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

The SIG pulls interviews from the Survey Solutions server: there is no endpoint where Survey Solutions would push data.

Household import

Endpoint	Method	Permission	Description
/api/menages/survey-solutions/import	POST	registre.import	Imports interviews of a questionnaire
/api/menages/survey-solutions/sync	POST	registre.import	Syncs one questionnaire, or all active household questionnaires
/api/menages/survey-solutions/questionnaires	GET	registre.import	Household questionnaires
/api/menages/survey-solutions/stats	GET	registre.menages_view	Import statistics

Updating existing households

Endpoint	Method	Permission	Description
/api/menages/survey-solutions/updates/process	POST	registre.menages_edit	Applies update interviews
/api/menages/survey-solutions/updates/sync	POST	registre.menages_edit	Manual update sync
/api/menages/survey-solutions/updates/questionnaires	GET	registre.menages_view	Update questionnaires
/api/menages/survey-solutions/updates/stats	GET	registre.menages_view	Update statistics

---

Synchronization

POST /api/menages/survey-solutions/sync

{ "questionnaireId": "<uuid du questionnaire dans le SIG>" }

Without questionnaireId, all active household questionnaires are synced.

{
  "success": true,
  "message": "Synchronisation terminée: 120 ménage(s) importé(s), 25 doublon(s), 5 erreur(s)",
  "resultats": {
    "succes": 120,
    "doublons": 25,
    "erreurs": 5,
    "questionnaires": [
      { "id": "…", "title": "Questionnaire ménage", "result": { "…": "détail par interview" } }
    ]
  }
}

Errors: 404 Questionnaire non trouvé, 400 Aucun questionnaire de type ménage configuré.

Targeted import

POST /api/menages/survey-solutions/import

{
  "questionnaireId": "<uuid du questionnaire dans le SIG>",
  "interviews": [{ "id": "…", "key": "12-34-56-78" }]
}

questionnaireId is required (400 ID du questionnaire requis) and the questionnaire must be of household type. Each interview's detail carries a success or duplicate status, or an error; a duplicate is not re-imported.

---

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

Import never replaces an existing household: an interview already imported is counted as a duplicate and skipped. Updating an existing household goes through the /api/menages/survey-solutions/updates/* routes.

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

Each interview in error appears in the result detail with its index and the error message; the other interviews of the batch are imported.

---

Configuration

Environment Variables

SUSO_API_URL=https://survey.example.org
SUSO_API_USER=<utilisateur API>
SUSO_API_PASSWORD=<voir gestionnaire de secrets>
SUSO_WORKSPACE=<workspace>

A project can have its own sync configuration (GET/PUT /api/projets/{id}/synchronisation); otherwise the global configuration applies.

Scheduling

php bin/console app:survey-solutions:sync

---

Permissions

Action	Permission
Synchronize	registre.collecte_sync
View status	registre.collecte_view

---

Best Practices

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