Skip to main content

Form Definition Scanning

Form definition scanning reads an application's form and field configuration and creates form models in Soln. Use it for low-code applications, CRM systems, ERP systems, and other applications that store their definitions in configuration tables or JSON/XML documents.

For example, a shared form_records table may contain customer, order, and contract records. A database structure scan only finds physical columns such as form_id and data. Form definition scanning identifies business fields such as Customer name and Order amount.

Understand The Three Configurations​

ConfigurationWhat it identifiesExample
Database structure scanPhysical tables, columns, keys, and relationshipsFinds forms, form_fields, and form_records
Form definition scanApplication forms and business fieldsIdentifies the account form and its customer_name field
Business data reading rulesWhere records and field values are storedReads customer_name from form_records.data

A completed form definition scan does not by itself make business records queryable. Configure business data reading rules next, then create a dataset. Configure relationships between forms separately through relationship definition scanning.

If the source is already a business table with suitable columns, you can create a dataset directly from that table without scanning form definitions first.

Before You Start​

  1. Create and test a data source, then scan its database structure.
  2. Locate the form and field definitions. They may be in separate tables or in the same document.
  3. Identify the form name, form code, and the value that assigns each field to its form.
  4. Prepare at least one form and its field samples. Include options, custom types, or JSON/XML content when those features are needed.

Names are display labels; codes identify business objects. For example, Customer is a name and account is a form code. Customer name is a field name and customer_name is its code. Avoid using a changeable display name as a stable code.

Create A Scan Rule​

  1. Enter the data source's structure page, open Form definition scanning, and create a rule.
  2. Enter a descriptive rule name, such as CRM forms and fields.
  3. Select the form definition source, choose its reading method, and map form properties.
  4. Fetch the form list and check names, codes, and external form IDs.
  5. Select a form. Configure its field definition source, owner matching, and field properties.
  6. Fetch fields and confirm that only fields belonging to that form appear. Switch to another form and check again.
  7. Configure options, unique fields, display-name fields, and type mappings where needed.
  8. Click Save and start scanning, wait for the background scan, and inspect the generated form models on the structure page.

Saving requires both form and field rules. Clicking save with a missing rule name or required reading setting produces a global prompt. Previews help verify the configuration; saving and running the scan generates or updates the definitions.

Configure The Form Definition Source​

Choose A Reading Method​

MethodDefinition storageMain settings
ColumnsOne form per row, with properties in separate columnsSelect the columns for name, code, and other properties
JSONObjects or lists in a JSON columnSelect the definition column and form list, then each item's properties
XMLXML nodes or attributesSelect the definition column and form nodes, then text or attributes

This reading method describes how definitions are stored, independently of a business field's standard type. A form read from database columns can still contain JSON fields.

Map Form Properties​

PropertyRequiredWhat to read
NameYesThe form's display name, such as Customer
CodeYesA stable form code or API name, such as account
External form IDWhen needed for matchingThe ID assigned by the source, such as f_customer
DescriptionNoA description of the form

Read the external form ID when field definitions, relationships, or business records use it to identify their form. This source ID is distinct from Soln's generated model ID and from the ID of an individual business record.

For JSON/XML, the list location selects individual form definitions. Property paths are relative to each selected definition. Prefer paths offered by the sample picker to avoid repeating the full document path inside a property mapping.

Configure The Field Definition Source​

Match Each Field To Its Form First​

Use the matching method that corresponds to the source value:

Value in the field definitionMatching methodPrerequisite
form_id = f_customerExternal form IDThe form rule reads f_customer
form_code = accountForm codeThe form rule reads account
Owner information inside JSON/XMLRead the owner from the documentSelect the form list, identity path, and whether it contains an ID or code

For example, form_fields.form_id should match forms.id, not form_records.id. If two forms both have a name field, distinguish the owning forms before reading their fields; the field code alone does not identify its owner.

Map Field Properties​

PropertyRequiredPurpose
Field nameYesA display label such as Customer name
Field codeYesA field identifier such as customer_name
External field IDWhen neededUsed when options or relationships match by field ID
Source field typeNo; recommendedConverts the application's field type to a Soln standard type
Required flagNoReads required-field metadata from the source
DescriptionNoA description of the field

Configure unique and display-name fields separately:

  • Flag matching: the field definition contains a flag, such as is_unique = true or is_display_name = true. Choose its location and matching value.
  • Field reference matching: a configuration location contains the target field's code or ID, such as title_field = customer_name on the form. Read the reference and select field-code or external-field-ID matching.
  • Leave these settings unconfigured when the source provides no corresponding information; configure them later as needed.

A unique-field setting describes the source's declared identity field. A display-name setting selects the label used for records or reference values. Scanning does not check all business records for duplicates or create unique constraints in the source database.

Read Field Options​

A single-choice field may store values such as important and normal. Read their labels, such as Important customer and Regular customer, to display them instead of only the raw values.

Option storageConfiguration
JSON/XML column on the field rowSelect the option column, list, and each item's label and value
Inside a field definition documentSelect the current field's option list, then each item's label and value
Separate option tableSelect the table, matching column, label column, and value column

Separate tables can match by field code, external field ID, or a matching value stored in the definition. Field-ID matching requires the field rule to read that ID. Matching by a value stored in the definition requires configuring that value's location.

When forms reuse field codes or dictionary identifiers, also configure the option table's owner-form column and ID/code matching to keep options from different forms separate.

Configure Source Field Type Mappings​

Open Form field type mappings from the form definition scan editor.

  • Source field type is an autocomplete input. Choose a common value or enter the exact type name returned by the application.
  • Standard types include string, integer, decimal, number, boolean, date, datetime, time, JSON, XML, array, UUID, and binary.
  • All form definition scans for the same data source share these mappings.
  • Custom mappings take precedence. Built-in rules handle types without a custom mapping; clearing a custom mapping restores the default behavior.
  • Run the form definition scan again after changing mappings to update discovered field types.

For example, the built-in mapping treats object as JSON. If the source uses single_line_text for text, add single_line_text → string. For a custom monetary type, add money_amount → decimal.

Check the source meaning and values rather than relying on a type name alone. For example, timestamp can have different meanings across databases. These mappings affect form field metadata; they do not change physical column types or source data.

Complete Example: Customers And Orders In A Shared Record Table​

This simplified CRM example illustrates the configuration. Your source does not need to use the same table names or codes.

1. Understand The Source​

Form definitions are stored in public.forms:

idapi_namename
f_customeraccountCustomer
f_ordersales_orderOrder

Field definitions are stored in public.form_fields:

idform_idapi_namenametypeis_uniqueis_display_name
fld_1f_customercustomer_codeCustomer codetexttruefalse
fld_2f_customercustomer_nameCustomer nametextfalsetrue
fld_3f_customercustomer_levelCustomer leveltextfalsefalse
fld_4f_customeraddressCustomer addressobjectfalsefalse
fld_5f_orderorder_noOrder numbertexttruetrue
fld_6f_orderamountOrder amountdecimalfalsefalse

An additional options column on form_fields contains the following value for customer_level:

[
{ "label": "Important customer", "value": "important" },
{ "label": "Regular customer", "value": "normal" }
]

Business records are stored in public.form_records:

idform_iddata
r_customer_1f_customerA JSON object containing customer field values
r_order_1f_orderA JSON object containing order field values

One customer's data value is:

{
"customer_code": "C001",
"customer_name": "Huayuan Technology",
"customer_level": "important",
"address": { "province": "Beijing", "city": "Beijing", "street": "18 Zhongguancun South Street" }
}

2. Configure Form Definitions​

Create a rule named CRM forms and fields:

SettingValue
Form definition sourcepublic.forms
Reading methodColumns
Namename
Codeapi_name
External form IDid

Fetch forms. Expect Customer / account and Order / sales_order, with external IDs f_customer and f_order.

3. Configure Field Definitions​

SettingValue
Field definition sourcepublic.form_fields
Reading methodColumns
Owner matchingExternal form ID
Owner identity locationDatabase column form_id
Field namename
Field codeapi_name
External field IDid
Source field typetype
Unique fieldFlag matching; location is_unique; matching value true
Display-name fieldFlag matching; location is_display_name; matching value true

For options, choose a JSON document in the options column. Select the whole array at $[*], label at $.label, and value at $.value. Reading options does not turn fields without options into single-choice fields.

Select Customer and fetch fields: expect only its first four fields. Switch to Order: expect only order_no and amount. If both forms show every field, check the form_id owner matching first.

4. Check Types And Scan Results​

The built-in mappings recognize text as string, decimal as decimal, and object as JSON. Click Save and start scanning, then check:

  • Customer has four fields; Order has two.
  • Customer code is marked as unique; Customer name is the display-name field.
  • Customer level has important → Important customer and normal → Regular customer options.
  • Customer address has the JSON standard type.

5. Configure Business Record Reading Next​

In business data reading rules, select public.form_records as the record source. Set form_id as the column storing the form identity and match by external form ID. Read field values from the corresponding codes inside data.

Customer then reads records where form_id = f_customer and values such as data.customer_name. Order reads records where form_id = f_order. The preview should show Huayuan Technology and the customer-level label Important customer.

Identify JSON subfields as described below if you need province and city separately in charts. Business record reading is a separate configuration step: do not use the form_fields definition table as the business record source.

JSON Example: Forms And Fields In One Document​

Suppose public.app_definitions.payload contains:

{
"forms": [
{
"id": "f_customer",
"code": "account",
"name": "Customer",
"fields": [
{ "id": "fld_1", "code": "customer_name", "name": "Customer name", "type": "text" },
{ "id": "fld_2", "code": "address", "name": "Customer address", "type": "object" }
]
}
]
}

Select public.app_definitions for both definition sources and JSON for both reading methods. Choose these locations from the sample:

AreaSettingPath or value
FormsDefinition columnpayload
FormsForm list$.forms[*]
FormsName / code / external form ID$.name / $.code / $.id
FieldsOwner matchingExternal form ID
FieldsOwner identity sourceJSON document
FieldsDefinition columnpayload
FieldsForm list$.forms[*]
FieldsOwner identity path$.id
FieldsField list$.fields[*], relative to each form definition
FieldsField name / code / external field ID / type$.name / $.code / $.id / $.type, relative to each field definition

Here, $.fields[*] reads the current form object's fields. Do not repeat the form list by using $.forms[*].fields[*] at this level.

For XML, follow the same order: select form nodes, their field nodes, then node text or attributes. Use paths generated from the XML sample; JSON $.xxx paths do not apply to XML.

Identify JSON/XML Subfields​

Identify subfields when a business value is a JSON/XML object and you need its internal values in datasets, charts, or API metadata. For example, expose province, city, and street beneath Customer address.

  1. Ensure the parent field is recognized as JSON or XML and its business-record reading is configured.
  2. Open Identify subfields for the field in the form definition scan editor's field list.
  3. Read business-record samples or paste a representative JSON/XML value.
  4. Review scalar paths, field names, and types. Select the fields to keep and adjust their order as needed.
  5. Apply the result to the scan rule, then save and run the scan.
  6. Refresh and save affected datasets so the subfields become available in chart configuration and API metadata.

Discovery reads up to 20 samples. Check additional samples for paths absent from those values. Arrays and repeated XML nodes are excluded. XML subfield querying is unavailable for MySQL and MariaDB.

Reading field definitions from JSON does not mean every field needs subfield discovery. Configure it when the business value itself is JSON/XML and its internal properties are needed.

Use AI To Help Analyze The Source​

Open a specific data source's structure page and ask the existing assistant:

Analyze the current data source. Identify the form and field definition sources and verify how fields match their owning forms. Propose mappings for names, codes, external IDs, types, and options, and report the sample validation results. Analyze only; do not save yet.

The current page provides data-source and selected-table context. The assistant can read metadata, inspect bounded samples, and test candidate relationships. Review its source tables, matching columns, and paths before applying the proposal. Similar names or a few matching samples do not prove that a relationship holds for every record.

Maintain Rules And Troubleshoot​

Each rule can have its own schedule. Rerun definition scans when source definitions change. If physical tables or columns changed too, refresh the database structure first. After scanning, check affected reading rules and datasets.

Deleting a form definition scan rule retains generated forms and fields while releasing them from that rule.

SymptomCheck first
No forms returnedSource rows, name/code columns, valid JSON/XML, and the form list location
Forms appear but fields do notWhether the owner value is an ID or code, and whether the form rule reads it
Fields from different forms are mixedThe owner column or document identity path
A field has an unknown typeThe type location and actual source value; add a mapping if needed, then rescan
Options are missing or mixed across formsOption list, label/value mappings, and field/form matching
Fields exist but business preview is emptyRecord source, form filtering, and field paths in the business reading rules
Subfield discovery returns no contentParent type, business reading, and empty/invalid samples or array-only values
Saving reports incomplete rulesBoth definition sources, required properties, owner matching, and enabled option/role settings

Continue with relationship definition scanning and business data reading rules.