Build automations

An automation chains M3 APIs together and runs them across many rows of input data. Use automations for migrating data, generating reports or making bulk changes, repeatably and guarded against running in the wrong environment.

Automations are grouped in automation collections, just like APIs in Run.

Create an automation

In the Automate workspace, click New to create a collection (rename it with the pencil icon), then Add automation. The automation editor opens:

An automation flows top to bottom: Data initialization (your input rows), one or more API steps, and Data export (the result). The right-hand rail holds the run, save and edit controls. Click Edit automation to make changes, and Finish editing when you're done.

Give the automation a clear name, and tick which Enabled environments it may run in.

With Loupe Code, Build with AI can draft the steps for you from a description and your files. See Build automations with AI.

Set up the input data

Click Configure on the Data initialization step:

Either Upload a file or Add a column manually. Loupe reads Excel files (.xlsx, .xls), CSV files, and raw M3 exports. The file's columns become your dataset. Name each column after the M3 field it feeds, such as ITNO; that enables automatic mapping later.

Then fill the grid: Add row and type, Paste rows from a spreadsheet, or Import CSV. Recent exports lets you pick up a file you exported earlier from Compare, Run, an automation or M3:

The key icon in a column header groups rows by that column. When rows are grouped, the whole automation runs once per group, and the Data initialization card shows a tab per group so you can inspect them.

An Alias renames the dataset everywhere it is referenced.

CSV files can be in UTF-8 or in Windows-1252, the encoding Excel often saves in. Loupe reads both, so letters such as å, ä and ö come through as they are.

Several files and workbook sheets

Some jobs need more than one file, such as customers in one file and their addresses in another. A Data initialization can hold several files, and each step chooses which one it runs for.

From a workbook: upload an Excel file with several sheets, and Loupe asks which sheets to import:

One sheet goes in the grid. Each other sheet you pick becomes a file of its own.

From separate files: in Configure, click Add a file under Files, and pick a CSV or Excel file. Give each file a clear name, for example Addresses. The file in the grid is named by the Alias.

Then say how they relate: which column of one file matches which column of the other. Loupe suggests a relation when two files share a column name.

• Click + Another column when it takes several columns to match a row, such as a customer number and an address number together.
• Tick Ignore case to match a1 with A1.
• Under the relation, Loupe counts how many rows found their match, and lists the keys of rows without one. In the example, one customer has no address number.

Each file gets a tab above the grid. The file in the grid can be edited; the others are shown read only:

In the steps: a step runs for one file, which you choose under In at the top of the step. It can also read the columns of a related file like any other value, for example the town of a customer's address (Addresses: TOWN). Relations are followed in both directions, and through several files as long as each link is a single row. A step reads exactly one related row: when a row has no related row, or several, the step skips it and the run tells you why. To choose those rows yourself, use a Where condition on the other file.

Files stay on this computer. Only their names, columns and relations are saved with the automation. The rows are gone after a reload, and Data initialization says which files are not loaded. Click Import files and pick all of them at once: each file loads where it belongs, matched by its file or sheet name, and otherwise by its columns. Or load them one by one with Load file in Configure.

Add an API step

Click Add API in the right-hand rail. The step's configuration opens:

1. For … in … decides what the API iterates over. The default, for All lines in Data init, runs the API once per input row. See Datasets and grouping.

2. Where skips rows that don't match a condition, for example only rows where STAT = 20. Conditions can also test whether an earlier step succeeded or failed for that row. See Where conditions.

3. Pick the program and transaction. Instead of a program you can pick an M3 Table to read it with filters, the same way Compare does.

4. Map the inputs. Auto-map fields matches dataset columns to API fields by name. Or click the list icon next to any input, Map field from API or dataset, to choose the source by hand:

   

Inputs you leave unmapped can take a static value or stay empty. The current CONO and DIVI of the selected environment are always available as sources, so you never hard-code a company number. Configure included inputs hides inputs you don't need from the list.

At the top right of the step you can cap Max transactions per bulk request, Max number of concurrent requests and Max number of records per request (0 means as many as M3 allows). Leave them blank for sensible defaults. Continue on error lets the run carry on past failed rows instead of stopping at the first failure.

Close the configuration with Close or Esc. A step without a transaction is removed again.

Where conditions

Click Add condition under Where to choose which rows the step runs for:

• Filter on field compares a value of the row: from the Data init, an earlier step, or a Transformation such as Translate warehouse: WHLO. Compare with =, !=, >, <, >=, <=, contains or starts with, or test whether the value is empty or is not empty. A value the row doesn't have counts as empty.
• Filter on result tests whether an earlier step succeeded or failed for the row. Use it to send failed rows down a different path, for example to create what a Get could not find.
• Filter on another file appears when the Data initialization has several files. It tests whether the row has a row in a related file, or has no row in it. For example, add addresses only for the customers that have one.

Join the conditions with and or or. and binds tighter than or, the way it does in SQL: each or starts a new group, and a row passes when every condition of one group matches. So

STAT = 20 and WHLO is not empty or ITNO = A1006

runs for the rows with status 20 and a warehouse, and also for item A1006 whatever its status. To require something of every row, add it to each group.

The step's card shows its conditions, so you can see at a glance which rows it runs for.

Configure the export

Click Configure on the Data export step:

1. Choose which dataset the export is based on, typically the output of your last API step, and optionally a For grouping:

   

2. Add columns one by one with Add column, or Add all columns from source. Rename a column with the pencil, and point it at a source field with Choose source:

   

3. A column can also read values that don't come from a row: a variable such as a cut-over date, or the date and time of the run. Columns from a Transformation write translated values, so the old and the new value can sit side by side:

   

Try it with a dry run

Before an automation changes anything, click Dry run in the right-hand rail. A dry run changes nothing in M3: steps that read run for real, so later steps get real data, and steps that write build their transactions and stop just before sending them. It needs no confirmation and leaves no run history. Like a real run, it only runs in an enabled environment.

Each write step shows Would send and the number of transactions it would have sent. Here only 4 of the 6 rows qualify: one has status 90, and one has no new warehouse. Click it to see every transaction, field by field:

If the transaction needs fields that the step doesn't set, the preview lists them in red: M3 would refuse every transaction until they are mapped. A step that needs the result of a write step can't be previewed, because that step never ran; it shows Needs and the step's name instead.

The export fills as well. Click Expand to check the whole file before you run:

Run it

Save automation, then Run automation. If the automation contains transactions that change data, Loupe first asks you to confirm, naming the environment and company/division it will run against.

Each step reports its progress: Preparing, Running, Processing results, then Successful or Error, along with how long it took. When the run finishes, the export grid fills and Export to Excel gives you the file. Expand opens the grid full screen.

Click a step's status to open its Latest response: how many transactions ran, succeeded and failed, the errors grouped by error code, and every transaction's input and output, in a table or as JSON. Toggle Only display errors to focus on what went wrong, fix the mapping or input, and run again. Stop automation cancels a run in progress; the log then marks which transactions never ran.

If a step is misconfigured, a Validation errors button appears on it and Run automation stays disabled until you fix it. Typical causes are a missing transaction, a reference to a dataset that no longer exists, or a field that isn't in the source step's outputs.

Chain more APIs

Real automations rarely stop at one step. Click Add API again. The new step is added after the last one, and its in dropdown can point at any earlier dataset, so one API's output becomes the next API's input. Steps can be dragged into a different order.

A typical pattern: a Lst transaction fans out rows, a Get enriches each row, and the export collects the result. Add transformation adds columns without calling M3, for example to translate old codes into new ones; see Transform and translate data. Add Wait inserts a pause of a configurable number of seconds when M3 needs breathing room between steps. Copy automation duplicates the current automation as a starting point for a new one.

Datasets and grouping

Every automation starts with one dataset, Data initialization. An API step that uses it as its source runs once per row, or once in total if you never configured any input data.

The For field in dataset setting controls grouping. With for All lines in Data init, the step runs for every row. Pick one or more fields instead, for Order number in Data init, and the step runs once per unique value of that field. That's how you turn a list of order lines into one AddBatchHead call per order.

Every API step produces a dataset of its own, named after its alias or its program and transaction. Later steps and the export can read from it, and can also filter on whether that step succeeded or failed for a given row.

Use an automation in Compare

Tick Use in compare to make a read-only automation available as a source in Compare. The Compare eligibility popover lists what is required: at least one API, only reading transactions (Get, Lst, Select, Search and tables), a configured data export, and a For field on the export that uniquely identifies each row.

Saving and history

Loupe saves the collection automatically a moment after every change. Save automation and Ctrl+S (⌘S) save immediately. The clock at the right end of the tab row opens the History panel, where every save is listed and any earlier version can be restored.