> ## 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.
# Base64 Media Retriever
## 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-based | Configuration-based |
| ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Reusability** | Can be reused across different flows by changing a few fields | Not reusable across different purposes or payloads |
| **Flexibility** | One prototype can serve multiple use cases | (Not always) Each use case requires its own dedicated configuration |
| **How to reuse** | Modify fields directly | Duplicate 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
| Parameter | Description | Required |
| -------------------- | ----------------------------------------------------------------------------------- | -------- |
| `media_base_url` | The base URL of the Magento 2 media storage | Yes |
| `output_field` | The field name in the output payload where the Base64 string will be stored | Yes |
| `authentication` | Optional : Authentication method to access the media endpoint | No |
| `allowed_mime_types` | Optional : 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
```json theme={null}
{
"sku": "PROD-001",
"url": "https://www.sample.org/leaf-blue.png"
}
```
### Example Output
```json theme={null}
{
"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:
\
An example of the new configuration:
## 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.