AI Builder & Large Uploads

The AI Builder

The onboarding wizard designs and provisions an application from a description. The AI Builder is what keeps that loop open afterwards.

Where to find it

Architect Panel → Data:

• AI Builder — describe a change, review what it proposes, apply it
• Sample Data — generate realistic test data for what you just built

Architect Panel → Configuration:

• Blueprint Packs — reusable starting points for common application shapes

The problem it solves

Once version one exists, the AI that built it traditionally stops being available, and every subsequent change means learning the platform's field architect. "Add a Suppliers table", "make Phone required", "we don't use Fax any more" are all things you should be able to simply say.

How to ask

Describe the outcome, not the mechanism.

• Good: "Track which supplier each part comes from." That gives it enough to design the relationship properly.
• Less good: "Add a foreign key to the parts table." That presumes an implementation which may not be the right one here.

Include the why where it is not obvious. "We need to record a second address because tenants often have a correspondence address" produces a better design than "add address2".

Review before applying

Changes are proposed for you to look at rather than applied silently. Read them, particularly anything touching data that already exists:

• Adding a field is safe.
• Making a field required interacts with every existing row that has it empty.
• Changing a type can lose data that does not convert.
• Removing a field is not reversible from here.

It works within the platform

What it produces is ordinary platform configuration — datastores, fields, forms, permissions. There is no separate AI-built layer to maintain, nothing is generated into a file you cannot edit, and anything it creates can be changed by hand afterwards exactly as if you had built it yourself.

Test with sample data

After a structural change, Sample Data generates realistic rows so you can see the forms and views behave before real data arrives. This is far more useful than it sounds — an empty datastore hides layout and validation problems that are obvious with fifty rows in it.

Blueprint packs

Blueprint Packs are reusable starting points for common application shapes. Where what you are building resembles something already modelled, starting from a pack and adjusting is faster and usually better-structured than describing it from nothing.

Worked example

A team running a supplier register asks: "we need to record which contract each supplier is on, and contracts have a start and end date". The builder proposes a Contracts datastore with date fields and a link from Supplier, plus the browse view and form to go with it. The team reviews the proposal, notices it made the end date required, changes that to optional because open-ended contracts exist, and applies it.

Where to be careful

Structural changes to a live system deserve the same care as any other change. Try them on a development instance where you have one, and avoid sweeping changes in the middle of a working day — a required field added at 11am is a required field every user meets immediately.

Recommendations

• One change at a time, reviewed and applied, rather than a paragraph of six.
• Say why, not how.
• Read the proposal for anything touching existing rows.
• Generate sample data and look at the forms before declaring it done.

Uploading Spreadsheets and Large Files

Describing a data model in prose is hard work when you already have it in a spreadsheet. Upload the file instead.

Where to find it

Architect Panel → Data:

• AI Builder — upload a file alongside your description
• Large Uploads — the chunked upload records and their state
• File Stores — where uploaded files are kept

Working from a spreadsheet

Upload the workbook and the builder reads its structure — the columns, the types, the values that actually appear — and proposes datastores and fields to match.

That is usually far closer to what you want than a description, because the spreadsheet already encodes decisions you would otherwise have to remember to mention: which fields are dates, which are numbers, which have a fixed set of values, which are optional in practice.

Tidy the sheet first — this matters most

The structure it infers is the structure you gave it, so preparation pays for itself:

• One header row, at the very top. Not a title, then a blank row, then headers.
• One table per sheet. Two tables side by side become one confused datastore.
• No merged cells. They destroy the column structure.
• No notes rows above the headers or between sections.
• Consistent types down a column. A date column with "TBC" in three rows will be read as text.
• Remove totals rows. A row saying "TOTAL 4,182" is not a record.

A spreadsheet organised for a human reader gives a noticeably worse result than a plain rectangle of data.

Large files

Uploads are chunked, so a file can be roughly a gigabyte rather than the tens of megabytes a single web request allows. The browser splits the file, the pieces are uploaded independently and reassembled on the server, and — because assembling a large file is not something a web request should do — the final step runs as a background job.

The tasks involved

• Background Jobs — dispatches and reaps queued work, including file assembly. Every minute.
• Document Text Extraction — indexes contents so uploaded documents are searchable. Every fifteen minutes.

Both ship disabled under Automation → Tasks. A large upload that reaches 100% and then appears to stall is almost always the Background Jobs task not running — the pieces are all there and nothing is assembling them.

What not to upload

The file contents reach the AI provider. Do not upload live personal data to design a schema.

A sample with realistic structure and invented values gives exactly the same design result without the disclosure — the builder is reading shapes, not people. Twenty made-up rows work as well as twenty thousand real ones.

Worked example

A team has tracked equipment in a spreadsheet for years: asset tag, description, location, purchase date, cost, custodian, and a Notes column. They copy the sheet, replace the names and tags with invented ones, delete the totals row at the bottom, and upload it. The builder proposes an Assets datastore with a date field, a currency field and a link to People for the custodian — which is the model they would have described, arrived at in one step.

Recommendations

• Send a sanitised sample, never live data.
• Fix the sheet before uploading, not the datastore afterwards.
• Enable Background Jobs first if you are uploading anything large.
• Check the inferred types before applying — dates and numbers read as text are the common miss.

The AI Builder for App Administrators

On an installation that charges for AI, the AI Builder can be opened to each tenant's own administrators as well as to architects. They describe a change in plain English and apply it to their own app, within a narrower set of changes than an architect has, and every plan is charged to their tenant's AI credit.

Where to find it

Admin Panel → AI:

• AI Builder — the tenant administrator's way in
• AI Credit — the credit each plan draws on

Architect Panel → Configuration:

• AI Settings — AI Builder for tenant administrators and Charge AI to tenants, in AI credit and billing

Architect Panel → Data:

• AI Builder — the architects' way in, with every kind of change available

When a tenant administrator can use it

All of these must be true. If one is not, the screen says which:

• AI Builder for tenant administrators is on. Otherwise: "The AI Builder isn't available to app administrators on this installation."
• AI billing is on, because otherwise nothing would meter what the builder spends. Otherwise: "The AI Builder is only open to app administrators where AI use is metered, and it isn't on this installation."
• They are inside their own app on a multi-tenant installation. Otherwise: "The AI Builder can only be opened inside your own app."
• They are an administrator of that tenant. Otherwise: "Only this app's administrators can use the AI Builder."
• The tenant's plan is live and includes the AI Builder. Otherwise: "Your plan doesn't include the AI Builder.", or the sentence about the subscription not being active.

The Admin Panel tile is granted automatically to self-serve tenants' administrator groups; other groups need it granted.

What a tenant administrator can change

• Can: add datastores and fields, rename things, adjust pick-lists, add roles and sign-in methods, and attach a spreadsheet to design from or import.
• Cannot: change layouts, rules, permissions, views, calculated fields, casework or workflows; add record numbering, record buttons or site pages; or write into the platform's user guide. A change set planned by an architect in the same tenant is cut down to this set if a tenant administrator applies it.
• Guarded: an administrator role cannot be removed through the builder, a new role can be no more than an ordinary administrator role, and a new sign-in method is added switched off.

Using it

1. Open AI Builder from the Admin Panel. Under the heading, a line shows the AI credit left this period and when it resets, with a link to AI Credit.
2. Describe the change and press Plan this change. The plan is an AI call charged to the tenant.
3. Read the proposal, then press Apply or Cancel.

When the tenant's credit is used up, a yellow panel shows the reason and Plan this change is disabled; the credit is checked before anything is sent, so no request is wasted. Architects' plans are recorded but never charged or refused.

Which model it uses

The builder runs on the aibuilder role, which inherits builder unless you set it on AI Settings. If no provider is configured the screen says so and names the provider the role is set to use.

What goes wrong, and how to tell

• A tenant administrator sees no AI Builder tile: the tile is not granted to their group.
• Plan this change is greyed out: the tenant's AI credit is used up; the yellow panel says when it resets.
• A change applied without some of its parts: those parts are outside what a tenant administrator may change. An architect can apply them.

Worked example

A self-serve customer's office manager, an administrator of their tenant, opens AI Builder from the Admin Panel and asks for a Suppliers datastore with a contact e-mail and a payment-terms pick-list. The plan shows the new datastore and fields; they apply it. The credit line drops slightly, and the plan appears on AI Credit under AI Builder.

Recommendations

• Switch tenant access on only with billing on; the platform enforces this anyway.
• Tell tenant administrators what they cannot change, so a trimmed change set is not a surprise.
• Point the aibuilder role at a capable model: a poor plan wastes the tenant's credit.
• Check AI Credit by feature to see how much the builder is used.