Beyond facilitating portability/transferability between OpenFn's platform, microservice, and lightning deployment pathways, the portability proposal establishes a simple, globally-applicable way of specifying workflow automation and systems integration that might be applied across workflow-engines/integration platforms across the sector. Nothing about the spec must be specific to OpenFn or any one of our individual products. We envision a future in which software built with Lightning, the OpenFn Integration Toolkit, and entirely new and different integration/workflow tools can adopt this specification.
It boils down to several key top-level artifacts:
workflows (containing jobs
- Jobs dictate what tasks or actions must be performed;
- Triggers when they must be performed;
- Globals are reusable constants, or datasets (like mapping tables) shared across jobs;
- and Credentials are what, if any, authentication they'll need to perform them.
If you're interested in contributing to the specification, reach out to OpenFn via the community forum, write to us, or suggest changes by submitting a pull request here.
The portability specification v4 defines how entire projects (groups of workflows with their associated triggers, credentials and jobs) can be represented as code. This specification has been written for Lightning, the fully open source webb app which extends the OpenFn DPG. It aims to (a) improve developer experience, allowing them to build and test workflows locally; (b) enable version control and an audit trail of project changes; and (c) enable users to port existing workflows from the OpenFn platform to Lightning.
This new specification has been designed and documented thanks to support from a Digital Square Global Goods grant.
project.zip structure and files:
name: "My Project" # The project name
globals: # All global constants accessible to this project
m126: Medical Referral
g01: General Checkup
ps: Psycho-social Support
workflows: # All workflows in a project
CommCare-to-OpenMRS: #The workflow name. Workflow names won't have spaces
jobs: # All jobs/steps in a workflow
Coerce-to-FHIR: # The job/step name
trigger: webhook #webhook urls are uids so are not included
credential: my-fihr-credential #looks up credential in state by its name
# when running locally, the credentials values are taken from the overrides file
# cli run workflow "CommCare-to-OpenMRS" --overrides ./keys-and-values.yaml
body: "file://./CommCare-to-OpenMRS/Coerce-to-FHIR.js" # each job job-body is stored in a separate file, within a folder for the whole workflow
# no "include", but pathlike doesn't work: if you're doing a uri you need to be explicit about it
# default to local fs -- no numbering because too complicated if users change the order
# this triggers a new workflow
fn(state => state)
sendEmail(state => state.emailContent)
Kobo-to-DHIS2: #This is a second workflow
cron: * 5 * * *
- id: '45bffee'
key: 'My Project'
- id: 'sj23n36'
- id: 'bss522g'
- id: '22aa4st'
- id: 'cfd7c68'
key: 'CommCare-to-OpenMRS' # this is the NAME and the KEY
- id: 'd1ecc4f'
- id: 'ns6yw54'
- id: '12bs52j'
- id: 'lk81hs6'
- id: 'sn26sh2'
- id: 'sk1722h'
- id: '12ms62y'
key: 'My FHIR Credential'
The full specification can be viewed here.