This repository holds the automated data workflows, built on OpenFn, that [PLACEHOLDER: what the integration achieves, e.g. "move community health data from CommCare into the national DHIS2 system"].
[PLACEHOLDER: Describe the source system(s) and what is recorded there, the destination system(s), and the problem this solves, for example removing manual re-entry or making data available for national reporting. Say whether data moves one way or both ways, and how often.]
This work is delivered [PLACEHOLDER: under the X initiative / for the Ministry of Health of Y], with Open Function (OpenFn) as the [PLACEHOLDER: interoperability implementer / technical partner]. [PLACEHOLDER: Standards followed, e.g. OpenHIE, HL7 FHIR R4.] Code is released under [PLACEHOLDER: licence, e.g. Apache 2.0].
Always work on a branch. If GitHub sync is enabled, every commit to
mainis deployed to the OpenFn project automatically.
- Who should read this
- Programme context and scope
- System overview
- The workflows
- How the workflows work
- Systems and connections
- Data mappings
- Administration
- Troubleshooting
- For developers
- Training materials
- Reference documents
- Team contacts
- Support and resources
- Programme and [PLACEHOLDER: health / operations] staff who want to understand what each workflow does and when it runs: read the system overview and the workflows, then Part 1 of each workflow's README (overview, diagram, schedule, and how to run).
- Developers and integrators who maintain or adapt the workflows: also read how the workflows work and for developers, then Part 2 of each workflow's README (steps, mapping, configuration, error handling, and troubleshooting).
[PLACEHOLDER: The goal in one or two sentences.]
| Integration | Moves data from → to | Workflows |
|---|---|---|
| [PLACEHOLDER: e.g. Aggregate reporting] | [PLACEHOLDER: Source → Destination] | [PLACEHOLDER: WF1] |
| [PLACEHOLDER] | [PLACEHOLDER] | [PLACEHOLDER] |
Out of scope: [PLACEHOLDER: e.g. districts already entering data directly in DHIS2; individual-level data; historical backfill before YYYY.]
OpenFn sits in the middle. It reads from [PLACEHOLDER: source systems] and writes to [PLACEHOLDER: destination systems], holding the credentials for both sides so the systems never connect to each other directly.
Figure: solution architecture. [PLACEHOLDER: one-line caption describing what the diagram shows.] [Source in Lucidchart]([PLACEHOLDER: Lucidchart link])
Source systems
- [PLACEHOLDER: System name]: [PLACEHOLDER: what it is and what data lives there].
Destination systems
- [PLACEHOLDER: System name] (
[PLACEHOLDER: host, version]): [PLACEHOLDER: what it receives, and from which workflow].
| Workflow | What it does | Trigger | Status | Details |
|---|---|---|---|---|
| WF1 | [PLACEHOLDER: one-line description in plain language] | [PLACEHOLDER: every 6 hours, 00:00, 06:00, 12:00, 18:00 UTC] | [PLACEHOLDER: Live / In testing / Blocked] | README |
| WF2 | [PLACEHOLDER] | [PLACEHOLDER: on demand (webhook)] | [PLACEHOLDER] | README |
[PLACEHOLDER: How the workflows relate to each other, if at all.]
Cron triggers run in UTC unless a different timezone is set on the trigger. [PLACEHOLDER: Add the local offset, e.g. 00:00 UTC is 03:00 EAT (UTC+3).] Any workflow can also be started by hand from the OpenFn app with the Run button.
These patterns are shared across the workflows. Each workflow's README describes its own variations.
[PLACEHOLDER: e.g. Each workflow stores a cursor (last run timestamp) and only asks the source for records updated since then. Say where the cursor lives: state, a Collection, or a sheet.]
[PLACEHOLDER: e.g. Destination IDs are calculated from the source record ID, so re-running the same record updates it in place.]
[PLACEHOLDER: e.g. Failed records are logged to a Google Sheet and a summary email goes to the admin list.]
If a run finds no new records, it stops quietly rather than reporting an error. This is normal during quiet periods.
| System | Role | Environment / address | OpenFn adaptor |
|---|---|---|---|
| [PLACEHOLDER: e.g. DHIS2] | [PLACEHOLDER: Destination (WF1, WF2)] | [PLACEHOLDER: https://...] |
dhis2 |
| (transforms) | Data shaping | n/a | common |
Credentials are not kept in this repository. They live in the OpenFn app under Project Settings → Credentials.
Each workflow's README has a Mapping section with a link to its full mapping spec. [PLACEHOLDER: link to the project mapping workbook, if there is one.]
- Implementer: [PLACEHOLDER: e.g. Open Function (OpenFn)]
- Deployment: [PLACEHOLDER: OpenFn-hosted (app.openfn.org) or self-hosted; include the instance URL]
- OpenFn project: [[PLACEHOLDER: project ID]](https://app.openfn.org/projects/[PLACEHOLDER: project-id]/w)
- Code repository: [github.com/OpenFn/[PLACEHOLDER: repo]](https://github.com/OpenFn/[PLACEHOLDER: repo])
- Maintenance: [PLACEHOLDER: who is responsible for maintenance, security updates, and monitoring, and for what period; note any handover date and receiving team]
- Data standards: [PLACEHOLDER: e.g. HL7 FHIR R4, OpenHIE patterns]
- Security: [PLACEHOLDER: e.g. HTTPS everywhere, OAuth2 where supported, role-based access, personal data handling under local policy]
- Monitoring: every run and its logs are visible in the OpenFn app under History. [PLACEHOLDER: add email summaries or log sheets, if used.]
The workflows depend on a few things staying true. If any of these change, a workflow may need updating:
- [PLACEHOLDER: e.g. DHIS2 keeps the programs, data elements, and codes the workflows expect.]
- [PLACEHOLDER: e.g. Each facility maps to a matching org unit.]
- Credentials: update them in the OpenFn app under Project Settings → Credentials.
- Mappings or codes: [PLACEHOLDER: where to edit, e.g. update the mapping workbook, then re-run the mappings workflow].
- Version control: work on a branch, open a pull request, then merge to
main. If GitHub sync is on, merging tomaindeploys to OpenFn automatically.
Common issues are below. Problems specific to one workflow are in that workflow's README.
| Symptom | Likely cause | What to check |
|---|---|---|
| Sign-in or authorization errors | A credential expired or is wrong | Update it in Project Settings → Credentials |
| Timeouts | The destination system is slow or unreachable | Confirm the system is up and reachable |
| A run does nothing | No new records since the last run | Normal during quiet periods; confirm in the run log |
| Records rejected by the destination | Invalid metadata (IDs, periods, codes) | Compare the payload against destination metadata |
| [PLACEHOLDER] | [PLACEHOLDER] | [PLACEHOLDER] |
- Clone the repository:
git clone https://github.com/OpenFn/[PLACEHOLDER: repo].git - Install the OpenFn CLI:
npm install -g @openfn/cli - Create a local
tmp/folder with astate.jsonfile for test input.tmp/is git-ignored; never commit real data.
├── workflows/ # OpenFn project code, managed by the CLI and GitHub sync
│ └── [workflow-name]/
│ ├── workflow.json
│ └── *.js # one file per step
├── docs/ # project documentation (safe from CLI pulls)
│ ├── images/ # project-wide images, e.g. solution architecture
│ └── workflows/
│ └── wf1-[name]/ # one folder per workflow, named after its workflows/ folder
│ ├── README.md
│ └── *.png # this workflow's BPMN and other images
├── sample-data/ # example payloads for local testing
├── writing-jobs.md # guide to writing OpenFn job code
└── claude.md # instructions for AI-assisted job writing
Keep documentation in docs/, not workflows/. A project pull from OpenFn can overwrite the workflows/ folder.
Run a single job:
openfn path/to/job.js -a @openfn/language-[adaptor] -s tmp/state.jsonRun a whole workflow:
openfn workflows/[workflow-name]/workflow.json[PLACEHOLDER: Any project-specific scripts, tests, or known local CLI issues.]
- writing-jobs.md: how to write job code
- OpenFn CLI docs: writing, running, and testing workflows locally
- Platform docs: running and testing workflows in the app
- Adaptor docs: functions available for each system
[PLACEHOLDER: Link to training recordings, slides, and exercises, and say who was trained.]
| Document | Covers |
|---|---|
| [PLACEHOLDER: Solution design] | Project-wide |
| [PLACEHOLDER: Mapping workbook] | [PLACEHOLDER: WF1, WF2] |
| Implementation checklist | Project-wide |
This is the only contacts list for the project; the workflow READMEs link back here. Please do not commit personal emails. Use role-based aliases or link to a project directory.
| Role | Name / team | Contact |
|---|---|---|
| Project lead | [PLACEHOLDER] | [PLACEHOLDER] |
| Integration lead | [PLACEHOLDER] | [PLACEHOLDER] |
| [PLACEHOLDER: System] focal point | [PLACEHOLDER] | [PLACEHOLDER] |
| System owner ([PLACEHOLDER: organisation]) | [PLACEHOLDER] | via project lead |
Open an issue in this repository using the bug report, change request, or feature request template, or email support@openfn.org. Include:
- A screenshot of the issue or the relevant area
- A link to the relevant workflow or run in OpenFn
- Expected behaviour
- Actual behaviour
- Error details (logs or screenshot)
- Urgency
- OpenFn documentation
- [PLACEHOLDER: Programme / initiative site]
- [PLACEHOLDER: Destination system API docs]
Last updated: [PLACEHOLDER: Month YYYY]
