Survey Solutions
Survey Solutions, the World Bank survey tool, feeds Bemba in three ways: household import, beneficiary updates and complaint import.
Access
There is no Survey Solutions menu. The screens open as follows:
| Screen | Path |
|---|---|
| Survey Solutions Configuration | Administration → Settings → Settings tab → API Integrations section → Open the Survey Solutions configuration |
| Survey Solutions page (overview) | Back button of the configuration screen |
| Household import | Data Collection → Data Collection → Households tab → Import, Survey Solutions source |
| Household update | Survey Solutions page → Household update |
| Complaint import | Complaints (GRM) → Survey Solutions - Complaints |
| Project account | Administration → Projects → Collection synchronisation ⟳ button |
Survey Solutions page
The page shows the connection status, the questionnaire counters and three actions:
| Action | Effect |
|---|---|
| Household import | Opens the collection import wizard |
| Household update | Updates existing beneficiaries (main, substitute) |
| Complaint import | Imports and categorises collected complaints |
It also lists the configured questionnaires, with their type, number of submissions and last synchronisation.
Configuration
Each project can collect with its own server and its own account. The configuration described here is the MIS global account, used by projects that have none of their own. To give a project its account, see Account per project.
Connection settings
| Field | Description |
|---|---|
| Server URL | Server address, for example https://your-instance.mysurvey.solutions |
| Workspace | Workspace; leave empty for the default one |
| API User | API account created in Survey Solutions |
| API Password | Password of that account |
Synchronisation settings
| Setting | Options | Description |
|---|---|---|
| Synchronization interval | 1, 3, 6, 12 or 24 hours | Frequency of scheduled synchronisation |
| Import only approved interviews | Yes / No | Limits synchronisation to interviews approved by headquarters |
Test and save
- Fill in the connection settings.
- Click Test Connection.
- If the test succeeds, click Save.
Managing questionnaires
Adding a questionnaire
- In the configuration, click Add Questionnaire.
- Select the questionnaire published on the server.
- Choose the Data Type:
| Type | Destination |
|---|---|
| Household | Social registry, through pre-collection |
| Update | Update of existing beneficiaries |
| Complaint | Grievance redress mechanism |
- For a Household questionnaire, set a Default region if needed. It is only used when the data is missing from the interview.
- Click Add.
Region, sector, surveyor and other fields are detected automatically in the questionnaire.
Removing a questionnaire from the list does not delete data already imported.
Household import
Survey Solutions households are imported with the wizard shared by all sources.
Menu: Data Collection → Data Collection → Households tab → Import
- Source: choose Survey Solutions, then the collection institution, the project and, if needed, the programme.
- Questionnaire: choose the questionnaire.
- Mapping: no manual mapping is needed for this source. The questionnaire is read according to its own structure:
- members come from the roster, and household size is their number;
- the head of household is the member whose relationship is "head";
- region, sector and locality are translated from the questionnaire codes, GPS from the coordinates question.
- Preview, then Start import.
Households arrive in pre-collection, linked to the chosen project and institution. They only enter the registry after validation. See Pre-collection.
Household update
Access: Survey Solutions page → Household update
This module updates already registered beneficiaries from an Update questionnaire.
| Category | Updated data |
|---|---|
| Beneficiary | Selection of main and substitute beneficiary, name |
| Contact and payment | MTN phone, Mobile Money account, contract signature |
| Documents | BI Antigo, BI CEDEAO, voter card, other documents |
| Location | GPS coordinates, update date |
- Choose a questionnaire, or keep All questionnaires.
- Click Start synchronization.
- Read the result: beneficiaries updated, not found, errors.
The update replaces existing values. A manual correction made in Bemba is overwritten by the questionnaire data.
Complaint import
Menu: Complaints (GRM) → Survey Solutions - Complaints
- Choose a Complaint questionnaire, or All questionnaires.
- Click Start synchronization. The result counts imported complaints, duplicates and errors.
- Under Complaints awaiting categorization, click Categorize.
- Choose the category, priority and type.
- Tick Send an acknowledgement of receipt by SMS if needed.
- Click Validate.
Interview statuses
| Survey Solutions status | Meaning |
|---|---|
| SupervisorAssigned | Assigned to the supervisor |
| Completed | Completed by the surveyor |
| RejectedBySupervisor | Rejected by the supervisor |
| ApprovedBySupervisor | Approved by the supervisor |
| RejectedByHeadquarters | Rejected by headquarters |
| ApprovedByHeadquarters | Approved by headquarters |
With the Import only approved interviews option, scheduled synchronisation only keeps interviews approved by headquarters.
Scheduled synchronisation
The server synchronises the questionnaires of each active configuration, each project's and the global one, at the chosen interval. An administrator can run synchronisation for a single project:
php bin/console app:survey-solutions:sync --projet=PROJECT_CODE
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
| Connection failed | Wrong URL | Check the server URL |
| Unauthorised | Wrong credentials | Check the API user and password |
| No questionnaire | Wrong workspace or questionnaire not published | Check the workspace and the API account rights |
| Beneficiaries "not found" during update | The household does not exist in Bemba | Import the household first |