From 88e7bae5a116b209f5497ab4f44ae3adba3892d6 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Fri, 16 Feb 2024 12:51:58 +0300 Subject: [PATCH 1/6] wip kobo to dhis2 --- docs/tutorials/kobo-to-dhis2.md | 103 ++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/kobo-to-dhis2.md b/docs/tutorials/kobo-to-dhis2.md index e0815c0c4a71..6a17c195b332 100644 --- a/docs/tutorials/kobo-to-dhis2.md +++ b/docs/tutorials/kobo-to-dhis2.md @@ -3,11 +3,106 @@ sidebar_label: Kobo to DHIS2 title: Kobo to DHIS2 Reporting Workflow slug: /kobo-to-dhis2 --- -:::warning Under construction -This docs page is under construction. Check back later for the complete docs, or check out the Docs Version "Platform (v1)". +Workflow Automation Tutorial: Fetching Kobotoolbox Form Submissions, Aggregating +OPV Dose, and Loading to DHIS2 -::: +### Overview: -# Tutorial: Kobo to DHIS2 Reporting Workflow +This tutorial guides you through creating an OpenFn workflow to fetch form +submissions from Kobotoolbox, transform the data by counting `OPV0_dose_given` +values, and load the results into DHIS2. +### Prerequisites: + +- OpenFn account +- Kobotoolbox account +- DHIS2 account + +### Step 1: Configure Kobotoolbox Adaptor + +In the OpenFn Inspector Editor, use the following code: + +```javascript +// Step 1: Fetch Form Submissions from Kobotoolbox +getSubmissions({ formId: 'aBpweTNdaGJQFb5EBBwUeo' }); +``` + +Explanation: + +- `getSubmissions`: Fetches form submissions. +- `{ formId: "aBpweTNdaGJQFb5EBBwUeo" }`: Specify the form ID to retrieve + submissions. + +### Step 2: Transform and Count OPV Dose Given + +In the OpenFn Inspector Editor, add the following code: + +```javascript +// Step 2: Transform and Count OPV Dose Given +fn(state => { + const opvDosesGivenCount = state.data.results.filter( + r => r['OPV0_dose_given'] === 'yes' + ).length; + + return { ...state, opvDosesGivenCount }; +}); +``` + +Explanation: + +- `fn`: A function in OpenFn to transform data. +- `opvDosesGivenCount`: Counts the occurrences of 'yes' in the `OPV0_dose_given` + field. + +### Step 3: Map and Load to DHIS2 + +Set up the DHIS2 adaptor: + +```json +{ + "hostUrl": "https://play.dhis2.org/dev", + "username": "admin", + "password": "@some(!)Password" +} +``` + +In the OpenFn Inspector Editor, add the following code: + +```javascript +// Create completeDate with format YYYY-MM-DD +fn(state => { + const today = new Date().toISOString().slice(0, 10); + console.log(state.opvDosesGivenCount, 'opv0 doses given'); + return { ...state, today }; +}); + +// Import to DHIS2 +create('dataValueSets', state => ({ + dataSet: 'BfMAe6Itzgt', // Child Health + completeDate: state.today, // Today's date in format 'YYYY-MM-DD' + period: '202402', // Feb 2024 + orgUnit: 'DiszpKrYNg8', // Ngelehun CHC + dataValues: [ + { + dataElement: 'pikOziyCXbM', // OPV0 doses given dataElement ID + value: state.opvDosesGivenCount, //# of OPV0 doses given + }, + ], +})); +``` + +Explanation: + +- `create('dataValueSets', {...})`: This OpenFn function is used to create a new + datavalueset in DHIS2. +- `dataSet`, `completeDate`, `period`, `orgUnit`: Details of the datavalueset. +- `dataValues`: An array containing data elements and their corresponding + values. + +### Conclusion + +Congratulations! You've successfully created an OpenFn workflow to automate the +process of fetching form submissions from Kobotoolbox, counting OPV doses given, +and loading data into DHIS2. Adjustments can be made based on specific +requirements or system changes. From db8ee5eeb78a03512bac758c1990b5c49397e6fe Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Fri, 16 Feb 2024 17:24:37 +0300 Subject: [PATCH 2/6] improvements --- docs/tutorials/kobo-to-dhis2.md | 66 ++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 13 deletions(-) diff --git a/docs/tutorials/kobo-to-dhis2.md b/docs/tutorials/kobo-to-dhis2.md index 6a17c195b332..12c131c837a6 100644 --- a/docs/tutorials/kobo-to-dhis2.md +++ b/docs/tutorials/kobo-to-dhis2.md @@ -19,27 +19,50 @@ values, and load the results into DHIS2. - Kobotoolbox account - DHIS2 account -### Step 1: Configure Kobotoolbox Adaptor +### Step 1: Get Kobo Form Submission -In the OpenFn Inspector Editor, use the following code: +Create a the first step in workflow convas and give it a name of +`Get Kobo Form Submission`. In this step we will be fetching submissions for a +form with an id `aBpweTNdaGJQFb5EBBwUeo`. This step uses the kobotoolbox adaptor +and we will use the following credential configuration + +```json +{ + "baseURL": "https://kf.kobotoolbox.org", + "username": "openfn_demo", + "password": "openfn_demo", + "apiVersion": "v2" +} +``` + +Open the OpenFn Inspector Editor and add the following code: ```javascript // Step 1: Fetch Form Submissions from Kobotoolbox getSubmissions({ formId: 'aBpweTNdaGJQFb5EBBwUeo' }); ``` -Explanation: +#### Explanation: - `getSubmissions`: Fetches form submissions. - `{ formId: "aBpweTNdaGJQFb5EBBwUeo" }`: Specify the form ID to retrieve submissions. -### Step 2: Transform and Count OPV Dose Given +#### Testing: -In the OpenFn Inspector Editor, add the following code: +Create an empty input `{}` then click `Create New Work Order` button to run the +workflow. The expected output should contain 17 records in `state.data.results` + +### Step 2: Count OPV Dose Given + +Create a down stream step after `Get Kobo Form Submission` and give it a name of +`Count OPV Dose Given`. In this step we are going to count all records with +`"OPV0_dose_given": "yes"`. This step will use `common` adaptor and does not +require any credentials. Open the OpenFn Inspector and add the following code in +the editor: ```javascript -// Step 2: Transform and Count OPV Dose Given +// Filter and Count OPV Dose Given fn(state => { const opvDosesGivenCount = state.data.results.filter( r => r['OPV0_dose_given'] === 'yes' @@ -49,25 +72,34 @@ fn(state => { }); ``` -Explanation: +#### Explanation: -- `fn`: A function in OpenFn to transform data. +- `fn`: A function in OpenFn for more flexible job writing. It gives you the + ability to do something to the state and return transformed data to state; - `opvDosesGivenCount`: Counts the occurrences of 'yes' in the `OPV0_dose_given` field. +#### Testing: + +Select the first step `Get Kobo Form Submission` and `Create New Work Order` +with an empty input. Both steps should be executed successfully and you should +see in the final state `opvDosesGivenCount: 3` added + ### Step 3: Map and Load to DHIS2 -Set up the DHIS2 adaptor: +Create a down stream step after `Count OPV Dose Given` and give it a name of +`Map and Load to DHIS2`. In this step we will create DHIS2 data values to DHIS2. +We will be using the following credential configuration ```json { "hostUrl": "https://play.dhis2.org/dev", "username": "admin", - "password": "@some(!)Password" + "password": "district" } ``` -In the OpenFn Inspector Editor, add the following code: +Open the OpenFn Inspector, add the following code in the editor: ```javascript // Create completeDate with format YYYY-MM-DD @@ -85,14 +117,15 @@ create('dataValueSets', state => ({ orgUnit: 'DiszpKrYNg8', // Ngelehun CHC dataValues: [ { - dataElement: 'pikOziyCXbM', // OPV0 doses given dataElement ID + categoryOptionCombo: 'HllvX50cXC0', + dataElement: 'x3Do5e7g4Qo', // OPV0 doses given dataElement ID value: state.opvDosesGivenCount, //# of OPV0 doses given }, ], })); ``` -Explanation: +#### Explanation: - `create('dataValueSets', {...})`: This OpenFn function is used to create a new datavalueset in DHIS2. @@ -100,6 +133,13 @@ Explanation: - `dataValues`: An array containing data elements and their corresponding values. +#### Testing + +Save your changes then navigate to the first step(Get Kobo Form Submission) and +create an empty input `{}` then click `Create New Work Order` button to run the +workflow. All steps should be executed successful and you should see the +`OPV0 doses given` updated in DHIS2 + ### Conclusion Congratulations! You've successfully created an OpenFn workflow to automate the From a016ea2e876e0e104bb801bd442db08a9dd12464 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Sat, 17 Feb 2024 13:05:56 +0300 Subject: [PATCH 3/6] update dhis mapping --- docs/tutorials/kobo-to-dhis2.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/kobo-to-dhis2.md b/docs/tutorials/kobo-to-dhis2.md index 12c131c837a6..9ec14405b5dc 100644 --- a/docs/tutorials/kobo-to-dhis2.md +++ b/docs/tutorials/kobo-to-dhis2.md @@ -102,23 +102,15 @@ We will be using the following credential configuration Open the OpenFn Inspector, add the following code in the editor: ```javascript -// Create completeDate with format YYYY-MM-DD -fn(state => { - const today = new Date().toISOString().slice(0, 10); - console.log(state.opvDosesGivenCount, 'opv0 doses given'); - return { ...state, today }; -}); - // Import to DHIS2 create('dataValueSets', state => ({ dataSet: 'BfMAe6Itzgt', // Child Health - completeDate: state.today, // Today's date in format 'YYYY-MM-DD' period: '202402', // Feb 2024 orgUnit: 'DiszpKrYNg8', // Ngelehun CHC dataValues: [ { - categoryOptionCombo: 'HllvX50cXC0', - dataElement: 'x3Do5e7g4Qo', // OPV0 doses given dataElement ID + categoryOptionCombo: 'Prlt0C1RF0s', //Fixed <1yr + dataElement: 'x3Do5e7g4Qo', // OPV0 doses given value: state.opvDosesGivenCount, //# of OPV0 doses given }, ], From 214f86b036d5f6c4b5ba1273c8539383b9b0eed5 Mon Sep 17 00:00:00 2001 From: aleksa-krolls Date: Wed, 21 Feb 2024 00:02:11 +0200 Subject: [PATCH 4/6] edits to copy and headers --- docs/tutorials/kobo-to-dhis2.md | 137 +++++++++++++++++++++++++------- 1 file changed, 107 insertions(+), 30 deletions(-) diff --git a/docs/tutorials/kobo-to-dhis2.md b/docs/tutorials/kobo-to-dhis2.md index 9ec14405b5dc..551a71fdf303 100644 --- a/docs/tutorials/kobo-to-dhis2.md +++ b/docs/tutorials/kobo-to-dhis2.md @@ -4,27 +4,53 @@ title: Kobo to DHIS2 Reporting Workflow slug: /kobo-to-dhis2 --- -Workflow Automation Tutorial: Fetching Kobotoolbox Form Submissions, Aggregating -OPV Dose, and Loading to DHIS2 +# Create a Workflow automating reporting between KoboToolbox & DHIS2 -### Overview: +In this tutorial, we are going to walk through how to create a simple OpenFn +Workflow that automates reporting from +[KoboToolbox](https://www.kobotoolbox.org/) (a mobile data collection app) and +[DHIS2](https://dhis2.org) (a health information system commonly used for +aggregate reporting on key indicators) using the the `kobotoolbox` and `dhis2` +[Adaptors](/adaptors). -This tutorial guides you through creating an OpenFn workflow to fetch form -submissions from Kobotoolbox, transform the data by counting `OPV0_dose_given` -values, and load the results into DHIS2. +### Video Walkthrough + +:::warning + +Coming soon: Video tutorial to guide you through this Workflow configuration. + +::: + +### Workflow Overview: + +This OpenFn Workflow will have 3 Steps: + +1. Fetch form submissions from Kobotoolbox +2. Count the number of `OPV0_dose_given` values recorded across submissions to + return an aggregate count of how many beneficiaries have received the OPV0 + immunication +3. Import the aggregate results to DHIS2 to report on the # of doses recorded + that week ### Prerequisites: -- OpenFn account -- Kobotoolbox account -- DHIS2 account +- You have an OpenFn Project +- You have a KoboToolbox account and form to sync (see below for demo + credentials to use) +- Login info for a DHIS2 instance (see below for login info for the "play" DHIS2 + instance) ### Step 1: Get Kobo Form Submission -Create a the first step in workflow convas and give it a name of -`Get Kobo Form Submission`. In this step we will be fetching submissions for a -form with an id `aBpweTNdaGJQFb5EBBwUeo`. This step uses the kobotoolbox adaptor -and we will use the following credential configuration +Create a the first step in Wrkflow convas. + +- Name: `Get Kobo Form Submission` +- Adaptor: `kobotoolbox` +- Version: `latest` +- Credential: see belo + +This step uses the kobotoolbox adaptor and we will use the following credential +configuration ```json { @@ -35,13 +61,24 @@ and we will use the following credential configuration } ``` -Open the OpenFn Inspector Editor and add the following code: +In this Step we want to be fetch form submissions from this demo form with the +id `aBpweTNdaGJQFb5EBBwUeo`. To do so, open the +[Inspector Editor](../build/steps/step-editor.md) and add the following Job +code: ```javascript // Step 1: Fetch Form Submissions from Kobotoolbox getSubmissions({ formId: 'aBpweTNdaGJQFb5EBBwUeo' }); ``` +:::tip Need help writing job code? + +Check out the docs on the ["kobotoolbox" Adaptor](/adaptors/kobotoolbox), +[configuring Steps](../build/steps/steps.md), and +[job-writing](../build/steps/jobs.md). + +::: + #### Explanation: - `getSubmissions`: Fetches form submissions. @@ -51,15 +88,23 @@ getSubmissions({ formId: 'aBpweTNdaGJQFb5EBBwUeo' }); #### Testing: Create an empty input `{}` then click `Create New Work Order` button to run the -workflow. The expected output should contain 17 records in `state.data.results` +workflow. [See docs](../build/workflows.md) for more on running Workflows +manually. + +The expected ` output`` should contain 17 records in `state.data.results` ### Step 2: Count OPV Dose Given -Create a down stream step after `Get Kobo Form Submission` and give it a name of -`Count OPV Dose Given`. In this step we are going to count all records with -`"OPV0_dose_given": "yes"`. This step will use `common` adaptor and does not -require any credentials. Open the OpenFn Inspector and add the following code in -the editor: +Create a second Step after `Get Kobo Form Submission` as follows: + +- Name: `Count OPV Dose Given` +- Adaptor: `common` (used whenever we want to add custom JavaScript functions) +- Version: `latest` +- Credential: none needd + +In this step we are going to count all records with `"OPV0_dose_given": "yes"`. +To add this logic, open the [Inspector](../build/steps/step-editor.md) and add +the following JOb code in the Editor: ```javascript // Filter and Count OPV Dose Given @@ -72,6 +117,14 @@ fn(state => { }); ``` +::tip Need help writing job code? Or modifying this logic? + +Check out the docs on the ["common" Adaptor](/adaptors/packages/common-docs), +[configuring Steps](../build/steps/steps.md), and +[job-writing](../build/steps/jobs.md). + +::: + #### Explanation: - `fn`: A function in OpenFn for more flexible job writing. It gives you the @@ -82,14 +135,18 @@ fn(state => { #### Testing: Select the first step `Get Kobo Form Submission` and `Create New Work Order` -with an empty input. Both steps should be executed successfully and you should -see in the final state `opvDosesGivenCount: 3` added +with an empty input ([see Workflow docs](../build/workflows.md) if you need help +with running and testing steps). Both steps should be executed successfully and +you should see in the final state `opvDosesGivenCount: 3` added. ### Step 3: Map and Load to DHIS2 -Create a down stream step after `Count OPV Dose Given` and give it a name of -`Map and Load to DHIS2`. In this step we will create DHIS2 data values to DHIS2. -We will be using the following credential configuration +Create a third Step after `Count OPV Dose Given` as follows: + +- Name: `Map and Load to DHIS2` +- Adaptor: `dhis2` +- Version: `v4.0.3` +- Credential: new `dhis2` credential with the following credential configuration ```json { @@ -99,7 +156,11 @@ We will be using the following credential configuration } ``` -Open the OpenFn Inspector, add the following code in the editor: +In this Step, we want to add logic to import `dataValues` to DHIS2 to "report" +on the aggregated OPV0 immunization does count calculated in Step 2. + +To do so, open the [Inspector](../build/steps/step-editor.md), add the following +Job code in the Editor: ```javascript // Import to DHIS2 @@ -117,6 +178,14 @@ create('dataValueSets', state => ({ })); ``` +::tip Need help writing job code? Or modifying this logic? + +Check out the docs on the ["dhis2" Adaptor](/adaptors/dhis2), +[configuring Steps](../build/steps/steps.md), and +[job-writing](../build/steps/jobs.md). + +::: + #### Explanation: - `create('dataValueSets', {...})`: This OpenFn function is used to create a new @@ -130,11 +199,19 @@ create('dataValueSets', state => ({ Save your changes then navigate to the first step(Get Kobo Form Submission) and create an empty input `{}` then click `Create New Work Order` button to run the workflow. All steps should be executed successful and you should see the -`OPV0 doses given` updated in DHIS2 +`OPV0 doses given` updated in DHIS2. See [Workflow docs](../build/workflows.md) +if you need help running or testing Workflows. ### Conclusion Congratulations! You've successfully created an OpenFn workflow to automate the -process of fetching form submissions from Kobotoolbox, counting OPV doses given, -and loading data into DHIS2. Adjustments can be made based on specific -requirements or system changes. +process of fetching form submissions from Kobotoolbox, calculated the aggregated +count of OPV doses given to beneficiaries, and reporting this count as +`dataValues` to DHIS2. + +:::tip Are you blocked? Have questions? + +Reminder to watch the video (_coming soon!_) or post on the +[Community](https://community.openfn.org) to ask for help! + +::: From 87958229612b5fc1abadccca1eb55bd4da7bdbad Mon Sep 17 00:00:00 2001 From: aleksa-krolls Date: Wed, 21 Feb 2024 00:14:29 +0200 Subject: [PATCH 5/6] updating tutorial intro page --- docs/tutorials/tutorial.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/tutorial.md b/docs/tutorials/tutorial.md index 8564566e0c8a..b9f6af0dcda4 100644 --- a/docs/tutorials/tutorial.md +++ b/docs/tutorials/tutorial.md @@ -1,10 +1,23 @@ --- -title: Workflow Tutorial +title: QuickStart +sidebar_label: Workflow QuickStart +slug: /tutorial --- -# Tutorial: Creating your first workflow -:::warning Under construction +# QuickStart: Creating your first workflow -This docs page is under construction. Check back later for the complete docs, or check out the Docs Version "Platform (v1)". +1. Go to your OpenFn Project > `Workflows` +2. Create a new [Workflow](../build/workflows.md) +3. Choose your [Trigger type](../build/triggers.md): Webhook Event (for real-time integration) or Cron Expression (for timer/scheduled-based integration) +3. Name your first `Step` (e.g., "Import form submission") and open it to choose the [Adaptor](/adaptors), Adaptor `Version`, and [Credential](../build/credentials.md) +4. Click the `` code button to open the [Inspector](../build/steps/step-editor.md) and add job code to the `Editor` panel to define the specific business logic or transformation rules for this workflow +5. In the `Input` panel on the left, add a custom input (e.g., a payload from a webhook request) or simply add empty brackets (`{}`) to run a Workflow with a cron trigger. See the [Workflow docs](docs/build/workflows.md) for help with running and testing Workflow. +6. If the Step suceeds, navigate back to the Canvase view and click the `+` icon to add a second Step. +7. If you want to define conditions for if/when this second Step should execute, update the [Path condition](../build/paths.md). +8. Then repeat the instruction steps #3-6 to finishing configuring this next Step, until the Workflow is complete. -::: +:::tip + +Check out the video and docs on the [Workflows page](../build/workflows.md) in the `Build` docs for in-depth help, or ask your questions on [Community](https://community.openfn.org)! + +::: \ No newline at end of file From 0af3b9fc49739c8e910e953cd5b83363fe448635 Mon Sep 17 00:00:00 2001 From: Aleksa Krolls Date: Wed, 21 Feb 2024 00:25:09 +0200 Subject: [PATCH 6/6] Update tutorial.md --- docs/tutorials/tutorial.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/tutorial.md b/docs/tutorials/tutorial.md index 9f4f09163438..18f3cf78cc50 100644 --- a/docs/tutorials/tutorial.md +++ b/docs/tutorials/tutorial.md @@ -1,7 +1,6 @@ --- -title: QuickStart +title: Tutorial sidebar_label: Workflow QuickStart -slug: /tutorial --- # Tutorial: Creating your first workflow @@ -20,4 +19,4 @@ slug: /tutorial Check out the video and docs on the [Workflows page](../build/workflows.md) in the `Build` docs for in-depth help, or ask your questions on [Community](https://community.openfn.org)! -::: \ No newline at end of file +:::