Iris authoring contracts · Antly Support

Page Builder V4 uses Iris to generate and refine page code. The contract is simple: Iris can produce React code that uses the runtime APIs documented in this section, and the page renderer compiles that code inside Antly's runtime shell.

What generated code can use

Iris-authored runtime code can use the same APIs as hand-written react blocks:

useJql and useJqlMutation for data.
Formik, Yup, Antly inputs, and multipart helpers for forms.
PageBuilderChart, PageBuilderIrisChat, and PageBuilderReport for product widgets.
useSearchParams, useRecordContext, useAuthentication, and page filter helpers for context.

Unsupported package imports are rejected by the runtime compiler. Use the injected globals or the explicitly supported runtime imports listed in /developer/runtime-overview.

Topic context

When configuring Iris topics for page authoring, include the business context the generated page must respect:

text

Build pages for finance operators. Use objects.Invoice as the primary namespace.
Prefer PageBuilderReport for exports and PageBuilderChart for visual summaries.
Do not hard-code tenant-specific IDs unless the user selected them in the builder.
Keep forms small and validate with Yup before calling useJqlMutation.

For runtime chat widgets, pass a smaller promptContext directly to PageBuilderIrisChat:

jsx

<PageBuilderIrisChat
  topic="finance-helper"
  namespace="objects.Invoice"
  promptContext="Answer using invoice records visible to the current user. Do not invent totals."
/>

Welcome copy and suggestion chips prefer the Iris topic form when a tenant topic row exists. To restyle the header / welcome / chips on a page, pass classNames — see /developer/widgets. Do not wrap the widget in editorial card chrome for those slots; the defaults are intentionally plain so page layout can own the look.

Style and media

Generated pages should use the design tokens and components already present in the app shell. Prefer simple layout classes, accessible labels, empty states, and loading states. Images should come from approved tenant media, configured content, or explicit URLs allowed by the deployment. For PageBuilderIrisChat, style the upper chrome with classNames rather than nesting the widget inside branded cards that fight the composer.

Review checklist

Before publishing generated code:

Confirm every JQL query has the correct schema, namespace, intent, and authenticationClass.
Confirm return fields are minimal.
Confirm mutations validate input and do not write hidden fields from the browser without server checks.
Confirm charts and reports handle empty data.
Confirm public pages do not include API keys or private-only namespaces.

For configurator guidance, see /guides/iris-in-page-builder and /guides/page-builder-v4.