Transformation Scripts Guide

Transformation scripts in Requestador are written in Python and are used to convert the raw AI response into the final format expected by the next step in the workflow or by the calling system, such as Pimcore.

A transformation script is executed after the AI response has been generated and, if applicable, after validation has confirmed that the response is acceptable.

Transformation helps ensure that AI-generated responses are:

• returned in the correct structure

• normalized into a predictable format

• aligned with downstream field mappings

• adapted to business-specific response requirements

• optionally enriched or mapped using catalog values

In simple scenarios, the transformation script may return the AI response unchanged. In more advanced use cases, it can reshape, rename, normalize, or reformat the output before it is used further.

The purpose of a transformation script is to prepare the final response that Requestador returns.

Typical transformation tasks include:

• passing through the AI response unchanged

• converting raw text into structured JSON

• renaming response fields

• normalizing values

• reshaping the response to match expected output fields

• mapping output values using catalogs

• reducing a larger response to only the fields that should be returned

Transformation scripts are especially useful when Pimcore or another target system expects a fixed output structure.

Transformation scripts are written in Python.

A script typically works with these inputs:

• chat_response – the raw AI response

• catalogs – available catalog data, when catalogs are attached to the action

A transformation script must return the final transformed response.

Typical structure:

This is the simplest pass-through version, where the response is returned exactly as received.

Requestador transformation scripts commonly fall into these categories:

1. Pass-through transformation

This is the simplest form of transformation. The script returns the AI response unchanged.

Use this when:

• the AI already returns the exact structure you need

• no renaming or normalization is required

• the output is already ready for Pimcore mapping

2. Structured output transformation

This type of transformation converts the AI response into a more controlled or structured format.

Use this when:

• the AI returns raw text that must become JSON

• only selected fields should be returned

• output keys must be renamed

• the downstream system expects a specific schema

3. Catalog-based transformation

This type of transformation uses catalog data to map, normalize, or enrich returned values.

Use this when:

• AI output must be matched to catalog entries

• codes, labels, or canonical values must be returned

• output needs to be translated into a controlled business format

Description

Pass-through transformation simply returns the AI response without modification.

This is suitable when:

• prompts are already designed to return the final desired output

• no additional formatting or mapping is needed

• validation already ensures the output is correct

Example script

What this script does

This script:

• accepts the raw AI response

• does not modify it

• returns it as the final output

Typical use cases

Use pass-through transformation when:

• the action prompt already instructs the model to return the correct JSON

• the target system can directly consume the response

• the response structure is already stable and validated

Description

Structured output transformation is used when the AI response must be adjusted before it is returned.

Typical examples:

• convert text to JSON

• rename keys

• keep only selected fields

• wrap values in a new structure

• standardize field names for Pimcore mapping

Example use case

The AI returns JSON with keys that do not match the expected field names in the target system. The transformation script reshapes the result into the required format.

Example pattern

Example pattern

Typical use cases

Use structured transformation when:

• the field names returned by the model differ from the required field names

• the downstream system expects a fixed naming convention

• prompts may vary, but the final response format must remain stable

Description

Catalog-based transformation uses attached catalog data to normalize or map returned values.

This is useful when the model returns a display value, synonym, or label, and the target system needs a catalog-defined value instead.

Example use case

The AI returns a category name, and the transformation script maps it to a canonical catalog value or internal identifier.

Example pattern

What this script does

This script:

• parses the response

• reads the returned category

• looks up the corresponding catalog value

• returns the mapped result in the final structure

Typical use cases

Use catalog-based transformation when:

• output values must be normalized

• internal business identifiers should be returned

• display values from AI are not the final values needed by the target system

Use pass-through transformation when:

• the AI already returns the exact required structure

• no normalization is needed

• you want the simplest possible flow

Use structured output transformation when:

• the output shape must be controlled

• field names need to be adapted

• the target system expects a different schema

Use catalog-based transformation when:

• output values must be mapped to controlled business values

• you need canonical or internal values instead of free-text labels

• catalogs are part of the workflow logic

Validation and transformation serve different purposes:

• Validation checks whether the response is acceptable

• Transformation prepares the response for downstream use

A typical sequence is:

1. AI returns a response

2. Validation script confirms the response is valid

3. Transformation script converts the response into the final format

4. The result is sent back to Pimcore or another system

In simple setups:

• validation may confirm structure

• transformation may simply return the response unchanged

In more advanced setups:

• validation checks schema and allowed values

• transformation reshapes and normalizes the result

• keep transformation logic focused on output shaping

• use validation first when structure must be enforced

• return only the fields needed by the downstream system

• normalize field names for consistency

• use catalogs when business-controlled output values are required

• keep prompts and transformation logic aligned

• test transformed output before configuring Pimcore mappings

• avoid unnecessary complexity if pass-through transformation is sufficient

Pass through the response unchanged

Parse and reshape JSON

Map values using a catalog

Returning raw output when downstream expects structured JSON

If Pimcore mappings expect defined field names, raw text may not be usable.

Doing validation inside transformation only

Transformation should not replace validation. If the structure must be guaranteed, validate first.

Returning the wrong final format

Be consistent about whether the workflow expects a string, JSON string, or already structured object.

Using catalog mappings without attached catalogs

If the catalog is not available in the action, catalog-based transformation will fail.

Using catalog mappings without attached catalogs

If the response is already correct, a pass-through transformation is often the best option.

Transformation scripts in Requestador are Python-based scripts that define the final form of the response returned by an action.

The most common transformation approaches are:

• Pass-through transformation for unchanged output

• Structured output transformation for reshaping and normalizing results

• Catalog-based transformation for mapping results to controlled business values

Using transformation scripts helps ensure that Requestador outputs are predictable, integration-ready, and aligned with the requirements of systems such as Pimcore.

If no transformation is required, the following script can be used: