npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.56 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (476) hide show

package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-payload-xml-order-update-graphql.md CHANGED Viewed

@@ -1,1472 +1,1472 @@
----
-template_id: tpl-ingest-payload-xml-to-order-update-graphql
-canonical_filename: template-ingestion-payload-xml-order-update-graphql.md
-sdk_version: latest
-runtime: versori
-direction: ingestion
-source: payload-xml
-destination: fluent-graphql
-entity: order
-format: xml
-logging: versori
-status: stable
-features:
-  - direct-payload-processing
-  - xml-parsing
-  - graphql-mutations
-  - order-query-before-update
-  - attribute-updates
----
-# Template: Ingestion - Payload XML to Order Update GraphQL
-**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
----
-## 📋 Implementation Prompt
-```
-I need a Versori webhook ingestion that:
-1) Receives XML payload directly in webhook request body with orderRef and attributes
-2) Parses XML to extract order reference and attributes (handles Versori $ format for attributes)
-3) Queries Fluent Commerce to get order ID by order reference
-4) Updates order attributes using updateOrder GraphQL mutation
-5) Returns success/error response
-6) Uses native Versori log from context
-Use the loaded docs to fill in SDK specifics and best practices.
-Keep the structure identical to the template; only adapt where needed.
-```
----
-## 📋 Template Overview
-This connector runs on the Versori platform. It receives XML payloads directly via webhook with order reference and attributes, queries Fluent Commerce to get the order ID, and updates order attributes using GraphQL mutations. Most operational settings (Fluent account/connection) are configured via activation variables.
-### What This Template Does
-```
-┌────────────────────────────────────────────────────────────────┐
-│          INGESTION WORKFLOW              │
-└────────────────────────────────────────────────────────────────┘
-1. TRIGGER
-  └─ Webhook: HTTP POST endpoint receives XML payload
-2. RECEIVE PAYLOAD
-  ├─ Extract XML from request body (ctx.data or ctx.request)
-  ├─ Validate payload structure
-  └─ Log incoming request
-3. PARSE XML
-  ├─ Parse XML payload (Versori auto-parses with $ format)
-  ├─ Extract order reference (handles $ for attributes, _ for text)
-  ├─ Extract attributes array
-  └─ Validate required fields
-4. QUERY ORDER
-  ├─ Query Fluent Commerce: order(ref: orderRef)
-  ├─ Get order ID and current state
-  ├─ Validate order exists
-  └─ Log order details
-5. BUILD UPDATE MUTATION
-  ├─ Construct UpdateOrderInput with ref
-  ├─ Map attributes to AttributeInput format
-  ├─ Preserve existing attributes (optional merge)
-  └─ Build GraphQL mutation variables
-6. EXECUTE MUTATION
-  ├─ Execute updateOrder GraphQL mutation
-  ├─ Handle success/error responses
-  └─ Log mutation result
-7. RETURN RESPONSE
-  ├─ Return success with order details
-  └─ Return error with details if failed
-```
-### Key Features
-- **Direct Payload Processing**: Receives XML payload directly in webhook request body
-- **Versori XML Parsing**: Handles Versori auto-parsed XML format ($ for attributes, _ for text)
-- **Order Query First**: Queries order by ref to get ID and validate existence
-- **GraphQL Mutation**: Uses updateOrder mutation to update attributes
-- **Attribute Mapping**: Converts XML attributes to Fluent AttributeInput format
-- **Error Handling**: Comprehensive error handling with detailed logging
-- **Native Versori Logging**: Uses Versori log from context
-### 📦 Package Information
-**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
-```bash
-npm install @fluentcommerce/fc-connect-sdk@latest
-```
----
-**Templates are designed for direct deployment; customize via activation variables.**
----
-## 📦 SDK Imports (Verified - Versori Optimized)
-```typescript
-// ✅ VERIFIED IMPORTS - These match actual SDK exports
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
-import {
-  createClient, // Universal client factory
-  XMLParserService, // XML parsing utility
-} from '@fluentcommerce/fc-connect-sdk';
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-// Versori platform imports
-import { webhook, http } from '@versori/run';
-```
-**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
-**⚠️ CRITICAL - Buffer Import Required:**
-The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
-- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
-- Without this import, code will crash with `ReferenceError: Buffer is not defined`
-- Always include this import in Versori templates, even if not directly used in the template code
-- Required for SDK internal operations and any Buffer usage in your code
-**✅ VERSORI PLATFORM - Use Native Logs:**
-- Use `log` from context: `const { log } = ctx;`
-- Native Versori logs are simpler and automatically integrated with platform monitoring
-**✅ VERSORI XML PARSING:**
-Versori automatically parses XML payloads when `Content-Type: application/xml` is set:
-- Attributes accessed via `$` (e.g., `element.$?.attributeName`)
-- Text content accessed via `_` (e.g., `element._`)
-- Nested elements accessed directly (e.g., `element.childElement`)
----
-## 🔐 Fluent Commerce Connection Setup
-**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
-**Connection Configuration:**
-1. **Create Connection in Versori:**
-   - Name: `fluent_commerce`
-   - Type: HTTP Basic Auth or OAuth2
-   - Credentials: Fluent Commerce API credentials
-2. **Connection Variables:**
-   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
-   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
-   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
-   - `FLUENT_USERNAME` - Username (if using Basic Auth)
-   - `FLUENT_PASSWORD` - Password (if using Basic Auth)
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Connection can be reused across workflows
-- ✅ No sensitive data in activation variables
-- ✅ Easier credential rotation
----
-## 📄 Expected XML Payload Format
-The webhook accepts **flat XML payloads**. All child elements except `orderRef` are automatically treated as order attributes.
-### ✅ PRIMARY FORMAT: Flat Structure (Recommended)
-**Simple format - just child elements, no nested attributes structure:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-12345</orderRef>
-  <externalOrderId>EXT-123456789</externalOrderId>
-  <customerNotes>Please leave package at front door</customerNotes>
-  <priority>high</priority>
-  <tags>rush,gift</tags>
-</orderUpdate>
-```
-**Type Auto-Detection:**
-- Numbers → `INTEGER` or `FLOAT` (auto-detected)
-- "true"/"false" → `BOOLEAN` (auto-detected)
-- Strings → `STRING` (default)
-**cURL Example:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  -d '<?xml version="1.0" encoding="UTF-8"?><orderUpdate><orderRef>ORD-12345</orderRef><externalOrderId>EXT-123456789</externalOrderId><customerNotes>Please leave package at front door</customerNotes><priority>high</priority></orderUpdate>'
-```
-### Complete Sample Payloads
-**Example 1: External System Reference Update**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-0017326966182</orderRef>
-  <externalOrderId>EXT-123456789</externalOrderId>
-  <sourceSystem>ERP-SAP</sourceSystem>
-  <integrationId>INT-987654321</integrationId>
-</orderUpdate>
-```
-**Example 2: Customer Notes and Business Flags**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-0017326966182</orderRef>
-  <customerNotes>Please leave package at front door</customerNotes>
-  <priority>high</priority>
-  <tags>rush,gift</tags>
-  <specialHandling>true</specialHandling>
-</orderUpdate>
-```
-**Note:** Metadata fields (`updateReason`, `updatedBy`, `timestamp`) are optional and excluded from attributes. All other child elements are treated as order attributes.
-**Versori XML Parsing Format (CRITICAL):**
-When Versori receives XML with `Content-Type: application/xml`, it **automatically parses** the XML into a JavaScript object. You do NOT need to manually parse XML - Versori handles it automatically.
-**Access Patterns:**
-- **Attributes**: `element.$?.attributeName` (e.g., `<orderUpdate orderRef="ORD-12345"/>` → `orderUpdate.$?.orderRef`)
-- **Text content**: `element._` or direct property access (e.g., `<orderRef>ORD-12345</orderRef>` → `orderRef._` or `orderRef`)
-- **Nested elements**: Direct property access (e.g., `<orderUpdate><orderRef>...</orderRef></orderUpdate>` → `orderUpdate.orderRef`)
-**Examples:**
-```typescript
-// XML: <orderUpdate orderRef="ORD-12345"/>
-// Versori auto-parsed: { orderUpdate: { $: { orderRef: "ORD-12345" } } }
-const orderRef = parsed.orderUpdate?.$?.orderRef; // ✅ "ORD-12345"
-// XML: <orderRef>ORD-12345</orderRef>
-// Versori auto-parsed: { orderRef: { _: "ORD-12345" } } OR { orderRef: "ORD-12345" }
-const orderRef = parsed.orderRef?._ || parsed.orderRef; // ✅ "ORD-12345"
-// XML: <attribute name="status" value="processing"/>
-// Versori auto-parsed: { attribute: { $: { name: "status", value: "processing" } } }
-const attrName = parsed.attribute?.$?.name; // ✅ "status"
-const attrValue = parsed.attribute?.$?.value; // ✅ "processing"
-```
-**Key Point:** Versori automatically parses XML when `Content-Type: application/xml` is set. Your webhook receives `ctx.data` as a pre-parsed JavaScript object - no manual XML parsing needed!
----
-## GraphQL Mutations
-### Query Order by Reference
-```graphql
-query GetOrder($ref: String!) {
-  order(ref: $ref) {
-    id
-    ref
-    status
-    attributes {
-      name
-      type
-      value
-    }
-  }
-}
-```
-### Update Order Mutation
-```graphql
-mutation UpdateOrder($input: UpdateOrderInput!) {
-  updateOrder(input: $input) {
-    id
-    ref
-    status
-    attributes {
-      name
-      type
-      value
-    }
-  }
-}
-```
-**UpdateOrderInput Structure:**
-- `id` (ID!) - Order ID (required) - Must use Fluent internal ID, not reference
-- `attributes` (Array<AttributeInput>) - Attributes to update
-- `status` (String) - Optional status update
-- Other optional fields as per schema
-**Note:** UpdateOrderInput requires `id: ID!` (the Fluent internal ID), not `ref`. This is why the template queries the order first to get the ID.
-**AttributeInput Structure:**
-- `name` (String!) - Attribute name
-- `type` (String!) - Attribute type (STRING, INTEGER, FLOAT, BOOLEAN, JSON, DATE)
-- `value` (String!) - Attribute value (stringified for non-STRING types)
----
-## 🔧 Complete Production Code
-### Versori Workflows Structure
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from webhook)
-### Recommended Project Structure
-```
-order-update-webhook/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-update.ts           # Webhook: Order update handler
-    │
-    ├── services/
-    │   └── order-update.service.ts       # Shared orchestration logic
-    │
-    ├── utils/
-    │   └── response-status.utils.ts      # FC status code mapping utilities
-    │
-    └── types/
-        └── order-update.types.ts         # Type definitions
-```
-**Benefits:**
-- ✅ Clear structure (webhook handlers in `webhook/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Centralized type definitions
-- ✅ Utility functions for consistent error handling (FC status codes)
----
-## Workflow Files
-### 1. Webhook Workflow (`src/workflows/webhook/order-update.ts`)
-**Purpose**: Handle order update requests via webhook
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/order-update`
-**Use Cases**: Order attribute updates from external systems, status changes
-```typescript
-import { webhook, http } from '@versori/run';
-import { executeOrderUpdate } from '../../services/order-update.service';
-import { mapErrorToFCStatus } from '../../utils/response-status.utils';
-/**
- * Webhook: Order Update Handler
- *
- * Endpoint: POST https://{workspace}.versori.run/order-update
- * Request body: XML with orderRef and flat attribute elements
- * Content-Type: application/xml
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: order-update.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const orderUpdateWebhook = webhook('order-update', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-  connection: 'order-update-webhook', // Versori validates API key
-}).then(
-  http('process-order-update', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-    log.info('🚀 [WEBHOOK] Order update request received', {
-      timestamp: new Date().toISOString(),
-      hasPayload: !!data,
-      contentType: ctx.request?.headers?.get('content-type'),
-    });
-    try {
-      // Reuse shared orchestration logic
-      const result = await executeOrderUpdate(ctx);
-      log.info('✅ [WEBHOOK] Order update completed successfully', {
-        orderRef: result.orderRef,
-        orderId: result.orderId,
-        attributesUpdated: result.attributesUpdated,
-      });
-      // Return response with FC200 status code
-      return {
-        success: true,
-        statusCode: result.statusCode,
-        orderRef: result.orderRef,
-        orderId: result.orderId,
-        attributesUpdated: result.attributesUpdated,
-        message: result.message || 'Order attributes updated successfully',
-      };
-    } catch (e: any) {
-      log.error('❌ [WEBHOOK] Order update failed', {
-        message: e?.message,
-        stack: e?.stack,
-      });
-      // Map error to FC status code
-      const fcStatus = mapErrorToFCStatus(e);
-      return {
-        success: false,
-        statusCode: fcStatus.statusCode,
-        retryable: fcStatus.retryable,
-        error: fcStatus.message,
-        details: e?.message || 'Unknown error occurred',
-      };
-    }
-  })
-);
-```
----
-### 2. Entry Point (`index.ts`)
-**Purpose**: Register all workflows with Versori platform
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- * - src/services/            → Shared service logic (reusable across workflows)
- */
-// Import webhook workflows
-import { orderUpdateWebhook } from './src/workflows/webhook/order-update';
-// Register all workflows with Versori platform
-export {
-  // Webhooks (HTTP-based triggers)
-  orderUpdateWebhook,
-};
-```
-**What Gets Exposed:**
-- ✅ `orderUpdateWebhook` → `https://{workspace}.versori.run/order-update`
----
-## 3. Type Definitions (`src/types/order-update.types.ts`)
-```typescript
-/**
- * Type Definitions for Order Update Ingestion
- *
- * Centralized type definitions for order update workflow
- */
-/**
- * Versori XML parsed format
- * Attributes accessed via $, text content via _
- */
-export interface VersoriXMLParsed {
-  [key: string]: unknown;
-  $?: Record<string, unknown>; // Attributes
-  _?: string; // Text content
-}
-/**
- * Order update request payload (XML parsed format)
- */
-export interface OrderUpdatePayload {
-  orderUpdate?: {
-    orderRef?: VersoriXMLParsed | string;
-    attributes?: {
-      attribute?: VersoriXMLParsed | Array<VersoriXMLParsed>;
-    };
-    $?: {
-      orderRef?: string;
-    };
-    [key: string]: VersoriXMLParsed | string | unknown; // Flat attributes
-  };
-  order?: {
-    ref?: VersoriXMLParsed | string;
-    $?: {
-      ref?: string;
-    };
-  };
-  [key: string]: unknown; // Allow additional fields
-}
-/**
- * Fluent AttributeInput format
- */
-export interface AttributeInput {
-  name: string;
-  type: 'STRING' | 'INTEGER' | 'FLOAT' | 'BOOLEAN' | 'JSON' | 'DATE';
-  value: string;
-}
-/**
- * Order query result
- */
-export interface OrderQueryResult {
-  id: string;
-  ref: string;
-  status?: string;
-  attributes?: Array<{
-    name: string;
-    type: string;
-    value: string;
-  }>;
-}
-/**
- * Order update result with FC status code
- */
-export interface OrderUpdateResult {
-  success: boolean;
-  statusCode: 'FC200' | 'FC400' | 'FC409' | 'FC504';
-  orderRef: string;
-  orderId: string;
-  attributesUpdated: number;
-  message?: string;
-  error?: string;
-  retryable?: boolean;
-}
-/**
- * Versori Context Interface
- * Represents the Versori runtime context passed to workflow functions
- */
-export interface VersoriContext {
-  log: {
-    info: (message: string, data?: Record<string, unknown>) => void;
-    warn: (message: string, data?: Record<string, unknown>) => void;
-    error: (message: string, data?: Record<string, unknown>) => void;
-    debug?: (message: string, data?: Record<string, unknown>) => void;
-  };
-  data?: unknown;
-  request?: Request;
-  activation: {
-    getVariable: (name: string) => string | undefined;
-    connections?: Record<string, unknown>;
-  };
-  connections?: Record<string, unknown>;
-}
-```
----
-## 4. Utility: Response Status Code Mapper (`src/utils/response-status.utils.ts`)
-```typescript
-/**
- * Response Status Code Utility
- *
- * Maps errors to Fluent Commerce (FC) status codes for consistent API responses
- */
-/**
- * FC Status Codes:
- * - FC200: OK (Successfully - No further action needed)
- * - FC400: Bad Request (Non-retryable)
- * - FC409: Duplicate Request, Entity already exists (Non-retryable)
- * - FC504: Timeout (Retryable)
- */
-export type FCStatusCode = 'FC200' | 'FC400' | 'FC409' | 'FC504';
-export interface FCStatusMapping {
-  statusCode: FCStatusCode;
-  retryable: boolean;
-  message: string;
-}
-/**
- * Map error to FC status code based on error message and type
- */
-export function mapErrorToFCStatus(error: unknown): FCStatusMapping {
-  const errorMessage =
-    error instanceof Error ? error.message : String(error);
-  const lowerMessage = errorMessage.toLowerCase();
-  // FC409: Duplicate/Already exists (Non-retryable)
-  if (
-    lowerMessage.includes('already exists') ||
-    lowerMessage.includes('duplicate') ||
-    lowerMessage.includes('unique constraint') ||
-    lowerMessage.includes('entity already exists')
-  ) {
-    return {
-      statusCode: 'FC409',
-      retryable: false,
-      message: 'Entity already exists. Duplicate request detected.',
-    };
-  }
-  // FC504: Timeout (Retryable)
-  if (
-    lowerMessage.includes('timeout') ||
-    lowerMessage.includes('timed out') ||
-    lowerMessage.includes('request timeout') ||
-    (error instanceof Error && error.name === 'TimeoutError')
-  ) {
-    return {
-      statusCode: 'FC504',
-      retryable: true,
-      message: 'Request timeout. Please retry.',
-    };
-  }
-  // FC400: Bad Request (Non-retryable)
-  // Validation errors, missing fields, invalid format
-  if (
-    lowerMessage.includes('required') ||
-    lowerMessage.includes('missing') ||
-    lowerMessage.includes('invalid') ||
-    lowerMessage.includes('bad request') ||
-    lowerMessage.includes('validation') ||
-    lowerMessage.includes('not found') ||
-    lowerMessage.includes('does not exist')
-  ) {
-    return {
-      statusCode: 'FC400',
-      retryable: false,
-      message: 'Bad request. Please verify payload and try again.',
-    };
-  }
-  // Default: FC400 for unknown errors (Non-retryable)
-  return {
-    statusCode: 'FC400',
-    retryable: false,
-    message: errorMessage,
-  };
-}
-/**
- * Create success response with FC200 status
- */
-export function createSuccessResponse<T extends Record<string, unknown>>(
-  data: T
-): T & { statusCode: 'FC200'; retryable: false } {
-  return {
-    ...data,
-    statusCode: 'FC200' as const,
-    retryable: false,
-  };
-}
-```
----
-## 5. Service: Order Update Processor (`src/services/order-update.service.ts`)
-```typescript
-/**
- * Order Update Service
- *
- * Processes order update requests: extracts order reference and attributes from XML payload,
- * queries Fluent Commerce to get order ID, and updates order attributes via GraphQL mutation.
- * Handles Versori XML parsing format ($ for attributes, _ for text).
- */
-import {
-  createClient,
-  XMLParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-import { Buffer } from 'node:buffer';
-import { mapErrorToFCStatus, createSuccessResponse } from '../utils/response-status.utils';
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-import type {
-  OrderUpdatePayload,
-  OrderUpdateResult,
-  VersoriContext,
-  AttributeInput,
-  OrderQueryResult,
-  VersoriXMLParsed,
-} from '../types/order-update.types';
-/**
- * GraphQL query to get order by reference
- */
-const GET_ORDER_QUERY = `
-  query GetOrder($ref: String!) {
-    order(ref: $ref) {
-      id
-      ref
-      status
-      attributes {
-        name
-        type
-        value
-      }
-    }
-  }
-`;
-/**
- * GraphQL mutation to update order
- */
-const UPDATE_ORDER_MUTATION = `
-  mutation UpdateOrder($input: UpdateOrderInput!) {
-    updateOrder(input: $input) {
-      id
-      ref
-      status
-      attributes {
-        name
-        type
-        value
-      }
-    }
-  }
-`;
-/**
- * Extract text content from Versori XML parsed format
- * Handles both object format ({ _: "text" }) and direct string
- */
-function extractTextContent(value: VersoriXMLParsed | string | undefined): string | null {
-  if (!value) {
-    return null;
-  }
-  if (typeof value === 'string') {
-    return value;
-  }
-  if (typeof value === 'object' && '_' in value) {
-    const text = value._;
-    return typeof text === 'string' ? text : null;
-  }
-  return null;
-}
-/**
- * Extract order reference from XML payload
- *
- * Supports multiple XML formats:
- * - <orderUpdate><orderRef>ORD-12345</orderRef></orderUpdate>
- * - <orderUpdate orderRef="ORD-12345"/>
- * - <order ref="ORD-12345"/>
- */
-function extractOrderRef(payload: OrderUpdatePayload): string | null {
-  // Try orderUpdate.orderRef (text content)
-  if (payload.orderUpdate) {
-    const orderUpdate = payload.orderUpdate;
-    // Try orderUpdate.orderRef as text
-    if (orderUpdate.orderRef) {
-      const ref = extractTextContent(orderUpdate.orderRef);
-      if (ref) {
-        return ref;
-      }
-      if (typeof orderUpdate.orderRef === 'string') {
-        return orderUpdate.orderRef;
-      }
-    }
-    // Try orderUpdate.$?.orderRef (root attribute)
-    if ('$' in orderUpdate && orderUpdate.$) {
-      const attrs = orderUpdate.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.orderRef === 'string') {
-        return attrs.orderRef;
-      }
-    }
-  }
-  // Try direct order element
-  if (payload.order) {
-    const order = payload.order;
-    // Try order.$?.ref (attribute)
-    if (typeof order === 'object' && '$' in order && order.$) {
-      const attrs = order.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.ref === 'string') {
-        return attrs.ref;
-      }
-    }
-    // Try order.ref (text content)
-    if (typeof order === 'object' && 'ref' in order) {
-      const ref = extractTextContent(order.ref as VersoriXMLParsed);
-      if (ref) {
-        return ref;
-      }
-    }
-  }
-  return null;
-}
-/**
- * Extract attributes from XML payload
- *
- * PRIMARY FORMAT: Flat structure - all direct children of orderUpdate (except orderRef and metadata)
- * - <orderUpdate><orderRef>ORD-123</orderRef><externalOrderId>EXT-123</externalOrderId></orderUpdate>
- *
- * Supports multiple XML formats:
- * - PRIMARY: Flat structure: <externalOrderId>...</externalOrderId>
- * - ALTERNATIVE: <attributes><attribute><name>...</name><value>...</value></attribute></attributes>
- * - ALTERNATIVE: <attributes><attribute name="..." value="..."/></attributes>
- */
-function extractAttributes(payload: OrderUpdatePayload): AttributeInput[] {
-  const attributes: AttributeInput[] = [];
-  const metadataFields = ['orderRef', 'attributes', '$', '_', 'updateReason', 'updatedBy', 'timestamp'];
-  // ✅ PRIMARY FORMAT: Flat structure - all direct children of orderUpdate (except orderRef and metadata)
-  // Example: <orderUpdate><orderRef>ORD-123</orderRef><externalOrderId>EXT-123</externalOrderId><customerNotes>Leave at door</customerNotes></orderUpdate>
-  if (payload.orderUpdate && typeof payload.orderUpdate === 'object') {
-    for (const [key, value] of Object.entries(payload.orderUpdate)) {
-      // Skip metadata fields
-      if (metadataFields.includes(key)) {
-        continue;
-      }
-      const textValue = extractTextContent(value as VersoriXMLParsed);
-      if (textValue !== null && textValue !== undefined) {
-        // Auto-detect type from value (basic detection for XML - mostly STRING)
-        // For more complex types, use the attributes format
-        let type: AttributeInput['type'] = 'STRING';
-        // Try to detect number
-        const numValue = Number(textValue);
-        if (!isNaN(numValue) && textValue.trim() !== '') {
-          type = Number.isInteger(numValue) ? 'INTEGER' : 'FLOAT';
-        }
-        // Try to detect boolean
-        else if (textValue.toLowerCase() === 'true' || textValue.toLowerCase() === 'false') {
-          type = 'BOOLEAN';
-        }
-        attributes.push({
-          name: key,
-          type,
-          value: textValue,
-        });
-      }
-    }
-  }
-  // ALTERNATIVE FORMAT: orderUpdate.attributes.attribute (nested structure)
-  // Only used if flat structure didn't yield any attributes
-  if (attributes.length === 0 && payload.orderUpdate?.attributes?.attribute) {
-    const attrArray = Array.isArray(payload.orderUpdate.attributes.attribute)
-      ? payload.orderUpdate.attributes.attribute
-      : [payload.orderUpdate.attributes.attribute];
-    for (const attr of attrArray) {
-      if (typeof attr === 'object') {
-        // Element format: <attribute><name>...</name><value>...</value></attribute>
-        const name = extractTextContent(attr.name as VersoriXMLParsed) ||
-                     (attr.$ as Record<string, unknown>)?.name as string;
-        const value = extractTextContent(attr.value as VersoriXMLParsed) ||
-                      (attr.$ as Record<string, unknown>)?.value as string;
-        const type = (extractTextContent(attr.type as VersoriXMLParsed) ||
-                     (attr.$ as Record<string, unknown>)?.type as string || 'STRING') as AttributeInput['type'];
-        if (name && value !== null && value !== undefined) {
-          attributes.push({
-            name: String(name),
-            type: type || 'STRING',
-            value: String(value),
-          });
-        }
-      }
-    }
-  }
-  return attributes;
-}
-/**
- * Parse webhook payload from Versori context
- *
- * CRITICAL: Versori automatically parses XML when Content-Type: application/xml is set.
- * The ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
- *
- * Handles both pre-parsed XML (ctx.data) and raw request body (ctx.request) as fallback
- */
-async function parseWebhookPayload(
-  ctx: VersoriContext
-): Promise<OrderUpdatePayload | null> {
-  const { log, data, request } = ctx;
-  // ✅ Scenario 1: Pre-parsed XML (Versori auto-parsed when Content-Type: application/xml)
-  // This is the PRIMARY path - Versori handles XML parsing automatically
-  if (data && typeof data === 'object' && data !== null) {
-    log.info('📥 [PARSE] Using Versori auto-parsed XML payload', {
-      hasData: true,
-      dataKeys: Object.keys(data),
-      contentType: request?.headers?.get('content-type'),
-    });
-    return data as OrderUpdatePayload;
-  }
-  // ⚠️ Scenario 2: Raw request body (fallback - should rarely be needed)
-  // Only used if Versori didn't auto-parse (e.g., wrong Content-Type header)
-  if (request && typeof request.text === 'function') {
-    log.warn('📥 [PARSE] Falling back to manual XML parsing (Content-Type may be incorrect)');
-    try {
-      const rawBody = await request.text();
-      if (!rawBody || rawBody.trim() === '') {
-        log.error('❌ [PARSE] Request body is empty');
-        return null;
-      }
-      const parser = new XMLParserService(log);
-      const parsed = await parser.parse(rawBody);
-      log.info('📥 [PARSE] Successfully parsed XML payload', {
-        parsedKeys: Object.keys(parsed),
-      });
-      return parsed as OrderUpdatePayload;
-    } catch (parseError: unknown) {
-      const errorMessage =
-        parseError instanceof Error ? parseError.message : String(parseError);
-      log.error('❌ [PARSE] Failed to parse XML payload', {
-        error: errorMessage,
-      });
-      return null;
-    }
-  }
-  log.error('❌ [PARSE] No valid payload found in context');
-  return null;
-}
-/**
- * Query order by reference to get ID and current state
- */
-async function queryOrderByRef(
-  client: FluentClient,
-  orderRef: string,
-  log: VersoriContext['log']
-): Promise<OrderQueryResult> {
-  log.info('🔍 [QUERY] Querying order by reference', { orderRef });
-  const result = await client.graphql({
-    query: GET_ORDER_QUERY,
-    variables: { ref: orderRef },
-  });
-  if (result.errors && result.errors.length > 0) {
-    log.error('❌ [QUERY] GraphQL query returned errors', {
-      errors: result.errors,
-      orderRef,
-    });
-    throw new Error(`GraphQL query failed: ${result.errors[0].message}`);
-  }
-  const order = (result.data as any)?.order;
-  if (!order) {
-    log.error('❌ [QUERY] Order not found', { orderRef });
-    throw new Error(`Order not found: ${orderRef}`);
-  }
-  log.info('✅ [QUERY] Order found', {
-    orderId: order.id,
-    orderRef: order.ref,
-    status: order.status,
-    currentAttributeCount: order.attributes?.length || 0,
-  });
-  return order as OrderQueryResult;
-}
-/**
- * Execute order update workflow
- *
- * Main orchestration function:
- * 1. Parse webhook payload
- * 2. Extract order reference and attributes
- * 3. Create Fluent client
- * 4. Query order by reference to get ID
- * 5. Build update mutation variables
- * 6. Execute updateOrder mutation
- *
- * Note: Authentication handled via Versori connection (fluent_commerce).
- * Retailer ID is not required for GraphQL mutations - connection handles authentication.
- *
- * CRITICAL: UpdateOrderInput requires id: ID! (not ref).
- * The query step retrieves order.id which must be used in the mutation.
- */
-export async function executeOrderUpdate(
-  ctx: VersoriContext
-): Promise<OrderUpdateResult> {
-  const { log, activation } = ctx;
-  log.info('🚀 [SERVICE] Starting order update processing');
-  // STEP 1: Parse webhook payload
-  // ✅ Versori automatically parses XML when Content-Type: application/xml is set
-  // ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
-  const payload = await parseWebhookPayload(ctx);
-  if (!payload) {
-    log.error('❌ [SERVICE] Failed to parse webhook payload', {
-      hasData: !!ctx.data,
-      hasRequest: !!ctx.request,
-    });
-    throw new Error(
-      'Failed to parse webhook payload. Ensure Content-Type: application/xml is set in request headers.'
-    );
-  }
-  log.info('📥 [SERVICE] Payload parsed successfully (Versori auto-parsed XML)', {
-    payloadKeys: Object.keys(payload),
-    note: 'Versori automatically parses XML when Content-Type: application/xml is set',
-  });
-  // STEP 2: Extract order reference
-  const orderRef = extractOrderRef(payload);
-  if (!orderRef) {
-    log.error('❌ [SERVICE] Order reference not found in XML payload', {
-      payloadKeys: Object.keys(payload),
-      expectedPatterns: [
-        'orderUpdate.orderRef',
-        'orderUpdate[@orderRef]',
-        'order[@ref]',
-      ],
-    });
-    throw new Error(
-      'Order reference not found in XML payload. Expected patterns: orderUpdate.orderRef, orderUpdate[@orderRef], or order[@ref]'
-    );
-  }
-  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
-  // STEP 3: Extract attributes
-  const attributes = extractAttributes(payload);
-  if (attributes.length === 0) {
-    log.warn('⚠️ [SERVICE] No attributes provided in payload', { orderRef });
-    throw new Error('At least one attribute is required for order update');
-  }
-  log.info('✅ [SERVICE] Attributes extracted', {
-    orderRef,
-    attributeCount: attributes.length,
-    attributeNames: attributes.map(a => a.name),
-  });
-  // STEP 4: Create Fluent client
-  // ✅ Pass ctx directly - createClient auto-detects Versori context
-  // Authentication handled via Versori connection (fluent_commerce)
-  const client = await createClient(ctx);
-  log.info('✅ [SERVICE] Fluent client created');
-  // STEP 5: Query order by reference to get ID
-  // ✅ Query first to:
-  //    - Validate order exists (fail-fast if order not found)
-  //    - Get order ID for logging and tracking
-  //    - Get current order state (optional: can merge with existing attributes)
-  const order = await queryOrderByRef(client, orderRef, log);
-  // STEP 6: Build update mutation variables
-  // ✅ CRITICAL: UpdateOrderInput requires id: ID! (not ref)
-  //    Use the ID from queryOrderByRef result - this is why we query first!
-  const updateVariables = {
-    input: {
-      id: order.id, // ✅ REQUIRED: UpdateOrderInput.id is ID! (required field)
-      attributes: attributes,
-    },
-  };
-  log.info('📤 [SERVICE] Executing updateOrder mutation', {
-    orderRef,
-    orderId: order.id,
-    attributeCount: attributes.length,
-  });
-  // STEP 7: Execute updateOrder mutation
-  const mutationResult = await client.graphql({
-    query: UPDATE_ORDER_MUTATION,
-    variables: updateVariables,
-  });
-  if (mutationResult.errors && mutationResult.errors.length > 0) {
-    log.error('❌ [SERVICE] GraphQL mutation returned errors', {
-      errors: mutationResult.errors,
-      orderRef,
-      orderId: order.id,
-    });
-    throw new Error(`GraphQL mutation failed: ${mutationResult.errors[0].message}`);
-  }
-  const updatedOrder = (mutationResult.data as any)?.updateOrder;
-  if (!updatedOrder) {
-    log.error('❌ [SERVICE] No order data returned from mutation', { orderRef });
-    throw new Error('No order data returned from updateOrder mutation');
-  }
-  log.info('✅ [SERVICE] Order updated successfully', {
-    orderRef,
-    orderId: updatedOrder.id,
-    attributesUpdated: attributes.length,
-  });
-  // Return success response with FC200 status code
-  return createSuccessResponse({
-    success: true,
-    orderRef,
-    orderId: updatedOrder.id,
-    attributesUpdated: attributes.length,
-    message: 'Order attributes updated successfully',
-  });
-}
-```
----
-## 5. Configuration
-### Activation Variables
-No activation variables required. Authentication is handled via Versori connection (`fluent_commerce`).
-**Note:** Configure Fluent Commerce credentials in the Versori connection settings. The connection handles authentication automatically.
-### Webhook Connection
-Create a Versori connection for webhook authentication:
-1. **Connection Name:** `order-update-webhook`
-2. **Type:** API Key or Basic Auth
-3. **Purpose:** Authenticate incoming webhook requests
-**Example webhook call:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-update.xml
-```
-**Example XML file (`order-update.xml`):**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-12345</orderRef>
-  <externalOrderId>EXT-123456789</externalOrderId>
-  <customerNotes>Please leave package at front door</customerNotes>
-  <priority>high</priority>
-</orderUpdate>
-```
-**CRITICAL: Content-Type Header**
-The `Content-Type: application/xml` header is **required** for Versori to automatically parse the XML. Without this header, Versori will not parse the XML and you'll need to manually parse using `XMLParserService`.
-**✅ CORRECT:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/xml" \  # ✅ Required!
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-update.xml
-```
-**❌ WRONG:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: text/plain" \  # ❌ Wrong Content-Type
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-update.xml
-```
----
-## 6. Error Handling
-The template includes comprehensive error handling:
-### Payload Parsing Errors
-- **Empty payload:** Returns error response
-- **Invalid XML:** Returns error with parse details
-- **Missing order reference:** Returns error with expected patterns
-- **Missing attributes:** Returns error if no attributes provided
-### Order Query Errors
-- **Order not found:** Returns error with order reference
-- **GraphQL query errors:** Returns error with GraphQL error details
-### Mutation Errors
-- **GraphQL mutation errors:** Returns error with mutation error details
-- **No response data:** Returns error if mutation doesn't return order data
-### Response Format with FC Status Codes
-**Success Response (FC200):**
-```json
-{
-  "success": true,
-  "statusCode": "FC200",
-  "orderRef": "ORD-12345",
-  "orderId": "12345",
-  "attributesUpdated": 3,
-  "message": "Order attributes updated successfully"
-}
-```
-**Error Responses:**
-**FC400 - Bad Request (Non-retryable):**
-```json
-{
-  "success": false,
-  "statusCode": "FC400",
-  "retryable": false,
-  "error": "Bad request. Please verify payload and try again.",
-  "details": "Order reference (orderRef) is required in payload"
-}
-```
-**FC409 - Duplicate/Already Exists (Non-retryable):**
-```json
-{
-  "success": false,
-  "statusCode": "FC409",
-  "retryable": false,
-  "error": "Entity already exists. Duplicate request detected.",
-  "details": "Order with reference ORD-12345 already exists"
-}
-```
-**FC504 - Timeout (Retryable):**
-```json
-{
-  "success": false,
-  "statusCode": "FC504",
-  "retryable": true,
-  "error": "Request timeout. Please retry.",
-  "details": "GraphQL mutation timed out after 30 seconds"
-}
-```
----
-## 7. Testing
-### Test with cURL - Flat Structure Format
-**Create `order-update.xml`:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-12345</orderRef>
-  <externalOrderId>EXT-123456789</externalOrderId>
-  <customerNotes>Please leave package at front door</customerNotes>
-  <priority>high</priority>
-</orderUpdate>
-```
-**Send with cURL:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-update.xml
-```
-### Test with Inline XML
-```bash
-# Test with inline XML (flat format)
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  -d '<?xml version="1.0" encoding="UTF-8"?><orderUpdate><orderRef>ORD-12345</orderRef><externalOrderId>EXT-123456789</externalOrderId><customerNotes>Please leave package at front door</customerNotes></orderUpdate>'
-```
-### Complete Sample XML Files
-**Example 1: External System Reference (`external-reference-update.xml`)**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-0017326966182</orderRef>
-  <externalOrderId>EXT-123456789</externalOrderId>
-  <sourceSystem>ERP-SAP</sourceSystem>
-  <integrationId>INT-987654321</integrationId>
-</orderUpdate>
-```
-**Example 2: Customer Notes and Business Flags (`customer-notes-update.xml`)**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderUpdate>
-  <orderRef>ORD-0017326966182</orderRef>
-  <customerNotes>Please leave package at front door</customerNotes>
-  <priority>high</priority>
-  <tags>rush,gift</tags>
-  <specialHandling>true</specialHandling>
-</orderUpdate>
-```
-### Expected Success Response
-```json
-{
-  "success": true,
-  "statusCode": "FC200",
-  "orderRef": "ORD-12345",
-  "orderId": "12345",
-  "attributesUpdated": 1,
-  "message": "Order attributes updated successfully"
-}
-```
-**FC Status Code:** `FC200` - OK (Successfully - No further action needed)
-### Expected Error Responses
-**FC400 - Bad Request:**
-```json
-{
-  "success": false,
-  "statusCode": "FC400",
-  "retryable": false,
-  "error": "Bad request. Please verify payload and try again.",
-  "details": "Order not found: ORD-12345"
-}
-```
-**FC409 - Duplicate/Already Exists:**
-```json
-{
-  "success": false,
-  "statusCode": "FC409",
-  "retryable": false,
-  "error": "Entity already exists. Duplicate request detected.",
-  "details": "Order with reference ORD-12345 already exists"
-}
-```
-**FC504 - Timeout:**
-```json
-{
-  "success": false,
-  "statusCode": "FC504",
-  "retryable": true,
-  "error": "Request timeout. Please retry.",
-  "details": "GraphQL mutation timed out"
-}
-```
----
-## 8. Customization
-### Custom Order Reference Element
-If your XML uses different element names, modify `extractOrderRef()`:
-```typescript
-function extractOrderRef(payload: OrderUpdatePayload): string | null {
-  // Add your custom element extraction logic
-  if (payload.customUpdate && typeof payload.customUpdate === 'object') {
-    const update = payload.customUpdate;
-    if ('$' in update && update.$) {
-      const attrs = update.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.orderId === 'string') {
-        return attrs.orderId;
-      }
-    }
-  }
-  // ... existing logic
-}
-```
-### Custom Attribute Extraction
-To customize how attributes are extracted from XML:
-```typescript
-function extractAttributes(payload: OrderUpdatePayload): AttributeInput[] {
-  // Add custom extraction logic for your XML structure
-  // e.g., handle nested attribute structures, namespaces, etc.
-}
-```
-### Merge with Existing Attributes
-To merge new attributes with existing ones (instead of replacing):
-```typescript
-// In executeOrderUpdate function, after queryOrderByRef:
-const existingAttributes = order.attributes || [];
-const mergedAttributes = [
-  ...existingAttributes,
-  ...attributes, // New attributes override existing ones with same name
-];
-const updateVariables = {
-  input: {
-    id: order.id, // ✅ REQUIRED: Use ID from query result
-    attributes: mergedAttributes,
-  },
-};
-```
----
-## Summary
-✅ **DO:**
-- Use Versori connection for Fluent Commerce credentials
-- Query order first to validate existence and get ID
-- Use `id` from query result in UpdateOrderInput (required field)
-- Handle Versori XML format ($ for attributes, _ for text)
-- Support multiple XML attribute formats
-- Log all steps for debugging
-- Return clear error messages
-❌ **DON'T:**
-- Hardcode credentials in code
-- Skip order query validation
-- Use `ref` in UpdateOrderInput (must use `id: ID!`)
-- Assume payload format without validation
-- Skip error handling
-- Ignore Versori XML parsing format ($ and _)
----
-## Next Steps
-1. **Deploy:** Copy code to your Versori project
-2. **Configure:** Set up Fluent Commerce connection and activation variables
-3. **Test:** Test webhook with sample XML payloads
-4. **Monitor:** Check Versori logs for order updates
-For more templates, see:
-- [JSON Payload Template](./template-ingestion-payload-json-order-update-graphql.md)
-- [Other GraphQL Mutation Templates](./graphql-mutations-guide.md)
+---
+template_id: tpl-ingest-payload-xml-to-order-update-graphql
+canonical_filename: template-ingestion-payload-xml-order-update-graphql.md
+sdk_version: latest
+runtime: versori
+direction: ingestion
+source: payload-xml
+destination: fluent-graphql
+entity: order
+format: xml
+logging: versori
+status: stable
+features:
+  - direct-payload-processing
+  - xml-parsing
+  - graphql-mutations
+  - order-query-before-update
+  - attribute-updates
+---
+# Template: Ingestion - Payload XML to Order Update GraphQL
+**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+---
+## 📋 Implementation Prompt
+```
+I need a Versori webhook ingestion that:
+1) Receives XML payload directly in webhook request body with orderRef and attributes
+2) Parses XML to extract order reference and attributes (handles Versori $ format for attributes)
+3) Queries Fluent Commerce to get order ID by order reference
+4) Updates order attributes using updateOrder GraphQL mutation
+5) Returns success/error response
+6) Uses native Versori log from context
+Use the loaded docs to fill in SDK specifics and best practices.
+Keep the structure identical to the template; only adapt where needed.
+```
+---
+## 📋 Template Overview
+This connector runs on the Versori platform. It receives XML payloads directly via webhook with order reference and attributes, queries Fluent Commerce to get the order ID, and updates order attributes using GraphQL mutations. Most operational settings (Fluent account/connection) are configured via activation variables.
+### What This Template Does
+```
+┌────────────────────────────────────────────────────────────────┐
+│          INGESTION WORKFLOW              │
+└────────────────────────────────────────────────────────────────┘
+1. TRIGGER
+  └─ Webhook: HTTP POST endpoint receives XML payload
+2. RECEIVE PAYLOAD
+  ├─ Extract XML from request body (ctx.data or ctx.request)
+  ├─ Validate payload structure
+  └─ Log incoming request
+3. PARSE XML
+  ├─ Parse XML payload (Versori auto-parses with $ format)
+  ├─ Extract order reference (handles $ for attributes, _ for text)
+  ├─ Extract attributes array
+  └─ Validate required fields
+4. QUERY ORDER
+  ├─ Query Fluent Commerce: order(ref: orderRef)
+  ├─ Get order ID and current state
+  ├─ Validate order exists
+  └─ Log order details
+5. BUILD UPDATE MUTATION
+  ├─ Construct UpdateOrderInput with ref
+  ├─ Map attributes to AttributeInput format
+  ├─ Preserve existing attributes (optional merge)
+  └─ Build GraphQL mutation variables
+6. EXECUTE MUTATION
+  ├─ Execute updateOrder GraphQL mutation
+  ├─ Handle success/error responses
+  └─ Log mutation result
+7. RETURN RESPONSE
+  ├─ Return success with order details
+  └─ Return error with details if failed
+```
+### Key Features
+- **Direct Payload Processing**: Receives XML payload directly in webhook request body
+- **Versori XML Parsing**: Handles Versori auto-parsed XML format ($ for attributes, _ for text)
+- **Order Query First**: Queries order by ref to get ID and validate existence
+- **GraphQL Mutation**: Uses updateOrder mutation to update attributes
+- **Attribute Mapping**: Converts XML attributes to Fluent AttributeInput format
+- **Error Handling**: Comprehensive error handling with detailed logging
+- **Native Versori Logging**: Uses Versori log from context
+### 📦 Package Information
+**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
+```bash
+npm install @fluentcommerce/fc-connect-sdk@latest
+```
+---
+**Templates are designed for direct deployment; customize via activation variables.**
+---
+## 📦 SDK Imports (Verified - Versori Optimized)
+```typescript
+// ✅ VERIFIED IMPORTS - These match actual SDK exports
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
+import {
+  createClient, // Universal client factory
+  XMLParserService, // XML parsing utility
+} from '@fluentcommerce/fc-connect-sdk';
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+// Versori platform imports
+import { webhook, http } from '@versori/run';
+```
+**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
+**⚠️ CRITICAL - Buffer Import Required:**
+The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
+- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
+- Without this import, code will crash with `ReferenceError: Buffer is not defined`
+- Always include this import in Versori templates, even if not directly used in the template code
+- Required for SDK internal operations and any Buffer usage in your code
+**✅ VERSORI PLATFORM - Use Native Logs:**
+- Use `log` from context: `const { log } = ctx;`
+- Native Versori logs are simpler and automatically integrated with platform monitoring
+**✅ VERSORI XML PARSING:**
+Versori automatically parses XML payloads when `Content-Type: application/xml` is set:
+- Attributes accessed via `$` (e.g., `element.$?.attributeName`)
+- Text content accessed via `_` (e.g., `element._`)
+- Nested elements accessed directly (e.g., `element.childElement`)
+---
+## 🔐 Fluent Commerce Connection Setup
+**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
+**Connection Configuration:**
+1. **Create Connection in Versori:**
+   - Name: `fluent_commerce`
+   - Type: HTTP Basic Auth or OAuth2
+   - Credentials: Fluent Commerce API credentials
+2. **Connection Variables:**
+   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
+   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
+   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
+   - `FLUENT_USERNAME` - Username (if using Basic Auth)
+   - `FLUENT_PASSWORD` - Password (if using Basic Auth)
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Connection can be reused across workflows
+- ✅ No sensitive data in activation variables
+- ✅ Easier credential rotation
+---
+## 📄 Expected XML Payload Format
+The webhook accepts **flat XML payloads**. All child elements except `orderRef` are automatically treated as order attributes.
+### ✅ PRIMARY FORMAT: Flat Structure (Recommended)
+**Simple format - just child elements, no nested attributes structure:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-12345</orderRef>
+  <externalOrderId>EXT-123456789</externalOrderId>
+  <customerNotes>Please leave package at front door</customerNotes>
+  <priority>high</priority>
+  <tags>rush,gift</tags>
+</orderUpdate>
+```
+**Type Auto-Detection:**
+- Numbers → `INTEGER` or `FLOAT` (auto-detected)
+- "true"/"false" → `BOOLEAN` (auto-detected)
+- Strings → `STRING` (default)
+**cURL Example:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  -d '<?xml version="1.0" encoding="UTF-8"?><orderUpdate><orderRef>ORD-12345</orderRef><externalOrderId>EXT-123456789</externalOrderId><customerNotes>Please leave package at front door</customerNotes><priority>high</priority></orderUpdate>'
+```
+### Complete Sample Payloads
+**Example 1: External System Reference Update**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-0017326966182</orderRef>
+  <externalOrderId>EXT-123456789</externalOrderId>
+  <sourceSystem>ERP-SAP</sourceSystem>
+  <integrationId>INT-987654321</integrationId>
+</orderUpdate>
+```
+**Example 2: Customer Notes and Business Flags**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-0017326966182</orderRef>
+  <customerNotes>Please leave package at front door</customerNotes>
+  <priority>high</priority>
+  <tags>rush,gift</tags>
+  <specialHandling>true</specialHandling>
+</orderUpdate>
+```
+**Note:** Metadata fields (`updateReason`, `updatedBy`, `timestamp`) are optional and excluded from attributes. All other child elements are treated as order attributes.
+**Versori XML Parsing Format (CRITICAL):**
+When Versori receives XML with `Content-Type: application/xml`, it **automatically parses** the XML into a JavaScript object. You do NOT need to manually parse XML - Versori handles it automatically.
+**Access Patterns:**
+- **Attributes**: `element.$?.attributeName` (e.g., `<orderUpdate orderRef="ORD-12345"/>` → `orderUpdate.$?.orderRef`)
+- **Text content**: `element._` or direct property access (e.g., `<orderRef>ORD-12345</orderRef>` → `orderRef._` or `orderRef`)
+- **Nested elements**: Direct property access (e.g., `<orderUpdate><orderRef>...</orderRef></orderUpdate>` → `orderUpdate.orderRef`)
+**Examples:**
+```typescript
+// XML: <orderUpdate orderRef="ORD-12345"/>
+// Versori auto-parsed: { orderUpdate: { $: { orderRef: "ORD-12345" } } }
+const orderRef = parsed.orderUpdate?.$?.orderRef; // ✅ "ORD-12345"
+// XML: <orderRef>ORD-12345</orderRef>
+// Versori auto-parsed: { orderRef: { _: "ORD-12345" } } OR { orderRef: "ORD-12345" }
+const orderRef = parsed.orderRef?._ || parsed.orderRef; // ✅ "ORD-12345"
+// XML: <attribute name="status" value="processing"/>
+// Versori auto-parsed: { attribute: { $: { name: "status", value: "processing" } } }
+const attrName = parsed.attribute?.$?.name; // ✅ "status"
+const attrValue = parsed.attribute?.$?.value; // ✅ "processing"
+```
+**Key Point:** Versori automatically parses XML when `Content-Type: application/xml` is set. Your webhook receives `ctx.data` as a pre-parsed JavaScript object - no manual XML parsing needed!
+---
+## GraphQL Mutations
+### Query Order by Reference
+```graphql
+query GetOrder($ref: String!) {
+  order(ref: $ref) {
+    id
+    ref
+    status
+    attributes {
+      name
+      type
+      value
+    }
+  }
+}
+```
+### Update Order Mutation
+```graphql
+mutation UpdateOrder($input: UpdateOrderInput!) {
+  updateOrder(input: $input) {
+    id
+    ref
+    status
+    attributes {
+      name
+      type
+      value
+    }
+  }
+}
+```
+**UpdateOrderInput Structure:**
+- `id` (ID!) - Order ID (required) - Must use Fluent internal ID, not reference
+- `attributes` (Array<AttributeInput>) - Attributes to update
+- `status` (String) - Optional status update
+- Other optional fields as per schema
+**Note:** UpdateOrderInput requires `id: ID!` (the Fluent internal ID), not `ref`. This is why the template queries the order first to get the ID.
+**AttributeInput Structure:**
+- `name` (String!) - Attribute name
+- `type` (String!) - Attribute type (STRING, INTEGER, FLOAT, BOOLEAN, JSON, DATE)
+- `value` (String!) - Attribute value (stringified for non-STRING types)
+---
+## 🔧 Complete Production Code
+### Versori Workflows Structure
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from webhook)
+### Recommended Project Structure
+```
+order-update-webhook/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-update.ts           # Webhook: Order update handler
+    │
+    ├── services/
+    │   └── order-update.service.ts       # Shared orchestration logic
+    │
+    ├── utils/
+    │   └── response-status.utils.ts      # FC status code mapping utilities
+    │
+    └── types/
+        └── order-update.types.ts         # Type definitions
+```
+**Benefits:**
+- ✅ Clear structure (webhook handlers in `webhook/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Centralized type definitions
+- ✅ Utility functions for consistent error handling (FC status codes)
+---
+## Workflow Files
+### 1. Webhook Workflow (`src/workflows/webhook/order-update.ts`)
+**Purpose**: Handle order update requests via webhook
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/order-update`
+**Use Cases**: Order attribute updates from external systems, status changes
+```typescript
+import { webhook, http } from '@versori/run';
+import { executeOrderUpdate } from '../../services/order-update.service';
+import { mapErrorToFCStatus } from '../../utils/response-status.utils';
+/**
+ * Webhook: Order Update Handler
+ *
+ * Endpoint: POST https://{workspace}.versori.run/order-update
+ * Request body: XML with orderRef and flat attribute elements
+ * Content-Type: application/xml
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: order-update.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const orderUpdateWebhook = webhook('order-update', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+  connection: 'order-update-webhook', // Versori validates API key
+}).then(
+  http('process-order-update', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+    log.info('🚀 [WEBHOOK] Order update request received', {
+      timestamp: new Date().toISOString(),
+      hasPayload: !!data,
+      contentType: ctx.request?.headers?.get('content-type'),
+    });
+    try {
+      // Reuse shared orchestration logic
+      const result = await executeOrderUpdate(ctx);
+      log.info('✅ [WEBHOOK] Order update completed successfully', {
+        orderRef: result.orderRef,
+        orderId: result.orderId,
+        attributesUpdated: result.attributesUpdated,
+      });
+      // Return response with FC200 status code
+      return {
+        success: true,
+        statusCode: result.statusCode,
+        orderRef: result.orderRef,
+        orderId: result.orderId,
+        attributesUpdated: result.attributesUpdated,
+        message: result.message || 'Order attributes updated successfully',
+      };
+    } catch (e: any) {
+      log.error('❌ [WEBHOOK] Order update failed', {
+        message: e?.message,
+        stack: e?.stack,
+      });
+      // Map error to FC status code
+      const fcStatus = mapErrorToFCStatus(e);
+      return {
+        success: false,
+        statusCode: fcStatus.statusCode,
+        retryable: fcStatus.retryable,
+        error: fcStatus.message,
+        details: e?.message || 'Unknown error occurred',
+      };
+    }
+  })
+);
+```
+---
+### 2. Entry Point (`index.ts`)
+**Purpose**: Register all workflows with Versori platform
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ * - src/services/            → Shared service logic (reusable across workflows)
+ */
+// Import webhook workflows
+import { orderUpdateWebhook } from './src/workflows/webhook/order-update';
+// Register all workflows with Versori platform
+export {
+  // Webhooks (HTTP-based triggers)
+  orderUpdateWebhook,
+};
+```
+**What Gets Exposed:**
+- ✅ `orderUpdateWebhook` → `https://{workspace}.versori.run/order-update`
+---
+## 3. Type Definitions (`src/types/order-update.types.ts`)
+```typescript
+/**
+ * Type Definitions for Order Update Ingestion
+ *
+ * Centralized type definitions for order update workflow
+ */
+/**
+ * Versori XML parsed format
+ * Attributes accessed via $, text content via _
+ */
+export interface VersoriXMLParsed {
+  [key: string]: unknown;
+  $?: Record<string, unknown>; // Attributes
+  _?: string; // Text content
+}
+/**
+ * Order update request payload (XML parsed format)
+ */
+export interface OrderUpdatePayload {
+  orderUpdate?: {
+    orderRef?: VersoriXMLParsed | string;
+    attributes?: {
+      attribute?: VersoriXMLParsed | Array<VersoriXMLParsed>;
+    };
+    $?: {
+      orderRef?: string;
+    };
+    [key: string]: VersoriXMLParsed | string | unknown; // Flat attributes
+  };
+  order?: {
+    ref?: VersoriXMLParsed | string;
+    $?: {
+      ref?: string;
+    };
+  };
+  [key: string]: unknown; // Allow additional fields
+}
+/**
+ * Fluent AttributeInput format
+ */
+export interface AttributeInput {
+  name: string;
+  type: 'STRING' | 'INTEGER' | 'FLOAT' | 'BOOLEAN' | 'JSON' | 'DATE';
+  value: string;
+}
+/**
+ * Order query result
+ */
+export interface OrderQueryResult {
+  id: string;
+  ref: string;
+  status?: string;
+  attributes?: Array<{
+    name: string;
+    type: string;
+    value: string;
+  }>;
+}
+/**
+ * Order update result with FC status code
+ */
+export interface OrderUpdateResult {
+  success: boolean;
+  statusCode: 'FC200' | 'FC400' | 'FC409' | 'FC504';
+  orderRef: string;
+  orderId: string;
+  attributesUpdated: number;
+  message?: string;
+  error?: string;
+  retryable?: boolean;
+}
+/**
+ * Versori Context Interface
+ * Represents the Versori runtime context passed to workflow functions
+ */
+export interface VersoriContext {
+  log: {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    debug?: (message: string, data?: Record<string, unknown>) => void;
+  };
+  data?: unknown;
+  request?: Request;
+  activation: {
+    getVariable: (name: string) => string | undefined;
+    connections?: Record<string, unknown>;
+  };
+  connections?: Record<string, unknown>;
+}
+```
+---
+## 4. Utility: Response Status Code Mapper (`src/utils/response-status.utils.ts`)
+```typescript
+/**
+ * Response Status Code Utility
+ *
+ * Maps errors to Fluent Commerce (FC) status codes for consistent API responses
+ */
+/**
+ * FC Status Codes:
+ * - FC200: OK (Successfully - No further action needed)
+ * - FC400: Bad Request (Non-retryable)
+ * - FC409: Duplicate Request, Entity already exists (Non-retryable)
+ * - FC504: Timeout (Retryable)
+ */
+export type FCStatusCode = 'FC200' | 'FC400' | 'FC409' | 'FC504';
+export interface FCStatusMapping {
+  statusCode: FCStatusCode;
+  retryable: boolean;
+  message: string;
+}
+/**
+ * Map error to FC status code based on error message and type
+ */
+export function mapErrorToFCStatus(error: unknown): FCStatusMapping {
+  const errorMessage =
+    error instanceof Error ? error.message : String(error);
+  const lowerMessage = errorMessage.toLowerCase();
+  // FC409: Duplicate/Already exists (Non-retryable)
+  if (
+    lowerMessage.includes('already exists') ||
+    lowerMessage.includes('duplicate') ||
+    lowerMessage.includes('unique constraint') ||
+    lowerMessage.includes('entity already exists')
+  ) {
+    return {
+      statusCode: 'FC409',
+      retryable: false,
+      message: 'Entity already exists. Duplicate request detected.',
+    };
+  }
+  // FC504: Timeout (Retryable)
+  if (
+    lowerMessage.includes('timeout') ||
+    lowerMessage.includes('timed out') ||
+    lowerMessage.includes('request timeout') ||
+    (error instanceof Error && error.name === 'TimeoutError')
+  ) {
+    return {
+      statusCode: 'FC504',
+      retryable: true,
+      message: 'Request timeout. Please retry.',
+    };
+  }
+  // FC400: Bad Request (Non-retryable)
+  // Validation errors, missing fields, invalid format
+  if (
+    lowerMessage.includes('required') ||
+    lowerMessage.includes('missing') ||
+    lowerMessage.includes('invalid') ||
+    lowerMessage.includes('bad request') ||
+    lowerMessage.includes('validation') ||
+    lowerMessage.includes('not found') ||
+    lowerMessage.includes('does not exist')
+  ) {
+    return {
+      statusCode: 'FC400',
+      retryable: false,
+      message: 'Bad request. Please verify payload and try again.',
+    };
+  }
+  // Default: FC400 for unknown errors (Non-retryable)
+  return {
+    statusCode: 'FC400',
+    retryable: false,
+    message: errorMessage,
+  };
+}
+/**
+ * Create success response with FC200 status
+ */
+export function createSuccessResponse<T extends Record<string, unknown>>(
+  data: T
+): T & { statusCode: 'FC200'; retryable: false } {
+  return {
+    ...data,
+    statusCode: 'FC200' as const,
+    retryable: false,
+  };
+}
+```
+---
+## 5. Service: Order Update Processor (`src/services/order-update.service.ts`)
+```typescript
+/**
+ * Order Update Service
+ *
+ * Processes order update requests: extracts order reference and attributes from XML payload,
+ * queries Fluent Commerce to get order ID, and updates order attributes via GraphQL mutation.
+ * Handles Versori XML parsing format ($ for attributes, _ for text).
+ */
+import {
+  createClient,
+  XMLParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+import { Buffer } from 'node:buffer';
+import { mapErrorToFCStatus, createSuccessResponse } from '../utils/response-status.utils';
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+import type {
+  OrderUpdatePayload,
+  OrderUpdateResult,
+  VersoriContext,
+  AttributeInput,
+  OrderQueryResult,
+  VersoriXMLParsed,
+} from '../types/order-update.types';
+/**
+ * GraphQL query to get order by reference
+ */
+const GET_ORDER_QUERY = `
+  query GetOrder($ref: String!) {
+    order(ref: $ref) {
+      id
+      ref
+      status
+      attributes {
+        name
+        type
+        value
+      }
+    }
+  }
+`;
+/**
+ * GraphQL mutation to update order
+ */
+const UPDATE_ORDER_MUTATION = `
+  mutation UpdateOrder($input: UpdateOrderInput!) {
+    updateOrder(input: $input) {
+      id
+      ref
+      status
+      attributes {
+        name
+        type
+        value
+      }
+    }
+  }
+`;
+/**
+ * Extract text content from Versori XML parsed format
+ * Handles both object format ({ _: "text" }) and direct string
+ */
+function extractTextContent(value: VersoriXMLParsed | string | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'object' && '_' in value) {
+    const text = value._;
+    return typeof text === 'string' ? text : null;
+  }
+  return null;
+}
+/**
+ * Extract order reference from XML payload
+ *
+ * Supports multiple XML formats:
+ * - <orderUpdate><orderRef>ORD-12345</orderRef></orderUpdate>
+ * - <orderUpdate orderRef="ORD-12345"/>
+ * - <order ref="ORD-12345"/>
+ */
+function extractOrderRef(payload: OrderUpdatePayload): string | null {
+  // Try orderUpdate.orderRef (text content)
+  if (payload.orderUpdate) {
+    const orderUpdate = payload.orderUpdate;
+    // Try orderUpdate.orderRef as text
+    if (orderUpdate.orderRef) {
+      const ref = extractTextContent(orderUpdate.orderRef);
+      if (ref) {
+        return ref;
+      }
+      if (typeof orderUpdate.orderRef === 'string') {
+        return orderUpdate.orderRef;
+      }
+    }
+    // Try orderUpdate.$?.orderRef (root attribute)
+    if ('$' in orderUpdate && orderUpdate.$) {
+      const attrs = orderUpdate.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.orderRef === 'string') {
+        return attrs.orderRef;
+      }
+    }
+  }
+  // Try direct order element
+  if (payload.order) {
+    const order = payload.order;
+    // Try order.$?.ref (attribute)
+    if (typeof order === 'object' && '$' in order && order.$) {
+      const attrs = order.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.ref === 'string') {
+        return attrs.ref;
+      }
+    }
+    // Try order.ref (text content)
+    if (typeof order === 'object' && 'ref' in order) {
+      const ref = extractTextContent(order.ref as VersoriXMLParsed);
+      if (ref) {
+        return ref;
+      }
+    }
+  }
+  return null;
+}
+/**
+ * Extract attributes from XML payload
+ *
+ * PRIMARY FORMAT: Flat structure - all direct children of orderUpdate (except orderRef and metadata)
+ * - <orderUpdate><orderRef>ORD-123</orderRef><externalOrderId>EXT-123</externalOrderId></orderUpdate>
+ *
+ * Supports multiple XML formats:
+ * - PRIMARY: Flat structure: <externalOrderId>...</externalOrderId>
+ * - ALTERNATIVE: <attributes><attribute><name>...</name><value>...</value></attribute></attributes>
+ * - ALTERNATIVE: <attributes><attribute name="..." value="..."/></attributes>
+ */
+function extractAttributes(payload: OrderUpdatePayload): AttributeInput[] {
+  const attributes: AttributeInput[] = [];
+  const metadataFields = ['orderRef', 'attributes', '$', '_', 'updateReason', 'updatedBy', 'timestamp'];
+  // ✅ PRIMARY FORMAT: Flat structure - all direct children of orderUpdate (except orderRef and metadata)
+  // Example: <orderUpdate><orderRef>ORD-123</orderRef><externalOrderId>EXT-123</externalOrderId><customerNotes>Leave at door</customerNotes></orderUpdate>
+  if (payload.orderUpdate && typeof payload.orderUpdate === 'object') {
+    for (const [key, value] of Object.entries(payload.orderUpdate)) {
+      // Skip metadata fields
+      if (metadataFields.includes(key)) {
+        continue;
+      }
+      const textValue = extractTextContent(value as VersoriXMLParsed);
+      if (textValue !== null && textValue !== undefined) {
+        // Auto-detect type from value (basic detection for XML - mostly STRING)
+        // For more complex types, use the attributes format
+        let type: AttributeInput['type'] = 'STRING';
+        // Try to detect number
+        const numValue = Number(textValue);
+        if (!isNaN(numValue) && textValue.trim() !== '') {
+          type = Number.isInteger(numValue) ? 'INTEGER' : 'FLOAT';
+        }
+        // Try to detect boolean
+        else if (textValue.toLowerCase() === 'true' || textValue.toLowerCase() === 'false') {
+          type = 'BOOLEAN';
+        }
+        attributes.push({
+          name: key,
+          type,
+          value: textValue,
+        });
+      }
+    }
+  }
+  // ALTERNATIVE FORMAT: orderUpdate.attributes.attribute (nested structure)
+  // Only used if flat structure didn't yield any attributes
+  if (attributes.length === 0 && payload.orderUpdate?.attributes?.attribute) {
+    const attrArray = Array.isArray(payload.orderUpdate.attributes.attribute)
+      ? payload.orderUpdate.attributes.attribute
+      : [payload.orderUpdate.attributes.attribute];
+    for (const attr of attrArray) {
+      if (typeof attr === 'object') {
+        // Element format: <attribute><name>...</name><value>...</value></attribute>
+        const name = extractTextContent(attr.name as VersoriXMLParsed) ||
+                     (attr.$ as Record<string, unknown>)?.name as string;
+        const value = extractTextContent(attr.value as VersoriXMLParsed) ||
+                      (attr.$ as Record<string, unknown>)?.value as string;
+        const type = (extractTextContent(attr.type as VersoriXMLParsed) ||
+                     (attr.$ as Record<string, unknown>)?.type as string || 'STRING') as AttributeInput['type'];
+        if (name && value !== null && value !== undefined) {
+          attributes.push({
+            name: String(name),
+            type: type || 'STRING',
+            value: String(value),
+          });
+        }
+      }
+    }
+  }
+  return attributes;
+}
+/**
+ * Parse webhook payload from Versori context
+ *
+ * CRITICAL: Versori automatically parses XML when Content-Type: application/xml is set.
+ * The ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
+ *
+ * Handles both pre-parsed XML (ctx.data) and raw request body (ctx.request) as fallback
+ */
+async function parseWebhookPayload(
+  ctx: VersoriContext
+): Promise<OrderUpdatePayload | null> {
+  const { log, data, request } = ctx;
+  // ✅ Scenario 1: Pre-parsed XML (Versori auto-parsed when Content-Type: application/xml)
+  // This is the PRIMARY path - Versori handles XML parsing automatically
+  if (data && typeof data === 'object' && data !== null) {
+    log.info('📥 [PARSE] Using Versori auto-parsed XML payload', {
+      hasData: true,
+      dataKeys: Object.keys(data),
+      contentType: request?.headers?.get('content-type'),
+    });
+    return data as OrderUpdatePayload;
+  }
+  // ⚠️ Scenario 2: Raw request body (fallback - should rarely be needed)
+  // Only used if Versori didn't auto-parse (e.g., wrong Content-Type header)
+  if (request && typeof request.text === 'function') {
+    log.warn('📥 [PARSE] Falling back to manual XML parsing (Content-Type may be incorrect)');
+    try {
+      const rawBody = await request.text();
+      if (!rawBody || rawBody.trim() === '') {
+        log.error('❌ [PARSE] Request body is empty');
+        return null;
+      }
+      const parser = new XMLParserService(log);
+      const parsed = await parser.parse(rawBody);
+      log.info('📥 [PARSE] Successfully parsed XML payload', {
+        parsedKeys: Object.keys(parsed),
+      });
+      return parsed as OrderUpdatePayload;
+    } catch (parseError: unknown) {
+      const errorMessage =
+        parseError instanceof Error ? parseError.message : String(parseError);
+      log.error('❌ [PARSE] Failed to parse XML payload', {
+        error: errorMessage,
+      });
+      return null;
+    }
+  }
+  log.error('❌ [PARSE] No valid payload found in context');
+  return null;
+}
+/**
+ * Query order by reference to get ID and current state
+ */
+async function queryOrderByRef(
+  client: FluentClient,
+  orderRef: string,
+  log: VersoriContext['log']
+): Promise<OrderQueryResult> {
+  log.info('🔍 [QUERY] Querying order by reference', { orderRef });
+  const result = await client.graphql({
+    query: GET_ORDER_QUERY,
+    variables: { ref: orderRef },
+  });
+  if (result.errors && result.errors.length > 0) {
+    log.error('❌ [QUERY] GraphQL query returned errors', {
+      errors: result.errors,
+      orderRef,
+    });
+    throw new Error(`GraphQL query failed: ${result.errors[0].message}`);
+  }
+  const order = (result.data as any)?.order;
+  if (!order) {
+    log.error('❌ [QUERY] Order not found', { orderRef });
+    throw new Error(`Order not found: ${orderRef}`);
+  }
+  log.info('✅ [QUERY] Order found', {
+    orderId: order.id,
+    orderRef: order.ref,
+    status: order.status,
+    currentAttributeCount: order.attributes?.length || 0,
+  });
+  return order as OrderQueryResult;
+}
+/**
+ * Execute order update workflow
+ *
+ * Main orchestration function:
+ * 1. Parse webhook payload
+ * 2. Extract order reference and attributes
+ * 3. Create Fluent client
+ * 4. Query order by reference to get ID
+ * 5. Build update mutation variables
+ * 6. Execute updateOrder mutation
+ *
+ * Note: Authentication handled via Versori connection (fluent_commerce).
+ * Retailer ID is not required for GraphQL mutations - connection handles authentication.
+ *
+ * CRITICAL: UpdateOrderInput requires id: ID! (not ref).
+ * The query step retrieves order.id which must be used in the mutation.
+ */
+export async function executeOrderUpdate(
+  ctx: VersoriContext
+): Promise<OrderUpdateResult> {
+  const { log, activation } = ctx;
+  log.info('🚀 [SERVICE] Starting order update processing');
+  // STEP 1: Parse webhook payload
+  // ✅ Versori automatically parses XML when Content-Type: application/xml is set
+  // ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
+  const payload = await parseWebhookPayload(ctx);
+  if (!payload) {
+    log.error('❌ [SERVICE] Failed to parse webhook payload', {
+      hasData: !!ctx.data,
+      hasRequest: !!ctx.request,
+    });
+    throw new Error(
+      'Failed to parse webhook payload. Ensure Content-Type: application/xml is set in request headers.'
+    );
+  }
+  log.info('📥 [SERVICE] Payload parsed successfully (Versori auto-parsed XML)', {
+    payloadKeys: Object.keys(payload),
+    note: 'Versori automatically parses XML when Content-Type: application/xml is set',
+  });
+  // STEP 2: Extract order reference
+  const orderRef = extractOrderRef(payload);
+  if (!orderRef) {
+    log.error('❌ [SERVICE] Order reference not found in XML payload', {
+      payloadKeys: Object.keys(payload),
+      expectedPatterns: [
+        'orderUpdate.orderRef',
+        'orderUpdate[@orderRef]',
+        'order[@ref]',
+      ],
+    });
+    throw new Error(
+      'Order reference not found in XML payload. Expected patterns: orderUpdate.orderRef, orderUpdate[@orderRef], or order[@ref]'
+    );
+  }
+  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
+  // STEP 3: Extract attributes
+  const attributes = extractAttributes(payload);
+  if (attributes.length === 0) {
+    log.warn('⚠️ [SERVICE] No attributes provided in payload', { orderRef });
+    throw new Error('At least one attribute is required for order update');
+  }
+  log.info('✅ [SERVICE] Attributes extracted', {
+    orderRef,
+    attributeCount: attributes.length,
+    attributeNames: attributes.map(a => a.name),
+  });
+  // STEP 4: Create Fluent client
+  // ✅ Pass ctx directly - createClient auto-detects Versori context
+  // Authentication handled via Versori connection (fluent_commerce)
+  const client = await createClient(ctx);
+  log.info('✅ [SERVICE] Fluent client created');
+  // STEP 5: Query order by reference to get ID
+  // ✅ Query first to:
+  //    - Validate order exists (fail-fast if order not found)
+  //    - Get order ID for logging and tracking
+  //    - Get current order state (optional: can merge with existing attributes)
+  const order = await queryOrderByRef(client, orderRef, log);
+  // STEP 6: Build update mutation variables
+  // ✅ CRITICAL: UpdateOrderInput requires id: ID! (not ref)
+  //    Use the ID from queryOrderByRef result - this is why we query first!
+  const updateVariables = {
+    input: {
+      id: order.id, // ✅ REQUIRED: UpdateOrderInput.id is ID! (required field)
+      attributes: attributes,
+    },
+  };
+  log.info('📤 [SERVICE] Executing updateOrder mutation', {
+    orderRef,
+    orderId: order.id,
+    attributeCount: attributes.length,
+  });
+  // STEP 7: Execute updateOrder mutation
+  const mutationResult = await client.graphql({
+    query: UPDATE_ORDER_MUTATION,
+    variables: updateVariables,
+  });
+  if (mutationResult.errors && mutationResult.errors.length > 0) {
+    log.error('❌ [SERVICE] GraphQL mutation returned errors', {
+      errors: mutationResult.errors,
+      orderRef,
+      orderId: order.id,
+    });
+    throw new Error(`GraphQL mutation failed: ${mutationResult.errors[0].message}`);
+  }
+  const updatedOrder = (mutationResult.data as any)?.updateOrder;
+  if (!updatedOrder) {
+    log.error('❌ [SERVICE] No order data returned from mutation', { orderRef });
+    throw new Error('No order data returned from updateOrder mutation');
+  }
+  log.info('✅ [SERVICE] Order updated successfully', {
+    orderRef,
+    orderId: updatedOrder.id,
+    attributesUpdated: attributes.length,
+  });
+  // Return success response with FC200 status code
+  return createSuccessResponse({
+    success: true,
+    orderRef,
+    orderId: updatedOrder.id,
+    attributesUpdated: attributes.length,
+    message: 'Order attributes updated successfully',
+  });
+}
+```
+---
+## 5. Configuration
+### Activation Variables
+No activation variables required. Authentication is handled via Versori connection (`fluent_commerce`).
+**Note:** Configure Fluent Commerce credentials in the Versori connection settings. The connection handles authentication automatically.
+### Webhook Connection
+Create a Versori connection for webhook authentication:
+1. **Connection Name:** `order-update-webhook`
+2. **Type:** API Key or Basic Auth
+3. **Purpose:** Authenticate incoming webhook requests
+**Example webhook call:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-update.xml
+```
+**Example XML file (`order-update.xml`):**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-12345</orderRef>
+  <externalOrderId>EXT-123456789</externalOrderId>
+  <customerNotes>Please leave package at front door</customerNotes>
+  <priority>high</priority>
+</orderUpdate>
+```
+**CRITICAL: Content-Type Header**
+The `Content-Type: application/xml` header is **required** for Versori to automatically parse the XML. Without this header, Versori will not parse the XML and you'll need to manually parse using `XMLParserService`.
+**✅ CORRECT:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/xml" \  # ✅ Required!
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-update.xml
+```
+**❌ WRONG:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: text/plain" \  # ❌ Wrong Content-Type
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-update.xml
+```
+---
+## 6. Error Handling
+The template includes comprehensive error handling:
+### Payload Parsing Errors
+- **Empty payload:** Returns error response
+- **Invalid XML:** Returns error with parse details
+- **Missing order reference:** Returns error with expected patterns
+- **Missing attributes:** Returns error if no attributes provided
+### Order Query Errors
+- **Order not found:** Returns error with order reference
+- **GraphQL query errors:** Returns error with GraphQL error details
+### Mutation Errors
+- **GraphQL mutation errors:** Returns error with mutation error details
+- **No response data:** Returns error if mutation doesn't return order data
+### Response Format with FC Status Codes
+**Success Response (FC200):**
+```json
+{
+  "success": true,
+  "statusCode": "FC200",
+  "orderRef": "ORD-12345",
+  "orderId": "12345",
+  "attributesUpdated": 3,
+  "message": "Order attributes updated successfully"
+}
+```
+**Error Responses:**
+**FC400 - Bad Request (Non-retryable):**
+```json
+{
+  "success": false,
+  "statusCode": "FC400",
+  "retryable": false,
+  "error": "Bad request. Please verify payload and try again.",
+  "details": "Order reference (orderRef) is required in payload"
+}
+```
+**FC409 - Duplicate/Already Exists (Non-retryable):**
+```json
+{
+  "success": false,
+  "statusCode": "FC409",
+  "retryable": false,
+  "error": "Entity already exists. Duplicate request detected.",
+  "details": "Order with reference ORD-12345 already exists"
+}
+```
+**FC504 - Timeout (Retryable):**
+```json
+{
+  "success": false,
+  "statusCode": "FC504",
+  "retryable": true,
+  "error": "Request timeout. Please retry.",
+  "details": "GraphQL mutation timed out after 30 seconds"
+}
+```
+---
+## 7. Testing
+### Test with cURL - Flat Structure Format
+**Create `order-update.xml`:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-12345</orderRef>
+  <externalOrderId>EXT-123456789</externalOrderId>
+  <customerNotes>Please leave package at front door</customerNotes>
+  <priority>high</priority>
+</orderUpdate>
+```
+**Send with cURL:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-update.xml
+```
+### Test with Inline XML
+```bash
+# Test with inline XML (flat format)
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  -d '<?xml version="1.0" encoding="UTF-8"?><orderUpdate><orderRef>ORD-12345</orderRef><externalOrderId>EXT-123456789</externalOrderId><customerNotes>Please leave package at front door</customerNotes></orderUpdate>'
+```
+### Complete Sample XML Files
+**Example 1: External System Reference (`external-reference-update.xml`)**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-0017326966182</orderRef>
+  <externalOrderId>EXT-123456789</externalOrderId>
+  <sourceSystem>ERP-SAP</sourceSystem>
+  <integrationId>INT-987654321</integrationId>
+</orderUpdate>
+```
+**Example 2: Customer Notes and Business Flags (`customer-notes-update.xml`)**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderUpdate>
+  <orderRef>ORD-0017326966182</orderRef>
+  <customerNotes>Please leave package at front door</customerNotes>
+  <priority>high</priority>
+  <tags>rush,gift</tags>
+  <specialHandling>true</specialHandling>
+</orderUpdate>
+```
+### Expected Success Response
+```json
+{
+  "success": true,
+  "statusCode": "FC200",
+  "orderRef": "ORD-12345",
+  "orderId": "12345",
+  "attributesUpdated": 1,
+  "message": "Order attributes updated successfully"
+}
+```
+**FC Status Code:** `FC200` - OK (Successfully - No further action needed)
+### Expected Error Responses
+**FC400 - Bad Request:**
+```json
+{
+  "success": false,
+  "statusCode": "FC400",
+  "retryable": false,
+  "error": "Bad request. Please verify payload and try again.",
+  "details": "Order not found: ORD-12345"
+}
+```
+**FC409 - Duplicate/Already Exists:**
+```json
+{
+  "success": false,
+  "statusCode": "FC409",
+  "retryable": false,
+  "error": "Entity already exists. Duplicate request detected.",
+  "details": "Order with reference ORD-12345 already exists"
+}
+```
+**FC504 - Timeout:**
+```json
+{
+  "success": false,
+  "statusCode": "FC504",
+  "retryable": true,
+  "error": "Request timeout. Please retry.",
+  "details": "GraphQL mutation timed out"
+}
+```
+---
+## 8. Customization
+### Custom Order Reference Element
+If your XML uses different element names, modify `extractOrderRef()`:
+```typescript
+function extractOrderRef(payload: OrderUpdatePayload): string | null {
+  // Add your custom element extraction logic
+  if (payload.customUpdate && typeof payload.customUpdate === 'object') {
+    const update = payload.customUpdate;
+    if ('$' in update && update.$) {
+      const attrs = update.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.orderId === 'string') {
+        return attrs.orderId;
+      }
+    }
+  }
+  // ... existing logic
+}
+```
+### Custom Attribute Extraction
+To customize how attributes are extracted from XML:
+```typescript
+function extractAttributes(payload: OrderUpdatePayload): AttributeInput[] {
+  // Add custom extraction logic for your XML structure
+  // e.g., handle nested attribute structures, namespaces, etc.
+}
+```
+### Merge with Existing Attributes
+To merge new attributes with existing ones (instead of replacing):
+```typescript
+// In executeOrderUpdate function, after queryOrderByRef:
+const existingAttributes = order.attributes || [];
+const mergedAttributes = [
+  ...existingAttributes,
+  ...attributes, // New attributes override existing ones with same name
+];
+const updateVariables = {
+  input: {
+    id: order.id, // ✅ REQUIRED: Use ID from query result
+    attributes: mergedAttributes,
+  },
+};
+```
+---
+## Summary
+✅ **DO:**
+- Use Versori connection for Fluent Commerce credentials
+- Query order first to validate existence and get ID
+- Use `id` from query result in UpdateOrderInput (required field)
+- Handle Versori XML format ($ for attributes, _ for text)
+- Support multiple XML attribute formats
+- Log all steps for debugging
+- Return clear error messages
+❌ **DON'T:**
+- Hardcode credentials in code
+- Skip order query validation
+- Use `ref` in UpdateOrderInput (must use `id: ID!`)
+- Assume payload format without validation
+- Skip error handling
+- Ignore Versori XML parsing format ($ and _)
+---
+## Next Steps
+1. **Deploy:** Copy code to your Versori project
+2. **Configure:** Set up Fluent Commerce connection and activation variables
+3. **Test:** Test webhook with sample XML payloads
+4. **Monitor:** Check Versori logs for order updates
+For more templates, see:
+- [JSON Payload Template](./template-ingestion-payload-json-order-update-graphql.md)
+- [Other GraphQL Mutation Templates](./graphql-mutations-guide.md)