Conversion definitions

A conversion definition is the setup record that declares one bulk document conversion, such as order to invoice. It names what is converted, what is created, which quantity is consumed and which action does the work, and it controls how the Bulk Conversion screen and its conversion batches behave. Every conversion exists only because an active definition exists for it. There is no built-in fallback, so a missing, inactive or incomplete definition means the conversion is unavailable.

Overview

Definitions live in the Sales app under Settings → Conversions, and belong to the Sales product licence. Each definition's Name is its conversion key, a stable dot-separated identifier such as sales.order-to-invoice. Screens and batches refer to the conversion by this key, so pick it once and don't rename it. Display Name is what users see.

A definition does four jobs:

Mapping: which document and lines are converted, and into which document.
Reservation: which quantity on the source line is consumed, and which pool it is reserved in.
Execution: which action stages the batch, which action converts each record, and how failures are contained.
Screen: which filters, columns, editable values and options the Bulk Conversion screen shows, plus print and schedule settings.

When to use it

Before anyone can use a Bulk Conversion screen, an active definition with the screen's conversion key must exist.
To change what the screen offers: filters, columns, which records are eligible, or the options users choose.
To tune how batches run: chunk size, attempt limits, failure isolation.
To add a print or scheduled variant of a conversion.

Prerequisites

The Sales product licence.
Create and edit access to Conversion Definition. By default the Sales Executive and Standard User profiles have full access.
Knowledge of the entity, field and action names involved. The definition uses internal names, not on-screen labels. Find them in Setup → Metadata on the source and target entities.
For a print conversion, a banded document report. For an automation-script conversion, a script bound to a server action on the source entity.

Procedure

Step 1 — Open the conversion list

Open the Sales app, choose Settings, and open Conversions. The list shows Name, Display Name, Category, Source Entity, Target Entity, Record Action Name, Quantity Pool, Pending Quantity Field, Failure Isolation, Chunk Size and Active.

Step 2 — Fill in the header

Create a definition, or open one and choose Edit. Enter Name (the conversion key), Display Name, Conversion Type, Category (groups conversions in pickers) and Description, and tick Active.

Step 3 — Map the source and target

On Source & Target, enter Source Entity (for example Order) and Source Line Entity (for example OrderLine). Then fill in the three fields that tie them together:

Source Line Navigation: the header-to-lines collection, for example OrderLines.
Source Line Parent Field: the line's link back to its header, for example OrderId.
Selection Args Key: the argument name that carries the user's picked lines to the action.

Finally enter Target Entity and, optionally, Target Line Entity.

Step 4 — Set the quantity and the actions

On Quantity & Actions, enter Pending Quantity Field (the source-line field holding what is still to convert, for example the pending invoice quantity) and Quantity Pool. Then set the actions:

Batch Action Name: the server action on the source entity that stages a batch.
Record Action Name: the per-record server action the batch runs for each source record.
Selection Fields (optional): extra line fields users may enter per line.

Step 5 — Restrict which records qualify

On Criteria, add Filter Criteria (JSON) for records that must never be offered, and Validation Criteria (JSON) for records that may be chosen but must be refused with a reason (see Configuration).

Step 6 — Set the execution policy

On Execution Policy, choose Failure Isolation, Chunk Size, Max Attempts and Max Line Attempts. Add Options (JSON) for choices users make on the screen.

Step 7 — Shape the screen

On UI Surface, list List Fields (columns of the records tab), Line Fields (columns of the lines tab) and Scope Fields (the filters). Each is a comma-separated list of field names.

Step 8 — Print and schedule settings

For a Print conversion, set Print Report and, if the report's record column isn't Id, Print Id Field. For a Schedule conversion, optionally set Schedule Presets (JSON).

Step 9 — Save and test

Save. Changes take effect straight away for new submissions, with no restart. Open the Bulk Conversion screen for this key, select one record and submit. Then check the batch under Recent runs.

Fields

Field	What it means	Notes
Name	The conversion key, for example `sales.order-to-invoice`	Required. Screens and batches refer to it, so keep it stable
Display Name	Name shown on the screen and on batches	Required
Conversion Type	What the screen's main button does	ServerAction (default), Schedule, Print. See Business rules
Category	Grouping for pickers, for example Sales or Procurement	Optional
Active	Whether the conversion is available	Clearing it switches the conversion off
Description	Shown under the screen title	Optional
Source Entity	The document converted from	Required
Source Line Entity	Its line entity	Required
Source Line Navigation	Header-to-lines collection name	Required
Source Line Parent Field	Field on the line pointing at its header	Required
Selection Args Key	Argument name that carries the picked lines	Required. If no lines are picked, every available line converts
Target Entity	The document created	Required. A run that creates no record of this entity marks the line Skipped
Target Line Entity	The target's line entity	Optional
Quantity Pool	Name of the reservation pool	Needed before a batch can be staged. Conversions that consume the same pending-quantity field on the same line entity must share one pool name
Pending Quantity Field	Line field holding what is left to convert	Required
Batch Action Name	Action that stages a batch	Required. A definition naming an action makes that action batch-based
Record Action Name	Action run once per source record	Without it, staging works but every line fails at run time
Selection Fields	Extra line fields users can enter, comma-separated	Name only fields the record action reads. Blank fields are not sent
Filter Criteria (JSON)	Rules for records that are never offered	Non-matching records are left out silently
Validation Criteria (JSON)	Rules for records that are refused with a reason	The reason is shown to the user
Failure Isolation	How much one failing record takes down	ChunkThenRecord (default), Record, Chunk
Chunk Size	Lines per transaction	Default 50
Max Attempts	Whole-batch attempts	Default 3
Max Line Attempts	Attempts per line for unexpected errors	Default 3
Options (JSON)	Options shown on the screen and passed to the action	See Configuration
List Fields	Records-tab columns	Comma-separated source fields
Line Fields	Lines-tab columns	Comma-separated line fields
Scope Fields	Filters shown, in order	Comma-separated source fields. Blank uses the standard set
Print Report	Document report rendered per record	Print type only. Must be a banded report
Print Id Field	Report column matched to record ids	Blank means `Id`
Schedule Presets (JSON)	Shortcuts in the schedule dialog	Schedule type only

Business rules

Only active, complete definitions count. A definition is ignored if it is inactive, or if it lacks Name, Display Name, Source Entity, Source Line Entity, Source Line Navigation, Selection Args Key, Source Line Parent Field, Target Entity, Pending Quantity Field or Batch Action Name. The screen then shows Conversion not available.
Staging checks the mapping. Each submission checks that both entities exist, that the source has the named line collection, and that the line has the pending-quantity and parent fields. It also checks that a quantity pool is set. A mistake fails the submission with a message naming the conversion and the missing piece.
Conversion types. ServerAction stages a batch and runs the record action for each record. Schedule does the same, but the screen opens the schedule dialog: run now, once at a time (reserves now), or repeating (reserves nothing until each run). Print renders the print report per selected record, reserves nothing and creates no batch. An automation-script type runs a bound script per record and fails the line if the script fails, is cancelled or isn't bound inline. Its picklist value may not be published to every organisation.
Failure isolation. ChunkThenRecord runs a chunk in one transaction and, if it fails, re-runs it one record at a time so only the bad record fails. Record always uses one transaction per record. Chunk is all-or-nothing per chunk. In every mode, a record rejected by validation fails straight away without taking down the chunk.
One result per record. The record action reports success or failure for the whole record. Every selected line of a record shares that result, and a succeeded line is credited with the quantity it asked for.
Deactivating a definition stops new submissions, and its existing batches can no longer be retried.

Example

An administrator sets up the order-to-invoice conversion for the Sales Bulk Conversion screen.

Under Sales → Settings → Conversions they create a definition with Name sales.order-to-invoice, Display Name "Order → Invoice", Conversion Type ServerAction, Category Sales, and tick Active.
On Source & Target: Source Entity Order, Source Line Entity OrderLine, Source Line Navigation OrderLines, Source Line Parent Field OrderId, Selection Args Key as expected by their invoicing action, Target Entity Invoice.
On Quantity & Actions: Pending Quantity Field PendingInvoiceQuantity and Quantity Pool order-line.invoice, plus the staging and per-record actions their tenant uses for bulk invoicing.
On Criteria, a filter so that only orders of active companies are offered: [{"target":"Header","expression":"PartnerAccount.IsActive == true"}].
On UI Surface: Scope Fields PartnerAccountId,BranchId,VisitRouteId,DocumentDate.
They save, open Sales → Bulk Conversion, and see Partner Account, Branch, Route and a date chip. A test batch of one order completes.

Training

Practice exercise

In a sandbox, open an existing conversion definition and add ExecutiveId to Scope Fields, between Branch and the date field. Save and reload the Bulk Conversion screen.

Expected result: a Sales Executive filter is available in the filter bar, in that position, and choosing an executive narrows the records listed. Remove the field again afterwards.

Quick reference

Name is the conversion key; don't rename it once screens use it.
Inactive or incomplete means the conversion is unavailable.
Quantity Pool must be shared by conversions consuming the same pending quantity.
Filter criteria hide records silently; validation criteria refuse them with a reason.
Record Action Name is what actually converts each record.
Print conversions reserve nothing and create no batch.
Saved changes apply to the next submission straight away.

Permissions

Conversion Definition is a Sales-licensed entity. The Sales Executive and Standard User profiles have full record access by default, and any profile can be granted it under Setup → Security. A user who can open the Bulk Conversion screen but lacks the batch actions it needs is covered in Bulk conversion → Permissions.

Configuration

Criteria JSON. Both criteria fields take a JSON array of rules, each { "target": "Header" or "Line", "expression": "...", "message": "..." }. The expression is a condition over the source record (Header) or its line (Line). Filter rules exclude silently. Validation rules refuse the record or line with the message. A validation rule on Line that refers to StockAvailable also turns on the screen's stock check, which flags selected lines that are short of stock. Malformed JSON is ignored, which makes the conversion more permissive, so re-check the JSON after saving.

Filter field rules. A definition can also carry rules that limit what each filter offers and what a run may take, for example only active companies, or only the branches of those companies. They are stored on the definition but don't appear on the standard form. Users see them, and can override them for a single schedule, in the schedule dialog's Filter rules table. An invalid rule stops the run rather than widening it.

Scope Fields. Lookup fields become pickers and date fields become a date-range chip that opens on today. Partner Account, Branch, Route, Account and Sales Executive keep their built-in behaviour: Branch depends on Partner Account, and only active resources are offered as executives. To narrow any other lookup, add a lookup filter on that field of the source entity. A filter that the organisation's single-company or single-branch setup hides is dropped. A blank list falls back to Partner Account, Branch, Sales Executive, Route, Account and document date, limited to fields the source entity has.

Options (JSON). An array of { "name", "label", "kind", "choices", "defaultValue" }, where kind is Text, Boolean, Number or Choice. The screen renders each option and sends the user's choice to the action. An option marked hidden is never shown or sent; its default acts as the definition's own setting.

Schedule Presets (JSON). An array of { "label", "cron", "description" } shown as shortcuts in the schedule dialog. A malformed value only loses the shortcuts.

Running in the background. Batches, select-all runs and repeating schedules run as background jobs: Stage a conversion from criteria for select-all and repeating runs, and the hourly Reconcile conversion batches. Both appear under Setup → Platform Operations → Monitoring → Jobs, and repeating schedules are listed on its Schedules tab.

Common problems

The screen says "Conversion not available"

No active, complete definition has the screen's key. Check that Active is ticked and that every required field is filled. A definition missing one is ignored entirely.

Submitting fails with "… QuantityPool is required"

Set Quantity Pool. Use the same pool name as any other conversion that consumes the same pending-quantity field.

Submitting fails with "… has no field …" or "… is not in the model"

An entity or field name is misspelled. Use the internal names from Setup → Metadata, not on-screen labels.

Every batch line fails with "has no RecordActionName"

Set Record Action Name, then retry the batch's failed lines.

Lines are Skipped with "The action ran without error but produced no …"

The record action ran but created nothing, usually because there was nothing left to convert. If that happens for every line, check that Target Entity matches what the action really creates.

"'…' is a print action; it does not stage a batch."

A batch action is wired to a Print definition. Point the batch action at a ServerAction or Schedule definition.

Common questions

Do changes affect batches that are already queued?

New settings apply to the next submission straight away. A queued batch keeps its own chunk size, attempt limits and the quantities it reserved at submission, but it looks up the definition again when it runs and when it is retried. So a corrected Record Action Name is used by a retry. Deactivating the definition means its batches can't be retried until you reactivate it.

The pool is how reservations are counted. If two conversions consume the same pending quantity on the same line, for example two ways of invoicing order lines, but use different pool names, each sees the full quantity as free. They could then promise the same units twice. Give them the same pool name so a line held by one is shown as held in the other.

Can I make a conversion run every night?

Yes. Set Conversion Type to Schedule, optionally add presets, and have a user choose Repeat on a schedule on the Bulk Conversion screen with the filters set. Each run converts whatever matches at that moment, and the schedule appears on the Jobs screen's Schedules tab.