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). For each source record it runs the conversion's action once, covering every selected line of that record. A record either converts or fails as a whole, and all its lines share the result.
• Failures are isolated. By default a chunk runs in one transaction. If anything in it fails, 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.
• 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. A background job looks up the matches, skips records with nothing left to convert and adds them to one batch in slices of 500. The batch stays Draft until the last slice is in, and is then queued.

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.

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.

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.

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.

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.

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 …". 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.

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.
• Background jobs: batches, select-all runs and repeating schedules run as background jobs. Follow them under Setup → Platform Operations → 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 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.

Related topics

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