Loading

Working on Extension Code

This article is for the architect who commissions, reviews and approves extension code. It sets out what extension code can and cannot do today, what the code checker enforces, and what to look for before approving a version, so you can judge a request and a piece of code without writing either.

Where to find it

Architect Panel → Layout & Pages:

  • App Code — where the code is written, checked and dry run

Architect Panel → Automation:

  • Extensions — where it is approved, put live and monitored

What extension code can do

  • Work with what the hook hands it. When drawing a field, that is the field, its current value, whether the form is being viewed or edited, and the current user's display name and groups. It is not given the rest of the record.
  • Read and write platform data, where the hook allows it. The Hooks card on the Extensions screen lists each hook's capabilities. One query returns at most 1,000 records.
  • Write messages to the Error Log, which is the way to leave a trace for later diagnosis.

What it cannot do today

  • Call outside services or websites. There is no way for an extension to make a web request, whatever the Outbound hosts setting says.
  • Send e-mail or handle files.
  • Read stored credentials such as API keys.
  • Run on record save, on a page, as an endpoint or as a scheduled task. Those hooks are listed but the platform does not call them yet. Use a field or a workflow step.

A request that needs any of these is not an extension today. Look at Workflow Builder steps or API Clients instead.

What the code checker enforces

Every saved version is checked before it can be approved. It refuses, among other things:

  • A full file. Extension code is the body only, and code that starts with an opening PHP tag is refused with a message saying so.
  • Functions that are not on the allowed list: "... is not on the list of functions an extension may call".
  • Code that is too large or too deeply nested, over 64 KB or too complex.

Passing the checker means the code uses only permitted building blocks. It does not mean the code is correct, efficient or safe with your data: that is what review is for.

Permissions are the code's responsibility

Data read and written by an extension does not go through the field-level security that applies on screens. If an extension shows or changes data, the code must itself decide who should see or change it, typically from the user's groups it is given. Ask about this in every review.

Reviewing a version before approval

  1. Open the extension in App Code and select the version in the Versions tab. Check the Gate result is a pass.
  2. Ask the developer to walk you through it: what it reads, what it writes, and what happens when a value is empty.
  3. Run Dry run. It writes nothing and sends nothing, and it supplies no record, so it shows the code runs rather than that every case is handled.
  4. Check the binding (Bound to) is the field or workflow step you intended.
  5. Approve and put it live, then watch Recent runs on the Extensions screen.

What goes wrong and how to tell

  • Repeated failures in Recent runs after going live: usually an empty or unexpected value. Roll back and have it handled.
  • "the code checker is not installed on this server, so no extension can be accepted": the hosting administrator must install it before any version can be approved.
  • Assistant-written code that will not pass: the assistant may suggest building blocks that do not exist. Treat its output as a draft.

Worked example

A manager asks for an extension that looks up a supplier's credit rating from an outside service when a purchase request is saved. The architect checks this article: extensions cannot call outside services and the record-save hook is not called yet, so the request is redirected to a workflow with an outbound API call. A second request, to show a warning on the purchase form when the order value exceeds the requester's limit, fits a field extension. The architect reviews the code, confirms it reads only the fields it needs, dry runs it, binds it to the order value field and puts it live.

Recommendations

  • Check a request against the can-and-cannot lists before anyone writes code.
  • Ask how empty values are handled in every review.
  • Insist the code enforces its own permissions where it shows or changes data.
  • Prefer configuration wherever it can do the job.