cambodia-IO

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)

See workflow 1 diagram source here.

Workflow 2: Sending case referrals to MoSVY (OSCaR –> Primero

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.

APIs* implemented:

*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

  1. 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
  2. f0-j2-syncsIdsToPrimero.js will update Primero cases with Oscar External Ids

Flow 1: Primero cases –> OSCaR (Data flow diagram)

  1. f1-j1-getPrimeroCases.js will fetch Primero case updates & referrals
  2. f1-j2-casesToOscar.js will upload Primero data to OScaR

Flow 2: OSCaR cases –> Primero (Data flow diagram)

  1. f2-j1-getOscarCases.js will fetch OSCaR case updates & referrals
  2. f2-j2-upsertCasesToPrimero.js will upload OSCaR data to Primero
  3. 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. Run Job

Flow 0: OSCaR ids –> Primero

f0-j1-getOscarCases.js sends a GET request to OSCaR to list cases where:

  1. New cases have been created

Example Request:

 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:

  1. New referrals have been created (indicated by Primero date field transitions_created_at).
  2. 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:

  1. New external referrals have been created (indicated by OSCaR field referred_external).
  2. Case updates made since the last OpenFn request(indicated by OSCaR date/time field since_date).

Example Request:

 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.

2. Referral Services

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: '{organization_name}' (e.g., cif) - Primero Agency ID: 'agency-{organization_name}' (e.g., agency-cif)

(7) Change Management (Considerations for Admins)

System administrators are responsible for identifying if changes may impact the OpenFn integration.

  1. Make use of change management best practices.
  2. If login credentials are changed for either system, the relevant Credential must be updated in OpenFn.org.
  3. 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.
  4. 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.
  5. 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 Agencies and 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: '{organization_name}' (e.g., cif)
    • Primero Agency ID: 'agency-{organization_name}' (e.g., agency-cif)

(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.

See links to the updated documentation below:

(9) Administration

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.

Support

Contact support@openfn.org with any questions or troubleshooting support.

MoSVY Primero system administrators will be the primary contacts responsible for ongoing integration monitoring and management:
sovansideth@gmail.com nheldarath8@gmail.com sideth@childreninfamilies.org

Other Support Contacts

UNICEF:
pkhauv@unicef.org
mkeng@unicef.org

OSCaR:
sokly@childreninfamilies.org
meas.kiry@childreninfamilies.org

Training Materials

V2 Training Materials

V1 Training Materials