`update_subform_interface`

Admin-only MCP tool.

Update an existing Subform Interface in a Formulize form.

Overview:

Subform Interfaces are used to provide an interface in one form, that shows the entries in another form. They are designed to work with forms that are connected in a one to many relationship, such as Each Province has many Cities, or Each Budget has many Budget Line Items, etc.

Important notes:

Subform Interfaces do not store user data. They are a collection of settings that control how the entries in the ‘many’ form are to be displayed and managed, when viewed from the ‘one’ form.
Subform Interfaces are very powerful tools for supporting complex data management scenarios. They allow users to manage entire sets of data through one screen, instead of having to manage each individual entry separately.

Properties common to all Subform Interfaces:

sourceForm (int, the form ID of the form to be displayed in this Subform Interface. If the source form is not already connected to this form, a new Linked Dropdown List will be created in the source form, and it will be linked to the Principal Identifer in this form. For example, if a Cities form is embedded in a Provinces form, and there is no existing connection between them, then a Linked Dropdown List will be added to the Cities form that links to the Province form’s principal identifier.)
sortingElement (int, the element ID of an element in the source form to sort the entries by. If not specified, entries will be shown in creation order.)
sortingDirection (string, either ‘ASC’ or ‘DESC’, indicating if the entries should be sorted in ascending or descending order. Default is ‘ASC’.)
showAddButton (int, either 1 or 0, indicating if an Add Entry button should be shown to users, if they have permission to add entries in the source form. Default is 1. Set to 0 if this Subform Interface should never include an Add Entry button.)
showDeleteButton (int, either 1 or 0, indicating if a Delete Entry button should be shown to users, if they have permission to delete entries in the source form. Default is 1. Set to 0 if this Subform Interface should never include a Delete Entry button.)

Subform Interface Type: Editable Row (subformEditableRow).

Description: This kind of Subform Interface allows users to view and edit the connected entries. Each connected entry shows up as a row of form elements, which can be edited in place. This is best for situations when only a few elements in the source form need to be edited at once (generally less than 5) and where users need to be able to edit multiple entries quickly, without necessarily having to open up each entry in a separate full form or modal popup.

Properties:

all the common properties for Subform Interfaces, plus:
elementsInRow (Required. An array of element ids, indicating which elements from the source form should be shown in each row.)
disabledElementsInRow (Optional. An array of element ids, indicating which elements in the row should be disabled (not editable). Default is an empty array, meaning all elements in the row are editable.)
entryViewingMode (Optional. A string, either ‘off’, ‘form_screen’ or ‘modal’. Default is ‘off’, which means there are no clickable icons for opening up each source form entry for viewing/editing. If ‘full_screen’ then there are clickable icons, and they will cause the page to reload with the correct Form Screen for showing the source form entry. If ‘modal’ then there are clickable icons, and they will open a modal popup box for showing the source form entry. For small forms, ‘modal’ is usually best. For large forms, ‘full_screen’ is usually best. If a user should not be able to view/edit the source form entries, or does not need to, then set this to ‘off’.

Examples:

An ‘Editable Row’ Subform Interface that shows elements 52, 66 and 71 from connected entries in form 7. Sort the entries by the value of element 52. Do not show a Delete button. Open entries in a modal popup for viewing/editing: { sourceForm: 7, elementsInRow: [52, 66, 71], sortingElement: 52, showDeleteButton: 0, entryViewingMode: ‘modal’ }
An ‘Editable Row’ Subform Interface that shows elements 52, 66 and 71 from connected entries in form 3. Open entries in the full form for viewing/editing. Disable elements 12 and 13 in the row: { sourceForm: 3, elementsInRow: [12, 13, 14, 15, 16, 17], disabledElementsInRow: [12, 13], entryViewingMode: ‘form_screen’ }

Subform Interface Type: Full Form (subformFullForm).

Description: This Subform Interface embeds a full version of the connected form, inside this form (ie: inside the form that the Subform Interface belongs to). The connected entries are shown as full forms, one after the other, inside the interface. They can be organized into collapsable accordions (generally the preferred option), or simply embedded right into the page (generally best for small forms, so as not to overwhelm the user). ‘Full Form’ Subform Interfaces are good for situations where users need to be able to edit the entire connected entry quickly, without necessarily having to open up each entry in a separate interface via a clickable icon.

Properties:

all the common properties for Subform Interfaces, plus:
elementsInHeading (Required. An array of element ids, indicating which elements from the source form should be shown as the headings that introduce each connected entry.)
fullFormMode (Optional. A string, either ‘collapsable’ or ‘not_collapsable’. Default is ‘collapsable’. If ‘collapsable’, then the connected entries will be shown in collapsable accordions, labelled with the values of the element specified in the elementsInHeading property. If ‘not_collapsable’, then the connected entries will be embedded in the page one after the other, with the elements specified in the elementsInHeading property used as headers above each form.)

Examples:

A ‘Full Form’ Subform Interface that shows connected entries in form 198. Show the values of elements 201 and 202 as the heading for each connected entry. Do not show the Add Entry button: { sourceForm: 198, elementsInHeading: [201, 202],showAddButton: 0 }
A ‘Full Form’ Subform Interface that shows connected entries in form 31. Show the value of element 69 as the heading for each connected entry. Sort the connected entries by the value of element 69. Show the connected entries as embedded forms one after the other, not in collapsable accordions: { sourceForm: 31, elementsInHeading: [69], sortingElement: 69, fullFormMode: ‘not_collapsable’ }

Subform Interface Type: Listings (subformListings).

Description: This Subform Interface provides a list view of connected entries. Each entry shows up as a row in a table, with a clickable icon to open up the full entry for viewing or editing. This is best for situations when users simply need to see a listing of entries, and/or when forms have a too many elements for comfortably showing in editable rows (generally more than 5).

Properties:

all the common properties for Subform Interfaces, plus:
elementsInRow (Required. An array of element ids, indicating which elements from the source form should be shown in the list view. The values of these elements will be shown in each row. The values will not be editable, they will be shown as plain text.)
entryViewingMode (Optional. A string, either ‘off’, ‘form_screen’ or ‘modal’. If ‘off’, then there are no clickable icons for opening up each connected entry for viewing/editing. If ‘full_screen’ then there are clickable icons, and they will cause the page to reload with the correct Form Screen for showing the connected entry. If ‘modal’ then there are clickable icons, and they will open a modal popup box for showing the connected entry. Default is ‘full_screen’. For small forms, ‘modal’ is usually best. For large forms, ‘full_screen’ is usually best. If a user should not be able to view/edit the embedded entries, or does not need to, then set this to ‘off’.

Example:

A ‘Listings’ Subform Interface that shows the values of elements 101, 102, 103, and 104, from connected entries in form 97. Sort the entries by the value of element 101. Open entries in a modal popup for viewing/editing: { sourceForm: 97, elementsInRow: [101, 102, 103, 104], sortingElement: 101, entryViewingMode: ‘modal’ }

Properties

Property	Type	Required?	Description
element_identifier	string or integer	Required
caption	string	Optional	Optional. The new label for the Subform Interface as it will now appear to users in forms.
properties	object	Optional	Optional. Updated configuration settings for the Subform Interface. The available properties depend on the element type. See the tool description for examples of what properties are needed for different element types. Use the get_form_details tool to see all the element types for the existing elements.
display	boolean	Optional	Optional. Whether the Subform Interface is displayed in the form or hidden. Default: true.
display_conditions	array of object	Optional	Optional. A given form entry must meet these conditions in order for this element to be displayed; otherwise it is not shown. Each condition includes an element, an operator, a value, and a ‘type’ flag indicating the logical set the condition belongs to: ‘match-all’ or ‘match-one-or-more’. Multiple match-all conditions are joined with a logical AND operator, and multiple match-one-or-more conditions are joined with a logical OR operator. Only include this property when you intend to change the conditions: omit it entirely to leave any existing conditions unchanged; provide the list of conditions to set or replace them; or provide an empty array ([]) to remove all conditions so the element is always displayed. When setting conditions based on linked elements, do not use foreign keys as values, and instead use the readable value which this tool understands automatically. Use the special value “{BLANK}” (without quotes) to match blank values. Examples: [ { “element”: “status”, “operator”: “=”, “value”: “Approved”, “type”: “match-all” } ] [ { “element”: “award_value”, “operator”: “>”, “value”: “500”, “type”: “match-all” }, { “element”: “award_year”, “operator”: “=”, “value”: “2026”, “type”: “match-all” } ] Match size 40 pants OR green pants: [ { “element”: “pant_size”, “operator”: “=”, “value”: “40”, “type”: “match-one-or-more” }, { “element”: “pant_color”, “operator”: “=”, “value”: “green”, “type”: “match-one-or-more” } ] Match incomplete orders that are due before today, and are going to either Canada or Mexico: [ { “element”: “order_state”, “operator”: “=”, “value”: “incomplete”, “type”: “match-all” }, { “element”: “order_due_date”, “operator”: “<”, “value”: “{TODAY}”, “type”: “match-all” }, { “element”: “order_destination”, “operator”: “=”, “value”: “Canada”, “type”: “match-one-or-more” }, { “element”: “order_destination”, “operator”: “=”, “value”: “Mexico”, “type”: “match-one-or-more” } ] Do not use foreign key values with linked elements; use the readable value instead: Incorrect: [ { “element”: “assigned_judge”, “operator”: “LIKE”, “value”: “509”, “type”: “match-all” } ] Correct: [ { “element”: “assigned_judge”, “operator”: “LIKE”, “value”: “Wapner”, “type”: “match-all” } ]
placement	string	Optional	The canonical position of the element in the form. This order is used on every form screen page that this element has been added to (newly created elements are automatically added to all pages that currently have all existing elements; to add an element to a page that has only some existing elements, use the update_form_screen tool). Use “top” to make this element the first element in the form, use “bottom” to make this element the last (which is the default for new elements), or use an element handle to place this element immediately after that element (based on the live state of the form at the time of this specific request; re-fetch get_form_details first if you need to see the current element order). On updates, omit this to leave the current position unchanged.

← Back to the MCP reference

Getting Started

Professional Services

The Formulize development team provides:
hosting, training, tech support, and consulting

Getting Started

Professional Services

Help and Documentation

`update_subform_interface`

Properties

Getting Started

Professional Services

Help and Documentation