Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alumio.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Base64 Media Retriever is a configuration-based transformer that retrieves media files (such as product images) from a Magento 2 source and converts them into Base64-encoded strings for inclusion in the data payload. It replaces the deprecated prototype-based base64-media-retriever previously used in the Legacy Magento 2 Connector.
This component has been migrated from a prototype-based implementation to a configuration-based setup as part of the Legacy Magento 2 Connector replacement project.

​
Prototype vs Configuration-based

This is an important behavioral difference to understand before setting up this component.
Prototype-basedConfiguration-based
ReusabilityCan be reused across different flows by changing a few fieldsNot reusable across different purposes or payloads
FlexibilityOne prototype can serve multiple use cases(Not always) Each use case requires its own dedicated configuration
How to reuseModify fields directlyDuplicate the configuration and adjust as needed
If you need to transform a different payload structure or serve a different use case, you must duplicate this transformer and adjust the configuration accordingly. Do not modify an existing configuration as another Route already uses it.

​
Type

Transformer

​
Purpose

This transformer fetches media files referenced in the source payload (typically product images) and encodes them as Base64 strings. This is useful when the target system expects media to be embedded directly in the payload rather than referenced by URL.

​
Configuration

ParameterDescriptionRequired
media_base_urlThe base URL of the Magento 2 media storageYes
output_fieldThe field name in the output payload where the Base64 string will be storedYes
authenticationOptional : Authentication method to access the media endpointNo
allowed_mime_typesOptional : List of allowed media types to retrieve (e.g. image/jpeg, image/png)No

​
Input / Output

Input: Payload containing media file URLs or paths (JSON) Output: Same payload with media files replaced or enriched with Base64-encoded strings

​
Example Input

{
  "sku": "PROD-001",
  "url": "https://www.sample.org/leaf-blue.png"	
}

​
Example Output

{
  "sku": "PROD-001",
  "url": "https://www.sample.org/leaf-blue.png",
  "base64_output": "iVBORw0KGgoAAAANSUhEUgAA..."
}

​
Usage

  1. Navigate to Transformers in your Alumio environment.
  2. Search for or create a new Base64 Media Retriever transformer.
  3. Configure the media_url, and output_field parameters.
  4. Add this transformer to the relevant route in the transformation step, typically after the Subscriber and before the target Publisher.

​
Deprecated VS New

An example of the deprecated configuration:
Image

An example of the new configuration:
Image

​
Notes

  • Replaces the prototype: base64-media-retriever
  • Unlike the prototype-based implementation, this configuration-based transformer is not reusable across different purposes or payloads. If you need to transform a different payload structure or serve a different use case, you must duplicate this transformer and adjust the configuration accordingly.
  • Large media files will significantly increase payload size. Consider whether Base64 encoding is strictly required by the target system.
  • If the target system supports URL-based media references, it is recommended to pass the media URL directly instead of encoding it.
  • Ensure the media_base_url is accessible from the Alumio environment at runtime.