Form Events

Custom script form events let you hook into the form lifecycle and react to user actions. All examples below assume you have access to the global tisa object (Form Script API).

onFormInit

type onFormInit = () => Promise<void>;

async function onFormInit() {
    const { form } = tisa;

    // Example: initialize defaults for a new form and wire simple dependencies
    if (form.isNewForm) {
        const { myField1, myField2 } = form.field;

        // set default values
        myField1.value = "AUTO";

        // react to changes (copy value on change)
        myField1.onChange((value) => {
            myField2.value = value;
        });
    }

    // Example: lock the whole form for display forms
    if (form.isDisplayForm) {
        form.readOnly = true;
    }
}
Copy

This event runs before the form UI is rendered (after Form Script API is initialized). Use it for early async prep and wiring logic.

onFormInitComplete

type onFormInitComplete = () => Promise<void>;

async function onFormInitComplete() {
    const { form } = tisa;
    const { myField1, myChoice } = form.field;

    // Example: tweak field properties after controls are rendered
    myField1.readOnly = false;
    myField1.required = true;
    myChoice.hidden = false;

    // Example: subscribe to changes
    myField1.onChange((newValue, { oldValue }) => {
        tisa.log.info(`myField1 changed: ${oldValue} -> ${newValue}`);
    });
}
Copy

This event runs after the form UI is rendered. Use it to adjust field/group visibility, required flags, and to bind change handlers.

onSubmitting

type onSubmitting = () => Promise<boolean>;

async function onSubmitting() {
    const { form } = tisa;
    const { startDate, endDate } = form.field;

    // Example: final validation before submit
    if (startDate.value && endDate.value && endDate.value < startDate.value) {
        tisa.log.error("End date must be after start date.", {
            showToast: true,
        });
        return true; // abort submit
    }

    return false; // continue submit
}
Copy

This event runs after built-in validation but before the item is saved. Return true to abort submission, false to continue. Ideal for last-mile validations or confirmations.

onOutcomeClicked

// nextState is the state internal name selected from the dropdown.
// outcome contains metadata about the selected outcome (may be undefined if not resolved).
type onOutcomeClicked = (
    nextState: string,
    outcome?: {
        title: string;
        titleResource: string;
        stateInternalName: string;
        stateId: number;
        transitionInternalName: string;
        transitionId: string;
        commentRequired: boolean;
        commentMode: 0 | 1 | 2; // Optional | Required | Hidden
        actionText?: string;
    },
) => void;

function onOutcomeClicked(nextState, outcome) {
    // Example: show info toast and toggle behavior based on requirement
    tisa.log.info(`Selected outcome: ${outcome?.title ?? nextState}`, {
        showToast: true,
    });

    if (outcome?.commentRequired) {
        // your logic when a comment is required for this outcome
    }
}
Copy

This event is triggered when the user selects an outcome from the task dropdown. Use it to react to the selection (e.g., UI hints, validations, or enabling related actions).