Skip to content

Commit 7324841

Browse files
redietrredietr
authored
Update README document
1 parent 59b65ef commit 7324841

1 file changed

Lines changed: 220 additions & 29 deletions

File tree

‎README.md‎

Lines changed: 220 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,238 @@
1-
# project-name
1+
# Integration: UNHCR proGres ↔ UNICEF Primero (via PING Middleware)
22

3-
Please update this readme when you start a new project.
4-
Summarize the solutions implemented or leverage Github pages to build a documentation site.
3+
## 1. Introduction
54

6-
*Note that commits to `main` will be auto-deployed to OpenFn app if the Github Sync is enabled. Always work on a branch!*
5+
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.
76

8-
## Getting started with the Repo
7+
**proGres** is UNHCR’s core case management and registration platform used to manage refugee records, interventions, and protection activities.
98

10-
1. create `/tmp` folder locally with a `state.json` file that you don't commit to github
11-
2. start writing and testing jobs locally with the relevant adaptor
9+
**Primero** is UNICEF’s case management platform used by protection actors to manage cases, referrals, and services for children and families.
1210

11+
To support coordinated protection programming, referrals and referral decisions must move reliably between systems.
1312

14-
## Getting Help
13+
This integration uses two intermediary layers:
1514

16-
To learn more about writing job code, see [writing-jobs.md](./writing-jobs.md)
15+
* **PING middleware** – exposes controlled APIs for interacting with proGres data
16+
* **OpenFn** – orchestrates integrations, performs transformations, and executes system-to-system communication
1717

18-
See the [OpenFn CLI docs](https://docs.openfn.org/documentation/cli-walkthrough#7-running-workflows) for more on writing, running, and testing workflows locally.
18+
Through this architecture, referral information and referral decisions are automatically synchronized between **proGres** and **Primero**, reducing manual data entry and improving coordination between agencies.
1919

20-
See the [Platform Docs](https://docs.openfn.org/documentation/build/steps/step-editor) for how to run and test workflows on the app.
20+
## 2. Project Objective
2121

22+
The objective of this integration is to enable interoperability between UNHCR and UNICEF protection systems through automated referral data exchange.
2223

23-
## Project Documentation
24+
Key goals:
2425

25-
The OpenFn team will often leverage [Github Pages](https://pages.github.com/) to configure a documentation site to organize and display project-specific information.
26-
This site can display the content on this README, or be pointed to another markdown `.md` file created on this repo specifically for docs.
26+
* Enable automated **referral creation** between systems
27+
* Synchronize **referral decisions** between organizations
28+
* Reduce manual workflows and duplicate data entry
29+
* Support coordinated case management across agencies
30+
* Maintain traceable and auditable data exchange
2731

28-
See this example Github pages site that displays this README as a simple site: [https://openfn.github.io/project/](https://openfn.github.io/project/)
32+
The integration relies on **PING middleware APIs** for controlled data exchange and **OpenFn workflows** for orchestration and transformation.
2933

30-
Github Page configuration can be adjusted in the `Settings` of this repository.
31-
<img width="1157" alt="Screenshot 2024-05-07 at 2 45 23 PM" src="https://github.com/OpenFn/project/assets/16758106/aa56f904-06b8-46a9-9ea1-18f973c8b527">
34+
## 3. Systems Involved
3235

36+
| System | Owner | Role in Integration |
37+
| ------- | ---------- | ----------------------------------------- |
38+
| proGres | UNHCR | Source protection system |
39+
| PING | UNHCR | Integration API layer exposing proGres |
40+
| OpenFn | OpenFn | Workflow orchestration and transformation |
41+
| Primero | UNICEF | Case management platform |
3342

34-
## Implementation Checklist
35-
[See OpenFn Docs site](https://docs.openfn.org/documentation/get-started/implementation-checklist) or [this workbook](https://docs.google.com/spreadsheets/d/1_XY0nx0OLNUsogrIHnRaSTyZ-KdcSXks-tqwm3ZfMc4/edit#gid=72612093) for a template work plan for the OpenFn implementation, or contact `support@openfn.org` to get the Asana-version of this checklist.
43+
## 4. Credentials and Access
3644

37-
## Administration
38-
_It's good practice to document on the read me who is responsible for managing & maintaining the OpenFn project._
39-
### Provisioning, Hosting, & Maintenance
40-
_Document details specific to your OpenFn deployment_
41-
- Deployment: SaaS or Local?
42-
- Platform Version: OpenFn V1 or V2
43-
- Maintenance: Specify the team responsible for software maintenance, security updates, etc. - confirm roles & responsibilities across systems
45+
| System | Credential Type | Description |
46+
| ------- | ------------------------------ | --------------------------------------------------- |
47+
| PING | API credentials / Bearer Token | Used by OpenFn to retrieve and update proGres data |
48+
| Primero | API token | Used to create and update case and referral records |
49+
| OpenFn | Platform credentials | Workflow execution environment |
4450

45-
### Support
46-
_List relevant support point of contacts and system administrators._
47-
- {Contact1 name, email}
51+
Sensitive credentials are managed through OpenFn credential management and are not stored directly in workflow code.
52+
53+
## 5. Workflow Overview
54+
55+
The integration is implemented using four OpenFn workflows.
56+
57+
| Workflow | Purpose | Trigger |
58+
| ------------ | ----------------------------------------------- | --------- |
59+
| Workflow 1.1 | Send referrals from proGres to Primero | Scheduled |
60+
| Workflow 1.2 | Send referral decisions from Primero to proGres | Scheduled |
61+
| Workflow 2.1 | Send referrals from Primero to proGres | Scheduled |
62+
| Workflow 2.2 | Send referral decisions from proGres to Primero | Scheduled |
63+
64+
# 6. Workflow Details
65+
66+
## Workflow 1.1 – Send Referrals to Primero
67+
68+
[OpenFn Workflow Link](https://app.openfn.org/projects/1813e824-91aa-4a3b-a49c-afa8b33af333/w/5d2383d8-5f58-451e-aec9-5709e403eea7)
69+
70+
**Purpose**
71+
72+
Retrieves referral interventions from proGres through PING and creates or updates the corresponding cases and services in Primero.
73+
74+
**Trigger**
75+
76+
Scheduled workflow execution.
77+
78+
**Workflow Steps**
79+
80+
1. Retrieve referral interventions from PING using the retrieval API.
81+
2. Retrieve detailed intervention and individual information.
82+
3. Aggregate related data such as languages and specific needs.
83+
4. Transform proGres data into the Primero case and service format.
84+
5. Search for an existing Primero case using the UNHCR individual identifier.
85+
6. Create a new case or update the existing case in Primero.
86+
7. Update the intervention transfer status in proGres through PING.
87+
88+
**Workflow Diagram**
89+
90+
<img width="1184" height="465" alt="image" src="https://github.com/user-attachments/assets/917a3966-c9fe-48fe-ae25-2c1d949e0ccb" />
91+
92+
**Field Mapping**
93+
94+
[Flow 1.1 Mapping Sheet Link](https://docs.google.com/spreadsheets/d/1YBe7QeUT1JKYicv5d88MBiY1YwIPusRG-pw112xe_Yw/edit?usp=sharing)
95+
96+
**Logging and Error Handling**
97+
98+
* API responses from PING and Primero are logged
99+
* Validation failures stop processing for the affected records
100+
* Failed records remain eligible for retry on the next run
101+
* Transaction identifiers and record IDs are logged for traceability
102+
103+
## Workflow 1.2 – Send Decision to PING
104+
105+
[OpenFn Workflow Link](https://app.openfn.org/projects/1813e824-91aa-4a3b-a49c-afa8b33af333/w/32d49f20-82a0-464f-b05e-fbabd22ce202)
106+
107+
**Purpose**
108+
109+
Sends referral decisions recorded in Primero back to proGres through the PING ingestion API.
110+
111+
**Trigger**
112+
113+
Scheduled workflow execution.
114+
115+
**Workflow Steps**
116+
117+
1. Retrieve updated cases from Primero using a timestamp cursor.
118+
2. Filter referrals assigned to UNHCR.
119+
3. Extract referral decision status and intervention identifiers.
120+
4. Transform decision information into the proGres intervention decision format.
121+
5. Send the decision payload to the PING ingestion API.
122+
6. Confirm ingestion status using the returned transaction identifier.
123+
124+
**Workflow Diagram**
125+
126+
<img width="889" height="553" alt="image" src="https://github.com/user-attachments/assets/84ed293b-1ac6-4813-b12a-c7a0a69ef1e7" />
127+
128+
**Field Mapping**
129+
130+
[Flow 1.2 Mapping Doc Link](https://docs.google.com/spreadsheets/d/1YBe7QeUT1JKYicv5d88MBiY1YwIPusRG-pw112xe_Yw/edit?gid=1598250610#gid=1598250610)
131+
132+
**Logging and Error Handling**
133+
134+
* Invalid or incomplete referrals are skipped
135+
* API errors returned from PING are captured in workflow logs
136+
* Transaction identifiers are logged for debugging and reconciliation
137+
138+
## Workflow 2.1 – Get Referrals from Primero
139+
140+
[OpenFn Workflow Link](https://app.openfn.org/projects/1813e824-91aa-4a3b-a49c-afa8b33af333/w/360b3fea-569a-401b-b7d4-3a68ad6f575a)
141+
142+
**Purpose**
143+
144+
Retrieves referrals created in Primero and sends them to proGres through PING.
145+
146+
**Trigger**
147+
148+
Scheduled workflow execution.
149+
150+
**Workflow Steps**
151+
152+
1. Retrieve recently updated cases from Primero.
153+
2. Filter cases where referrals are assigned to UNHCR.
154+
3. Retrieve referral records associated with those cases.
155+
4. Retrieve Primero user details for referral contact information.
156+
5. Transform referral data into the proGres intervention structure.
157+
6. Send the referral payload to the PING ingestion API.
158+
7. Query the ingestion status endpoint to confirm processing.
159+
160+
**Workflow Diagram**
161+
162+
<img width="1128" height="514" alt="image" src="https://github.com/user-attachments/assets/57f36fb8-420e-4bc9-97fc-a4e39d0654c5" />
163+
164+
**Field Mapping**
165+
166+
[Flow 2.1 Mapping Sheet Link](https://docs.google.com/spreadsheets/d/1YBe7QeUT1JKYicv5d88MBiY1YwIPusRG-pw112xe_Yw/edit?gid=1904546815#gid=1904546815)
167+
168+
**Logging and Error Handling**
169+
170+
* Invalid records are skipped
171+
* PING ingestion API responses are logged
172+
* Ingestion status responses are recorded for monitoring
173+
174+
## Workflow 2.2 – Update Referral Decision in Primero
175+
176+
[OpenFn Workflow Link](https://app.openfn.org/projects/1813e824-91aa-4a3b-a49c-afa8b33af333/w/6a3a0cce-79bb-4a25-8fb2-40a9ff505818)
177+
178+
**Purpose**
179+
180+
Retrieves referral decisions recorded in proGres and updates the corresponding referrals in Primero.
181+
182+
**Trigger**
183+
184+
Scheduled workflow execution.
185+
186+
**Workflow Steps**
187+
188+
1. Retrieve referral decision records from PING.
189+
2. Filter decision records based on status values.
190+
3. Retrieve detailed decision information for each referral.
191+
4. Locate the corresponding referral within Primero.
192+
5. Update the referral decision status in Primero.
193+
6. Mark the record as synchronized in proGres.
194+
195+
**Workflow Diagram**
196+
197+
<img width="1203" height="414" alt="image" src="https://github.com/user-attachments/assets/28e6543f-ed17-46dc-a96e-22954d31679e" />
198+
199+
200+
**Field Mapping**
201+
202+
[Flow 2.2 Mapping Sheet Link](https://docs.google.com/spreadsheets/d/1YBe7QeUT1JKYicv5d88MBiY1YwIPusRG-pw112xe_Yw/edit?gid=1480651081#gid=1480651081)
203+
204+
**Logging and Error Handling**
205+
206+
* Records without a matching Primero referral are skipped
207+
* Failed updates remain eligible for retry
208+
* API responses and synchronization results are logged
209+
210+
## 7. UAT Test Cases
211+
212+
1. [Workflow 1.1 and 1.2 Test Plan](https://drive.google.com/file/d/1Hssrq2y3OuveXfS9NqiSt40qloZimSWu/view?usp=drive_link)
213+
2. [Workflow 2.1 and 2.2 Test Plan](https://docs.google.com/document/d/1QCdiXYZaFmrYUGYl9enw6F2L6GVtNKwLeBkc-f5vQOU/edit?usp=drive_link)
214+
215+
## 8. Monitoring and Maintenance
216+
217+
Operational monitoring focuses on workflow execution and successful data synchronization.
218+
219+
Key monitoring points:
220+
221+
* OpenFn workflow run logs
222+
* API responses from PING and Primero
223+
* Transaction IDs returned by ingestion APIs
224+
* Verification that records are created or updated in the destination system
225+
226+
## 9. Contacts
227+
228+
### UNHCR Team
229+
230+
| Name | Email | Role |
231+
| ---- | ----- | ---- |
232+
| TODO | TODO | TODO |
233+
234+
### UNICEF Team
235+
236+
| Name | Email | Role |
237+
| ---- | ----- | ---- |
238+
| TODO | TODO | TODO |

0 commit comments

Comments
 (0)