create_user_list_element

Required. ID of the form that this will be part of.

Required. The type of User List Element to create.

Required. The label for the User List Element as it will appear to users in forms and in lists.

Required. Additional configuration settings for the User List Element. The available properties depend on the element type. See the tool description for examples of what properties are needed for different element types.

Optional. The heading to use at the top of a column in lists of entries. If not specified, the caption will be used. Some captions are long and descriptive, and a shorter heading would be more appropriate for in a list of data.

Optional. A longer description or help text for the User List Element, shown to users filling out the form. This is NOT an internal notes field, this content appears as part of the element.

Optional. Whether the User List Element is required to have a value when users fill out the form. Default: false

Optional. Whether the User List Element is the principal identifying element for entries in this form. Principal identifiers are used in various places in Formulize to represent an entry. The Principal Identifier would typically be a ‘Name’ text box or other element that unique identifies the entry. Each form can only have one Principal Identifier. If a form has a Principal Identifier, and another element is created or updated with this value set to true, the existing Principal Identifier will be replaced with the new one. Default: false.

Optional. Whether the User List Element element is disabled (visible but not usable) in the form. Default: false.

This is the internal name, used in the database and in API calls. This is optional and does not normally need to be specified, as the system will determine it automatically from the form title and element caption. If the user specifically requests a handle, use this to force the handle to be a certain value. The system may still modify it for uniqueness, so check the tool result to see the actual handle used in by system. Maximum length is 64 characters.

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. Provide a list of conditions to restrict when the element is displayed; if you omit this property (or provide an empty array) it has no conditions and 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” } ]

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.

Optional. The MariaDB data type to be used for the field in the database where this data will be stored. The system will default to text in most cases, but will set smart defaults if the type is specifically a number box or a linked element storing foreign keys, etc. Generally this does not need to be specified, but can be used if the user has specifically stated that a certain data type must be used for a given element. Valid types are: text, int(x), decimal(x,y), date, datetime, time, char(x), varchar(x). For int(x), the x is the number of digits to display in MariaDB when showing the number. For decimal(x,y), the x is the total number of digits, and y is the number of digits after the decimal point. For char(x) and varchar(x), the x is the maximum number of characters to store.