The United Nations High Commissioner for Refugees (UNHCR) and the United Nations Children’s Fund (UNICEF) operate protection and case management systems used to support refugees, displaced populations, and vulnerable children.
proGres is UNHCR’s core case management and registration platform used to manage refugee records, interventions, and protection activities.
Primero is UNICEF’s case management platform used by protection actors to manage cases, referrals, and services for children and families.
To support coordinated protection programming, referrals and referral decisions must move reliably between systems.
This integration uses two intermediary layers:
- PING middleware – exposes controlled APIs for interacting with proGres data
- OpenFn – orchestrates integrations, performs transformations, and executes system-to-system communication
Through this architecture, referral information and referral decisions are automatically synchronized between proGres and Primero, reducing manual data entry and improving coordination between agencies.
The objective of this integration is to enable interoperability between UNHCR and UNICEF protection systems through automated referral data exchange.
Key goals:
- Enable automated referral creation between systems
- Synchronize referral decisions between organizations
- Reduce manual workflows and duplicate data entry
- Support coordinated case management across agencies
- Maintain traceable and auditable data exchange
The integration relies on PING middleware APIs for controlled data exchange and OpenFn workflows for orchestration and transformation.
| System | Owner | Role in Integration |
|---|---|---|
| proGres | UNHCR | Source protection system |
| PING | UNHCR | Integration API layer exposing proGres |
| OpenFn | OpenFn | Workflow orchestration and transformation |
| Primero | UNICEF | Case management platform |
| System | Credential Type | Description |
|---|---|---|
| PING | API credentials / Bearer Token | Used by OpenFn to retrieve and update proGres data |
| Primero | API token | Used to create and update case and referral records |
| OpenFn | Platform credentials | Workflow execution environment |
Sensitive credentials are managed through OpenFn credential management and are not stored directly in workflow code.
The integration is implemented using four OpenFn workflows.
| Workflow | Purpose | Trigger |
|---|---|---|
| Workflow 1.1 | Send referrals from proGres to Primero | Scheduled |
| Workflow 1.2 | Send referral decisions from Primero to proGres | Scheduled |
| Workflow 2.1 | Send referrals from Primero to proGres | Scheduled |
| Workflow 2.2 | Send referral decisions from proGres to Primero | Scheduled |
Full documentation details can be found here
Purpose
Retrieves referral interventions from proGres through PING and creates or updates the corresponding cases and services in Primero. The full specification is described here.
Trigger
Scheduled workflow execution.
Workflow Steps
- Retrieve referral interventions from PING using the retrieval API.
- Retrieve detailed intervention and individual information.
- Aggregate related data such as languages and specific needs.
- Transform proGres data into the Primero case and service format.
- Search for an existing Primero case using the UNHCR individual identifier.
- Create a new case or update the existing case in Primero.
- Update the intervention transfer status in proGres through PING.
Workflow Diagram
Field Mapping
Logging and Error Handling
- API responses from PING and Primero are logged
- Validation failures stop processing for the affected records
- Failed records remain eligible for retry on the next run
- Transaction identifiers and record IDs are logged for traceability
Purpose
Sends referral decisions recorded in Primero back to proGres through the PING ingestion API. The full specification is described here.
Trigger
Scheduled workflow execution.
Workflow Steps
- Retrieve updated cases from Primero using a timestamp cursor.
- Filter referrals assigned to UNHCR.
- Extract referral decision status and intervention identifiers.
- Transform decision information into the proGres intervention decision format.
- Send the decision payload to the PING ingestion API.
- Confirm ingestion status using the returned transaction identifier.
Workflow Diagram
Field Mapping
Logging and Error Handling
- Invalid or incomplete referrals are skipped
- API errors returned from PING are captured in workflow logs
- Transaction identifiers are logged for debugging and reconciliation
Purpose
Retrieves referrals created in Primero and sends them to proGres through PING. The full specification is described here.
Trigger
Scheduled workflow execution.
Workflow Steps
- Retrieve recently updated cases from Primero.
- Filter cases where referrals are assigned to UNHCR.
- Retrieve referral records associated with those cases.
- Retrieve Primero user details for referral contact information.
- Transform referral data into the proGres intervention structure.
- Send the referral payload to the PING ingestion API.
- Query the ingestion status endpoint to confirm processing.
Workflow Diagram
Field Mapping
Logging and Error Handling
- Invalid records are skipped
- PING ingestion API responses are logged
- Ingestion status responses are recorded for monitoring
Purpose
Retrieves referral decisions recorded in proGres and updates the corresponding referrals in Primero. The full specification is described here.
Trigger
Scheduled workflow execution.
Workflow Steps
- Retrieve referral decision records from PING.
- Filter decision records based on status values.
- Retrieve detailed decision information for each referral.
- Locate the corresponding referral within Primero.
- Update the referral decision status in Primero.
- Mark the record as synchronized in proGres.
Workflow Diagram
Field Mapping
Logging and Error Handling
- Records without a matching Primero referral are skipped
- Failed updates remain eligible for retry
- API responses and synchronization results are logged
Operational monitoring focuses on workflow execution and successful data synchronization.
Key monitoring points:
- OpenFn workflow run logs
- API responses from PING and Primero
- Transaction IDs returned by ingestion APIs
- Verification that records are created or updated in the destination system
| Name | Role | |
|---|---|---|
| TODO | TODO | TODO |
| Name | Role | |
|---|---|---|
| TODO | TODO | TODO |