[Issue #6898] Handle restructuring objects for nested fields (#7035)

## Summary

<!-- Use "Fixes" to automatically close issue upon PR merge. Use "Work
for" when UAT is required. -->
Fixes #6898

## Changes proposed

<!-- What was added, updated, or removed in this PR. -->
Add `_apply_pivot_object_transform` and associated `pivot_object`
transform type to XML transformation logic.
Add `FORM_XML_TRANSFORM_RULES` to sf424a form to test XML generation
integration.
Add tests to mirror real-world example.

## Context for reviewers

<!-- Technical or background context, more in-depth details of the
implementation, and anything else you'd like reviewers to know about
that will help them understand the changes in the PR. -->
Our JSON structure for `forecasted_cash_needs` and possibly others in
the future differs slightly from the expected XML format. In XML, we
need to pivot the JSON object to create the correct structure. Here we
add the ability to do that in the JSON transform.

It's possible the PR doesn't need us to add `FORM_XML_TRANSFORM_RULES`,
but I figured we will need it anyway and best to add it for now.

## Validation steps

<!-- Manual testing instructions, as well as any helpful references
(screenshots, GIF demos, code examples or output). -->
See new unit tests.

Author: mikehgrantsgov

api/src/form_schema/forms/sf424a.py

@@ -773,6 +773,66 @@
     },
 }
 
+# XML Transformation Rules for SF-424A
+FORM_XML_TRANSFORM_RULES = {
+    # Metadata
+    "_xml_config": {
+        "description": "XML transformation rules for converting Simpler SF-424A JSON to XML",
+        "version": "1.0",
+        "form_name": "SF424A",
+        "namespaces": {
+            "default": "http://apply.grants.gov/forms/SF424A-V1.0",
+            "SF424A": "http://apply.grants.gov/forms/SF424A-V1.0",
+        },
+        "xsd_url": "https://apply07.grants.gov/apply/forms/schemas/SF424A-V1.0.xsd",
+        "xml_structure": {"root_element": "SF424A", "version": "2.0"},
+        "null_handling_options": {
+            "exclude": "Default - exclude field entirely from XML (recommended)",
+            "include_null": "Include empty XML element: <Field></Field>",
+            "default_value": "Use configured default value when field is None",
+        },
+    },
+    # Forecasted Cash Needs - Section D
+    # This requires pivoting the data structure from JSON to XML format
+    "forecasted_cash_needs": {
+        "xml_transform": {
+            "type": "conditional",
+            "target": "BudgetForecastedCashNeeds",
+            "conditional_transform": {
+                "type": "pivot_object",
+                "source_field": "forecasted_cash_needs",
+                "field_mapping": {
+                    "BudgetFirstYearAmounts": {
+                        "BudgetFederalForecastedAmount": "federal_forecasted_cash_needs.total_amount",
+                        "BudgetNonFederalForecastedAmount": "non_federal_forecasted_cash_needs.total_amount",
+                        "BudgetTotalForecastedAmount": "total_forecasted_cash_needs.total_amount",
+                    },
+                    "BudgetFirstQuarterAmounts": {
+                        "BudgetFederalForecastedAmount": "federal_forecasted_cash_needs.first_quarter_amount",
+                        "BudgetNonFederalForecastedAmount": "non_federal_forecasted_cash_needs.first_quarter_amount",
+                        "BudgetTotalForecastedAmount": "total_forecasted_cash_needs.first_quarter_amount",
+                    },
+                    "BudgetSecondQuarterAmounts": {
+                        "BudgetFederalForecastedAmount": "federal_forecasted_cash_needs.second_quarter_amount",
+                        "BudgetNonFederalForecastedAmount": "non_federal_forecasted_cash_needs.second_quarter_amount",
+                        "BudgetTotalForecastedAmount": "total_forecasted_cash_needs.second_quarter_amount",
+                    },
+                    "BudgetThirdQuarterAmounts": {
+                        "BudgetFederalForecastedAmount": "federal_forecasted_cash_needs.third_quarter_amount",
+                        "BudgetNonFederalForecastedAmount": "non_federal_forecasted_cash_needs.third_quarter_amount",
+                        "BudgetTotalForecastedAmount": "total_forecasted_cash_needs.third_quarter_amount",
+                    },
+                    "BudgetFourthQuarterAmounts": {
+                        "BudgetFederalForecastedAmount": "federal_forecasted_cash_needs.fourth_quarter_amount",
+                        "BudgetNonFederalForecastedAmount": "non_federal_forecasted_cash_needs.fourth_quarter_amount",
+                        "BudgetTotalForecastedAmount": "total_forecasted_cash_needs.fourth_quarter_amount",
+                    },
+                },
+            },
+        }
+    },
+}
+
 SF424a_v1_0 = Form(
     # https://grants.gov/forms/form-items-description/fid/241
     form_id=uuid.UUID("08e6603f-d197-4a60-98cd-d49acb1fc1fd"),

api/src/services/xml_generation/conditional_transformers.py

@@ -5,13 +5,65 @@
 """
 
 import logging
-from typing import Any, cast
+from typing import Any
 
 from src.util.dict_util import get_nested_value
 
 logger = logging.getLogger(__name__)
 
 
+def _apply_pivot_object_transform(
+    transform_config: dict[str, Any], source_data: dict[str, Any]
+) -> dict[str, Any] | None:
+    """Apply pivot transformation to restructure nested objects."""
+    source_field = transform_config.get("source_field")
+    field_mapping = transform_config.get("field_mapping", {})
+
+    # Validate source_field is configured properly
+    if not source_field or not isinstance(source_field, str):
+        raise ConditionalTransformationError(
+            "pivot_object requires 'source_field' to be a non-empty string"
+        )
+
+    # Get the source object to pivot
+    source_path = source_field.split(".")
+    source_object = get_nested_value(source_data, source_path)
+
+    result = {}
+
+    for target_field, target_subfields in field_mapping.items():
+        if not isinstance(target_subfields, dict):
+            continue
+
+        # Build nested object for this target field
+        nested_result = {}
+        for target_subfield, source_path_str in target_subfields.items():
+            # Parse the source path
+            if not isinstance(source_path_str, str):
+                continue
+
+            path_parts = source_path_str.split(".")
+            value = source_object
+
+            # Navigate through the path
+            for part in path_parts:
+                if isinstance(value, dict) and part in value:
+                    value = value[part]
+                else:
+                    value = None
+                    break
+
+            # Add value if found
+            if value is not None:
+                nested_result[target_subfield] = value
+
+        # Only add target field if we got at least one value
+        if nested_result:
+            result[target_field] = nested_result
+
+    return result if result else None
+
+
 class ConditionalTransformationError(Exception):
     """Exception raised when conditional transformation fails."""
 
@@ -44,22 +96,34 @@ def evaluate_condition(condition: dict[str, Any], source_data: dict[str, Any]) -
     if condition_type == "field_equals":
         field_path = condition.get("field")
         expected_value = condition.get("value")
-        path_list = field_path.split(".") if isinstance(field_path, str) else (field_path or [])
-        actual_value = get_nested_value(source_data, cast(list[str], path_list))
+        if not field_path or not isinstance(field_path, str):
+            raise ConditionalTransformationError(
+                "field_equals condition requires 'field' to be a non-empty string"
+            )
+        path_list = field_path.split(".")
+        actual_value = get_nested_value(source_data, path_list)
         return actual_value == expected_value
 
     elif condition_type == "field_in":
         field_path = condition.get("field")
         allowed_values = condition.get("values", [])
-        path_list = field_path.split(".") if isinstance(field_path, str) else (field_path or [])
-        actual_value = get_nested_value(source_data, cast(list[str], path_list))
+        if not field_path or not isinstance(field_path, str):
+            raise ConditionalTransformationError(
+                "field_in condition requires 'field' to be a non-empty string"
+            )
+        path_list = field_path.split(".")
+        actual_value = get_nested_value(source_data, path_list)
         return actual_value in allowed_values
 
     elif condition_type == "field_contains":
         field_path = condition.get("field")
         search_value = condition.get("value")
-        path_list = field_path.split(".") if isinstance(field_path, str) else (field_path or [])
-        actual_value = get_nested_value(source_data, cast(list[str], path_list))
+        if not field_path or not isinstance(field_path, str):
+            raise ConditionalTransformationError(
+                "field_contains condition requires 'field' to be a non-empty string"
+            )
+        path_list = field_path.split(".")
+        actual_value = get_nested_value(source_data, path_list)
         if isinstance(actual_value, list):
             return search_value in actual_value
         return False
@@ -89,6 +153,7 @@ def apply_conditional_transform(
 
     Supports:
     - one_to_many: Map array field to multiple XML elements
+    - pivot_object: Restructure nested objects by pivoting dimensions
 
     Args:
         transform_config: Conditional transformation configuration
@@ -110,10 +175,13 @@ def apply_conditional_transform(
         max_count = transform_config.get("max_count", 10)
 
         if source_field and target_pattern:
-            source_path = (
-                source_field.split(".") if isinstance(source_field, str) else (source_field or [])
-            )
-            source_values = get_nested_value(source_data, cast(list[str], source_path))
+            # Validate source_field is a string
+            if not isinstance(source_field, str):
+                raise ConditionalTransformationError(
+                    "one_to_many requires 'source_field' to be a string"
+                )
+            source_path = source_field.split(".")
+            source_values = get_nested_value(source_data, source_path)
 
             if isinstance(source_values, list):
                 result = {}
@@ -128,6 +196,9 @@ def apply_conditional_transform(
 
         return None
 
+    elif transform_type == "pivot_object":
+        return _apply_pivot_object_transform(transform_config, source_data)
+
     else:
         raise ConditionalTransformationError(
             f"Unknown conditional transform type: {transform_type}"