Bulk conversion and conversion batches

The Bulk Conversion screen turns many source documents into their next document in one submission (for example confirmed orders into invoices), and every submission becomes a conversion batch, a record that converts the selection in the background and reports what happened to each line. You pick records or lines on the screen, the platform reserves their quantity and queues the batch, and a background worker creates the target documents. Afterwards you read the outcome under Recent runs or on the batch record, and you can retry or cancel from there.

Overview

Each conversion is driven by a conversion definition, a setup record that names the source document, the target document, the quantity being consumed and the action that does the work. The Sales app's Bulk Conversion entry runs the order-to-invoice conversion. The Procurement app's Bulk Conversion entry runs the goods-receipt conversion. Both use the same screen. Which filters, columns and options you see comes from the definition, so your screen may differ from the one described here. Administrators set definitions up as described in Conversion definitions.

A conversion batch has a number, a status, line counters and one batch line per source line it covers. The batch line records the quantity requested, the quantity processed, its own status, the document it produced and any error.

When to use it

• You need to convert dozens or thousands of documents for a branch and a date range, and you don't want to open each one.
• You want the work to keep running after you close the page. The batch runs on the server, not in your browser.
• You want a record of what was converted, what was skipped and why.

The Sales app also has an older Order Processing screen that invoices orders straight away, while you wait. It is described in Bulk order processing. This page covers the batch-based Bulk Conversion screen.

How xMatix handles it

• One submission is one batch. The screen sends the whole selection with one submission key. If the selected records belong to different companies or branches, the submission is split into one batch per company and branch, so each batch can be filtered and secured by its own scope.
• Quantity is reserved when you submit. Each source line's quantity goes into a reservation pool. Two conversions that consume the same pending quantity share one pool, so the same units can't be promised twice. While a batch holds a line, the screen shows the held quantity in an In batch column and offers only the rest.
• The work runs in chunks. The worker takes lines in chunks (50 by default), always whole source records, so a record with more lines than the chunk size is still taken in one piece. For each source record the conversion's action covers every selected line of that record.
• Some actions run a whole chunk in one call. The order invoicing actions used for order to invoice can process many orders at once. For them, every order in the chunk is converted in a single pass. An order the action refuses fails on its own with its reason, and the rest of the chunk converts. Inside an order, a line that has no stock fails on its own while the order's other lines are invoiced. Any other action runs one record at a time, and then a record either converts or fails as a whole, with all its lines sharing the result.
• Failures are isolated. By default a chunk runs in one transaction. If an unexpected error stops it, the chunk is rolled back and re-run one record at a time, so good records still convert and only the faulty one is marked failed. A record rejected by validation is marked failed straight away and the run continues.
• Whole-document conversions. If the definition doesn't name a line argument for its action (the action works on the whole document), the batch always converts every pending line of each selected record. Quantities typed on the lines tab don't apply.
• Documents that were created are kept. Cancelling or failing a batch never deletes target documents that were already produced.

Prerequisites

• The Sales product licence. Conversion definitions and batches belong to Sales; without it, the screen can't load a conversion.
• An active conversion definition for the screen's conversion. Otherwise the screen shows Conversion not available.
• View access to the Bulk Conversion page, the conversion's batch action on the source document, and the batch actions described under Permissions.
• Source documents with quantity still pending for the conversion. For order to invoice, that is the order lines' pending invoice quantity.

Procedure

Step 1 — Open the screen and set the filters

Open the app (for example Sales) and choose Bulk Conversion. The filter bar shows the filters the definition names. Partner Account and Branch are pre-filled from your resource record. Date filters appear as one chip that opens on Today, with presets Yesterday, Last 7 days, Last 30 days, This month, Last month and Custom range…. Changing Partner Account clears Branch, because the branches offered depend on the company. Other filters, such as Route, Account and Sales Executive, are added with + Add filter, and Clear filters removes them. No filter is mandatory. If your organisation runs a single company or a single location, the Partner Account or Branch filter is hidden.

The list shows only records that still have quantity available to convert. If nothing matches, the screen says so and offers Show last 30 days and Clear filters.

Step 2 — Choose whole records or individual lines

The screen has three tabs: the source records (for example Orders), their lines (for example Order Lines) and Recent runs.

• On the records tab, ticking a record selects all of its available lines at their full available quantity.
• On the lines tab, each line shows its In batch quantity (held by another batch) and an editable Available quantity. That starts at pending minus held and can't go higher. Typing a smaller number converts only that much and leaves the rest pending. Typing a quantity ticks the line.
• Ticking the header checkbox on the records tab selects every matching record on the server, not just the rows loaded on screen. You can then untick individual records to exclude them. This isn't available for print conversions or while a line filter or line search is active. In that case only the loaded records are selected and the screen says Only the loaded records were selected. With every matching record selected, each line converts its full available quantity, so quantities typed on the lines tab don't apply.

The selection bar shows how many records and lines, how many units and the value you selected. If you change a filter, search or sort while records are selected, Keep your selection? asks whether to keep or clear it.

Step 3 — Check the warnings

If a selected line is no longer available (another batch took it, or it was converted elsewhere), the screen lists it and offers Remove unavailable. If the definition checks stock, a banner reports lines that are short of stock, with Review lines and Unselect short lines. Clear these before you submit. Unless the conversion is set to exclude errors, one unavailable line rejects the whole submission.

Step 4 — Submit

Press the main button. Its label names the target and the count, for example Invoice 12 orders or Invoice 30 lines. For a schedule conversion it reads Schedule …, and for a print conversion Print … (see Step 6 and Step 7).

A receipt titled Batch … queued shows Records submitted, Lines queued, Excluded (pending/held), Failed validation and Total quantity. If a line's available quantity dropped after you loaded the screen, the batch takes the smaller amount and the receipt lists it under Changed since you loaded them. Records refused by the definition's criteria are listed under Rejected records with the reason. Open batch opens the batch record. The selection is cleared and the screen switches to Recent runs.

With every matching record selected, the receipt says Staging every matching record instead, because the server doesn't receive a list of records. The batch is created, numbered and set to Draft the moment you submit. A background job then looks up the matches, skips records with nothing left to convert and adds them to the batch in slices of 500. The batch is queued once the last slice is in. The run converts exactly what your filter bar sends. If nothing matches, the batch is closed Completed with the message "0 record(s) matched; nothing left to convert." If the lookup itself fails, the batch is closed Failed with "Staging failed: …" and anything already staged is released.

If the definition sets a synchronous limit and you hand-pick more records than that, the receipt reads Batch … created — staging in the background. The batch is created in Draft at once, its lines are added by the same background job, and it is queued when they are all in. Any line that can't be reserved by then is kept as Skipped with its reason instead of rejecting the submission. Scheduled submissions are never moved to the background.

Step 5 — Follow the batch

Recent runs lists the conversion's batches for the selected company and branch, newest first, with Batch, Status, Lines, Succeeded, Failed, Skipped, Queued and Completed. Filter by All, Failed, With errors, Completed or Processing. The list refreshes every few seconds while a batch is running. Latest Batch Status opens a summary of the newest batch with its line counts, requested and processed quantity, and times.

Open a batch to see its record. The header shows the conversion, status, total, succeeded and failed lines. The Lines tab lists each batch line with its source document and line, requested and processed quantity, status, the document it produced, and any validation or error message. The Details tab shows the batch's fields.

Step 6 — Schedule a conversion (schedule conversions only)

If the definition's type is Schedule, the main button opens a dialog with three choices:

• Run now. The batch is queued straight away.
• Run once at a specific time. The selected lines are reserved now and the batch waits in Scheduled until that time, then is queued. A time more than five minutes in the past is refused.
• Repeat on a schedule. Pick a preset or Custom schedule… (built with Build a schedule). Nothing is reserved or staged now. Each run converts whatever matches the filters at that moment. Date ranges are left out, so every run picks up what is ready then.

For a repeating schedule, or a run over every matching record, the dialog shows Filter rules: what each of the conversion's filter rules matches right now. Use Add rule or edit a rule to change it for this schedule only, and Use the definition's rules to go back. A rule shown as Invalid stops the run.

Only a repeating schedule applies the filter rules again on each run. A run over every matching record, now or once later, converts exactly what the filter bar sends; the rules only limit what the filter dropdowns offer. On a repeating run, a rule on a filter you picked is strict, while a rule on a filter you left empty keeps records that have no value in that field (for example, orders with no route).

Step 7 — Print instead of converting (print conversions only)

If the definition's type is Print, the main button renders the definition's document report for each selected record and opens a preview. Printing reserves nothing and creates no batch.

Step 8 — Retry or cancel a batch

On the batch record:

• Retry Failed Lines puts the failed lines back to pending and queues the batch again. Each line is re-checked against the source as it is now. A line is retried for whatever quantity is still pending and not held elsewhere, up to what it originally asked for. A line with nothing left stays failed, and its error says why.
• Cancel Batch stops a batch. A Queued or Scheduled batch is cancelled at once and its pending lines release their quantity. A Processing batch moves to Cancelling and stops at the end of the current chunk. A finished batch can't be cancelled; you are told it has already finished.

Step 9 — Open a batch line to see what happened to it

On the batch's Lines tab, open a line. Its page header shows the line's Status, Source Document, Requested Quantity and Processed Quantity, and the page groups the rest into Identity, Source, Quantities, Status and result, Attempts and timeline and Diagnostics. Read Validation Message for why a line was skipped, and Error for why it failed. Result Document is the document it produced. The only action on the line is Delete. To stop work, use Cancel Batch on the batch rather than deleting lines (see Business rules).

Fields

Batch fields

The batch record, in the order its Details tab shows them. All of them are set by the platform; you read them, you don't type them.

Batch line fields

One batch line per source line, in the order the line page shows them. All of them are set by the platform. The batch's Lines tab shows Name, Sequence, Source Document, Source Line Number, Requested Quantity, Processed Quantity, Status, Result Document, Validation Message, Error and Created On.

Business rules

Batch status.

Skipped lines never make a batch fail: a batch where every line was skipped ends Completed.

Line status. Pending, Processing, Succeeded, Skipped (nothing left to convert, not an error), Failed and Cancelled. A line that hits an unexpected error goes back to Pending and is retried, up to the definition's line attempt limit (3 by default). Then it is marked Failed. A validation failure, a deleted source record or a missing action fails the line straight away, with no retry. Succeeded, Skipped, Cancelled and finally Failed lines release their reservation.

Per-line results in a bulk pass. When an order invoicing action runs a chunk in one call, each line gets its own verdict. A line with no stock fails with "No stock available to allocate for item '…' (requested …)." or "Nothing was available to invoice for '…'." while the order's other lines succeed. A line that was only partly invoiced succeeds with the smaller Processed Quantity. An order refused as a whole fails all its lines with the reason. These failures are not retried automatically, and their quantity is released straight away, so the source line shows as available again.

When the action does nothing. If the action runs without error but creates no target document (for example, the order was fully invoiced by another route in the meantime), the line is marked Skipped with the message "The action ran without error but produced no …".

Submission checks. A line with no pending quantity, or whose quantity is fully held by another batch, can't be submitted. Neither can a requested quantity of zero or less. Unless the conversion excludes errors, any such line rejects the whole submission with "N line(s) cannot be converted. Refresh the list and try again." Nothing is written. If another batch takes the quantity in the instant between the check and the reservation, the line is kept as Skipped with a message instead.

Whole-batch retries. If an attempt fails outright, the batch is marked Failed and tried again after a wait of 2, 4, 8 … minutes (at most 30), until it reaches its attempt limit.

Background housekeeping. An hourly job, Reconcile conversion batches, releases reservations left behind by finished or deleted lines. It also releases select-all batches stuck in Draft and flags batches that seem stuck. Deleting a batch also deletes its lines and releases what they held. Deleting a single line from its page releases what that line held, but the batch's counters are only recounted while the batch is still open, so a finished batch keeps counting the deleted line.

Example

A sales coordinator at a distribution company invoices the week's confirmed orders for the Riverside depot.

1. They open Sales → Bulk Conversion. Partner Account and Branch are already set to their company and the Riverside depot. They change the date chip to Last 7 days and add a Route filter for the north route, and 12 orders are listed.
2. They tick all 12 orders on Orders. On Order Lines, one line of order SO-1182 asks for 40 cases, but only 25 are going out this week, so they type 25 in Available. The other 15 cases stay pending on the order.
3. Back on Orders, they press Invoice 12 orders. The receipt shows Batch CB-0215 queued, 12 records submitted, 31 lines queued.
4. Under Recent runs the batch moves from Queued to Processing. A minute later it shows CompletedWithErrors: 29 succeeded, 2 failed.
5. They open the batch. On Lines, both failed lines belong to order SO-1197, with "No stock available to allocate for item …". The order's other lines were invoiced. After the warehouse posts the missing receipt, they press Retry Failed Lines, and the batch ends Completed.

Training

Practice exercise

In a sandbox with the Sales app and an active order-to-invoice conversion definition, create three confirmed orders for one branch dated today, each with two lines of items that have stock at that branch. Open Sales → Bulk Conversion, select two orders on the records tab and one line of the third order on the lines tab with half its quantity, then submit.

Expected result: one batch is queued with five lines. Under Recent runs it reaches Completed. The batch's Lines tab shows five succeeded lines, each showing the invoice it produced in Result Document. The third order still shows its other line and half of the first as available on the screen.

Quick reference

• Each submission makes one batch per company and branch.
• In batch is quantity held by another batch; Available is what you can still convert.
• The header checkbox selects every matching record, not just the loaded rows.
• Skipped means nothing was left to convert. It is not an error.
• Retry Failed Lines re-checks quantity before it retries.
• Cancel Batch on a running batch stops at the next chunk. Documents already created stay.
• Scheduled one-off runs reserve now. Repeating schedules reserve nothing until each run.
• A "select all" batch is created in Draft at once and queued when staging finishes.
• Open a batch line and read Validation Message (skipped) or Error (failed).
• In a bulk order-invoicing pass, a line without stock fails alone; the rest of the order converts.

Permissions

Sales Executive, Standard User and System Admin have full record access to conversion batches and batch lines by default. Only records you are allowed to update are converted; a record you can't see is reported as "The record could not be found, or is not visible to you."

Configuration

• Conversion definitions: Sales app → Settings → Conversions. Each definition decides the screen's filters, columns, options, criteria, failure handling, chunk size, attempt limits, and whether it converts, schedules or prints. See Conversion definitions.
• Batch numbering: set up a document numbering series for Conversion Batch to give batches your own numbers. Without one, batches get a generated number starting with CVB.
• Screen placement: the Bulk Conversion pages are app pages, and the conversion screen's settings in the page designer choose which conversion it runs. They also control an optional second-conversion button in the screen header (on the Sales page it is labelled GRN Conversion and opens the goods-receipt conversion): Show Conversion Button, Button Label, On Click (open in a window or go to another page), Conversion Definition and Carry Over Filters & Selection, which hands up to 100 ticked records to the second screen.
• Bulk execution and the synchronous limit: two hidden options on the definition's Options (JSON) tune large runs. BulkExecution set to false makes an action that can process many records at once run one record at a time instead. SyncStagingLimit set to a number of records sends any larger hand-picked submission to background staging, as described in Step 4. Neither is shown on the screen or stored on the batch. The help next to Record Action Name on the definition says whether its action runs in bulk. See Conversion definitions.
• Background jobs: batches, select-all runs and repeating schedules run as background jobs. Follow them under Setup → Platform → Monitoring → Jobs. Repeating schedules appear on its Schedules tab. The Reconcile conversion batches schedule runs hourly.

Common problems

"Conversion not available"

No active, complete definition exists for the screen's conversion key, or Sales isn't licensed. Ask an administrator to check the definition under Sales → Settings → Conversions and that it is marked active.

"N line(s) cannot be converted. Refresh the list and try again."

At least one selected line had nothing left, was held by another batch, or had a zero quantity when you submitted, and nothing was staged. Press Refresh, use Remove unavailable, and submit again.

A line I selected was converted for less than I asked

Its available quantity fell after you loaded the screen, so the batch took what was left. The receipt lists it under Changed since you loaded them. The remainder stays pending on the source line.

Lines are Skipped with "Quantity … is committed to an in-progress batch"

Another open batch already holds that quantity. Wait for it to finish, or cancel it if it was a mistake. Its quantity is released and the lines appear again.

Lines failed with "has no RecordActionName"

The definition doesn't name the action that converts each record. An administrator sets Record Action Name on the definition, then you use Retry Failed Lines.

"Conversion '…' is no longer registered, so this batch cannot be retried."

The definition was deactivated or removed after the batch ran. Reactivate it to retry.

Retry left lines failed with "Retry skipped: …"

The source line has no pending quantity left, or other batches hold all of it. The message gives the numbers. Nothing more can be converted until quantity frees up.

A "select all" batch closed Completed with "0 record(s) matched; nothing left to convert."

No record matching the filters had anything left to convert when the background job looked. Check the filter bar (date range, branch, route) and that the documents still have pending quantity, then run again. A batch closed Failed with "Staging failed: …" stopped while looking up matches; the message names the cause, and whatever was staged has been released.

One line of an order failed but the rest of the order was invoiced

The order was converted in a bulk pass, and that line had no stock (or nothing left to invoice). Only that line failed, and its quantity is free again. Add stock or correct the line, then use Retry Failed Lines, or convert the line again from the screen.

A scheduled batch won't retry

A batch in Scheduled is waiting for its run time; retry says so. Cancel it if you want to run the selection now.

Common questions

Can I close the page after submitting?

Yes. The batch runs on the server, so closing the page or signing out doesn't stop it. Come back to Recent runs, or open the batch record from its link, to see the result. The receipt and the list read the batch's own counters, so they show the same outcome whoever looks. If a worker stops part-way, another one picks the batch up once its claim lapses, and finished chunks are not redone.

What happens if I submit the same selection twice?

The quantity is already reserved by the first batch, so the second submission finds nothing available. Each line is either refused on the screen or staged as Skipped. Nothing is converted twice. The In batch column shows the held quantity while the first batch is still open, and the lines disappear from the screen once converted.

Does cancelling undo invoices that were already created?

No. Cancel stops further work and releases quantity for lines that hadn't run. Target documents already created are real documents and stay, so cancel or reverse them individually if needed. A running batch finishes its current chunk before it stops.

Why did one order produce several failed lines?

The conversion action runs once per source record, covering all of that record's selected lines. If it fails, every selected line of that record fails with the same message. Fix the cause and use Retry Failed Lines. The exception is a bulk order-invoicing pass, where a line with no stock fails on its own and the order's other lines are still invoiced; there, several failed lines on one order mean several lines were short.

Related topics

• Conversion definitions
• Bulk order processing
• Invoices
• The sales order lifecycle
• Conversion Batch reference
• Conversion Batch Line reference