> ## Documentation Index > Fetch the complete documentation index at: https://docs.mercora.io/llms.txt > Use this file to discover all available pages before exploring further. # Steps > Every kind of step an automation can take, what each field means, and an example of each. An automation's steps run in order, from step 1 down. Each step does one thing: works something out, finds or changes a record, waits for a person, or decides where the run goes next. ## Add a step Click **Add a step** under the last step. The menu groups the steps by kind; type in **What should happen next?** to search. Click one to add it: it opens below the others, ready to fill in. ![The Add a step menu with the AI and Mercora groups](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/add-step-menu.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=62eabb0298ff43a3bc97197a3fd7fce7) The top of the Add a step menu: the AI step and the Mercora steps. ![The Add a step menu scrolled to the People and Logic groups](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/add-step-menu-more.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=4bfc80070b95559fe7331c40c36eeba4) Further down: the People and Logic steps. | Group | Steps | Use it to | | - | - | - | | **AI** | [Work something out](#work-something-out) | Read, compare and judge, from a brief you write | | **Mercora** | [Find a record](#find-a-record), [Find contacts](#find-contacts), [Update a record](#update-a-record), [Report a finding](#report-a-finding), [Make a confirmation](#make-a-confirmation) | Do one thing in Mercora, the same way every time | | **Apps** | [An app's actions](#app-actions) | Do one thing in a connected app, such as sending an email | | **People** | [Ask someone to approve](#ask-someone-to-approve), [Ask someone a question](#ask-someone-a-question) | Wait for a person's decision or answer | | **Logic** | [If](#if), [Wait for](#wait-for), [Tell someone](#tell-someone), [Stop here](#stop-here) | Decide where the run goes, pause it, or leave a note | The menu lists only the steps this automation can use here. A Mercora step shows once the automation can be given the area it needs; an app shows once an admin has connected it and switched its actions on. If no step matches what you need, describe it in an AI step's brief instead. Fields marked **\*** are required. Most fields take a value from the trigger or an earlier step, picked by name: see [Use values from earlier steps](https://docs.mercora.io/workflows/automation-values.md). ## AI ### Work something out An AI step does the job its brief describes. It reads what the automation may read under **Uses**, plus what started the run (the document, the request or the message) and the answer of the step before. Use it where judgement is needed: comparing two documents, reading payment terms, drafting a reply. | Field | What it does | | - | - | | **Brief** | What the step should do, in plain words. The first sentence becomes the step's sentence in the list. | | **Skills** | Click **+ Skill** to give the step a skill: a written method it follows, such as how your team checks a freight invoice. | | **Can stop and ask** *owner* | On: when the step can't settle something (two sources disagree, a value is missing, a reference is ambiguous), it pauses and asks the owner in the Inbox, then carries on with the answer. | | **Who approves what it proposes** | Who decides the changes this step proposes. The owner by default. | | **Run the steps below once for each record it creates or changes** | On: when the step creates or changes several records (such as the trades in one recap email), every step below it runs once per record, each in a run of its own. | ![An open AI step with its brief, Skills, Can stop and ask, Who approves what it proposes and the run-per-record switch](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-ai.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=b259c256f5fea5defadffd3c088aed5e) An AI step that compares an invoice with its contract. **Example brief:** "Compare this invoice with its trade's contract: price per unit, quantity and currency. Say whether they match and, if not, exactly what differs, with both values." Write the brief the way you'd brief a colleague: what to look at, what to compare, and what a good answer contains. An AI step never makes a change itself: it proposes one, only where the automation has **Propose changes**, and each proposal waits in the Inbox. When it finds nothing worth reporting, it says so, and a run whose last step found nothing ends without an Inbox card. A later step can ask an AI step for a value by name, such as "matches contract" or "due date": the AI step then hands that value back. See [Ask an AI step for a value](https://docs.mercora.io/workflows/automation-values.md#ask-an-ai-step-for-a-value). ## Mercora ### Find a record Looks up one trade, contract or invoice by its exact reference. It only reads. | Field | What to set | | - | - | | **Record type** \* | **Trade**, **Contract** or **Invoice** | | **Reference** \* | The reference to look up: usually a value from the trigger, such as "from the request · Contract number" | ![An open Find a record step: Record type Contract, Reference from the request · Contract number](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-find-record.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=c8c88889e867d01a0e6323b685f26819) Find the contract whose number another system sent. **What later steps can pick from it:** **Its id**, **Reference**, **Its trade**, **Counterparty**, **Quantity**, **Price**, **Currency** and **Amount**. If nothing has that reference, the step still finishes, with every value empty: follow it with an [If](#if) such as "from step 1 · Its id is not empty". If two records share the reference, the step fails rather than pick one. The automation needs **Read** on the record's area. ### Find contacts Finds the email addresses of the contacts on a trade, an invoice or a counterparty, for a later step that sends an email. Set **Trade, invoice or counterparty**, and optionally **Which side** (customer, supplier or both) and **Contact role contains**. Later steps can pick **Their email addresses**, **Their names**, **Counterparties** and **How many**. It shows in the menu where the automation can be given the **Counterparties** area. ### Update a record Proposes a change to one trade, shipment, contract or invoice. It always asks first: the person under **Approved by** sees the exact change in the Inbox and approves, edits or rejects it. | Field | What to set | | - | - | | **Record type** \* | **Trade**, **Shipment**, **Contract** or **Invoice** | | **Record** \* | Which record: its id, picked from the trigger or an earlier step. For the invoice that started the run, "from the document · The document". After a [Find a record](#find-a-record) step, "from step 1 · Its id". | | **Fields to change** \* | Type the field's name, such as `due_date`, and click **Add field**. A row for it appears: pick its new value. Add one row per field. | | **Approved by** | Who approves the change. The owner by default. | ![An open Update a record step: Record type Invoice, Record from the document, Due date from step 1, Approved by the owner](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-update-record.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=9345e08057d924f952deab98b12f95bf) Propose the invoice's new due date, worked out by step 1, for Alex Morgan to approve. The automation needs **Propose changes** on the record's area. If the record already holds those values when the step runs, nothing is asked and the step is done. Later steps can pick **Its id**. ### Report a finding Ends the run with a card in the Inbox under **Needs you**. Write the **Finding** as text with values in it: type, click **+ value** to put in a value, and carry on typing in the box after it. ![An open Report a finding step with text and two values: from the document · Invoice number and from step 1 · What differs](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-report.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=d68162b9a69093d58b6f91a602f0e3bf) If invoice KSS-INV-26-0288 charged USD 540/MT, the finding would read "Invoice KSS-INV-26-0288 differs: unit price USD 540/MT, contract VCS-P-2026-0688 USD 528/MT". Only [Tell someone](#tell-someone) steps can come after it: they leave their notes, then the run ends. ### Make a confirmation Draws a PDF of a trade's terms and files it on the trade. Set **Trade** to the trade's id, such as "from the document · Its trade". It asks first; a workspace admin can let it run without review, since the PDF comes from the approved trade and nothing leaves Mercora. Later steps can pick **The confirmation** (the new document) and **Its file name**. It needs the **Trades** area. ## Apps ### App actions Once an admin connects an app and switches its actions on under **Settings → Integrations**, the **Add a step** menu lists them under **Apps** as *app* · *action*, each marked with how it acts: * **Only reads**: runs straight away, such as finding a contract in your CTRM. * **Asks first**: waits for the person under **Approved by** to approve the exact inputs, then runs once. This is how anything that changes data or leaves Mercora acts, such as sending an email. Some actions work only inside an AI step, so they aren't in the menu: give the app **Read** or **Propose changes** under **Uses**, and describe what to do in an AI step's brief. An app step lists its required inputs first; the rest are under **More inputs**. A few low-risk actions, such as an email to your own team, can run without review: only a workspace admin can switch that on, on the step. See [Integrations](https://docs.mercora.io/integrations/overview.md) for what each app offers. ![The table of actions automations may use for an integration](https://mintcdn.com/placeholder-f4ffdeec/22McaegbdDRSI41b/images/integrations/automation-actions-table.png?fit=max\&auto=format\&n=22McaegbdDRSI41b\&q=85\&s=1231a9cfbc589f8f2e0241d7a57e343c) An app's actions, as an admin switches them on for automations in Settings → Integrations. ## People ### Ask someone to approve Waits until a person approves, edits or rejects what the step before drafted. Set **What** *person* **approves** (a short title for the card) and **Approved by**. Rejecting ends the run. ![An open Ask someone to approve step with its title and Approved by](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-approval.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=fdbf0b161fc568768d39f22628332e75) Alex Morgan approves the broker order the AI step drafted. It can't be step 1, since it approves the step before it. If the AI step before it found nothing to report and only **Tell someone** steps come after it, there is nothing to approve and the step is skipped. Later steps can pick **What was approved**. ### Ask someone a question Waits for a person's answer. Set **What** *person* **is asked** and **Answered by**. The answer goes to the next step, and any later step can pick it as **The answer**. ![An open Ask someone a question step: Which account should the credit note go to?, Answered by the owner](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-ask.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=3e6ff96fe0f56b13a55070a6e30bb6ec) Ask which account a credit note goes to. ## Logic ### If Lets the run carry on only when a value matches. Mercora checks the rule itself: no AI decides it. 1. Click **Add a rule**. 2. Click **Pick a value** and pick what to check, such as "from step 1 · Matches contract". 3. Pick the test. Tests that compare need a second value: pick it, or type one. 4. Under **Otherwise**, pick what happens when the rule doesn't hold: **Stop here, nothing to report** (the run ends quietly) or **Skip to step** *N* (a later step). ![An open If step: from step 1 · Matches contract is no, Otherwise Stop here, nothing to report](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-if.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=24da01a8736b107daf2c947ce927de26) Carry on to the finding only when step 1 says the invoice doesn't match. | Test | Holds when | | - | - | | **is not empty** | The value is there | | **is empty** | The value is missing or blank | | **is** / **is not** | The two values are the same text, or differ (ignoring capitals and spaces at either end) | | **contains** | The first value contains the second | | **is more than** / **is less than** | Both are numbers and the first is larger, or smaller | | **is yes** / **is no** | The value is yes (or true), or no (or false) | Add up to three rules with **Add a rule**, then choose **All of them** or **Any of them**. A missing value is never guessed: only **is empty** holds for it. Numbers must be plain, such as `1200` or `1200.50`; "1,200" is not read as a number. ![An If rule comparing from step 1 · Due date with from the document · Due date](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-if-compare.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=8f54708db9cb83137758dd810b64084f) Compare two values: carry on only when the due date step 1 worked out differs from the one on the invoice. ### Wait for Pauses the run. Pick what it waits for under **Wait for**: | Wait for | Set | Carries on when | | - | - | - | | **A set time** | **For** a number of minutes, hours or days | The time is up | | **Until a date from an earlier step** | **Until**: a date value, such as an AI step's "chase date" | That date comes | | **A document to reach the trade** | **Document** types, **On the trade** (a trade from the trigger or an earlier step), **Up to** a limit | A document of those types is matched to that trade | | **Another system to call back** | **Up to** a limit. Your system calls the address shown, `POST /api/v1/agents/{id}/runs/{runId}/callback` | Your system calls back | For a document or a callback, choose what happens at the limit: **carry on without it** or **treat it as failed**. A set time, and the limit on a document or callback wait, can be at most 30 days; an **Until** wait lasts until its date. A test skips waits. A document wait counts only documents that reach the trade after the run started; one already on the trade doesn't end it. If no trade was found before the step, it fails. ![An open Wait for step: A document to reach the trade, Document Bill of Lading, On the trade from the document · Its trade, Up to 14 days then carry on without it](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-wait.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=d94023c38476169776d9af5c71288619) Wait up to 14 days for a B/L to reach the contract's trade, then carry on without it. Later steps can pick **The document** and **Its type** after a document wait. When it carried on without one, both are empty: check with an If such as "from step 1 · The document is empty". After a callback, ask the step for any field the call sends, by name. ### Tell someone Leaves a note in a member's Inbox, and the run carries on without waiting. Pick who under **Tell** (the owner by default) and write the **Note**, with values if you like. Their notification settings can also send it to their email or WhatsApp. ![An open Tell someone step with a note containing from the document · Contract number](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/step-tell.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=efaabbd0178672bf5008ad07af4c4715) Tell the owner which contract has no B/L yet. ### Stop here Ends the run as done. Use it to end one branch of an If. To run step 2 when a rule holds and step 4 when it doesn't: 1. **If** the rule, otherwise **Skip to step 4** 2. The step for when the rule holds 3. **Stop here** 4. The step for when it doesn't ## Who is asked Every step that involves a person names one member: an AI step's **Who approves what it proposes**, an approval, a question, an **Update a record** or app step that asks first, a **Tell someone** note, and a failure plan. It's the owner unless you pick someone else, and the member you pick must be able to see what their card shows. Where the step waits for a decision, that member or a workspace admin decides; a **Tell someone** note only lands in their Inbox. ## If a step fails An AI step, a Mercora or app step, and a **Wait for** step can each have a plan for when they fail. With no plan, a failed step stops the run: it ends as failed, with the step and the reason, and a card in the Inbox. To change that, open the step's **⋯** menu and click **Add what happens if it fails**. An **If it fails** row appears, set to **Ask someone**. Pick: * **Ask someone**: the member you pick sees what failed and chooses **Try again**, **I did it by hand · carry on** or **Stop the run**. * **Tell someone and carry on**: they get a note and the run goes on. Not offered when a later step uses this step's values, since those values would be missing. * **Stop the run**: removes the plan again, so a failure stops the run as above. ![If it fails: Ask someone, The owner, with the note Later steps use its values, so it can't just carry on](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/if-it-fails.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=d7578cfe13c5c346ad19d0b9be79f47e) If the AI step fails, ask the owner. It can't just carry on, because step 2 uses its values. ## Next steps * [Use values from earlier steps](https://docs.mercora.io/workflows/automation-values.md): fill the steps' fields with values from the trigger and from each other. * [Examples](https://docs.mercora.io/workflows/automation-examples.md): four automations that combine these steps. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.