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. None are supplied with a new organisation, so each conversion your users need is a definition you create. Each definition's Name is its conversion key, a stable 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.

You don't have to type most of a definition. On a new definition, choose the Source Entity and then the Record Action Name, the server action that converts one record. xMatix then fills every blank field that action implies: the line entity and its links, the pending quantity, the target, the quantity pool, the action's options, and a key and display name. You review the result and save.

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 make an existing per-record server action, such as an order's invoicing action, available for bulk conversion.
• 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.
• An existing, active server action on the source entity that converts one record, for example the action behind an order's invoicing button. The definition makes an action batch-based; it doesn't create the conversion logic. Check the action under Setup → Metadata → the source entity → Logic → Actions.
• The definition stores internal entity, field and action names, not on-screen labels. The pickers on the form list them for you. If you type a value instead, take the name from Setup → Metadata.
• 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 — Start a definition

Choose New to create a definition. To change an existing one, open it and choose Edit. The same form opens in both cases. Leave Name and Display Name blank for now if you want xMatix to suggest them. Choose Conversion Type, enter a Category (it orders the conversion list) and a Description, and tick Active.

Step 3 — Pick the source entity

On Source & Target, choose Source Entity from the list of entities, for example Order. Blank Scope Fields and List Fields are filled with the standard fields that entity has, such as Partner Account, Branch and Document Date.

Step 4 — Pick the record action and let the form fill in

On Quantity & Actions, open Record Action Name. It lists the source entity's active server actions as Label (internal name). Until a source entity is chosen it shows Select the source entity first. Choose the action that converts one record.

On a new definition the form then fills every blank field it can work out from that action and from the entity model:

• Batch Action Name: the same action, unless you pick a different staging action.
• Source Line Entity, Source Line Navigation and Source Line Parent Field: the line collection the action reads, for example OrderLine, OrderLines and OrderId.
• Selection Args Key: the argument the action reads the lines from. It is left blank when the action reads no line list (it works on the whole document).
• Pending Quantity Field: the numeric line field the action consumes, for example the pending invoice quantity.
• Target Entity and Target Line Entity: the document the action creates, for example Invoice and InvoiceLine.
• Quantity Pool: Source.Target, for example Order.Invoice.
• Options (JSON): the options the action reads.
• Name and Display Name: for example order-to-invoice and Order → Invoice.

A value you have already entered is never replaced. If another definition already uses the same action, its values fill in what the action alone doesn't show.

Step 5 — Review what was filled

Check each filled field and correct anything that is wrong. Your correction is kept. Set Target Entity by hand if it stayed blank. That happens when the action creates its document through another service. Add Selection Fields if users should enter extra values per line. Pick them from the line entity's fields, and name only fields the record action reads.

If you are editing an existing definition, nothing is filled in automatically. Fill in or change each field yourself.

Step 6 — Restrict which records qualify

On Criteria, use 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. Each is edited as a table. Add one row per criterion with Target (Header or Line), Expression and, for validation, the Message shown to the user. See Configuration.

Step 7 — Set the execution policy

On Execution Policy, enter Failure Isolation, Chunk Size, Max Attempts and Max Line Attempts. Review Options (JSON), the choices users make on the screen. It is edited as a table of Name, Label, Kind, Choices and Default.

Step 8 — Shape the screen

On UI Surface, pick List Fields (columns of the records tab) and Scope Fields (the filters, in order) from the source entity's fields. Pick Line Fields (columns of the lines tab) from the line entity's fields. Each is stored as a comma-separated list of internal field names.

Step 9 — Print and schedule settings

For a Print conversion, set Print Report on the Print tab and, if the report's record column isn't Id, Print Id Field. For a Schedule conversion you can add shortcuts on the Schedule tab in Schedule Presets (JSON). It is a table of Label, Cron (UTC) and Description.

Step 10 — Save and test

Save. The record page groups the saved values into Identity, Source, Target, Reservation pool, Actions and Execution policy, with Edit in the header. 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

Business rules

• Automatic fill on new definitions only. When a new definition names a source entity and an action, xMatix fills its blank fields. It works out the values from a reading of the action's program code made when the platform was built, from the entity model, from naming conventions (Invoice → InvoiceLine, a line field called Pending Quantity, Open Quantity, Remaining Quantity or Balance Quantity), and from any other definition on the same action. Each value is checked against the entity model before it is written, so a name that isn't a real entity, collection or numeric field is left blank rather than saved. The fill runs while you edit the new form and again on save, so a definition created through the API is completed the same way. Existing definitions are never rewritten.
• 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, Source Line Parent Field, Target Entity, Pending Quantity Field or Batch Action Name. The screen then shows Conversion not available. A definition saved with some of these still blank, for example through the API, is kept so that you can open and finish it, but it is ignored until it is complete.
• 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.
• What the action receives. For each record, the batch sends the record action that record's staged lines under the Selection Args Key, with their quantities. That holds whether the user picked individual lines or whole records, so an action that requires an explicit line list works in both cases. With a blank key, no line list is sent and the batch always takes every pending line of each record.
• Bulk execution. An action that can process many records in one call (today the order invoicing actions) runs each chunk in a single pass. A record it refuses fails on its own and the rest of the chunk converts, and it can report a result per line: a line with no stock fails alone while the record's other lines convert, and a partly converted line is credited with what was actually converted. Turn this off for one definition with the hidden BulkExecution option (see Configuration). An automation script bound to the action keeps it on the one-record-at-a-time path.
• One result per record otherwise. Any other 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.

1. Under Sales → Settings → Conversions they choose New, set Conversion Type ServerAction and Category Sales, and tick Active. They leave Name and Display Name blank.
2. On Source & Target they pick Source Entity Order. Scope Fields and List Fields fill with the order's partner, branch and date fields.
3. On Quantity & Actions they pick, in Record Action Name, the order action their organisation uses to invoice selected order lines. The form fills Batch Action Name with the same action. It also fills Source Line Entity OrderLine, Source Line Navigation OrderLines, Source Line Parent Field OrderId, the Selection Args Key the action reads, the pending invoice quantity field, Target Entity Invoice, Target Line Entity InvoiceLine and Quantity Pool Order.Invoice. Name and Display Name become order-to-invoice and Order → Invoice.
4. They change Name to sales.order-to-invoice to match their naming scheme. That change is kept.
5. On Criteria they add a Filter Criteria row with Target Header and Expression PartnerAccount.IsActive == true, so that only orders of active companies are offered.
6. On UI Surface they add Visit Route to Scope Fields after Branch.
7. 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 order conversion definition, choose Edit, and add Executive 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.

As a second exercise, choose New, pick Source Entity Order and then any order server action in Record Action Name, without saving. Expected result: the line, pending quantity, target, pool, name and display name fields fill in. Note which fields stayed blank, then cancel.

Quick reference

• On a new definition, pick Source Entity, then Record Action Name; the rest fills in.
• Only blank fields are filled, and only on new definitions.
• 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. The form edits both criteria fields as a table, one row per rule, and stores them as a JSON array of { "target": "Header" or "Line", "expression": "...", "message": "..." }. Members the table doesn't show, for example ones added through the API, are kept when you edit a row. 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. The rules always shape what the filter dropdowns offer, but only a repeating schedule applies them again to the records on each run; a run over every matching record converts exactly what the user's filter bar sends.

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). Edited as a table and stored as 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. Two hidden options are read by the engine itself:

• BulkExecution with default false makes an action that can process many records at once run one record at a time for this definition. Not set means bulk where the action supports it. The help next to Record Action Name shows a Bulk execution line saying whether the action runs in bulk.
• SyncStagingLimit, a Number, sets how many hand-picked records are staged while the user waits. A larger submission creates its batch in Draft at once, with its number, and stages the lines in a background job; the batch is queued when staging finishes, and lines that can't be reserved are kept as Skipped instead of rejecting the submission. Scheduled submissions are never moved to the background. Not set means every submission stages while the user waits.

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

"What does this action do?" help (optional). You can add a help button under Record Action Name that explains the picked action. It shows what the action reads (the argument and line rows), what it loads and creates, which options it reads, and which blank fields it would fill. Unlike the automatic fill, it also works on an existing definition. It writes its suggestions into the form's empty fields only, and nothing is stored until you save. It is not set up out of the box:

1. Under Setup → Metadata → Conversion Definition → Logic → Actions, add a server action named DescribeConversionAction. It needs no record.
2. Grant that action to the security profiles that edit conversion definitions.
3. In the layout designer, open the Conversion Definition form and select Record Action Name. Under Help button, set Type to Server action, choose DescribeConversionAction as the Server action, and set Fill fields to Only empty fields. Save the layout.

The button appears once an action is picked.

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 → 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.

Record Action Name lists nothing, or says "Select the source entity first"

The list shows only the active server actions of the entity in Source Entity. Choose the source entity first. If the action you want still isn't listed, check under Setup → Metadata → the source entity → Logic → Actions that it exists, is a server action and is active.

I picked the action but some fields stayed blank

Automatic fill only writes values it can confirm against the entity model, and it never runs on an existing definition. Fill the remaining fields by hand. Target Entity is the one most often left blank, when the action creates its document through another service. On an existing definition, the optional help button (see Configuration) can suggest the values.

I changed Source Entity or the action, but the other fields kept their old values

Automatic fill writes only to blank fields, so values filled for the first choice stay. Clear the fields you want worked out again, or start a new 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.

Can I trust the values the form fills in?

Treat them as a well-founded starting point. They are read from the action's program code as it stood when the platform was built, and each name is checked against the entity model before it is written, so nothing filled in points at a field or entity that doesn't exist. They can still be wrong for your purpose. For example, an action may read several line collections, or you may want a different pool name. Review every filled field, save, and run a test batch on one record before your users rely on the conversion.

Why must two conversions share a quantity pool?

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.

Related topics

• Bulk conversion and conversion batches
• Bulk order processing
• Conversion Definition reference
• Conversion Batch reference
• Entity behavior: actions
• Design a form layout
• Sales overview