Skip to content
Public template

About

Template repo for backing up OpenFn projects & workflow config. See the README and the OpenFn Docs site for more.

Resources

Stars

1 star

Watchers

6 watching

Forks

Latest commit

 

History

74 Commits

Folders and files

Repository files navigation

[PLACEHOLDER: Project name]

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 main is deployed to the OpenFn project automatically.


Table of contents


Who should read this

  • 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).

Programme context and scope

[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.]


System overview

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.

Solution architecture

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

The workflows

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.


How the workflows work

These patterns are shared across the workflows. Each workflow's README describes its own variations.

Picking up only what changed

[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.]

Not creating duplicates

[PLACEHOLDER: e.g. Destination IDs are calculated from the source record ID, so re-running the same record updates it in place.]

Handling errors and notifications

[PLACEHOLDER: e.g. Failed records are logged to a Google Sheet and a summary email goes to the admin list.]

Ending cleanly when there is nothing to do

If a run finds no new records, it stops quietly rather than reporting an error. This is normal during quiet periods.


Systems and connections

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.


Data mappings

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


Administration

Where it lives

  • 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]

Standards and security

  • 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.]

Keeping it working

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

Making changes

  • 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 to main deploys to OpenFn automatically.

Troubleshooting

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]

For developers

  1. Clone the repository: git clone https://github.com/OpenFn/[PLACEHOLDER: repo].git
  2. Install the OpenFn CLI: npm install -g @openfn/cli
  3. Create a local tmp/ folder with a state.json file for test input. tmp/ is git-ignored; never commit real data.

Repository layout

├── 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.

Running locally

Run a single job:

openfn path/to/job.js -a @openfn/language-[adaptor] -s tmp/state.json

Run a whole workflow:

openfn workflows/[workflow-name]/workflow.json

[PLACEHOLDER: Any project-specific scripts, tests, or known local CLI issues.]

Learn more


Training materials

[PLACEHOLDER: Link to training recordings, slides, and exercises, and say who was trained.]


Reference documents

Document Covers
[PLACEHOLDER: Solution design] Project-wide
[PLACEHOLDER: Mapping workbook] [PLACEHOLDER: WF1, WF2]
Implementation checklist Project-wide

Team contacts

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

Support and resources

Submitting support or feature requests

Open an issue in this repository using the bug report, change request, or feature request template, or email support@openfn.org. Include:

  1. A screenshot of the issue or the relevant area
  2. A link to the relevant workflow or run in OpenFn
  3. Expected behaviour
  4. Actual behaviour
  5. Error details (logs or screenshot)
  6. Urgency

External documentation

  • OpenFn documentation
  • [PLACEHOLDER: Programme / initiative site]
  • [PLACEHOLDER: Destination system API docs]

Last updated: [PLACEHOLDER: Month YYYY]

About

Template repo for backing up OpenFn projects & workflow config. See the README and the OpenFn Docs site for more.

Resources

Stars

1 star

Watchers

6 watching

Forks

Releases

Packages

Contributors

Languages