IO Solution between Primero and OSCaR Systems
Automated information exchange between the Primero and OSCaR systems has been implemented on OpenFn to enable interoperability between MoSVY (Primero users) and NGO case workers (OSCaR users) in Cambodia. This OpenFn solution was implemented in partnership with UNICEF Cambodia.
(1) Interoperability Solution Overview
See this project background for an overview of the Primero & OSCaR interoperability project and requirements. See the user guides for step-by-step instructions for MoSVY and NGO case workers.
Three interoperability workflows have been implemented to facilitate a bi-directional sync between the Primero and OSCaR systems to share relevant case and referral data between systems. This is to support the following functional requirements.
Workflow 1: Sending case referrals to NGOs (Primero -> OSCaR)
- Sending MoSVY government referrals to NGO case workers
- Syncing referral decisions from Oscar to Primero: When NGO case workers accept/reject a referral the decision is sent to the MoSVY case worker.
See workflow 1 diagram source here.
Workflow 2: Sending case referrals to MoSVY (OSCaR –> Primero
- Sending NGO referrals to MoSVY case workers
- Syncing referral decisions from Primero to Oscar: When MoSVY case workers accept/reject a referral the decision is sent to the NGO case worker.
- Syncing all NGO cases to Primero for MoSVY case workers to view (to prevent duplicate work)
See workflow 2 diagram source here.
Videos (TODO: UPDATE WITH V2 Videos)
See this video playlist for the solution overview & demo of the interoperability workflows (V1 solution).
(2) Integration with System APIs
To automate the IO workflows, a bi-directional integration has been configured on the OpenFn platform to connect the Primero and OSCaR APIs.
*Note that these APIs are newly implemented and were developed at the start of this integration implementation.
OpenFn Adaptors (API wrappers) implemented:
(3) Interoperability Workflows
To achieve a bi-directional systems sync, multiple OpenFn jobs have been implemented to automate the different workflow steps.
Flow 0: Oscar ids –> Primero
- f0-j1-getOscarCases.js will fetch new Oscar cases to check for newly accepted OSCaR cases where an “oscar_number” has been assigned; we then want to sync this external ID back to Primero
- f0-j2-syncsIdsToPrimero.js will update Primero cases with Oscar External Ids
Flow 1: Primero cases –> OSCaR (Data flow diagram)
- f1-j1-getPrimeroCases.js will fetch Primero case updates & referrals
- f1-j2-casesToOscar.js will upload Primero data to OScaR
Flow 2: OSCaR cases –> Primero (Data flow diagram)
- f2-j1-getOscarCases.js will fetch OSCaR case updates & referrals
- f2-j2-upsertCasesToPrimero.js will upload OSCaR data to Primero
- f2-j3-updateReferralPending.js will set default ‘Pending’ service status for new referrals in Primero
(4) Automation Triggers
Trigger Type: Cron Timer
Every hour at
00 minutes (cron:
00 * * * *) OpenFn will run the workflows to sync case data between the Primero and OSCaR systems. The flows may also be executed on-demand at any time by a designated OpenFn admin user by clicking the “Run” button on a job in OpenFn.org.
Flow 0: OSCaR ids –> Primero
f0-j1-getOscarCases.js sends a GET request to OSCaR to list cases where:
- New cases have been created
GET /api/v1/organizations/clients?since_date='2020-07-01 01:00:00'
Flow 1: Primero cases –> OSCaR
f1-j1-getPrimeroCases.js sends a GET request to Primero to list cases where:
- New referrals have been created (indicated by Primero date field
- Case updates made since the last OpenFn request, indicated by Primero _date/time_field
transitions_changed_at. (Note: This happens if the case owner, case owner’s phone, case owner’s Agency, or the Service Implemented On fields are changed.)
The OpenFn Primero adaptor is being used for this request. See the adaptor docs for helper functions and sample requests.
Trigger Type: Flow
Flow 2 is triggered by Flow 1 success. Once
f1-j2-casesToOscar.js successfully runs,
f2-j1-getOscarCases.js is automatically triggered to run.
Flow 2: OSCaR cases –> Primero
f2-j1-getOscarCases.js sends a GET request to OSCaR to list cases where:
- New external referrals have been created (indicated by OSCaR field
- Case updates made since the last OpenFn request(indicated by OSCaR date/time field
GET /api/v1/organizations/clients?since_date='2020-07-01 01:00:00'&referred_external=true
(5) Data Sharing Protocols & Mappings
Data Sharing Agreements
See this folder for copies of the data sharing agreements between the MoSVY and Cambodia (OSCaR user) agencies.
See this mapping specification for the data element mappings implemented in the interoperability solution. This includes detailed integration mappings for Services and Primero Users/Case Owners.
Data Entry Protocols
In order for data to be successfully exchanged as expected, users should follow the data entry protocols defined in the training sessions. For an overview of the data entry steps in both the OSCaR and Primero systems (see the below videos). If these data entry steps are not followed and consent is not provided in the Primero system, then these cases may not be eligible for case sharing and referrals between systems. See the videos (above) for guidance.
(6) Solution Assumptions
1. Unique Identifiers
OpenFn will perform
upsert() (update if record exists, create if new) operations in both the Primero and OSCaR systems when syncing data. To ensure no duplicate cases are entered, OpenFn will use the below identifiers to check for existing cases. We assume that these identifiers are unique.
- OSCaR unique id:
oscar_numberin Primero system)
- Primero unique id:
external_idin OSCaR system)
2. Referral Services
- Service types are mapped between systems as defined in the Service Map. If any services change, this map and OpenFn jobs must be updated.
- For every 1 service created in the source system, 1 referral will be sent to the destination system
- When a service subtype is not selected in Primero, OpenFn will sync a default “not specified” service type to Oscar. Oscar requires the “service type” field so these services will always be rejected. See training slides for details.
- Oscar case decision is automatically reflected on the first referral form. See training slides for details.
3. Primero Case Owner Assignment
When cases are synced with Primero, they will be automatically assigned to a Province user case owner by OpenFn (see
owned_by field in mappings). The Province will be determined by the location code of the child provided by OSCaR. See Province User Map for the list of generic Primero Province users.
4. Organization/ Agency names
Agency IDs and Names are mapped between systems assuming specific naming conventions (see below). Any new organizations/agencies should be registered following the same naming conventions, otherwise the OpenFn jobs may need to be updated.
- Oscar Organization Name:
- Primero Agency ID:
(7) Change Management (Considerations for Admins)
System administrators are responsible for identifying if changes may impact the OpenFn integration.
- Make use of change management best practices.
- If login credentials are changed for either system, the relevant Credential must be updated in OpenFn.org.
- If system changes are made to any of the fields referenced in the field mappings, the OpenFn jobs should be reviewed and tested to confirm no impact on the integration.
- If the list of available Agencies or Services in either system changes, then the Administrator should review the mapping document to confirm no updates are required in the OpenFn Interoperability automation.
- If new Agencies/ Organizations are created in either system, OSCaR and Primero teams will coordinate to manually register the new agencies in each system (this is not an automated process). Primero administrators will need to (1) add the new agency to the list of
Implementing Agenciesand create a new generic agency user (e.g.,
agency-cif-user). Agency/Organization Ids should follow the below naming conventions, otherwise the OpenFn mappings may need to be updated:
- Oscar Organization Name:
- Primero Agency ID:
- Oscar Organization Name:
(8) 2022 Primero V2 Upgrade
This interoperability solution was originally implemented in 2020 to work with Primero V1. In 2022, it was updated by OpenFn team in partnership with UNICEF Cambodia and OSCaR/Children in Families core team, in order to ensure compatibility with the Primero V2 upgrade and new features available in this version.
New jobs were written for V2 and the changes listed below were added to the solution. The original V1 OpenFn jobs were deprecated with this upgrade.
- Syncing of 2nd referrals to enable caseworkers to send multiple referrals over time for 1 child
- Syncing referral decisions to “accept”/”reject” referrals and notify source systems
- New field mappings:
date of referral
- Primero Service
Referral Statusfield now has a default
Pendingvalue when creating services for outbound referrals
- Implemented change to not group Services in Primero by
service_typeand ensure 1 Primero Service record will exist for every new OSCaR service referred
See links to the updated documentation below:
Provisioning, Hosting, & Maintenance
This integration is hosted on OpenFn.org with Primero SaaS. OpenFn will provide ongoing maintenance support to the MoSVY administrators managing OpenFn and Primero.
Contact firstname.lastname@example.org with any questions or troubleshooting support.
MoSVY Primero system administrators will be the primary contacts responsible for ongoing integration monitoring and management:
email@example.com firstname.lastname@example.org email@example.com
Other Support Contacts