Custom field transformations

A SimplyFill mapping isn't limited to one-to-one aliases. Each field_mappings value can be an object that runs a small transformation against your data payload before writing to the PDF — concatenation, uppercase, conditional defaults, currency formatting, and more.

This guide walks through the most useful transformation patterns. For the full mapping shape, see Mappings concept.

Enhanced value form

The simple value form is a string (the alias). The enhanced form is an object:

{
  "raw_pdf_field": {
    "source": "your_alias",
    "transform": "<expression>",
    "condition": { "if": "...", "then": "...", "else": "..." }
  }
}

Either transform, condition, or both can be present. If neither is, it's equivalent to the simple form.

Concatenation

PDF has one full_name field; your app has first_name and last_name. Concatenate at generation time:

{
  "f1_02[0]": {
    "source": "first_name",
    "transform": "concat(first_name, ' ', last_name)"
  }
}

source declares the primary alias for clarity / validation; transform is the actual expression evaluated against the full data payload.

Uppercase / lowercase / title case

Useful for fields that the PDF expects in a specific case:

{
  "state_code[0]": {
    "source": "state",
    "transform": "upper(state)"
  },
  "subject_line[0]": {
    "source": "subject",
    "transform": "title(subject)"
  }
}

Conditional defaults

The PDF field should be "N/A" if the alias is missing, otherwise the alias value:

{
  "middle_initial[0]": {
    "source": "middle_initial",
    "condition": {
      "if": "is_empty(middle_initial)",
      "then": "N/A",
      "else": "middle_initial"
    }
  }
}

Available if predicates: is_empty, is_present, equals, not_equals, greater_than, less_than, matches (regex).

Currency formatting

Numbers from your domain often arrive as raw cents or unformatted decimals. Format on the way out:

{
  "total_amount[0]": {
    "source": "amount_cents",
    "transform": "currency(amount_cents, 'USD', 2)"
  }
}

Outputs $1,250.00 from 125000.

Date formatting

Dates from your domain are typically ISO 8601. The PDF probably wants a friendlier form:

{
  "hire_date[0]": {
    "source": "hire_date",
    "transform": "date_format(hire_date, 'MM/DD/YYYY')"
  }
}

If your data is missing the alias and you want today's date, combine condition and a literal:

{
  "hire_date[0]": {
    "source": "hire_date",
    "condition": {
      "if": "is_empty(hire_date)",
      "then": "today()",
      "else": "date_format(hire_date, 'MM/DD/YYYY')"
    }
  }
}

Combining transformations across fields

You can reference any alias from the data payload in any transformation. To derive a full address from individual components into a single PDF field:

{
  "address_block[0]": {
    "source": "street1",
    "transform": "concat(street1, '\\n', city, ', ', state, ' ', zip)"
  }
}

The \n becomes a newline inside the PDF text widget (assuming the widget is multi-line).

Transformation reference

The list grows over time — see /changelog for additions.

Validation

Mappings with transformations go through the same /mappings/{id}/validate endpoint as plain mappings. The validator parses every transformation expression and reports syntax errors before you go to production.

Related

• Mappings concept
• Create mapping (API)
• HR onboarding workflow — uses transformations for the offer letter