intro.mdx

id	adaptors-intro
title	Adaptors
sidebar_label	Introduction
slug	/

import { generateList } from '/static/js/components/adaptorList'; import { compareVersions } from 'compare-versions'; import publicPaths from './packages/publicPaths.json';

Connect Anything.

First, it's important to note that OpenFn can connect to any system via HTTP, but our community has also built dozens of "adaptors" to save time & money while connecting to most commonly used digital public goods and key ICT4D systems.

You can even run web scraping or browser automation tools with OpenFn. It's almost like a universal translator... 🖖

What's an adaptor?

An adaptor is an open-source Javascript or Typescript module that provides OpenFn users with a clean set of helper functions that help communicate with a specific external system.

An adaptor sits between the OpenFn platform (ie, app.openfn.org) and some backing service or system (e.g., DHIS2, Salesforce, Postgres).

Its job is to provide a clean, high-level JavaScript interface to uses writing workflows in OpenFn. Users who write OpenFn job code are usually inexperienced programmers, and rarely experts in all the systems that a workflow has to connect with. A good adaptor will make that user's journey easier.

In the past, we often referred to them as "language packages" and the two terms are sometimes used interchangeably, but the preferred way of communicating about adaptors is as follows:

• "What adaptor is that job using?" ("That job is using language-dhis2.")
• "The DHIS2 adaptor is called language-dhis2."
• "I don't have the right adaptor for this job, let me install it by running npm install @openfn/language-dhis2.

In short, most adaptors follow the naming convention @openfn/language-xyz.

Adaptor Badges

OpenFn uses badges to label adaptors based on how they are built and maintained. The scale being used is:

• Actively maintained adaptor : Core

  Core adaptors are actively maintained by the OpenFn team and/or trusted partners. They receive regular updates, security fixes, and documentation improvements.

• Newly created adaptor by an external contributor: Community

  Community adaptors are contributed by external developers and may not follow a regular maintenance cadence. Contributions and PRs are welcome.

• Adaptors not actively maintained: Legacy

  Legacy adaptors are not actively maintained and may not receive updates.

Learn More About Adaptors

Explore this YouTube playlist to gain a deeper understanding of OpenFn adaptors.

<iframe width="560" height="315" src="https://www.youtube.com/embed/videoseries?si=mnfXiLEM83eUzADd&list=PL1pD3-abjHJ1cSQAoMd_ODCU_AauvyZeL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen ></iframe>

Adaptors vs. Workflows

Adaptors are reusable components that make connecting with a specific app easier, whereas Workflows are the project-specific processes that you want to automate. OpenFn users will always leverage Adaptors to better understand how to work with specific APIs, to access Adaptor helper functions (or "shortcuts") to more quickly build Workflows, and to handle authenticatio. See the below diagram.

Where to find adaptors

Here's a list of the {generateList().length} publicly supported OpenFn adaptors. Note that only some have been migrated to our new and have their docs sites served here. For the rest, you can view the docs and source by clicking into the adaptor and choosing your version.

{generateList().map(a => { return (

{a.module} {publicPaths.find(p => p.name == a.module) && ( <> {' ('} p.name == a.module).docsId }`} > docs {')'} )}

{publicPaths.find(p => p.name == a.module) ? (

The current{' '} p.name == a.module).docsId }`} > API docs , p.name == a.module).changelogId }`} > changelog , and p.name == a.module).readmeId }`} > developer readme for {a.module} are available here. You can view the source & documentation via these links:

) : (

This adaptor hasn't been migrated yet, but it still works just fine and you can view the source & documentation via these links:

)}

{a.versions .sort((a, b) => compareVersions(b.version, a.version)) .map(v => { return (
• {v.version} {' '}
); })}

); })}

On OpenFn

When creating or editing a job step, you can choose the adaptor to run the job. This way you "import" the needed operations. Simply open the dropdown list of adaptors, and click on one.

On npm

Most of our adaptors are also available on npmjs.com.

Don't see an adaptor for your app?

Explore our "universal" adaptors that support a wide variety of protocols, such as:

• HTTP
• SFTP

Or build your own (see below)!

Building and extending adaptors

See the Github Adaptors wiki for the technical guide to developing adaptors.

Adaptors' source code and technical documentation for developing or extending existing adaptors can be found on this linked repository: https://github.com/OpenFn/adaptors

:::info Questions or Adaptor Requests?

Head to community.openfn.org to collaborate with others or to provide adaptors feedback.

:::