From 297a9e14104f8c78b03e0f4dd567650d470c4990 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Fri, 5 Jun 2026 16:58:33 +0300 Subject: [PATCH 1/2] add warning for image processing in openfn --- docs/jobs/image-handling.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/jobs/image-handling.md b/docs/jobs/image-handling.md index 02cca348eb64..0f9be4d5e8d0 100644 --- a/docs/jobs/image-handling.md +++ b/docs/jobs/image-handling.md @@ -14,6 +14,18 @@ need additions to adaptors. ::: +:::warning Platform limitations for image manipulation + +OpenFn does **not** natively support advanced image manipulation such as resizing, compression, format conversion, or writing EXIF metadata. + +- **No external binary access** — platform jobs run in a sandboxed Node.js environment and cannot invoke external programs such as `imagemagick`, `ffmpeg`, or similar tools. +- **EXIF metadata** — writing EXIF data to image files is not supported in the OpenFn job environment due to technical constraints in the Node.js runtime. +- **Supported scope** — the supported use cases are (a) fetching an image via URL and forwarding it as-is to a downstream system, and (b) encoding it as a Base64 string for embedding in JSON payloads. Avoid Base64 for large files as it significantly increases payload size. + +If your workflow requires actual image transformation, pre-process the image outside of OpenFn (e.g., in a dedicated microservice or cloud function) and pass the result to OpenFn. + +::: + ## Base64 (standard handling) In essence, the way to deal with images/PDFs/other files and be able to save @@ -57,7 +69,4 @@ fn(state => { ## Summary -Most use cases should **_Just Work ™️_**. If you have a specific need involving -large file sizes or high volumes and you need to process images, rather than -just moving them from place to place, you might need to make a change to your -adaptor. +Most use cases — fetching an image from one system and uploading it to another — should **_Just Work ™️_**. For workflows that require transforming the image itself (resize, compress, reformat, add EXIF data), see the limitations note above; those operations must happen outside of OpenFn. From c2dfe94e7233766e8321eba16aa62fa6bebff075 Mon Sep 17 00:00:00 2001 From: Emmanuel Evance Date: Wed, 8 Jul 2026 10:50:17 +0300 Subject: [PATCH 2/2] update image manipulation docs --- docs/jobs/image-handling.md | 60 ++++++++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 10 deletions(-) diff --git a/docs/jobs/image-handling.md b/docs/jobs/image-handling.md index 0f9be4d5e8d0..635e96937dd9 100644 --- a/docs/jobs/image-handling.md +++ b/docs/jobs/image-handling.md @@ -9,20 +9,28 @@ other binaries. This page explains how you do it. :::success The tl;dr: -Images and other binaries mostly **_Just Work™️_**. Edges cases might -need additions to adaptors. +Images and other binaries mostly **_Just Work™️_**. Edges cases might need +additions to adaptors. ::: -:::warning Platform limitations for image manipulation +:::info Advanced image manipulation -OpenFn does **not** natively support advanced image manipulation such as resizing, compression, format conversion, or writing EXIF metadata. +Need to resize, compress, strip embed EXIF metadata, or read metadata from an +image? Use the +[`image-utils` adaptor](https://docs.openfn.org/adaptors/packages/image-utils-docs), +which runs these operations natively in your job, no external microservice +required. See +[Image manipulation with the `image-utils` adaptor](#image-manipulation-with-the-image-utils-adaptor) +below for details. -- **No external binary access** — platform jobs run in a sandboxed Node.js environment and cannot invoke external programs such as `imagemagick`, `ffmpeg`, or similar tools. -- **EXIF metadata** — writing EXIF data to image files is not supported in the OpenFn job environment due to technical constraints in the Node.js runtime. -- **Supported scope** — the supported use cases are (a) fetching an image via URL and forwarding it as-is to a downstream system, and (b) encoding it as a Base64 string for embedding in JSON payloads. Avoid Base64 for large files as it significantly increases payload size. - -If your workflow requires actual image transformation, pre-process the image outside of OpenFn (e.g., in a dedicated microservice or cloud function) and pass the result to OpenFn. +- **No external binary access**: platform jobs still run in a sandboxed Node.js + environment and cannot invoke external programs such as `imagemagick` or + `ffmpeg`. The `image-utils` adaptor works entirely within the Node.js runtime, + so it doesn't need them. +- **Large files**: Base64 significantly increases payload size, so avoid it for + large files where possible; prefer working with Buffers (the default return + format for `image-utils` operations). ::: @@ -67,6 +75,38 @@ fn(state => { }); ``` +## Image manipulation with the `image-utils` adaptor + +For workflows that need to actually transform an image rather than just move it, +use the +[`image-utils` adaptor](https://docs.openfn.org/adaptors/packages/image-utils-docs). +It provides: + +```js +// resize an image to given `width`/`height` dimensions. +resize(state.data.buffer, { width: 1200, height: 1600 }); +// reduce image quality/file size until it meets a target `maxBytes`, down to a `minQuality` floor. +compress(state.data.buffer, { maxBytes: 700 * 1024, minQuality: 20 }); +// remove all EXIF metadata from an image. +stripMetadata($.data.photoBase64); +// write EXIF key-value pairs (e.g. `UserComment`) into a JPEG. +embedMetadata($.data.buffer, { UserComment: 'patient-id=42' }); +// read an image's dimensions, orientation, size, and EXIF data without modifying it. +metadata($.data.photoBase64); +``` + +Each operation accepts a Base64 string or Buffer and writes its result to +`state.data` (typically as a `buffer`, with `parseAs: 'base64'` available where +you need a string instead). + +See the +[`image-utils` adaptor documentation](https://docs.openfn.org/adaptors/packages/image-utils-docs) +for full details on each function's options and return values. + ## Summary -Most use cases — fetching an image from one system and uploading it to another — should **_Just Work ™️_**. For workflows that require transforming the image itself (resize, compress, reformat, add EXIF data), see the limitations note above; those operations must happen outside of OpenFn. +Most use cases — fetching an image from one system and uploading it to another — +should **_Just Work ™️_**. For workflows that require transforming the image +itself (resize, compress, strip/embed EXIF data, or read metadata), use the +[`image-utils` adaptor](https://docs.openfn.org/adaptors/packages/image-utils-docs) +as described above.