diff --git a/adaptors/asana.md b/adaptors/asana.md new file mode 100644 index 000000000000..dbc846a2176a --- /dev/null +++ b/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/) + + + + diff --git a/adaptors/collections.md b/adaptors/collections.md index 635adf2c212f..a693df81fc92 100644 --- a/adaptors/collections.md +++ b/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 diff --git a/adaptors/fhir-fr.md b/adaptors/fhir-fr.md new file mode 100644 index 000000000000..38ac51106d25 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/adaptors/fhir-ndr-et.md b/adaptors/fhir-ndr-et.md new file mode 100644 index 000000000000..2a42c6a3ab2e --- /dev/null +++ b/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). \ No newline at end of file diff --git a/adaptors/fhir.md b/adaptors/fhir.md new file mode 100644 index 000000000000..91d22834dcb9 --- /dev/null +++ b/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). + diff --git a/adaptors/http.md b/adaptors/http.md new file mode 100644 index 000000000000..295cb231281d --- /dev/null +++ b/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": "test@openfn.org", + "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/) + + + + diff --git a/adaptors/library/jobs/DHIS2-DataValues-API.js b/adaptors/library/jobs/DHIS2-DataValues-API.js index b305cd977439..ef582f0a7c03 100644 --- a/adaptors/library/jobs/DHIS2-DataValues-API.js +++ b/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, + }, + ], +}); diff --git a/adaptors/library/jobs/DHIS2-Events-API.js b/adaptors/library/jobs/DHIS2-Events-API.js index e1b02e6b8373..ff5175fdddcf 100644 --- a/adaptors/library/jobs/DHIS2-Events-API.js +++ b/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, + }, + ], +}); diff --git a/adaptors/library/staticExamples.json b/adaptors/library/staticExamples.json index 02cd577b75e3..6b3c2f65f040 100644 --- a/adaptors/library/staticExamples.json +++ b/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", diff --git a/adaptors/mailchimp.md b/adaptors/mailchimp.md new file mode 100644 index 000000000000..a0bac033c7dc --- /dev/null +++ b/adaptors/mailchimp.md @@ -0,0 +1,41 @@ +--- +title: MailChimp Adaptor +--- + +## About Mailchimp + +[Mailchimp](https://mailchimp.com/) is a marketing automation platform that allows businesses to design, send, and manage email campaigns. It also provides tools for audience management, analytics, and integrations with other platforms to support marketing efforts. + +## Integration Options + +Mailchimp supports two primary integration options: + +**1. Rest API:** Mailchimp offers a REST API that enables external applications to interact with its services. This option is ideal for applications requiring scheduled or bulk synchronization with OpenMRS. Refer to the Mailchimp REST API [documentation](https://mailchimp.com/developer/marketing/api/) for detailed guidelines on endpoints and payload formats. + +**2. Webhook:** Webhook or Data Forwarding to push data from MailChimp to external systems ([see docs](https://mailchimp.com/developer/transactional/docs/webhooks/)). This option is suited for real-time, event-based data integration. + +## Authentication + +When integrating with Mailchimp via OpenFn, authentication via **API Key** is supported ([see MC docs](https://mailchimp.com/developer/marketing/docs/fundamentals/#connecting-to-the-api). See this adaptor's [Configuration docs](/adaptors/packages/mailchimp-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: + +``` +{ + "server": "us11", + "apiKey": "0eb22c7b4a1c5bcd789379bf8a92902d-us13" +} +``` + +### Helpful Links +1. [Developer Portal](https://mailchimp.com/developer/) +2. [API Reference](https://mailchimp.com/developer/marketing/) +3. [Webhook Setup Guide](https://mailchimp.com/developer/marketing/guides/set-up-webhooks/) + +### Implementation Examples + +1. GIFE Project - Mailchimp -> Salesforce sync: [https://github.com/OpenFn/gife](https://github.com/OpenFn/gife) + + + + diff --git a/adaptors/mongodb.md b/adaptors/mongodb.md new file mode 100644 index 000000000000..5c6f560b0428 --- /dev/null +++ b/adaptors/mongodb.md @@ -0,0 +1,36 @@ +--- +title: MongoDB Adaptor +--- + +## About MongoDB + +[MongoDB](https://www.mongodb.com/) is a NoSQL, document-oriented database that stores data in BSON (Binary JSON) format, enabling easy storage and retrieval of complex and hierarchical data structures + +## Integration Options + +The `mongodb` adaptor provides direct database connections for accessing data and executing SQL and standard database operations. See [functions](/adaptors/packages/mongodb-docs) for more on how to use this adaptor. + + +## Authentication + +See the [MongoDB docs](https://www.mongodb.com/docs/) for the latest on supported authentication methods. When integrating with a MongoDB database via OpenFn, you authenticate via SSH using authorized database credentials. See this adaptor's [configuration docs](/adaptors/packages/mongodb-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: + +``` +{ + "clusterHostname": "yourCluster-xxxyzzz.mongodb.net", + "username": "admin", + "password": "@secret(!)Pass" +} +``` + +### Helpful Links + +1. [MongoDB documentation](https://www.mongodb.com/docs/) + + + + + + diff --git a/adaptors/mssql.md b/adaptors/mssql.md new file mode 100644 index 000000000000..50b809a17ac6 --- /dev/null +++ b/adaptors/mssql.md @@ -0,0 +1,37 @@ +--- +title: MSSQL Adaptor +--- + +## About MSSQL + +[Microsoft SQL Server](https://learn.microsoft.com/en-us/sql/?view=sql-server-ver16) (MSSQL) is a relational database management system (RDBMS) developed by Microsoft. It supports a wide variety of applications, including data warehousing, transaction processing, and business intelligence. It can be accessed and manipulated using SQL to extract or load data. + +## Integration Options + +The `mssql` adaptor provides direct database connections for accessing data and executing SQL and standard database operations. See [functions](/adaptors/packages/mssql-docs) for more on how to use this adaptor. + + +## Authentication + +See [MSSQL docs](https://learn.microsoft.com/en-us/sql/?view=sql-server-ver16) for the latest on supported authentication methods. When integrating with an MSSQL database via OpenFn, you authenticate via SSH using authorized database credentials. See this adaptor's [Configuration docs](/adaptors/packages/mssql-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: + +``` +{ + "server": "something.database.windows.net", + "database": "demo-db", + "userName": "admin", + "password": "@super(!)Password" +} +``` + +### Helpful Links + +1. [MSSQL documentation](https://learn.microsoft.com/en-us/sql/?view=sql-server-ver16) + + + + + + diff --git a/adaptors/mysql.md b/adaptors/mysql.md new file mode 100644 index 000000000000..bc64964a31d9 --- /dev/null +++ b/adaptors/mysql.md @@ -0,0 +1,37 @@ +--- +title: MySQL Adaptor +--- + +## About MySQL + +MySQL is a free and open-source relational database management system. It can be accessed and manipulated using SQL to extract or load data. + +## Integration Options + +The `mysql` adaptor provides direct database connections for accessing data and executing SQL and standard database operations. See [functions](/adaptors/packages/mysql-docs) for more on how to use this adaptor. + + +## Authentication + +See the [MySQL docs](https://dev.mysql.com/doc/) for the latest on supported authentication methods. When integrating with a MySQL database via OpenFn, you authenticate via SSH using authorized database credentials. See this adaptor's [configuration docs](/adaptors/packages/mysql-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: + +``` +{ + "host": "some-host-url.compute-1.amazonaws.com", + "database": "demo-db", + "user": "admin-demo", + "password": "@super(!)Secretpass" +} +``` + +### Helpful Links + +1. [MySQL documentation](https://dev.mysql.com/doc/) + + + + + + diff --git a/adaptors/ocl.md b/adaptors/ocl.md new file mode 100644 index 000000000000..8fb50a6df0e8 --- /dev/null +++ b/adaptors/ocl.md @@ -0,0 +1,38 @@ +--- +title: OCL Adaptor +--- + +## About OCL + +[OCL (Open Concept Lab)](https://openconceptlab.org/) is an open-source platform that provides a collaborative environment for creating, managing, and sharing standardized healthcare terminologies, dictionaries, and value sets. + +Relationships between concepts are defined in OCL as `mappings`. The API supports searching and editing concepts and mappings, building `sources`, and logically grouping concepts and mappings into `collections`. [See OCL docs](https://docs.openconceptlab.org/en/latest/oclapi/overview.html#overview) to learn more, access the [Swagger API](https://api.openconceptlab.org/swagger/), and to learn more about the cloud instance available at [https://openconceptlab.org](https://openconceptlab.org). + +## Integration Options + +**1. Rest API:** OCL offers a REST API that allows systems to interact with its concept dictionaries and value sets. With the API, you can: +This option is suited for scheduled synchronization or workflows requiring regular updates to or from OCL. Refer to the [OCL REST API documentation](https://docs.openconceptlab.org/en/latest/oclapi/overview.html) for endpoint details and usage examples. + +**2. Bulk Export and Import**: OCL supports exporting and importing concept dictionaries and value sets in various formats (e.g., JSON, CSV). This allows for manual or automated bulk data integration. Use this option for one-time data transfer or systems without direct API connectivity. + +## Authentication +When integrating with OCL via OpenFn, you must provide a username and password to generate an authorization token ([see OCL docs](https://docs.openconceptlab.org/en/latest/oclapi/overview.html#authentication-and-authorization)). See this adaptor's [Configuration docs](/adaptors/packages/ocl-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: + +``` +{ + "hostUrl": "https://api.openconceptlab.org/", + "username": "usernmame", + "password": "supersecretpassword" +} +``` +## Helpful Links +1. [OCL Developer Guide](https://docs.openconceptlab.org/) +2. [OCL API Reference](https://docs.openconceptlab.org/en/latest/oclapi/apireference/index.html) +3. [OCL Community Support](https://openconceptlab.org/category/community/) +4. [OCL GitHub Repository](https://github.com/OpenConceptLab) + + +## Implementation Examples +1. OpenFn Prototype for Médecins Sans Frontières (MSF) LIME Project - OpenMRS -> OCL -> DHIS2 sync: https://github.com/OpenFn/openfn-lime diff --git a/adaptors/openmrs.md b/adaptors/openmrs.md new file mode 100644 index 000000000000..98eb0f3339a6 --- /dev/null +++ b/adaptors/openmrs.md @@ -0,0 +1,40 @@ +--- +title: OpenMRS Adaptor +--- + +## About OpenMRS + +[OpenMRS (Open Medical Record System)](https://openmrs.org/) is an open-source platform designed to manage electronic medical records (EMRs) in low-resource environments. It provides a framework that allows developers to extend its core functionality through custom modules and APIs. + +## Integration Options + +**1. Rest API:** OpenMRS offers a REST API that enables external applications to interact with its database and perform bulk operations. This option is ideal for applications requiring scheduled or bulk synchronization with OpenMRS. Refer to the OpenMRS REST API [documentation](https://wiki.openmrs.org/) for detailed guidelines on endpoints and payload formats. + +**2. Webhook:** OpenMRS does not natively support webhooks as a standard feature. However, the platform is highly extensible and allows for customization through its module system. More details can be found on the OpenMRS [documentation page​](https://wiki.openmrs.org/). + +## Authentication + +When integrating with OpenMRS via OpenFn, **Basic Authentication** is supported. See this adaptor's [Configuration docs](/adaptors/packages/openmrs-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: + +``` +{ + "instanceUrl": "http://openmrs.com/instance/url", + "password":"test", + "username":"test" +} +``` + +### Helpful Links + +1. [OpenMRS Developer Guide](https://openmrs.atlassian.net/wiki/spaces/docs/pages/25476048/Developer+Guide) +2. Community Forums: [OpenMRS Talk](https://talk.openmrs.org/) + +### Implementation Examples + +1. OpenFn Prototype for Médecins Sans Frontières (MSF) LIME Project - OpenMRS -> DHIS2 sync: [https://github.com/OpenFn/openfn-lime](https://github.com/OpenFn/openfn-lime) + + + + diff --git a/adaptors/primero.md b/adaptors/primero.md index a1545169db73..155ce35c995b 100644 --- a/adaptors/primero.md +++ b/adaptors/primero.md @@ -63,7 +63,7 @@ See the examples section more sample Primero jobs. ### Integration tips - Data forwarding can be enabled in Primero. There is a webhook that can forward - case information to a designated URL endpoint (e.g., OpenFn Inbox). This data + case information to a designated URL endpoint (e.g., OpenFn Inbox). This feature requires a backend configuration update that the Primero support team can help with. The data forwarding can happen automatically on insert of a new case, as well as on-demand when a user clicks the `Sync` button (which may be added to the page layout if this feature is in use). diff --git a/adaptors/rapidpro.md b/adaptors/rapidpro.md new file mode 100644 index 000000000000..c062ebecabdc --- /dev/null +++ b/adaptors/rapidpro.md @@ -0,0 +1,42 @@ +--- +title: RapidPro Adaptor +--- + +## About RapidPro + +[RapidPro](https://app.rapidpro.io/) is an open-source platform for building scalable, automated messaging workflows. It is widely used in development and humanitarian contexts for managing communication via SMS, social media, and other messaging channels. + + +## Integration Options + +**RapidPro supports two primary integration options:** + +**1. Rest API:** RapidPro has an available REST API that enables external services like OpenFn to pull data RapidPro, or push data from external apps to RapidPro. This option suits scheduled, bulk syncs or workflows that must update data in RapidPro with external information. See [functions](/adaptors/packages/rapidpro-docs) for more on how to use this adaptor to work with the API. + +**2. Webhook:** RapidPro also has a Webhook or Data Forwarding to push data from Rapidpro to external systems. This option is suited for real-time, event-based data integration. Check out the RapidPro [developer documentation](https://docs.rapidpro.io/webhooks/) to learn how to set up a webhook to push data to OpenFn. + +## Authentication + +When integrating with RapidPro via OpenFn, one primary authentication method is supported: **Personal Access Token (PAT)**. See this adaptor's [Configuration docs](/adaptors/packages/rapidpro-configuration-schema) for more on 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: + +``` +{ + "host": "https://app.rapidpro.io/", + "token": "#Super-sSCrecrete-token" +} +``` + +### Helpful Links + +1. [RapidPro API documentation](https://rapidpro.io/api/v2/) +2. [RapidPro Community](https://community.rapidpro.io/) + +### Implementation Examples + +1. Sample RapidPro -> DHIS2 sync: [https://github.com/OpenFn/rapidpro-dhis2](https://github.com/OpenFn/rapidpro-dhis2) + + + + diff --git a/adaptors/sftp.md b/adaptors/sftp.md new file mode 100644 index 000000000000..af2a5fe78c49 --- /dev/null +++ b/adaptors/sftp.md @@ -0,0 +1,39 @@ +--- +title: SFTP Adaptor +--- + +## About SFTP + +[SFTP (Secure File Transfer Protocol)](https://www.techtarget.com/searchcontentmanagement/definition/Secure-File-Transfer-Protocol-SSH-File-Transfer-Protocol) is a secure method for transferring files between systems over an encrypted SSH connection. It is widely used for securely uploading, downloading, and managing files on remote servers. + +Using this adaptor, you can read and write files (e.g., `csv`, `xls`, `json` files) saved on a SFTP server. + +## Integration Options + +**Direct File Transfers:** SFTP allows users to manually or programmatically transfer files between a local and remote system. See [functions](/adaptors/packages/sftp-docs) for more on how to use this adaptor to work with an SFTP server. + +## Authentication + +When integrating with a SFTP server via OpenFn, you can provide a `username` and `password` for an authorized user to authenticate. See this adaptor's [Configuration docs](/adaptors/packages/sftp-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: + +``` +{ + "host": "191.173.128.88", + "username": "name", + "password": "pwd" +} +``` + +### Helpful Links +1. [Best Practices for SFTP](https://www.ssh.com/academy/ssh/sftp) + +### Implementation Examples + +1. Women for Women International - SFTP -> Salesforce sync: [https://github.com/OpenFn/women-for-women](https://github.com/OpenFn/women-for-women) + + + + + diff --git a/docs/build-for-developers/cli-collections.md b/docs/build-for-developers/cli-collections.md new file mode 100644 index 000000000000..504700a22556 --- /dev/null +++ b/docs/build-for-developers/cli-collections.md @@ -0,0 +1,264 @@ +--- +title: Collections CLI Usage +sidebar_label: Collections +slug: /collections-cli +--- + +The OpenFn CLI includes support for reading from and writing to +[Collections](/documentation/build/collections): a key/value store built into +OpenFn. + +:::caution Versions + +Collections support was added to the CLI in version 1.9.0. + +Run `npm install -g @openfn/cli` to update or install. + +::: + +You can use the CLI to: + +- Explore the contents of Collections without running a Workflow +- Experiment with query syntax to get the keys you need +- Update mapping objects and lookup tables from local (or source-controlled) + files +- Manually remove unneeded data + +:::tip + +Got feedback? Want more Collections support in the CLI? Post a Feature Request +to [community.openfn.org](https://community.openfn.org/c/feature-requests)! + +::: + +Get started with the Collections API with `openfn collections --help` + +You'll need a Personal Access Token (PAT) to access a collection. You'll also +need to ensure a collection has been created before you can read or write to +it - see +[Managing Collections](http://localhost:3000/documentation/build/collections#managing-collections) + +:::info Trying to use Collections in a CLI workflow? + +These docs explain how to use the `openfn collections` CLI command. + +If you're running an expression or workflow through the CLI, you need to use the +collections adaptor - check out the +[Collections Adaptor Docs](http://localhost:3000/adaptors/collections#cli-usage) +for detauls + +::: + +## Getting a PAT + +Data inside Collections is securely stored under a Project, and access is +strictly only allowed to users with access to that Project. So if you want to +access a Collection, you have to tell the server who you are. + +We do this using Personal Access Tokens. See +[Create and Manage API Tokens](/documentation/api-tokens#about-api-tokens) for +more details. + +One you have a PAT, you need to pass it in to the CLI. The easiest way to do +this is to set your `OPENFN_PAT` env var, which the CLI will use automatically. + +If you're using multiple access tokens, you can pass `--token` to the CLI to +override the default. + +```bash +openfn collections get my-collection \* --token $MY_OPENFN_PAT +``` + +:::tip + +The rest of this guide assumes that the `OPENFN_PAT` env var has been set. So +long as it has, as you're using a server which has a `my-collection` collection, +all examples will work. + +::: + +## Setting a server + +By default, the CLI will point to our primary platform at +https://app.openfn.org. + +If you're running from open source or using a different deployment, you'll also +need to tell the CLI which Collections server to use. + +You can do this by passing `--lightning` directly: + +```bash +openfn collections get my-collection \* --lightning http://localhost:4000 +``` + +Or by setting the `OPENFN_ENDPOINT` environment variable. + +:::tip + +To see which server the CLI is using, ask for debug-level logging in your +output: + +```bash +openfn collections get my-collection \* --log debug +``` + +::: + +## Fetching items + +You can fetch items from a Collection by passing a collection name and a key, or +key pattern (like `*` for "everything", or `2024*` for keys starting with +`2024`) + +```bash +openfn collections get +``` + +For example, to get everything from `my-collection`, run: + +```bash +openfn collections get my-collection \* +``` + +:::tip + +In unix shells (MacOS or Linux), the `*` character has special meaning. So if +you want to get all items, you have to escape it or quote it: + +``` +openfn collections get my-collection \* +``` + +Including `*` in a pattern string should still work: + +``` +openfn collections get my-collection 2024* +``` + +::: + +Collections are saved as strings, but will be serialized to JSON in the output. + +By default the CLI will log downloaded values to your shell. To write to disk, +pass `--output` or `-o` with a file path relative to your working directory: + +```bash +openfn collections get my-collection \* -o /tmp/my_collection.json +``` + +To format the output to make it easier to read, add the `--pretty` flag for +pretty-printing: + +```bash +openfn collections get my-collection \* -o /tmp/my_collection.json --pretty +``` + +It's important to understand that the output works a bit differently if you're +getting one specific item with a single key or getting many items with a key-pattern. + +A single key always returns its value "raw" or "verbatim", without the key +attached. So for a key `item-1` which holds a JSON object as a value, then this: + +```bash +openfn collections get my-collection item-1 +``` + +Will download and save something like this: + +```js +{ + "id": "item-1" + /* ... other properties of the value */ +} +``` + +If you use a key-pattern to retrieve data, the value is output in multi-item +mode: which is a JSON object where the key is the item's key, and the value is +the item's value: + +So if we get all items whose key starts with `item-`: + +```bash +$ openfn collections get my-collection item-1* +``` + +The resulting data will look like this: + +```json +{ + "item-1": { + "id": "item-1" + /* ... other properties of the value */ + }, + "item-10": { + "id": "item-10" + /* ... other properties of the value */ + } +} +``` + +## Uploading items + +You can use the `collections` command to upload data to a collection. When +uploading, values always come from a file on disk. In this example we'll use +JSON files, but if you're uploading a single value it doesn't have to be valid +JSON. + +The `set` command has two modes. To upload a single item, use: + +```bash +openfn collections set +``` + +This will read the data in `path/to/value.json` as a string, and upsert it under +the provided key. Key patterns are not supported. + +To bulk upsert multiple values, use: + +```bash +openfn collections set --items +``` + +The `items.json` file must contain a JSON object where the keys are item keys +and the values are item values (just like the multi-item get command returns): + +```json +{ + "item-1": { + "id": "item-1" + /* ... other properties of the value */ + }, + "item-10": { + "id": "item-10" + /* ... other properties of the value */ + } +} +``` + +:::tip + +Remember that Collections always uses an _upsert_ strategy when uploading new +items. + +This means that if a key does not exist, it will be created and assigned a +value. If it already exists, its value will be updated. + +::: + +## Removing items + +You can also remove items from a collection with the `collections remove` +command: + +```bash +openfn collections remove +``` + +Key-patterns are supported and allow you to remove multiple keys. + +Use `--dry-run` to get a list of the keys that would be deleted without actually +running the delete: + +```bash +openfn collections remove my-collection 2024* --dry-run +``` diff --git a/docs/build/collections.md b/docs/build/collections.md index b818c827972d..d68dae597c66 100644 --- a/docs/build/collections.md +++ b/docs/build/collections.md @@ -55,10 +55,20 @@ uploaded to a collection using the CLI. ## Collections Basics -Data is stored in Collections as key-value pairs, where the key is a unique -identifier for some data (like a UUID, or timestamp). The value is always a -string - although JSON objects will be automatically serialized to a string -using the Collections API. +:::tip + +The Collections API is automatically available to all Workflows and does not +require any credentials. Authentication with the OpenFn platform is managed for +you. + +You can use the Collections API with any adaptor. + +::: + +Data is stored as key-value pairs, where the key is a unique identifier for +some data (like a UUID, or timestamp). The value is always saved as a string +(although you can pass JSON-compatible objects directly, which will be +automatically serialized by the Collections API). Keys can be fetched in bulk and filtered by _pattern_. For example, the pattern `2024*` will match all keys which start with `2024`. Designing keys to have an @@ -74,6 +84,36 @@ collections.get('openfn-patient-registrations', '2024*').then(state => { }); ``` +Returned items are written to state.data as an array of `[{ key, value }]` +pairs: + +```js +{ + "data": { + "20240102-5901257": { + "name": "Tom Waits", + "id": "5901257", + }, + "20240213-0183216": { + "name": "Billie Holiday", + "id": "0183216", + } + } +} +``` + +If fetching a single item (i.e. no `*` in the key), it will be written directly +to `state.data` with no key: + +```js +{ + "data": { + "name": "Billie Holiday", + "id": "0183216", + } +} +``` + Every key permanently saves its creation date, so as well as fetching by key-pattern, you can also filter keys by date. This example fetches all keys created before 30th September 2024: @@ -117,6 +157,15 @@ collections.set('openfn-demo', 'commcare-fhir-value-mappings', { }); ``` +If setting multiple values at once, pass a key generator function instead of an +id to generate a key for each item. For example, if several value are saved in +an array on `state.data`: + +```js +collections.set('openfn-demo', (patient, state) => patient.id, $.patients); +``` + +The key generator will be called with each value and must return a string key. ## Managing Collections diff --git a/docs/contribute/openfn-roadmap.md b/docs/contribute/openfn-roadmap.md index e2b49175d205..4bb21dbb8127 100644 --- a/docs/contribute/openfn-roadmap.md +++ b/docs/contribute/openfn-roadmap.md @@ -13,7 +13,7 @@ progress [here](#what-are-we-currently-working-on). ## Our approach to product development At OpenFn, we follow the [Shape Up approach](https://basecamp.com/shapeup) to -help our small engineering team build _meaningul_ products and features faster +help our small engineering team build _meaningful_ products and features faster without compomising on quality. With Shape Up in place, we typcially commit to _projects_ that can be delivered in a 4-6 week period with multiple releases based on QA approval within the building cycle. We also proiritize feedback and @@ -46,41 +46,41 @@ immediate roadmap. ### See [**_Now_**](https://github.com/orgs/OpenFn/projects/3/views/1) 🚧 for what's been funded and is currently being built -### See [**_Next_**](https://github.com/orgs/OpenFn/projects/3/views/2) 📝 for what's being shaped and _may_ be funded in the next cycle - ### See [**_Epics_**](https://github.com/orgs/OpenFn/projects/3/views/7) 🤔 for a list of projects that we're considering, roughly-prioritized ### See [**_Bugs_**](https://github.com/orgs/OpenFn/projects/3/views/22) 🐞 for reported bugs -We will update this site periodically (ideally after each cycle, typically -lasting between 2-6 weeks) to reflect our progress on major items. You can also -keep track of all new features, changes, and bug fixes in our +We will update this site monthly to reflect our progress on major items. You can +also keep track of all new features, changes, and bug fixes in real-time via our [Changelog](https://openfn.github.io/lightning/changelog.html). ## How to **get involved** -We use [Canny](https://openfn.canny.io/feature-requests) to receive, track, -engage and manage new feature requests from the community of users of OpenFn -globally whilst giving users the ability to the upvote their favoritie and -mission critical feature request. +We collect feedback and new feature requests via our +[Community](https://community.openfn.org/c/feature-requests/) site. This allows +OpenFn core team and users to track, engage by upvoting their favorite and +mission critical feature requests. ### Upvote features 👍 -1. Go to [openfn.canny.io](https://openfn.canny.io/feature-requests) +1. Go to the community + [feature request board](https://community.openfn.org/c/feature-requests/) 2. Scroll down or use the filter and search features to see existing feature requests -3. Click on the (^) beside the request to upvote +3. Click on the (Vote) button beside the title of the request to upvote 4. If you want more upvotes for this feature request, share a link to the feature with your network ### Request a new feature 💡 -1. Go to [openfn.canny.io](https://openfn.canny.io/feature-requests) -2. Provide a very clear, concise and descriptive title for the feature (e.g., +1. Go to the community + [feature request board](https://community.openfn.org/c/feature-requests/) +2. Click on `+ New Topic` to create a new request. +3. Provide a very clear, concise and descriptive title for the feature (e.g., "Make the new workflow button green") -3. Describe the feature request in detail and why it's important to you -4. Share the feature request on the OpenFn community and across your - professional network for upvotes +4. Describe the feature request in detail and why it's important to you. Helpful + if you can add reference images and links. +5. Share the feature request on across your professional network for upvotes :::info Tip @@ -116,26 +116,27 @@ OpenFn/Lightning is the fully open-source workflow automation platform at the core of the OpenFn Digital Public Good (learn more about the product [here](/documentation#openfn-v2-lightning-)). -| **Feature** | **`Status`** | **Target Timeline** | **Related Links** | **Description** | -| --------------------------------------------------------------------- | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1. Enable workflow snapshotting | Delivered | Q3 '24 | [Issue 1680](https://github.com/OpenFn/lightning/issues/1680) | Keep a snapshot of a snapshot based on a run or saved changes of the workflow. Allow users to be able to view snapshot and switch to the latest version of the workflow from a snapshot mode. | -| 2. Enable configurable concurrency by workflow | Delivered | Q3 '24 | [Issue 2002](https://github.com/OpenFn/lightning/issues/2022) | Allow users to control the limit of concurrent runs per workflow in a project. | -| 3. New workflow triggers (Kafka) | Delivered | Q3 '24 | [Issue 1801](https://github.com/OpenFn/lightning/issues/1801) | Enable a new trigger type that allows users to run workflows based on messages from a Kafka cluster. | -| 4. AI-enabled assitants | Delivered | Q3 '24 | [Issue 2193](https://github.com/OpenFn/lightning/issues/2193) | LLM based AI assitant that supports users with job writing, debugging and co-piloting their workflow design process. | -| 5. Invite new users as collaborators | Delivered | Q3 '24 | [Issue 1835](https://github.com/OpenFn/lightning/issues/1835) | Invite users who do not have OpenFn accounts to projects as collaborators. | -| 6. Allow users to create projects | Delivered | Q3 '24 | [Issue 1700](https://github.com/OpenFn/Lightning/issues/1700) | All users to create new projects from their dashboard. | -| 7. Allow users to export workorder history | Delivered | Q3 '24 | [Issue 1698](https://github.com/OpenFn/lightning/issues/1698) | Allow project users to be able to export workorder history. The workorder history contains ALL logs and data clips (Input and Output) associated with runs in a workorder. | -| 8. Project datastores and buffers | Shaped | Q4 '24 | [Issue 2190](https://github.com/OpenFn/lightning/issues/2190) | Allow users to configure a data store or buffer that allows temporary of storage of data that can be used in a workflow. | -| 9. Make User Onboarding better | Shaped | Q4 '24 | [Issue 2523](https://github.com/OpenFn/Lightning/issues/2523) | Control what is printed in run logs by specifying log levels and allow users to disable printing console.logs, for data privacy once workflows are handling production data. | -| 10. Snapshots and Audit Trail | Shaped | Q4 '24 | [Issue 2526](https://github.com/OpenFn/Lightning/issues/2526) | Control what is printed in run logs by specifying log levels and allow users to disable printing console.logs, for data privacy once workflows are handling production data. | -| 11. Implement Monaco Editor | Tracked | Q4 '24 | [Issue 2126](https://github.com/OpenFn/Lightning/issues/2126) | Implement monaco editor for code editor or log viewing across the platform | -| 12. Allow users to switch between sandbox and production modes | Tracked | Q4 '24 | [Issue 2524](https://github.com/OpenFn/Lightning/issues/2524) and [Issue 2525](https://github.com/OpenFn/Lightning/issues/2525) | Allow users to be able to switch between sandbox and production modes in their projects. | -| 13. Control log outputs | Tracked | Q4 '24 | [Issue 1755](https://github.com/OpenFn/Lightning/issues/1755) | Control what is printed in run logs by specifying log levels and allow users to disable printing console.logs, for data privacy once workflows are handling production data. | -| 14. Enable manual workflow triggers | Tracked | Q1 '25 | [Issue 2155](https://github.com/OpenFn/lightning/issues/2155) | Add funtionality that allows users to manually trigger workflow with JSON/CSV data as input data clip | -| 15. Redesign workflow canvas and inspector interface | Tracked | Q1 '25 | [Issue 2021](https://github.com/OpenFn/lightning/issues/2021) | Redesign the workflow canvas and inspector interface to make workflow design better to help user build workflow faster and easier. | -| 16. Improved History page filter | Tracked | Q1 '25 | [Issue 1791](https://github.com/OpenFn/lightning/issues/1791) | Extend workorder history page and enable cascading filtering. This is useful for debuging, failure recovery and auditability of the workflow. | -| 17. Enhanced websocket worker Monitoring | Tracked | Q1 '25 | [Issue 608](https://github.com/OpenFn/kit/issues/608) | Give users better visibility of what's happening on inside the worker, especially when an error occurs during run execution. | -| 18. Expanded Audit Trail and Node Authentication (ATNA) functionality | Tracked | Q1 '25 | [Issue 271](https://github.com/OpenFn/Lightning/issues/271) | Extend audit trail functionality to cover more aspects of ATNA, reference [OpenHIE IOL requirement IOLWF-1](https://guides.ohie.org/arch-spec/openhie-component-specifications-1/openhie-interoperability-layer-iol#openhie-iol-workflow-requirements). | +| **Feature** | **Status** | **Timeline** | **Link(s)** | **Description** | +| ---------------------------------------------------- | ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| • Workflow snapshots | Delivered | Q3 '24 | [Issue 1680](https://github.com/OpenFn/lightning/issues/1680) | Keep a snapshot of a snapshot based on a run or saved changes of the workflow. Allow users to be able to view snapshot and switch to the latest version of the workflow from a snapshot mode. | +| • Configurable run concurrency by workflow | Delivered | Q3 '24 | [Issue 2002](https://github.com/OpenFn/lightning/issues/2002) | Allow users to control the limit of concurrent runs per workflow in a project. | +| • Kafka workflow trigger | Delivered | Q3 '24 | [Issue 1801](https://github.com/OpenFn/lightning/issues/1801) | A new workflow trigger type that creates a new workorder when a Kafka message is received . | +| • Allow users to create new projects | Delivered | Q3 '24 | [Issue 1700](https://github.com/OpenFn/lightning/issues/1700) | Allow users to create new projects from the project list page. | +| • Export work order history with logs and data clips | Delivered | Q3 '24 | [Issue 1698](https://github.com/OpenFn/lightning/issues/1698) | Allow project users to be able to export workorder history. The workorder history contains ALL logs and data clips (Input and Output) associated with runs in a workorder. | +| • Project datastores and buffers | Delivered | Q4 '24 | [Issue 2190](https://github.com/OpenFn/lightning/issues/2190) | Allow users to configure a data store or buffer that allows temporary of storage of data that can be used in a workflow. | +| • Make User Onboarding better with resources | Delivered | Q4 '24 | [Issue 2523](https://github.com/OpenFn/Lightning/issues/2523) | Control what is printed in run logs by specifying log levels and allow users to disable printing console.logs, for data privacy once workflows are handling production data. | +| • Snapshots and Audit Trail | In dev | Q4 '24 | [Issue 2526](https://github.com/OpenFn/Lightning/issues/2526) | Control what is printed in run logs by specifying log levels and allow users to disable printing console.logs, for data privacy once workflows are handling production data. | +| • Enable Save and Sync on Canvas and Inspector | In dev | Q4 '24 | [Issue 2707](https://github.com/OpenFn/lightning/issues/2707) | Make version control more accessible to user by allowing users to save and sync their changes to GitHub via the canvas and inspector. | +| • Make AI Assistant available for all users | In dev | Q4 '24 | [Issue 2613](https://github.com/OpenFn/lightning/issues/2613) | Add AI Assistant to help users build workflows faster and easier. | +| • OpenFn Workflow JSON APIs | Shaped | Q4 '24 | [Issue 2126](https://github.com/OpenFn/Lightning/issues/2126) | Expose API endpoints that allows developers to interact with OpenFn from other platforms or within jobs. e.g create a new workflow with the jobs given a JSON payload. | +| • Manual Runs for Cron jobs | Shaped | Q4 '24 | [Issue 1880](https://github.com/OpenFn/Lightning/issues/1880) | Allow users to manually run cron triggered workflows with a custom cursor and run now button. | +| • Workflow library | Tracked | Q1 '25 | [Issue 2723](https://github.com/OpenFn/lightning/issues/2723) | Create a library of common workflows that users can easily access and clone for use in their projects. | +| • Load local adaptors into lightning | Tracked | Q1 '25 | [Issue 2155](https://github.com/OpenFn/lightning/issues/2155) | Enable lightning to use local adaptors to allow developers quickly test adaptors locally without deploying to npm | +| • Allow custom inputs for manual runs | Tracked | Q1 '25 | [Issue 2155](https://github.com/OpenFn/lightning/issues/2155) | Users should be able to trigger a manual run with a custom input data. The input data can a raw JSON, CSV, I/O data clip or dataset from project collections | +| • Redesign workflow canvas and inspector interface | Tracked | Q1 '25 | [Issue 2722](https://github.com/OpenFn/lightning/issues/2722) | Redesign the canvas and inspector to make user experience and workflow building better for users. | +| • Enable sandbox and production modes | Tracked | Q1 '25 | [Issue 2524](https://github.com/OpenFn/Lightning/issues/2524) and [Issue 2525](https://github.com/OpenFn/Lightning/issues/2525) | Allow users to be able to switch between sandbox and production modes in their projects. | +| • Control log output and levels | Tracked | Q1 '25 | [Issue 1755](https://github.com/OpenFn/Lightning/issues/1755) | Control what is printed in run logs by specifying log levels and allow users to disable printing console.logs, for data privacy once workflows are handling production data. | +| • Enhanced websocket worker Monitoring | Tracked | Q1 '25 | [Issue 608](https://github.com/OpenFn/kit/issues/608) | Give users better visibility of what's happening on inside the worker, especially when an error occurs during run execution. | _You can follow Lightning's progress and track delivered features in the [Changelog](https://openfn.github.io/lightning/changelog.html)._ @@ -147,23 +148,21 @@ databases, and even raw data files, enabling interoperability with any information system ([read more](/adaptors/)). Adaptors, alongside OpenFn's workflow engine, enable automated workflows that cut across digital systems. -| **Feature** | **`Status`** | **Target Timeline** | **Related Links** | **Description** | -| ------------------------------------------------------------------------------------------------- | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1. Add "magic" functions to existing, in-demand adaptors | Delivered | Q1 2024 | [Issue 243](https://github.com/OpenFn/adaptors/issues/243) | Add functions, dynamic lists, and shortcuts to fast-track workflow configuration for key adaptors including HTTP, [DHIS2](https://dhis2.org/), [CommCare](https://www.dimagi.com/commcare/), & [OpenMRS](https://openmrs.org/) | -| 2. New [`OpenMRS`](https://openmrs.org/) adaptor version | Delivered | Q2 2024 | [See existing adaptor docs](/adaptors/packages/openmrs-readme) | To ensure compliance with OpenMRS v3 | -| 3. Enhancements to [`FHIR`](http://www.hl7.org/fhir/) & [`OpenHIM`](http://openhim.org/) adaptors | Delivered | Q3 2024 | See existing adaptors for [FHIR](/adaptors/packages/fhir-docs) and [OpenHIM](/adaptors/packages/openhim-docs) | To rebuild the existing 2021 [OpenFn Instant-OpenHIE reference demo](/documentation/get-started/standards#openhie-standard-architecture) to highlight the exchange of data between existing non-FHIR digital health tools and a HAPI FHIR server. (OpenFn Lightning is OpenHIE-compliant and can be used as a workflow engine for the OpenHIE Interoperability layer - [learn more here](/documentation#openfn-v2-lightning-#standards-and-compliance-matter).) We also want to demonstrate data exchange between existing non-FHIR digital health tools and key components of Google’s [Open Health Stack](https://developers.google.com/open-health-stack) and [Cloud Healthcare API](https://cloud.google.com/healthcare-api/docs/concepts/fhir) | -| 4. Enhancements to the [`OCL`](https://openconceptlab.org/) adaptor | Tracked | Q4 2024 | [See existing adaptor docs](/adaptors/packages/ocl-readme) | To ensure that mappings stored in OCLs can be more easily access and processed as inputs in OpenFn/Lightning workflows | -| 5. Implement [MOSIP](https://mosip.io/#1) Adaptor | Tracked | Q1 2025 | [Issue 737](https://github.com/OpenFn/adaptors/issues/737) | Enable OpenFn workflows to integrate with the MOSIP platform for identity management use cases across countries. | -| 6. Implement [OpenCRVS](https://www.opencrvs.org/) Adaptor | Tracked | Q1 2025 | [Issue 736](https://github.com/OpenFn/adaptors/issues/736) | Enable OpenFn workflows to integrate with OpenCRVS for CRVS workflows.| -| 7. Implement [ArcGIS](https://www.arcgis.com/) Adaptor | Tracked | Q1 2025 | [Issue 738](https://github.com/OpenFn/adaptors/issues/738) | Enable Geospatial data management in OpenFn Workflows.| -| 8. Support Personal Access Tokens in DHIS2 | Tracked | Q1 2025 | [Issue 697](https://github.com/OpenFn/adaptors/issues/697) | Extend the DHIS2 Adaptor to support Personal Access Tokens (PAT).| +| **Feature** | **Status** | **Timeline** | **Link(s)** | **Description** | +| ------------------------------------------------------------------------------------------------ | ---------- | ------------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| • Develop an [`OpenLMIS`](https://openlims.org/) adaptor | Delivered | Q3 2024 | [Issue 533](https://github.com/OpenFn/adaptors/issues/533) | Enable users to build workflows that interface with OpenLIMS | +| • Enhancements to [`FHIR`](http://www.hl7.org/fhir/) & [`OpenHIM`](http://openhim.org/) adaptors | Delivered | Q3 2024 | See existing adaptors for [FHIR](/adaptors/packages/fhir-docs) and [OpenHIM](/adaptors/packages/openhim-docs) | To rebuild the existing 2021 [OpenFn Instant-OpenHIE reference demo](/documentation/get-started/standards#openhie-standard-architecture) to highlight the exchange of data between existing non-FHIR digital health tools and a HAPI FHIR server. (OpenFn Lightning is OpenHIE-compliant and can be used as a workflow engine for the OpenHIE Interoperability layer - [learn more here](/documentation#openfn-v2-lightning-#standards-and-compliance-matter).) We also want to demonstrate data exchange between existing non-FHIR digital health tools and key components of Google's [Open Health Stack](https://developers.google.com/open-health-stack) and [Cloud Healthcare API](https://cloud.google.com/healthcare-api/docs/concepts/fhir) | +| • Enhancements to the [`OCL`](https://openconceptlab.org/) adaptor | Tracked | Q1 2025 | [See existing adaptor docs](/adaptors/packages/ocl-readme) | To ensure that mappings stored in OCLs can be more easily access and processed as inputs in OpenFn/Lightning workflows | +| • Implement [MOSIP](https://mosip.io/#1) Adaptor | Tracked | Q1 2025 | [Issue 737](https://github.com/OpenFn/adaptors/issues/737) | Add an adaptor that enables users to integrate with MOSIP for identity management use cases across countries. | +| • Implement [OpenCRVS](https://www.opencrvs.org/) Adaptor | Tracked | Q1 2025 | [Issue 736](https://github.com/OpenFn/adaptors/issues/736) | Enable OpenFn workflows to integrate with OpenCRVS for CRVS workflows. | +| • Implement [ArcGIS](https://www.arcgis.com/) Adaptor | Tracked | Q1 2025 | [Issue 738](https://github.com/OpenFn/adaptors/issues/738) | Add an ARCGIS adaptor for users to build weorkflow that manage data sync between source and online maps with OpenFn Workflows. | +| • Support Personal Access Tokens in DHIS2 | Tracked | Q1 2025 | [Issue 697](https://github.com/OpenFn/adaptors/issues/697) | Extend the DHIS2 Adaptor to support Personal Access Token(PAT). | ### Docs Roadmap -| **Feature** | **`Status`** | **Target Timeline** | **Related Links** | **Description** | -| ----------------------------------------------------------- | ------------ | ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1. OpenFn and the [OpenHIE](https://ohie.org/) architecture | Delivered | 2024 | [See current docs](/documentation#openfn-v2-lightning-#standards-and-compliance-matter) | New page dedicated to how OpenHIE aligns with OpenHIE architecture; expansion of the existing small section on standards | -| 2. New Lightning User Guidance | In Progress | 2024 | To be hosted on docs.openfn.org | New documentation, videos, and other user guidance on how to use OpenFn/Lightning and how to migrate existing OpenFn/platform projects to Lightning (the new OpenFn "v2") | +| **Feature** | **Status** | **Timeline** | **Link(s)** | **Description** | +| ----------------------------- | ----------- | ------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| • New Lightning User Guidance | In Progress | 2025 | To be hosted on docs.openfn.org | New documentation, videos, and other user guidance on how to use OpenFn/Lightning and how to migrate existing OpenFn/platform projects to Lightning (the new OpenFn "v2") | ## Have questions, feedback or found a bug? diff --git a/docs/contribute/writing-code.md b/docs/contribute/writing-code.md index 74c19bd587c2..51fc6555f523 100644 --- a/docs/contribute/writing-code.md +++ b/docs/contribute/writing-code.md @@ -12,11 +12,11 @@ There are three ways you can contribute to the OpenFn DPG: ### 1. Build or extend OpenFn adaptors - Requires knowledge of Javascript and Typescript -- See the [README.md](https://github.com/OpenFn/lightning#contribute-to-this-project) to learn how to contribute +- See the [README.md](https://github.com/OpenFn/adaptors#contributing) to learn how to contribute ### 2. Add or improve a feature on the OpenFn Lightning platform - Requires knowledge of Elixir and Pheonix Liveview -- See the [README.md](https://github.com/OpenFn/adaptors#contributing) to learn how to contribute +- See the [README.md](https://github.com/OpenFn/lightning#contribute-to-this-project) to learn how to contribute ### 3. Add to or improve our documentation diff --git a/docs/get-started/standards.md b/docs/get-started/standards.md index 9972963b4212..bdac96dc0c0c 100644 --- a/docs/get-started/standards.md +++ b/docs/get-started/standards.md @@ -147,14 +147,14 @@ OpenFn solutions are: OpenFn is used by health organizations to connect multiple FHIR- and non-FHIR compliant systems in a secure, stable, and scalable manner. OpenFn can facilitate 2 categories of FHIR workflows: -### 1. Non-FHIR to FHIR +### 1. Non-FHIR to FHIR Data Exchange -OpenFn users can configure Workflows to convert non-FHIR data to FHIR-compliant formats, and then route to FHIR systems. +OpenFn users can configure workflows to convert non-FHIR data to FHIR-compliant formats, and then route to FHIR systems. For example, get data from CommCare mobile app, convert to FHIR, and send to national health system's FHIR store. ![nonFHIR Workflow](/img/workflow_nonfhir_fhir.png) -### 2.FHIR to FHIR +### 2. FHIR to FHIR Data Exchange OpenFn users can also configure Workflows to automate the exchange and routing of _already_ FHIR-compliant data to other FHIR-compliant systems. @@ -162,6 +162,14 @@ For example, get data from OpenMRS's FHIR API, and forward to the national healt ![FHIR Workflow](/img/workflow_fhir_fhir.png) +## FHIR Adaptors +OpenFn [adaptors](/adaptors) aim to fast-track integration setup with target applications (including FHIR endpoints!). The core team is currently working on a suite of FHIR-specific adaptors to enable interoperability with FHIR systems. + +- See [existing adaptors](/adaptors/fhir) +- See [Adaptors Wiki](https://github.com/OpenFn/adaptors/wiki/Generating-Fhir-Adaptors) for how to build your own FHIR adpator specific to your target FHIR Implementation Guide + +Version-specific adaptors (fhir-r4, fhir-r5) are coming soon! + ## Other Data Standards OpenFn Workflows can automate data transformation, cleaning, and formatting rules to ensure compliance with _your_ organization's specific standards. diff --git a/package.json b/package.json index 46fd827deaf1..63d8248ff648 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "generate-library": "docusaurus generate-library", "generate-adaptors": "docusaurus generate-adaptors", "start": "docusaurus generate-adaptors & docusaurus start", - "start:dev": "docusaurus generate-adaptors -m && docusaurus start", + "start:dev": "docusaurus generate-adaptors -m && docusaurus generate-library && docusaurus start", "start-offline": "docusaurus start", "build": "docusaurus build", "swizzle": "docusaurus swizzle", @@ -62,4 +62,4 @@ "cytoscape": "3.28.1" }, "packageManager": "yarn@3.2.3" -} +} \ No newline at end of file diff --git a/sidebars-main.js b/sidebars-main.js index 73552380fb76..91db46d24e10 100644 --- a/sidebars-main.js +++ b/sidebars-main.js @@ -122,6 +122,7 @@ module.exports = { 'build-for-developers/cli-usage', 'build-for-developers/cli-walkthrough', 'build-for-developers/cli-challenges', + 'build-for-developers/cli-collections', ], }, { diff --git a/yarn.lock b/yarn.lock index 26208d22395e..daa24ff00681 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5804,13 +5804,13 @@ __metadata: linkType: hard "cross-spawn@npm:^7.0.0, cross-spawn@npm:^7.0.3": - version: 7.0.3 - resolution: "cross-spawn@npm:7.0.3" + version: 7.0.6 + resolution: "cross-spawn@npm:7.0.6" dependencies: path-key: ^3.1.0 shebang-command: ^2.0.0 which: ^2.0.1 - checksum: 671cc7c7288c3a8406f3c69a3ae2fc85555c04169e9d611def9a675635472614f1c0ed0ef80955d5b6d4e724f6ced67f0ad1bb006c2ea643488fcfef994d7f52 + checksum: 8d306efacaf6f3f60e0224c287664093fa9185680b2d195852ba9a863f85d02dcc737094c6e512175f8ee0161f9b87c73c6826034c2422e39de7d6569cf4503b languageName: node linkType: hard @@ -10782,11 +10782,11 @@ __metadata: linkType: hard "nanoid@npm:^3.3.7": - version: 3.3.7 - resolution: "nanoid@npm:3.3.7" + version: 3.3.8 + resolution: "nanoid@npm:3.3.8" bin: nanoid: bin/nanoid.cjs - checksum: d36c427e530713e4ac6567d488b489a36582ef89da1d6d4e3b87eded11eb10d7042a877958c6f104929809b2ab0bafa17652b076cdf84324aa75b30b722204f2 + checksum: dfe0adbc0c77e9655b550c333075f51bb28cfc7568afbf3237249904f9c86c9aaaed1f113f0fddddba75673ee31c758c30c43d4414f014a52a7a626efc5958c9 languageName: node linkType: hard