Skip to content

Form input logic

In the orchestrator core, form input elements are now class based and subclass the FormPage class in the core.

from orchestrator.forms import FormPage, ReadOnlyField

And the validators module exposes validators that also function as "input type widgets":

from orchestrator.forms.validators import CustomerId, choice_list, Choice

It's worth poking around in that module to see the various input types the core library exposes.

Form examples

Here is a relatively simple input form:

equipment = get_planned_equipment()
choices = [f"{eq['name']}" for eq in equipment]

EquipmentList = choice_list(
    Choice("EquipmentEnum", zip(choices, choices)),

class CreateNodeEnrollmentForm(FormPage):
    class Config:
        title = product_name

    customer_id: CustomerId = ReadOnlyField(CustomerId(ESNET_ORG_UUID))
    select_node_choice: EquipmentList

# Don't call like this CreateNodeEnrollmentForm() or you'll
# get a vague error.
user_input = yield CreateNodeEnrollmentForm

It has a read only ORG ID and exposes a list of devices pulled from ESDB for the user to choose from.

Choice widgets

Of note: min_items and max_items do not refer to the number of elements in the list. This UI construct allows for an arbitrary number of choices to be made - there are + and - options exposed in the UI allowing for multiple choices selected by the user. So min 1 / max 1 tells the UI to display one pull down list of choices one of which must be selected, and additional choices can not be added.

If one defined something like min 1 / max 3 it would display one pulldown box by default and expose a + element in the UI. The user could click on it to arbitrarily add a second or a third pulldown list. min 0 would not display any list by default but the user could use + to add some, etc.

Since multiple choices are allowed, the results are returned as a list even if there is only a single choice element:

eq_name = user_input.select_node_choice[0]

The zip() maneuver takes the list and makes it into a dict with the same keys and values. So the display text doesn't have to be the same as the value returned.

Accept actions

Confirming actions is a common bit of functionality. This bit of code displays some read only NSO payload and lets the user ok the dry run:

from orchestrator.forms import FormPage, ReadOnlyField
from orchestrator.forms.validators import Accept, LongText

def confirm_dry_run_results(dry_run_results: str) -> State:
    class ConfirmDryRun(FormPage):
        nso_dry_run_results: LongText = ReadOnlyField(dry_run_results)
        confirm_dry_run_results: Accept

    user_input = yield ConfirmDryRun

    return user_input

Generic python types

It is possible to mix generic python types in the with the defined validation fields:

class CreateLightPathForm(FormPage):
    class Config:
        title = product_name

    customer_id: CustomerId
    contact_persons: ContactPersonList = []  # type: ignore
    ticket_id: JiraTicketId = ""  # type: ignore
    service_ports: ListOfTwo[ServicePort]  # type: ignore
    service_speed: bandwidth("service_ports")  # type: ignore # noqa: F821
    speed_policer: bool = False
    remote_port_shutdown: bool = True

Multi step form input

Similar to the original "list based" form Input elements, to do a multistep form flow yield multiple times and then combine the results at the end:

def initial_input_form_generator(product: UUIDstr, product_name: str) -> FormGenerator:
    class CreateNodeForm(FormPage):
        class Config:
            title = product_name

        customer_id: CustomerId = ReadOnlyField(CustomerId(SURFNET_NETWORK_UUID))
        location_code: LocationCode
        ticket_id: JiraTicketId = ""  # type:ignore

    user_input = yield CreateNodeForm

    class NodeIdForm(FormPage):
        class Config:
            title = product_name

        ims_node_id: ims_node_id(
            user_input.location_code, node_status="PL"
        )  # type:ignore # noqa: F821

    user_input_node = yield NodeIdForm

    return {**user_input.dict(), **user_input_node.dict()}

custom form field

You can create a custom field component in the frontend. The components in orchestrator-gui/src/lib/uniforms-surfnet/src can be used to study reference implementations for a couple of custom form field types.

For it to show up in the form, you have to do 2 things, a pydantic type/class in the backend and add the component to the AutoFieldLoader.tsx.

as an example I will create a custom field with name field and group select field.

pydantic type/class in backend

Create a pydantic type/class.

from uuid import UUID

class ChooseUser(str):
    group_id: UUID  # type:ignore

    def __modify_schema__(cls, field_schema: dict[str, Any]) -> None:
        uniforms: dict[str, Any] = {}

        if cls.group_id:
            uniforms["groupId"] = cls.group_id

        field_schema.update(format="ChooseUser", uniforms=uniforms)

And add it to a form:

def initial_input_form_generator(product: UUIDstr, product_name: str) -> FormGenerator:
    class ChoseUserForm(FormPage):
        class Config:
            title = product_name

        user: ChooseUser

    user_input = yield ChoseUserForm

To prefill the user_id, you need to add the value to the prop, for prefilling the group_id you need to create a new class:

def user_choice(group_id: int | None = None) -> type:
    namespace = {"group_id": group_id}
    return new_class(
        "ChooseUserValue", (ChooseUser,), {}, lambda ns: ns.update(namespace)

def initial_input_form_generator(product: UUIDstr, product_name: str) -> FormGenerator:
    class ChoseUserForm(FormPage):
        class Config:
            title = product_name

        user: user_choice("group_id_1") = "user_id_1"

    user_input = yield ChoseUserForm

auto field loader

The auto field loader is for loading the correct field component in the form. It has switches that check the field type and the field format. You have to add your new form field here.

for this example, we would need to add to a ChooseUser case to the String switch:

import ChooseUserField from "custom/uniforms/ChooseUserField";

export function autoFieldFunction(props: GuaranteedProps<unknown> & Record<string, any>, uniforms: Context<unknown>) {
    const { allowedValues, checkboxes, fieldType, field } = props;
    const { format } = field;

    switch (fieldType) {
        case String:
            switch (format) {
                case "ChooseUser":
                    return ChooseUserField;


custom field example

example custom field to select a user by group.

import { EuiFlexItem, EuiFormRow, EuiText } from "@elastic/eui";
import { FieldProps } from "lib/uniforms-surfnet/src/types";
import React, { useCallback, useContext, useEffect, useState } from "react";
import { WrappedComponentProps, injectIntl } from "react-intl";
import ReactSelect, { SingleValue } from "react-select";
import { getReactSelectTheme } from "stylesheets/emotion/utils";
import { connectField, filterDOMProps } from "uniforms";
import ApplicationContext from "utils/ApplicationContext";
import { Option } from "utils/types";
import { css } from "@emotion/core";

export const ChoosePersonFieldStyling = css` {
        display: flex;
        flex-direction: row;
        flex-wrap: wrap; {
            width: 50%;
        div.user-select {
            width: 50%;
            padding-left: 5px;

interface Group {
    id: string;
    name: string;

interface User {
    id: string;
    name: string;
    age: number;

export type ChooseUserFieldProps = FieldProps<
        groupId?: string;
    } & WrappedComponentProps

const groupToOption = (group: Group): Option => {
    return {
        label: `${, 8)} ${}`,

const userToOption = (user: User): Option => {
    return {
        label: `${} (${user.age})`,

declare module "uniforms" {
    interface FilterDOMProps {
        groupId: never;

function ChoosePerson({
}: ChooseUserFieldProps) {
    const { apiClient, customApiClient, theme } = useContext(ApplicationContext);

    const [groups, setGroups] = useState<Group[]>([]);
    const [selectedGroupId, setGroupId] = useState<number | string | undefined>(groupId);
    const [users, setUsers] = useState<User[]>([]);
    const [loading, setLoading] = useState(true);

    const onChangeGroup = useCallback(
        (option: SingleValue<Option>) => {
            let value = option?.value;
            if (value === undefined) return;


            // do api call to get users by group id and set users with the fetched data.
            setTimeout(() => {
                let users = [{ id: "user_id_1", name: "user 1", age: 25 }, { id: "user_id_2", name: "user 2", age: 30 }]
                if (value == "group_id_2") {
                    users = [{ id: "user_id_3", name: "user 3", age: 35 }]
                } else if (value == "group_id_3") {
                    users = [{ id: "user_id_4", name: "user 4", age: 40 }, { id: "user_id_5", name: "user 5", age: 45 }]
            }, 1000)

    useEffect(() => {

        // do api call to get groups for the first select.

        setTimeout(() => {
                { id: "group_id_1", name: "group 1" },
                { id: "group_id_2", name: "group 2" },
                { id: "group_id_3", name: "group 3" }

            if (groupId) {
                onChangeGroup({ value: groupId } as Option);
        }, 1000)
    }, [onChangeGroup, apiClient, groupId]);

    // use i18n translations.
    const groupsPlaceholder = loading ? "Loading..." : "Select a group";
    const userPlaceholder = loading ? "Loading..." : selectedGroupId ? "Select a user" : "Select a group first";

    const group_options: Option[] = (groups as Group[])
        .sort((x, y) => x.label.localeCompare(y.label));
    const group_value = group_options.find((option) => option.value === selectedGroupId?.toString());

    const user_options: Option<string>[] = users
        .sort((x, y) => x.label.localeCompare(y.label));
    const user_value = user_options.find((option) => option.value === value);

    const customStyles = getReactSelectTheme(theme);

    return (
        <EuiFlexItem css={ChoosePersonFieldStyling}>
            <section {...filterDOMProps(props)}>
                    labelAppend={<EuiText size="m">{description}</EuiText>}
                    error={showInlineError ? errorMessage : false}
                    <section className="group-user">
                        <div className="group-select">
                            <EuiFormRow label="Group" id={`${id}.group`} fullWidth>
                                <ReactSelect<Option, false>
                                    isDisabled={disabled || readOnly || groups.length === 0}
                        <div className="user-select">
                            <EuiFormRow label="User" id={id} fullWidth>
                                <ReactSelect<Option<string>, false>
                                    onChange={(selected) => {
                                    isDisabled={disabled || readOnly || users.length === 0}

export default connectField(injectIntl(ChoosePerson), { kind: "leaf" });