Make buttons and change the base's code

A button on an item or on a list does several things with one click, in order: Issue on an invoice sets its status to Issued and mails it to the customer, Make the invoice on an order makes an invoice with the order's lines. You list its steps; nobody writes code, and it works on every base. Making buttons is for the base's builders.

1. In Builder, open the table, then its Custom actions page, and click Add action.
2. Give it a Title and an Icon. Pick where it runs: On a single item, On one or more items (on the item and on the items ticked in the list, in one go: Change or delete many items at once) or On the list, with no item, and how it is Shown as. Ask first is the question the button asks before it runs, such as "Issue this invoice?", Who may run it the roles, and Only when a condition on the item that hides the button when it does not hold.
3. Under Steps, click Add step and pick what it does, one of the kinds under The steps a button can take.
4. Give each step its values, from the sources under Where a step's values come from.
5. Click Done, then Save table.

The steps a button can take

• Set a field of the item, such as its Status to Issued;
• Create an item of any list, with Copy rows to bring the item's lines into the new one's, all of them or Only the rows that match; ticking fields under Update instead when one has the same changes the item that has the same value instead of making a second one;
• Update items: the items a reference of this item names, such as the order's customer, or the items of a list that match a filter, at most 1,000, such as every active product; a filter's value can be an answer of the button's form or a field of the item, with Use a placeholder;
• Send an email, Call a webhook, Run an agent or Start a workflow, as an automation does (Run actions when an item changes); an email and a webhook go out once the button has run and all it did is saved, and a webhook is sent once, with no more tries (Send webhooks to another service);
• Run code, for what the other steps cannot say, such as a call to another company's system (Read, change and try the base’s code);
• Open a form, the last step: a new item's form, filled in with the values you give it (Open a filled-in form from a button).

Where a step's values come from

Each value of a button's step is one you type, one with Insert a field, such as {{customer.email}}, a field of the base's settings, such as {{settings.iban}} (Keep rates and the closed month in a settings table), or Work it out in SQL, the language of the base's database, such as r.stock + i.quantity: r is the item the button is on and i the answers of its form.

• On a date, choose Today, The start of this week, of this month or of this year, or Relative to a day, such as 30 days from today; on a date and time, choose Now. The button then writes the base's day and time, in the base's time zone.
• A reference can also Find by… a unique field of the item it names, such as a product by its SKU, and with Add one when none matches it adds that item when none has it.

How a button runs

A button's steps run as the person who clicks, under their role's rules, and either all of them happen or none does: if one fails, such as a create that misses a required field, nothing is saved and the person reads why. On ticked items, this holds for all of them at once (Change or delete many items at once). A change to many items shows in their history as one change.

• A button can also ask for a few values first, in a small form, such as Restock's quantity on a product; the assistant adds such a form when you ask it for the button. On a button for one item, a field of the form can have the setting Ask when, a condition on the item, such as started_on is null: the form then asks for the field only when the condition is true for the item, and a value sent for it at other times is ignored.
• A button that sends an email always asks first, because you cannot stop a mail after you send it: if you leave Ask first empty, it asks "Email invoice? This sends a mail. You cannot stop the mail after you send it.", with the button's own title.
• While the base takes no mail, its first mail to a customer also asks to let customers answer (Let customers answer your first mail).

The example shop's buttons

The example shop's buttons are all steps:

• On an invoice, Issue, Mark paid and Cancel. On an order, Make the invoice, which makes a draft invoice with the order's lines and today's date and opens it, Order again, Send invoice and Cancel order.
• On a product, Restock, which records the stock movement and raises the stock; on the products list, Raise prices, which raises the price of every active product by the percent you type, and Restock the lowest.

A button's Open a form step opens a new item's form filled in from the item you are on, and saves nothing until you do. The example shop's Order again opens a new order's form filled in from the order you are on, its lines included. Its customer is locked: shown, not editable, with "Set by Order again" under it. Nothing is saved until you click Save, and leaving the form stores nothing.

• Under After saving, an open step goes to the new item, or comes back to the item the button was on.
• Duplicate opens the same kind of form with nothing locked (Open an item’s page: comments, history, Follow and Duplicate).

The base's code is JavaScript kept in the base itself, with its versions like the rest, which the base runs where fields, rules and steps cannot say what your base should do, such as a call to another company's system, a PDF made on the server or a total worked out over several lists. The assistant writes it when you ask (Add buttons and behaviour with the assistant), and the base's builders read it, change it and try it where it sits. Reading and changing the code, its run log and its test runs are for the base's builders.

Code sits in four places:

• a button's Run code step, on its table's Custom actions page (Make a button that does several steps, with no code): it runs with the button's other steps, as the person who clicks;
• an automation's Run code action, on the automation's page (Run actions when an item changes): it runs as the base, after a change, on a schedule, or when a webhook or a mail comes in;
• a field Computed by code, in the field's box on the Fields page (Work a value out with a computed field (a formula)): its value is worked out each time the item is read;
• the table's Form code, on its General page, which fills in a form's values while it is filled (Give new items default values).

1. In Builder, open the table, then the place. To add code, pick Run code as a button's step or an automation's action, or switch on a field's Computed by code or the table's Form code. To remove it, delete the step or the action, or switch it off.
2. Write or change the code in its box. Tab puts in a tab, as in any code editor; Shift+Tab leaves the box.
3. Under the box, pick the item to try it on, where the code runs on one, such as On the order, and click Test run. Input (JSON) holds what the code is given besides the item, such as the answers of a button's form. The code runs on that item as the box holds it now, saved or not, and nothing is saved and nothing is sent. You see what it gives back, a file as a link to download it, the lines it wrote to its log, and the mails and the calls to other services it would have sent; or, when it fails, why, with the line and column.
4. Save as you save the rest: a button's, a field's or the Form code's change with Save table, an automation on its page. Code with a mistake, such as a misspelt name, or an empty box ("Write the code") is refused, with what is wrong under its box, such as "Line 3, column 7: …", and nothing changes. A change of code alone applies at once.

See the runs that failed in the run log

Below each code box, its Run log lists the runs of that code that failed, reached a limit or wrote lines to its log, newest first: when, the line and column, and why, such as "The run used its step budget". Open one to see the lines it wrote to its log; the refresh icon fetches the latest. The assistant reads the same log when you tell it that something did not work.

Dates and times in code

Code reads dates and times as the base shows them, in the base's Time zone in Settings, General: today's date, and an item's date and time, such as when an order was placed. So a mail that a button or an automation sends names the same day and hour the order's page shows, near midnight too. The base's checks, defaults and formulas also take today in the base's time zone. So a date that the form gives as today is today for a check too, and the base does not refuse it as a date in the future.

Limits and details

• Code reaches nothing the base's builders cannot already reach: a button's code works under the rules of the person who clicks, an automation's as the base.
• Code calls only the hosts in the base's Allowed hosts, and Stripe's, api.stripe.com, while the base holds Stripe, and PayPal's, api-m.paypal.com and api-m.sandbox.paypal.com, while it holds PayPal (Add Stripe to your base).
• Code names a secret and never holds its value, and a call that puts a secret where it may not go, such as a key in a body, is refused before anything is sent (Store the keys of other services).
• Each run is limited in the work, the changes, the mails and the calls it makes.