Merge branch 'main' into collections-docs-tweak

adaptors/asana.md

@@ -0,0 +1,44 @@
+---
+title: Asana Adaptor
+---
+
+## About Asana
+
+[Asana](https://app.asana.com/) is a web-based project management tool that helps teams organize, plan, collaborate, and execute tasks. 
+
+## Integration Options
+
+Asana supports 2 primary integration options:
+
+1. Rest API: Asana has an available REST API that enable external services like OpenFn to pull data from Asana, or push data from external apps to Asana. This option is suited for scheduled, bulk syncs or workflows that must update data in Asana with external information. See [functions](/adaptors/packages/asana-docs) for more on how to use this adaptor to work with the API.
+
+2. Webhook: Asana also has a [Webhook or Data Forwarding](https://developers.asana.com/docs/webhooks-guide) to push data from Asana to external systems. This option is suited for real-time, event-based data integration. Check out the Asana [devloper documentation](/adaptors/packages/asana-docs) to learn how to set up a webhook to push data to OpenFn.
+
+## Authentication
+
+See [Asana docs](https://developers.asana.com/docs/authentication) for the latest on supported authentication methods. 
+
+When integrating with Asana via OpenFn, there is one primary authentication method supported: **Personal Access Token (PAT)**. You can generate a personal access token from the Asana [developer console](https://developers.asana.com/docs/personal-access-token).
+
+See this adaptor's [Configuration docs](/adaptors/packages/asana-configuration-schema) for more on the required authentication parameters.
+
+See platform docs on [managing credentials](/documentation/manage-projects/manage-credentials) for how to configure a credential in OpenFn. If working locally or if using a Raw JSON credential type, then your configuration will look something like this:
+
+```
+{
+  "apiVersion": "1.0",
+  "token": "sample-tokenyWSJdXBACMLLWMNGgADFA"
+}
+```
+
+### Helpful Links
+
+1. [API documentation](https://developers.asana.com/docs/overview)
+
+### Implementation Examples
+
+1. The Wildlife Conservation Society (WCS) - KoboToolBox -> GoogleSheets -> Asana sync: [https://openfn.github.io/ConSoSci/asana/](https://openfn.github.io/ConSoSci/asana/)
+
+
+
+

adaptors/collections.md

@@ -4,38 +4,42 @@ title: Collections Adaptor
 
 ## Collections Overview
 
-The Collections API provides access to a secure key/value store on the OpenFn
-Platform. It is designed for high performance over a large volume of data.
+The Collections API provides access to a secure key/value store that allows
+users to store, update and reuse data across workflows in their OpenFn projects.
+It is designed for high performance over a large volume of data.
 
-Collections are secure, private datastores which are visible only to Workflows
-within a particular OpenFn Project. They can be created, managed and destroyed
-from the OpenFn Admin page.
+Collections are secure, private datastores which are only accessible to
+Workflows within a particular OpenFn Project. They can be created, managed and
+destroyed from the OpenFn Admin page.
+
+The Collections Adaptor provides an interface to workflows to use the
+Collections API.
 
 When running in the CLI, a Personal Access Token can be used to get access to
 the collection (generated from the app at /profile/tokens).
 
-See the [Collections](documentation/build/collections) Platform Docs to learn
-more about Collections.
+Learn more about Collections and common use cases in the
+[Collections Docs](/documentation/build/collections).
 
 :::caution
 
-Collections must be created in the platform Admin page before they can be used.
-
-Refer to the [Collections Docs](documentation/build/collections) for details
+Collections must be created in the
+[Platform Admin page](https://docs.openfn.org/documentation/build/collections#managing-collections)
+before they can be used.
 
 :::
 
 ## The Collections Adaptor
 
-The Collections API is inserted into all Steps through a special kind of
-adaptor.
+The Collections API is inserted into all each Step of a Workflow through a
+special kind of adaptor.
 
 Uniquely, the Collections adaptor it is designed to be run _alongside_ other
-adaptors, not by itself. It is injected into the runtime environment for you for
-you by OpenFn. This makes the Collections API available to every Step in a
-Workflow, regardless of which adaptor it is using.
+adaptors, not by itself. It is automatically injected into the runtime
+environment making the Collections API available to every Step in a Workflow,
+regardless of which adaptor it is using.
 
-If using the CLI run a workflow with Collections, refer to the
+If using the CLI the use Collections locally, refer to the
 [CLI Usage](#cli-usage) guide below.
 
 ## Usage Guide
@@ -256,21 +260,22 @@ fn(state => {
 
 ## CLI usage
 
-:::info
+Workflows which use Collections can be run through the CLI. You will need to:
+
+- Get a Personal Access Token (PAT)
+- Update the `workflow.json` with your PAT and the OpenFn endpoint
+- Set the step to use the Collections adaptor
 
-Improved Collections support is coming to the CLI soon!
+:::tip
+
+You can also call the Collections API directly from the CLI. See the
+[CLI Collections Guide](/documentation/collections-cli)
 
 :::
 
 Collections are designed for close integration with the platform app, but can be
 used from the CLI too.
 
-You will need to:
-
-- Set the job to use two adaptors
-- Pass a Personal Access Token
-- Set the Collections endpoint
-
 You can get a Personal Access Token from any v2 deployment.
 
 Remember that a Collection must be created from the Admin page before it can be

adaptors/fhir-fr.md

@@ -0,0 +1,15 @@
+---
+title: FHIR-FR IG Adaptor
+---
+
+## Custom FHIR Adaptor: fhir-fr
+Note❗: This is a custom adaptor generated from this France FHIR Implementation Guide: https://hl7.fr/ig/fhir/core/2.0.0/index.html
+
+Custom FHIR adaptors generate a suite of helper functions specific to their source Implementation Guides.
+
+See the generic [fhir adaptor](/adaptors/fhir) and our [docs on standards](/documentation/get-started/standards) for more general guidance on OpenFn + FHIR.
+
+## Build your own FHIR Adaptor
+See the [Adaptors Wiki](https://github.com/OpenFn/adaptors/wiki/Generating-Fhir-Adaptors) to build your own adaptor for _your_ implementation guide by trying out our fhir-adaptor-generator (which is a new tool still in testing). 
+
+Please share any questions or feedback on [community.openfn.org](https://community.openfn.org). 

adaptors/fhir-ndr-et.md

@@ -0,0 +1,15 @@
+---
+title: FHIR-NDR-ET IG Adaptor
+---
+
+## Custom FHIR Adaptor: fhir-ndr-et
+Note❗: This is a custom adaptor generated from this Implementation Guide `Ethiopia FHIR Implementation Guide - HIV Treatment & Care Services` authored by Jembi Health Systems: https://build.fhir.org/ig/jembi/ethiopia-hiv/branches/master/index.html
+
+Custom FHIR adaptors generate a suite of helper functions specific to their source Implementation Guides.
+
+See the generic [fhir adaptor](/adaptors/fhir) and our [docs on standards](/documentation/get-started/standards) for more general guidance on OpenFn + FHIR.
+
+## Build your own FHIR Adaptor
+See the [Adaptors Wiki](https://github.com/OpenFn/adaptors/wiki/Generating-Fhir-Adaptors) to build your own adaptor for _your_ implementation guide by trying out our fhir-adaptor-generator (which is a new tool still in testing). 
+
+Please share any questions or feedback on [community.openfn.org](https://community.openfn.org). 

adaptors/fhir.md

@@ -0,0 +1,48 @@
+---
+title: FHIR Adaptor
+---
+
+## About FHIR
+
+[FHIR](https://www.hl7.org/fhir/overview.html) stands for Fast Healthcare Interoperability Resources. It is a standard for representing and exchanging healthcare data electronically. 
+
+
+:::tip About this adaptor and features coming soon! 
+
+This adaptor is very basic and generic, used mostly to integrate demo FHIR servers. It's a work-in-progress, so share questions and feedback on [community.openfn.org](https://community.openfn.org).
+
+**FHIR version-specific adaptors (e.g., `fhir-r4`) with enhanced functionality are coming soon** to fast-track integration setup with more helper functions, templates, and docs than this simple adaptor. See the [Adaptors Wiki](https://github.com/OpenFn/adaptors/wiki/Generating-Fhir-Adaptors) for how to build an adaptor specific to your FHIR Implementation Guide. 
+
+:::
+
+## Integration Options
+
+**1. Rest API:** The FHIR specification includes a REST API that enables external services like OpenFn to pull data from the FHIR server, or push data from external apps to FHIR servers. This option is suited for scheduled, bulk syncs or workflows that must update data with external information. See [functions](/adaptors/packages/fhir-docs) for more on how to use this adaptor to work with the API.
+
+**2. Webhook:** The FHIR specification does not inherently define a webhook or data-forwarding mechanism. However, many FHIR implementations and platforms offer extensions or configurations that support similar functionality. This option is suited for real-time, event-based data integration. Check out the FHIR `Subscription` resource [documentation](https://build.fhir.org/subscription-definitions.html) to learn more about one way this might be implemented. 
+
+## Authentication
+
+The FHIR standard does not directly prescribe authentication and authorization methods. Instead, it provides security guidelines and leaves the choice of implementation to the developers of FHIR servers and clients. See the FHIR [docs](https://www.hl7.org/fhir/security.html) for the latest security-related recommendations. Depending on the FHIR systems being integrated via OpenFn, you might employ a Basic Auth, API key, or OAuth authentication scheme. 
+
+See this adaptor's [Configuration docs](/adaptors/packages/fhir-configuration-schema) for more on the required authentication parameters.
+
+See platform docs on [managing credentials](/documentation/manage-projects/manage-credentials) for how to configure a credential in OpenFn. If working locally or if using a Raw JSON credential type, then your configuration will look something like this to define your target endpoint and FHIR version:
+
+```
+{
+  "baseUrl": "https://hapi.fhir.org", //fhir endpoint
+  "apiPath": "baseR4" //fhir version
+}
+```
+
+### Helpful Links
+
+1. [API documentation](https://www.hl7.org/fhir/http.html)
+2. [Digital Square on FHIR](https://digitalsquare.org/resourcesrepository/digital-square-on-fhir-4c78p)
+3. [Basic guide to interacting with FHIR Server](https://smilecdr.com/docs/fhir_standard/fhir_introduction.html)
+4. [Creating your first FHIR resource](https://medblocks.com/blog/fhir-101-creating-your-first-patient-resource-like-a-pro)
+5. Google's [Open Health Stack](https://developers.google.com/open-health-stack) tooling for working with FHIR
+
+Have resources or links to share? Submit a PR to edit this page or post on [community.openfn.org](https://community.openfn.org).
+

adaptors/http.md

@@ -0,0 +1,39 @@
+---
+title: HTTP Adaptor
+---
+
+## About the HTTP "universal" adaptor
+
+Communicate with web apps using [HTTP (HyperText Transfer Protocol)](https://www.cloudflare.com/learning/ddos/glossary/hypertext-transfer-protocol-http/). 
+This adaptor enables out-of-box integration with any REST API! 
+
+## Integration Options
+
+Use this adaptor to communicate with **any REST API** or any other app that can communicate via HTTP. 
+
+**Note that OpenFn also supports Webhooks, but that is a workflow trigger type ([see docs](/documentation/build/triggers#webhook-event-triggers)), not an adaptor.**
+
+## Authentication
+
+HTTP itself does not enforce authentication, but many applications that use HTTP implement security mechanisms to control access. Common methods that can be used when integrating with OpenFn include Basic Authentication, API Keys and OAuth. See this adaptor's [Configuration docs](/adaptors/packages/http-configuration-schema) for more on the required authentication parameters.
+
+See platform docs on [managing credentials](/documentation/manage-projects/manage-credentials) for how to configure a credential in OpenFn. If working locally or if using a Raw JSON credential type, then your configuration will look something like this:
+
+```
+{
+  "username": "[email protected]",
+  "password": "@some(!)Password",
+  "access_token": "00QCjAl4MlV-WPX",
+  "baseUrl": "https://instance_name.surveycto.com"
+}
+```
+
+
+### Implementation Examples
+
+1. UNICEF Primero - UNHCR Progres Interoperability: [https://github.com/OpenFn/primero-progres](https://github.com/OpenFn/primero-progres)
+2. UNICEF Thailand Primero Interoperability: [https://openfn.github.io/primero-thailand/](https://openfn.github.io/primero-thailand/)
+
+
+
+

adaptors/library/jobs/DHIS2-DataValues-API.js

@@ -1,20 +1,25 @@
 // ----
 // Add data to data value sets in DHIS2 using a generic JSON message, submitted
-// by Taylor Downs @ OpenFn.
+// by Taylor Downs @ OpenFn. Co-authored by @mtuchi
 // ---
 
-dataValueSet(
-  fields(
-    field('dataSet', 'pBOMPrpg1QX'),
-    field('orgUnit', 'DiszpKrYNg8'),
-    field('period', '201401'),
-    field('completeData', dataValue('form.date')),
-    field('dataValues', function (state) {
-      return [
-        dataElement('qrur9Dvnyt5', dataValue('form.prop_a')(state)),
-        dataElement('oZg33kd9taw', dataValue('form.prop_b')(state)),
-        dataElement('msodh3rEMJa', dataValue('form.prop_c')(state)),
-      ];
-    })
-  )
-);
+create('dataValueSets', {
+  dataSet: 'pBOMPrpg1QX',
+  completeDate: $.form.date,
+  period: '201401',
+  orgUnit: 'DiszpKrYNg8',
+  dataValues: [
+    {
+      dataElement: 'f7n9E0hX8qk',
+      value: $.form.prop_a,
+    },
+    {
+      dataElement: 'Ix2HsbDMLea',
+      value: $.form.prop_b,
+    },
+    {
+      dataElement: 'eY5ehpbEsB7',
+      value: $.form.prop_c,
+    },
+  ],
+});

adaptors/library/jobs/DHIS2-Events-API.js

@@ -1,25 +1,30 @@
 // ----
 // Create new events in DHIS2 using a generic JSON message, submitted by
-// Taylor Downs @ OpenFn for demonstration porpoises.
+// Taylor Downs @ OpenFn, Co-authored by @mtuchi
 // ---
 
-event(
-  fields(
-    field('program', 'eBAyeGv0exc'),
-    field('orgUnit', 'DiszpKrYNg8'),
-    field('eventDate', dataValue('meta.date')),
-    field('status', 'COMPLETED'),
-    field('storedBy', 'admin'),
-    field('coordinate', {
-      latitude: '59.8',
-      longitude: '10.9',
-    }),
-    field('dataValues', function (state) {
-      return [
-        dataElement('qrur9Dvnyt5', dataValue('form.prop_a')(state)),
-        dataElement('oZg33kd9taw', dataValue('form.prop_b')(state)),
-        dataElement('msodh3rEMJa', dataValue('form.prop_c')(state)),
-      ];
-    })
-  )
-);
+create('events', {
+  program: 'eBAyeGv0exc',
+  orgUnit: 'DiszpKrYNg8',
+  occurredAt: $.meta.date,
+  status: 'COMPLETED',
+  storedBy: 'admin',
+  geometry: {
+    type: 'POINT',
+    coordinates: [59.8, 10.9],
+  },
+  dataValues: [
+    {
+      dataElement: 'qrur9Dvnyt5',
+      value: $.form.prop_a,
+    },
+    {
+      dataElement: 'oZg33kd9taw',
+      value: $.form.prop_b,
+    },
+    {
+      dataElement: 'msodh3rEMJa',
+      value: $.form.prop_c,
+    },
+  ],
+});

adaptors/library/staticExamples.json

@@ -59,12 +59,12 @@
   {
     "expressionPath": "jobs/DHIS2-DataValues-API",
     "adaptor": "dhis2",
-    "name": "Add data values"
+    "name": "Create data values"
   },
   {
     "expressionPath": "jobs/DHIS2-Events-API",
     "adaptor": "dhis2",
-    "name": "Add events"
+    "name": "Create new events"
   },
   {
     "expressionPath": "jobs/ODK-Create-Many-Records-Moving-In-And-Out-Of-Repeat-Blocks",