Data-source component schema

Team Forms data sources are configured outside the form. A form component stores the ID of an existing source; it does not contain SharePoint, Excel, or authentication configuration.

When using the AI assistant, it must obtain IDs from list_data_sources. For a row-based selector it must also call get_data_source_samples and use field names from the returned item. Never copy an ID or field name from an example.

Component mapping

Data-source type	Form component	Notes
`sharepoint-list`	`spSelect`	Select one or more cached list rows.
`sharepoint-file`	`spSelect`	Select cached data extracted from a supported file.
`excel-online`	`spSelect`	Select cached workbook rows.
`form-submissions`	`spSelect`	Select cached submissions from another form.
`team-members`	`spSelect`	Select cached team-member rows.
`sharepoint-file-preview`	`sharepointFilePreview`	Display an online SharePoint file preview; this is not a row selector.

SharePoint data selector (`spSelect`)

An spSelect stores the selected row object. With multiple: true, it stores an array of row objects. Do not set valueProperty: Team Forms needs the object so other fields can read values such as data.site.SiteCode.

{
  "type": "spSelect",
  "key": "site",
  "label": "Site",
  "dataSourceId": "tool-returned-data-source-id",
  "template": "<span>{{ item.SiteName }}</span>",
  "labelProperty": {
    "label": "🛠 Custom",
    "value": "custom"
  },
  "selectFields": ["SiteName", "SiteCode"],
  "sampleItem": {
    "SiteName": "Perth Office",
    "SiteCode": "PER"
  },
  "removeDuplicates": true,
  "sortBy": "SiteName",
  "sortDirection": "asc"
}

Property	Type	Behaviour
`dataSourceId`	string	Exact ID of an existing row-based Team Forms data source.
`template`	HTML string	Renders each option with Form.io interpolation. Read fields from `item`, for example `<span>{{ item.Name }}</span>`.
`labelProperty`	object	When supplying a custom `template` directly, set this to `{ "label": "🛠 Custom", "value": "custom" }` so the builder exposes and preserves the custom template. Builder-selected fields instead use their field label and an `item.Field` value.
`multiple`	boolean	Stores an array of row objects instead of one row object.
`selectFields`	string array	Projects each source row to these property paths before it is stored and before duplicates are removed.
`sampleItem`	object	One representative projected row used to infer available fields for email suggestions, connector schemas, and executable-code types. It is metadata, not a default or submitted value.
`removeDuplicates`	boolean	Removes rows whose projected objects are exactly equal.
`sortBy`	string	Source property path used for sorting.
`sortDirection`	`"asc" \| "desc"`	Sort direction; defaults to `"asc"`.
`filterQuery`	JavaScript string	Filters rows by assigning a boolean to `show`; the current source row is `item` and current form answers are `data`.

Fields and duplicate removal

Duplicate removal happens after selectFields is applied and compares the entire projected object. This means two rows displaying the same label are not duplicates if other retained fields differ.

To show unique site names, use:

{
  "template": "<span>{{ item.SiteName }}</span>",
  "labelProperty": {
    "label": "🛠 Custom",
    "value": "custom"
  },
  "selectFields": ["SiteName"],
  "removeDuplicates": true
}

Only SiteName is then stored in the selected value. If later calculations also need SiteCode, include it in selectFields; uniqueness will then be based on the SiteName and SiteCode combination.

Sample item

sampleItem is important even though it does not control the options shown at runtime. Team Forms reads its shape to offer accurate form fields in the email-template editor, describe the selected object to executable-code tooling, and expose its properties in generated connector schemas.

When using the AI assistant:

Call get_data_source_samples after selecting the source.
Use its preview.sampleItem object. This already contains the live sample when previewUsesLiveData is true.
Apply the same selectFields projection while preserving nested object paths.
Store the result as the component’s sampleItem.

sampleItem is always one object, including when multiple: true. Do not wrap it in an array. Do not invent field names or store a non-object omission message when the tool returns no usable sample. Large values may be truncated by the tool; retained property names and value shapes must still come from its result. Avoid retaining irrelevant large or embedded fields by limiting selectFields to what the form actually needs.

Filtering

filterQuery is executable JavaScript, not Handlebars and not a wrapping function. Assign the result to show:

show = item.Region === data.region

Use exact property names from get_data_source_samples. For more involved executable changes, the AI assistant should load the component’s JavaScript development context before adding the code.

SharePoint file preview (`sharepointFilePreview`)

This layout component displays an existing sharepoint-file-preview source in an iframe. It requires online SharePoint access and is omitted from generated PDFs.

{
  "type": "sharepointFilePreview",
  "key": "policyPreview",
  "label": "Policy document",
  "input": false,
  "dataSourceId": "tool-returned-file-preview-source-id",
  "height": 600,
  "pdfVisibility": "hidden"
}

height is measured in pixels and must be at least 200. The dataSourceId must refer to a source whose type is exactly sharepoint-file-preview; row-based sources cannot be used.