Skip to main content
When a draft is generated from a Policy and when a Quote is bound, every field the two entities share is copied unchanged. Conversion Rules state the exceptions: a shared field that is not carried, and a destination that gets a different or transformed value. They let your application and policy models serve different purposes: a Quote can collect separate name fields while the resulting Policy stores a combined customer name, for example. For a plain-language introduction, see Quote ↔ Policy conversion rules in the app guide. This page is the authoring reference. Each rule belongs to your company’s field-model configuration.

What is copied by default

A field is shared when the two entities of a direction (Quote and Policy, or Submission and Quote) both declare it with the same referenceId and the same value type (type and cardinality). In each direction and transaction type except QUOTE_TO_SUBMISSION, every shared field that no rule names is copied unchanged, as if you had written source.<referenceId> for it. These fields are never copied by default:
  • a field calculated on the destination entity, including one whose calculated value the caller may override;
  • a field that is system-managed on either entity;
  • the platform’s own Quote fields, such as quoteType, the endorsement, cancellation and reinstatement dates, and previousPolicy;
  • system keys and platform Joins;
  • the full-term containers, such as fullTermPricingInfo and fullTermBillingInfo, which required framework rules carry.
A field declared on only one entity is never copied; it is written only by a rule. A rule names a field when its destinationPath is the field or a path under it. A rule on mailingAddress.city therefore stops the default copy of the whole mailingAddress field in that scope. The default copy is not a rule. Export and the Conversion Rules page show only the rules you author. Do not author source.<sameField> for a shared field: the default copy already writes it.

When rules run

QUOTE_TO_SUBMISSION runs when a new-business or renewal Quote is first saved without a Submission: the new Submission holds what its rules write. SUBMISSION_TO_QUOTE runs for NEW_BUSINESS when a Quote is started from its Submission: the new Quote holds what the rules write from the Submission’s values. SUBMISSION_TO_QUOTE copies shared fields by default, like the Quote and Policy directions. QUOTE_TO_SUBMISSION has no default copy. A Submission is never made from a Quote, so the conversion writes only the destinations its rules name, and a field both entities declare stays as the Submission holds it unless a rule writes it. New business has no source Policy, so it has no POLICY_TO_QUOTE rule set. Author each direction separately: a rule combining two Quote fields into one Policy field does not specify how to split that value when generating another Quote. For cancellation and reinstatement, QUOTE_TO_POLICY rules are framework-only. These transactions change lifecycle state; ordinary field edits belong in an endorsement. Required framework rules and platform lifecycle processing remain separate from your optional business mappings. Generate returns an editable draft without storing a Quote: what the conversion writes (the default copy and your rules), with quoteType set from the transaction type, the Quote’s calculated fields worked out as a save would, and null in every other field. A rule that writes quoteType does not change it. Bind converts the submitted or persisted Quote data the same way. Editing a generated draft therefore affects the values available to Bind.

Author an exception

Add rules to the conversionRules array in your configuration. A row has four properties: For example, this rule writes a Quote’s applicantName into a Policy’s customerName:
This is one optional row, not a complete import body. Both fields must exist in their respective models, have compatible types and cardinalities, and the destination must permit tenant writes. Here both are Single String fields. Keep your other authored rules and all required framework rows when adding it. This rule stops a shared internalNotes field from reaching the Policy at a renewal bind:
SKIP() must be the whole expression. Configuration validation rejects it inside a larger expression. The destination rules for ownership, scope and overlap apply to a SKIP() row as to any other. The combination of direction, transaction type, and destination path is unique. You can author a different expression for customerName during RENEW, but cannot give it two writers within QUOTE_TO_POLICY/NEW_BUSINESS.

Transform values with JEXL

Expressions can combine values, use conditional logic, perform arithmetic, and call supported pure functions. For example, replace the expression above with:
For firstName = "Alex" and lastName = "Morgan", the result is "Alex Morgan". Declare both source fields as Single String fields. These examples illustrate other business mappings. Their source fields must be declared and their destination types must match the expression results. Date arithmetic can express a renewal end date through a tenant-authored POLICY_TO_QUOTE/RENEW rule. It does not grant permission to overwrite a framework-pinned date rule in another scope. No framework rule writes policyEndDate for POLICY_TO_QUOTE/RENEW, because the renewal end date is your decision. Without a rule, the default copy writes the expiring term’s end date into the renewal draft. State a rule for it: an expression, or SKIP() to leave it out of the draft.

Available inputs

Use source.applicantName, not bare applicantName. Every rule sees the same source and transaction inputs. Rules cannot read another rule’s output, and row order does not control execution. To combine values, read the original source fields together in one expression. Only pure, deterministic functions are allowed: the same inputs must produce the same result. Explicit date arithmetic is supported; reading the current clock, querying other records, allocating identifiers, or making external calls is not. JEXL expressions are not arbitrary JavaScript programs. Configuration validation rejects unsupported or unsafe function calls. See Author JEXL expressions for syntax and JEXL reference for the macros accepted by conversion rules.

Copy, skip, clear, or write

At an ENDORSE bind, a destination with no write keeps the Policy’s current value. At a NEW_BUSINESS or RENEW bind, and in a generated draft, it has no value unless the destination calculates one. Use CLEAR() for an explicit null result. Bare null is rejected: JEXL treats it as an identifier rather than a null literal. Referencing a nonexistent field is also invalid; it is not a way to request omission. “No write” describes the conversion step. Required framework values and transaction lifecycle behavior still apply. If an expression fails structurally, the conversion fails; it does not silently supply a replacement value or return a partially converted result.

Destinations and required rules

A rule can target a top-level field or a nested field through Single-cardinality objects, such as mailingAddress.city. Whole List values can be assigned when types and cardinalities match. Indexed paths, wildcards, per-list-item destination paths, and traversal through Joins are not supported. Within one direction and transaction type, mailingAddress and mailingAddress.city cannot both have writers. Different sibling fields can. Your configuration includes required framework rules for platform-owned values: the policy type, time zone and term dates, the fullTermPolicyRatingResult container, the fullTermPricingInfo container from a quote to its policy, and the billing copy. No rule carries a policy’s fullTermPricingInfo onto a new quote: the quote’s pricing calculation prices it. The billing copy is the three QUOTE_TO_POLICY rules for NEW_BUSINESS, ENDORSE and RENEW that write fullTermBillingInfo from source.fullTermBillingInfo, so the bind copies the Quote’s billing to the Policy unchanged. Keep their destinations and expressions intact. Optional tenant rules cannot write system-managed fields or replace pinned framework behavior; no tenant rule may write either entity’s fullTermBillingInfo, because the Quote calculates its own and the billing copy carries it to the Policy. Validation and import reject missing or changed framework rules, including on a first import or a forced import.

Maintain and validate your configuration

New companies receive an authored starter configuration, including required Conversion Rules. Customize that configuration for your business:
  1. Export the current configuration through the Configuration API.
  2. Review the rules affected by your field or business change. For each direction and transaction type, decide whether the default copy is right or the field needs an exception.
  3. Edit those rules while preserving the complete configuration and required rows.
  4. Validate the complete body or use an import dry run. Fix invalid source references, destinations, expressions, types, cardinalities, or overlapping writers.
  5. Import through your normal review process, then verify the intended Generate, Bind and endorsement rating behavior in a test environment.
When renaming or removing a field, update rules that reference it. Adding a field to both Quote and Policy with the same referenceId and type carries it at every conversion with no rule; add SKIP() rules where it should not cross. Deleting a rule on a shared field, including a SKIP() rule, turns the default copy back on for it.

Fields your rating reads

Rating an endorsement rates the whole policy term. The part of the term that contains the endorsement’s effective date is rated from the endorsement Quote. Every other part is rated from the endorsement Quote with each shared field replaced by that Policy segment’s value. Calculated fields are worked out again, not copied. POLICY_TO_QUOTE rules play no part in rating. The QUOTE_TO_POLICY ENDORSE conversion runs only to work out where the bind will split the term, and a rule that fails there fails the rating. A field your rating workflows read must therefore be a shared field, and your QUOTE_TO_POLICY rules for NEW_BUSINESS, ENDORSE and RENEW must carry it unchanged: no SKIP() and no expression that reshapes it. A Quote-only input is rated at the endorsement’s value across the whole term, and a shared input that the bind skips is rated at whatever the Policy holds, possibly nothing. Configuration validation does not check this.