Note on implementation history: The original OpenFn implementation connecting Primero and proGres used UNHCR's DTP middleware. That DTP-based Gambella pilot has been inactive since July 2025. Its configuration is preserved on the
adaptors-version-upgradebranch at github.com/OpenFn/primero-progres.The current implementation uses UNHCR's PING middleware and is documented in this README. This document supersedes the DTP-era documentation while retaining the project context, programmatic requirements, and compliance information that remain applicable.
Contact support@openfn.org for assistance with either implementation.
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.
You can find an overview, expectations, prerequisites, and timelines for implementing interoperability at www.cpims.org/interoperability.
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.
| Requirement | Solution Overview |
|---|---|
| Primero will be a source of intervention cases and decisions and a destination for intervention cases and decisions coming from proGres v4. | OpenFn automates data extraction via the Primero v2 API to get and process outbound referrals that should be sent to proGres. Using OpenFn workflows, this automation is configured to run on a scheduled basis, extract data from Primero in JSON format, and transform it to align with PING system requirements and the agreed mapping specifications. |
| proGres v4 will be a source of intervention cases and decisions and a destination for intervention cases and decisions coming from Primero. | OpenFn polls the PING middleware APIs on a scheduled basis to retrieve new referrals and decisions from proGres. On retrieval, OpenFn workflows validate and transform the data and forward it to Primero. Decisions made in Primero are subsequently sent back to proGres via PING ingestion APIs. |
| Due to the highly sensitive nature of the data, it must be secured properly. There is a high need for authorization and authentication to control access to the data. | OpenFn out-of-box platform features are leveraged to ensure the highest level of security. Credentials are stored in OpenFn's credential management system and are never embedded in workflow code. See the Security and Compliance section for additional details. |
| System | Owner | Role in Integration |
|---|---|---|
| proGres v4 | UNHCR | Source protection and case management system |
| PING | UNHCR | Integration API layer exposing proGres data |
| OpenFn | OpenFn | Workflow orchestration and transformation |
| Primero v2 | 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 | Integration platform used to automate and orchestrate data exchange workflows |
Sensitive credentials are managed through OpenFn credential management and are not stored directly in workflow code.
The integration is implemented as four OpenFn workflows covering two bidirectional flows.
| Workflow | Direction | Purpose | Trigger |
|---|---|---|---|
| Workflow 1.1 | proGres → Primero | Send referrals from proGres to Primero | Scheduled Cron |
| Workflow 1.2 | Primero → proGres | Send referral decisions from Primero to proGres | Scheduled Cron |
| Workflow 2.1 | Primero → proGres | Send referrals from Primero to proGres | Scheduled Cron |
| Workflow 2.2 | proGres → Primero | Send referral decisions from proGres to Primero | Scheduled Cron |
Full documentation details can be found here.
Flow 1 (proGres → Primero Referral Sharing)
This flow automates the sending of referrals originating in proGres to Primero (Workflow 1.1) and the return of Primero's acceptance or rejection decisions back to proGres (Workflow 1.2).
Flow 2 (Primero → proGres Referral Sharing)
This flow automates the sending of referrals originating in Primero to proGres (Workflow 2.1) and the return of proGres's acceptance or rejection decisions back to Primero (Workflow 2.2).
If consent is revoked by a Primero user, please see Annex 1: Consent and Assent in Primero's CPIMS+ and proGres v4 Child Protection Modules for the applicable SOP.
Find both data flow diagrams 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.
This interoperability solution leverages the standardized Global Inter-Agency Case Management Task Force Interagency Forms in Primero but may be localized for each implementation to meet unique data sharing agreements and/or Primero system configurations.
The following details are shared between Primero and proGres:
- Consent of the child
- Basic identification (name(s), date of birth, sex, current address, telephone, languages spoken, UNHCR individual ID, UNHCR registration group number)
- Services (type of service, reason for referral, implementing agency, service requestor details, and referral status)
- Users (configured for receiving proGres referrals)
Important: These workflows transmit refugee PII across three systems — full name, date of birth, sex, UNHCR ID, phone, address, and protection concerns including SGBV indicators. Confirm that data processing agreements between UNHCR and UNICEF cover the specific fields in scope, and that OpenFn's role as a data processor is reflected in those agreements.
The exchange of only a defined set of service types (a.k.a. "intervention types") is supported between agencies. See the mapping specification for the current list. Primero and proGres users must be trained to NOT send other service types in interagency referral requests.
This solution can be re-implemented and localized with a relatively low level of effort for other Primero systems. To reuse it, implementers can clone the OpenFn project configuration and make the adjustments noted in the Configuration Considerations section. The key steps for re-implementation are outlined at github.com/OpenFn/unicef-unhcr-io.
Data element mapping specifications detail which fields will be exchanged between systems. Given each implementation's unique data sharing agreement and Primero localizations, these may change. For every Primero field in the mapping, the document notes: (1) the related Interagency Form, and (2) whether the mapping may be localized.
If changes are to be made to the mapping specification, they should (1) first be identified and documented by business owners in the mapping document, then (2) provided to technical implementers to make the corresponding OpenFn workflow changes. For change requests, duplicate the relevant tab to create a new version, and add highlighting to show changes for version control purposes.
Workflow 1.1
The PING endpoint SHP-2358 may return multiple rows per intervention due to joins on language and specific needs. The workflow deduplicates these before sending to Primero. If SHP-2358 changes its response structure, deduplication will produce incorrect results without erroring.
If more than one Primero case matches on unhcr_individual_no, only the first result is used with no warning.
Workflow 1.2
If a service's progres_interventionnumber doesn't follow the expected comma-delimited format (intervention number, LP intervention ID, business unit), the record is dropped with a log message and never retried. This will quietly discard any referral created before the composite format was introduced.
Workflow 2.1
Cases are filtered to those where at least one service has service_implementing_agency === 'UNHCR' — exact case match. A Primero instance configured with lowercase or mixed-case values will result in all referrals being silently excluded.
When a caseworker's Primero profile is incomplete, the workflow silently substitutes the CPIMS admin's contact details (name, email, and phone) in the referral sent to proGres. The receiving party in proGres has no indication that this substitution occurred.
If a Primero service_type value isn't found in the service map, the workflow sends the legal support GUID to proGres with no warning. A misconfigured or extended Primero lookup list will produce silent mismatch in proGres.
Workflow 2.2
The statusText() function defaults anything that isn't explicitly 125080002 to "accepted". If proGres introduces a new status code, it will be written to Primero as an acceptance.
General Assumptions
- UNICEF Primero updates on services will not be shared with UNHCR/proGres; only the original referral request and subsequent decisions are exchanged.
- If a UNICEF Primero user revokes consent for a case, a manual SOP will be followed for communicating that with UNHCR. The interoperability solution does not communicate this change automatically.
- Only the configured set of service/intervention types is supported. See the mapping specification linked above.
When implementing this interoperability solution for a new Primero/proGres instance, implementers and system administrators should consider the following:
-
PING Environment Identifiers: Every PING API call carries three identifiers —
ShippingProcessId,PartnerId, andInteropId— that are specific to this UNHCR-UNICEF deployment. Before deploying elsewhere, all of these must be replaced with values issued by PING for the new environment. The partner ID also appears directly in the ingestion endpoint URL (e.g./api/ingestion/v2/PNR-1363/data), so it must be updated there as well, not just in the request body. -
Service/Intervention Type GUIDs: Two mappings translate service types between Primero and proGres (one per flow direction). Both are hardcoded with proGres GUIDs that belong to this specific proGres installation. A different country's proGres instance will have different GUIDs, and incorrect values may be accepted silently. These must be verified against the target environment before go-live.
- To update mappings for the proGres → Primero direction, locate the intervention type map in Workflow 1.1. New services should follow the format:
'proGres intervention type description': 'Primero DB value'. - To update mappings for the Primero → proGres direction, locate the service map in Workflow 2.1. New services should follow the format:
'Primero DB value': 'proGres intervention GUID'. - Reminder: Make any mapping changes in the mapping specification document before updating the workflow configuration.
- To update mappings for the proGres → Primero direction, locate the intervention type map in Workflow 1.1. New services should follow the format:
-
Intervention Type Descriptions (Workflow 1.1): The workflow only accepts a fixed set of proGres intervention type descriptions. Anything outside that list throws an error. If the new deployment's proGres uses different terminology, this map must be updated or referrals will fail on arrival.
-
Language Lookup Keys: The language lookup keys (e.g.
language1,language2) are specific to this Primero instance's configuration. A different Primero deployment will almost certainly use different keys. Both the inbound and outbound language maps must be replaced. -
Required Fields in Primero: Are there any fields on the Primero case or related forms that are (1) instance-specific localizations and (2) required when a case is registered? If so, these must be included in the mapping specifications. The source value must either come from a corresponding field in proGres, or a default value must be provided; otherwise a required field will be submitted blank.
-
Focal Point User: Has the "focal point user" for receiving referrals from UNHCR been identified? Initially, one user (e.g.
progresv4_primero_intake) reviews all referrals from proGres and reassigns them to the appropriate case workers. As the programme expands, per-agency intake users (e.g.plan_international_intake,save_the_children_intake) can be configured. -
Implementing Agency Value: All services are configured to be exchanged with UNHCR. The Primero workflow filters on
service_implementing_agency === 'UNHCR'(exact case match). Ensure the Primero instance's lookup list value matches exactly, and that users select "UNHCR" andunhcr_cwwhen creating outbound referrals. -
Hardcoded Values Requiring Human Decisions Before Go-Live: The following values do not cause an immediate error if left unchanged but will behave incorrectly in production:
- The fallback CPIMS admin email in Workflow 2.1
- The two proGres organization GUIDs in Workflow 2.1 (
progres_businessunitandprogres_organizationfrom) - The
module_id(set toprimeromodule-cp) in Workflow 1.1
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
The OpenFn platform complies with the UNICEF CLASS I System Security Requirements. OpenFn is not a standalone system but rather a system carefully configured by UNICEF, OpenFn, or UNICEF's partners to comply with project-level security requirements and to connect with other systems in the UNICEF ecosystem (such as Primero). OFG implementation consultants must support partners to ensure the OpenFn implementation is in compliance with relevant security requirements and adhering to best practices.
Full Security and Go-Live Checklist: view here.
| Checklist Item | Comments | Timeline | Status |
|---|---|---|---|
| 1. Do not persist Primero data as Messages in OpenFn | OpenFn projects should be configured to not persist Primero information in the OpenFn project inbox. Primero case data should never sit at rest in OpenFn. OpenFn is the data processor; UNICEF is the data controller. | Before go-live and connection to production systems | ⏳ Pending — to be verified before go-live. |
| 2. Delete notification payloads after successful sync | OpenFn production projects will be configured to delete payloads received from PING after the data has been successfully synced with Primero, so that no data is stored on OpenFn servers at rest. | Before go-live and connection to production systems | ⏳ Pending — to be verified before go-live. |
| 3. Configure Github repository and connect with OpenFn project | GitHub provides version control and management of different development pipelines and change requests. | Before integration setup begins | ⏳ Pending — repository not yet configured for production. |
| 4. Seek partner sign-off on information logged in OpenFn Activity History | Do not log any personally identifiable information — only system IDs and date timestamps required for transaction auditing. | Before go-live and connection to production systems | ⏳ Pending — partner sign-off not yet obtained. |
| 5. Reset OpenFn credentials for production system and share with UNHCR | PING will authenticate to OpenFn using credentials that must be reset before go-live and shared securely with UNHCR administrators. | Before go-live and connection to production systems | ⏳ Pending — prototype credentials in use; production credentials not yet issued. |
| 6. Confirm appropriate access settings for the Github repository | GitHub repositories should never contain data, only integration workflow code. Consider making the repository private and granting read/write access only to relevant project administrators. | Before go-live and connection to production systems | ⏳ Pending — access controls not yet finalized. |
| 7. Confirm list of administrator users who need access to the OpenFn project | Only project admins who need access to OpenFn for ongoing integration monitoring should be granted access to the production project on OpenFn. | Before go-live and connection to production systems | ⏳ Pending — user list not yet confirmed. |
| 8. Confirm with UNICEF and UNHCR partners that OpenFn credential is granted API-only access | Ensure no overly broad or unnecessary permissions are granted to the OpenFn credentials used to access Primero or PING. | Before go-live and connection to production systems | ⏳ Pending — to be confirmed with partners before go-live. |
| 9. Train administrators on OpenFn platform administration, user management, and integration activity monitoring | Training is critical to total solution handover and ensuring security best practices are maintained during the project lifetime. | Before go-live and connection to production systems | ⏳ Pending — training not yet scheduled. |
Current PING-based solution documentation
- Workflow Documentation Folder
- Flow 1.1 Mapping Sheet
- Flow 1.2 Mapping Sheet
- Flow 2.1 Mapping Sheet
- Flow 2.2 Mapping Sheet
- Security and Go-Live Checklist
- Workflow 1.1 and 1.2 Test Plan
- Workflow 2.1 and 2.2 Test Plan
Gambella DTP-era solution documentation (archived)
- Github site with detailed documentation
- Ethiopia, Gambella Primero – ProGres IA Referral Exchange Mapping Specification (2021 Final Version)
- Archived Legacy Decision-Making IA Mapping Specification for Ethiopia, Gambella (2019–2021)
- Primero IO Training for Administrators
- Primero-Progres IO Flows and Testing Steps
Template interagency solution documentation (reusable/replicable)
- Github site with detailed documentation
- IA Data Element Mapping Specification template
- Programmatic prerequisites, expectations and timelines
| Name | Role | |
|---|---|---|
| Jessica Stuart-Clark | stuartcl@unhcr.org | Child Protection Officer |
| Name | Role | |
|---|---|---|
| Jan Panchalingam | jpanchalingam@unicef.org | Primero Lead |
Post on community.openfn.org or contact support@openfn.org for private queries.