Forms API

AilaFlow forms combine separate HTML, CSS, and JavaScript fragments. They render process data, collect input, and submit schema-valid values.

The API is available through the global ailaflow object. No import is required.

Form contexts

Forms must work on mobile and desktop. Use accessible controls, readable validation, and responsive layouts.

Event handling

Bind actions with a button’s onclick handler. Do not use onsubmit.

<button type="button" onclick="submitRequest(this)">Submit</button>

Use type="button" to prevent native form submission.

Read process data

readVariable(name)

Returns a readable variable value or null when unset. It fails if the variable does not exist or the form cannot read it.

const request = await ailaflow.readVariable('$request');

Validate user expressions

validateUserAccessExpression(expression)

Returns null for valid syntax or an error message for invalid syntax.

const error = await ailaflow.validateUserAccessExpression(
  '@robert or @{.team = "finance"}'
);

This checks syntax only. It does not verify that users exist or that the expression matches anyone.

Submit a form

submitForm(values, transientParams?)

All required values must be included and must match their JSON Schemas.

try {
  await ailaflow.submitForm({
    request: { title: 'New laptop', amount: 1500 }
  });
} catch (error) {
  showError(error);
}

Behavior depends on context:

• Start form: starts a new process execution.
• Task form: completes the current task.
• Return form: starts another execution of the same process.

Task output variables are arrays. Submit one item per output variable:

await ailaflow.submitForm({
  answer: ['Approved']
});

Open the start form

openStartForm(transientParams?)

From a Return form, opens the process’s original Start form:

try {
  await ailaflow.openStartForm({ draftId: 'draft_1' });
} catch (error) {
  showError(error);
}

Use it when the user should enter start values instead of submitting them directly from the Return form.

Transient parameters

Transient parameters pass short-lived data to the next form jump.

getTransientParams()

Returns the parameters from the previous submitForm or openStartForm call, or null.

const params = await ailaflow.getTransientParams();

Transient parameters are not persisted or forwarded automatically. Pass them again on the next jump if they are still needed. Prefer them for sensitive values that must not be stored.

Temporary user storage

Browser-only user storage persists strings across form jumps and page reloads for the current user.

await ailaflow.writeUserStorage('view', 'compact');
const view = await ailaflow.readUserStorage('view');

Keys must contain 1–32 characters. Do not store sensitive values.

Open external links

openLink(url)

Opens a URL in a new browser tab:

try {
  await ailaflow.openLink('https://example.com');
} catch (error) {
  showError(error);
}

Use this API instead of <a> or window.open(), which are blocked by the form sandbox.

Iframe restrictions

Forms run in an iframe with an opaque origin. Do not use:

• localStorage, sessionStorage, or IndexedDB
• Cookies or Cache Storage
• Service workers
• window.parent or window.top
• Authenticated same-origin fetch or XHR

Use AilaFlow APIs for storage and host interaction.

Error handling

Wrap submitForm, openStartForm, and openLink calls in try/catch. Show a useful error and keep the form available for correction.