Virtual Dataset

# Virtual Dataset

Virtual Dataset allows you to bind a Dataset Base Control to a field while providing your own custom Data Source. We currently have two Data Providers - Memory and FetchXml. Memory Provider allows you to work with a collection of data that you have stored in memory and FetchXml Provider allows you to do the same thing with data retrieved through FetchXml. Both of these providers support basic Dataset features, which include:

Sorting
Filtering
Paging
Validation
Editing (including linked entities)
Quick Find
Cell Customizers

Attachments Grid Displayed On Form

NOTE: Due to a bug in Power Apps maker, this PCF can only be bind through legacy form editor.

# Data Providers

Static binding allows you to choose between two providers - FetchXml and Memory. After you select a provider, you need to specify it's Data Source through additional static binding.

# FetchXml Data Provider

FetchXml provider expects a valid FetchXml string as Data Source.

# Memory Data Provider

Memory Data Provider expects a stringified JSON key-value array as input. The array should contain key-value pairs consisting of column name and it's value. This is the exact same structure you would see in a raw OData response. This means OptionSets are represented by a number, lookups have GUIDs and etc. This applies to each data type. If you are not sure what value should be used for a specific Data Type, run an OData query against some entity containing fields of this data type and see what you get back.

{
   "@odata.context":"https://devbox-1959.crm4.dynamics.com/api/data/v9.1/$metadata#talxis_fields",
   "value":[
      {
         "@odata.etag":"W/\"4363703\"",
         "talxis_file_name":null,
         "_owninguser_value":"e86450b3-5882-ef11-ac20-000d3abee5ab",
         "talxis_clientextensibilitydatasource":null,
         "talxis_singlelinetext":"Text",
         "talxis_clientextensibilitybindingfield":null,
         "talxis_name":"Batch 1",
         "talxis_dateandtime":"1972-01-15T00:00:00Z",
         "_transactioncurrencyid_value":"13292e9f-7881-ef11-ac21-000d3a2b5e17",
         "talxis_clientextensibilitymetadata":null,
         "exchangerate":1,
         "talxis_currency_base":998472,
         "talxis_singlelineemail":"test@test.cz",
         "versionnumber":4363703,
         "talxis_file":null,
         "talxis_singlelineurl":"https://www.seznam.cz",
         "talxis_image":null,
         "talxis_multiple":"Multiple Text",
         "statecode":0,
         "talxis_image_timestamp":null,
         "talxis_wholeduration":710135,
         "talxis_twooptions":true,
         "_createdonbehalfby_value":null,
         "utcconversiontimezonecode":null,
         "statuscode":1,
         "talxis_multiselectoptionsetcolorful":"742070000,742070001",
         "talxis_fetchxmlbindingfield":null,
         "talxis_memorybindingfield":null,
         "talxis_clientextensibilitycolumns":null,
         "talxis_optionsetcolorful":742070000,
         "modifiedon":"2024-10-12T10:34:53Z",
         "talxis_wholenone":991020,
         "talxis_image_url":null,
         "talxis_fetchxmldata":null,
         "_ownerid_value":"e86450b3-5882-ef11-ac20-000d3abee5ab",
         "talxis_fieldid":"6c9e8489-1086-ef11-ac21-6045bd91c897",
         "_owningteam_value":null,
         "_modifiedonbehalfby_value":null,
         "createdon":"2024-10-09T07:31:46Z",
         "talxis_twooptionscolorful":false,
         "talxis_imageid":null,
         "_owningbusinessunit_value":"551c1778-4881-ef11-ac21-000d3a2b5e17",
         "timezoneruleversionnumber":0,
         "talxis_dateandtimetzi":null,
         "talxis_multiselectoptionset":"742070000,742070001",
         "talxis_fetchxmlcolumns":null,
         "_createdby_value":"e86450b3-5882-ef11-ac20-000d3abee5ab",
         "talxis_fetchxmlentitymetadata":null,
         "talxis_singlelinephone":"123456789",
         "talxis_dateonly":"1968-09-02T00:00:00Z",
         "_talxis_parentfield_value":"ac6aa5c8-4086-ef11-ac21-000d3abee5ab",
         "_modifiedby_value":"e86450b3-5882-ef11-ac20-000d3abee5ab",
         "overriddencreatedon":null,
         "importsequencenumber":null,
         "talxis_decimal":2000000,
         "talxis_currency":998472,
         "talxis_memorydata":null,
         "talxis_optionset":742070000,
         "talxis_memorycolumns":null,
         "talxis_memoryentitymetadata":null
      }
   ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# Lookup Column

In order to use Lookups in Memory Provider, your Data Source needs to include these three properties:

_{lookupColumnName}_value: GUID assigned to the lookup record. It serves as a unique identifier within the Dataset, allowing it to distinguish a specific lookup record. When utilizing the Dataset Client API, this GUID integrates into scenarios where a typical Lookup GUID would appear. For instance, when subscribing to the onDatasetItemOpened event, if a user clicks on this lookup, the entityReference will include this GUID value.
_{lookupColumnName}_@Microsoft.Dynamics.CRM.lookuplogicalname: Logical name that corresponds to the record table in Dataverse. Within Memory Provider, the logical name can either align with an existing table in Dataverse (entity bound) or be an arbitrary string (virtual). When the Lookup field is entity bound, it gains the ability to search through records, enabling users to edit the Lookup value (assign it a different GUID). You should also add the logical name to the Targets metadata prop in the column definition in order for the Lookup to be fully entity bound. If a random string is used, the editing functionality for the Lookup will be disabled.
_{lookupColumnName}_value@OData.Community.Display.V1.FormattedValue: Refers to the formatted value displayed to the user, representing the result of the Lookup.

Example of entity boud Lookup field:

{
   "name":"entityBoundLookup",
   "alias":"entityBoundLookup",
   "dataType":"DataTypes.LookupSimple",
   "displayName":"Entity Bound Lookup",
   "order": 0,
   "visualSizeFactor":150,
   "metadata":{
      "IsValidForUpdate": false,
      "Targets":[
         "account"
      ]
   }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Column Definition


[
   {
      "_entityBoundLookup_value":"ca07e627-5e00-4c4d-a7cf-8dcf0dd39437",
      "_entityBoundLookup_@Microsoft.Dynamics.CRM.lookuplogicalname":"account",
      "_entityBoundLookup_value@OData.Community.Display.V1.FormattedValue":"Account 1"
   }
]

1
2
3
4
5
6
7
8
9

Data Source

Example of Example of virtual Lookup field:

{
   "name":"virtualLookup",
   "alias":"virtualLookup",
   "dataType":"DataTypes.LookupSimple",
   "displayName":"Virtual Lookup",
   "order": 0,
   "visualSizeFactor":150,
   "metadata":{
      "IsValidForUpdate":true,
      "Targets":[
         "virtualEntity"
      ]
   }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Column Definition


[
   {
      "_virtualLookup_value":"f1c75b22-4c25-4019-91e0-2d55df6fed22",
      "_virtualLookup_@Microsoft.Dynamics.CRM.lookuplogicalname":"virtualEntity",
      "_virtualLookup_value@OData.Community.Display.V1.FormattedValue":"Virtual Entity 1"
   }
]

1
2
3
4
5
6
7
8
9

Data Source

# File and Image Columns

In order to use File and Image columns in Memory Provider, your Data Source needs to include these five (six) properties:

Property	Description
`{fileColumnName}`	Unique file identifier, can be any GUID.
`{fileColumnName.fileName}`	Name of the file.
`{fileColumnName.filesizeinbytes}`	Size of the file in bytes.
`{fileColumnName.mimetype}`	Mimetype (opens new window) of the file.
`{fileColumnName.fileurl}`	URL where the file can be downloaded from.
`{fileColumnName.thumbnailurl}`	URL for a thumbnail preview of the image (required for image columns only).

Example of a memory provider file and image fields:

[
   {
      "name":"file",
      "alias":"file",
      "dataType":"File",
      "displayName":"File",
      "order":0,
      "visualSizeFactor":150,
      "metadata":{
         "IsValidForUpdate":true
      }
   },
   {
      "name":"image",
      "alias":"image",
      "dataType":"Image",
      "displayName":"Image",
      "order":0,
      "visualSizeFactor":150,
      "metadata":{
         "IsValidForUpdate":true
      }
   }
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Column Definitions


{
   "file":"c3c9ffca-52e1-4c5b-a2ee-8520bec82544",
   "file.filename":"document_report_2025.pdf",
   "file.filesizeinbytes":902119,
   "file.mimetype":"application/pdf",
   "file.fileurl":"https://storage.example.com/files/docs/document_report_2025.pdf",
   "image":"439150e1-1ede-41e0-93bb-4da0b1e5254b",
   "image.filename":"sunset_landscape.jpg",
   "image.filesizeinbytes":902119,
   "image.mimetype":"image/jpeg",
   "image.fileurl":"https://storage.example.com/images/sunset_landscape.jpg",
   "image.thumbnailurl":"https://storage.example.com/images/thumbs/sunset_landscape_thumb.jpg"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Data Source

# Columns

Columns binding can be used to specify properties for each column. It expects a stringified JSON array containing objects of column props. This object is based on the PCF Dataset Column interface (opens new window).

[
  {
    "name": "datetime",
    "alias": "datetime",
    "dataType": "DateAndTime.DateAndTime",
    "displayName": "Date Time",
    "order": 0,
    "visualSizeFactor": 300
  },
  {
    "name": "mail",
    "alias": "mail",
    "dataType": "SingleLine.Email",
    "displayName": "Mail",
    "order": 1,
    "visualSizeFactor": 300,
    "metadata": {
      "IsValidForUpdate": true
    }
  },
  {
    "name": "lookup",
    "alias": "lookup",
    "dataType": "Lookup.Simple",
    "displayName": "Lookup",
    "order": 2,
    "visualSizeFactor": 300,
    "metadata": {
      "Targets": ["customLookup"]
    }
  },
  {
    "name": "optionset",
    "alias": "optionset",
    "dataType": "OptionSet",
    "displayName": "OptionSet",
    "order": 3,
    "visualSizeFactor": 300,
    "metadata": {
      "OptionSet": [
        {
          "Color": "red",
          "Label": "Option 1",
          "Value": 1
        },
        {
          "Color": "blue",
          "Label": "Option 2",
          "Value": 2
        }
      ]
    }
  }
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

NOTE: When you define columns using setColumns in the Client API, the control will utilize these specified columns, overriding any configurations set in the Columns binding or any defaults provided by the data provider.

# Extensions

In order to provide more features, we have extended the native column interface with additional props.

Prop Name	Description
`type`	A column can serve multiple purposes: it may contain data or fulfill other roles, such as displaying a ribbon or notifications. This property specifies whether the control treats the column as a data or action column, adapting its behavior accordingly (e.g., excluding data-specific features like non-editable icons in headers).
`alignment`	Defines the alignment of the column. If not specified, numbers default to right-aligned, while other types default to left-aligned.
`isDraggable`	Determines if the user can customize the column's position.
`metadata`	Allows you to define or override Xrm Attribute Metadata (opens new window) for a column.
`oneClickEdit`	Removes the need to double-click a cell to edit its value. Note: Enabling this on too many columns may reduce performance; use only when the performance decrease is acceptable for your use case.
`controls`	Used to set up cell customizers.

# Provider specific features

Depending on which provider you choose, a different minimal amount of props is required for the column to show in the UI:

FetchXml Provider: name
Memory Provider: name, displayName and dataType (opens new window)

# Memory Provider

Memory Provider requires all columns that are being used to be defined in the Column binding. If you do not specify the column in the binding, it will not appear in the control.

# FetchXm Provider

FetchXml Provider handles column binding in a slightly different way compared to other providers. When your FetchXml query does not include a savedqueryid, it behaves the same as MemoryProvider: any columns not explicitly specified in the Columns binding will be ignored. However, if the FetchXml includes a savedqueryid, the control retrieves the associated layoutxml to define the columns automatically.

When you define columns in the Columns binding and the FetchXml contains a savedqueryid, the details provided in the Columns binding take precedence, overriding the corresponding information in the layoutxml. Additionally, if you specify a column in the Columns binding that isn’t present in the layoutxml, it will be added to the control alongside the columns defined by the layout.

# Virtual Columns

FetchXml Provider offers support for virtual columns, which are columns that do not exist in Dataverse. Instead, it’s up to the developer to define their behavior and functionality. To designate a column as virtual, simply append the __virtual suffix to its name. This signals the provider that it should skip fetching metadata for that column from Dataverse. Once defined, virtual columns can be manipulated just like regular columns—allowing you to use actions such as setValue and getValue, apply expressions, and perform other operations as needed.

# Entity Metadata

Entity Metadata binding allows you to define/override any Xrm Entity Metadata (opens new window). For example, you can change the DisplayCollectionName, so the UI can better describe your dataset. For Memory Provider, it is required to specify the PrimaryIdAttribute prop. The binding accepts a stringified JSON object that corresponts to the Xrm Entity Metadata (opens new window) interface.

# Bindings Summary

Property Name	Description	Of Type	Input	Output	Usage	Required
bindingField	Binding Field	`SingleLine.Text`	`N/A`	`N/A`	`bound`	`true`
DataProvider	Data Provider that the control will use to fetch data.	`Enum ("Memory" \| "FetchXml")`	`"FetchXml"`	`N/A`	`input`	`true`
Data	Data Source depending on the provider (FetchXml for FetchXml Provider, JSON array for Memory Provider).	`Multiple`	`"<fetch><entity name="account"><attribute name="name"/></entity></fetch>"`	`N/A`	`input`	`true`
Columns	JSON array containing the column definitions.	`Multiple`	`[{"name": "name", "isHidden": false}]`	`N/A`	`input`	`true`
EntityMetadata	Optional property allowing you to override/define Entity Metadata	`Multiple`	`{"DisplayCollectionName": "Custom Collection Name"}`	`N/A`	`input`	`false`
Height	Can be used to force the control to always stay at fixed height.	`SingleLine.Text`	`500px`	`N/A`	`input`	`false`
RowHeight	Sets a custom height for rows.	`Whole.None`	`42`	`N/A`	`input`	`false`
EnableEditing	Enable or disable editing functionality in the control.	`Enum ("Yes" \| "No")`	`"Yes"`	`N/A`	`input`	`false`
EnablePagination	Enable or disable pagination in the control.	`Enum ("Yes" \| "No")`	`"Yes"`	`N/A`	`input`	`false`
EnableFiltering	Enable or disable filtering options in the control.	`Enum ("Yes" \| "No")`	`"Yes"`	`N/A`	`input`	`false`
EnableSorting	Enable or disable sorting options in the control.	`Enum ("Yes" \| "No")`	`"Yes"`	`N/A`	`input`	`false`
EnableNavigation	Enable or disable navigation options in the control.	`Enum ("Yes" \| "No")`	`"Yes"`	`N/A`	`input`	`false`
EnableOptionSetColors	Enable or disable OptionSet colors in the control.	`Enum ("Yes" \| "No")`	`"No"`	`N/A`	`input`	`false`
SelectableRows	Defines if and how rows can be selected.	`Enum ("None" \| "Single" \| "Multiple")`	`"Single"`	`N/A`	`input`	`false`
EnableQuickFind	Enable or disable the Quick Find feature in the control.	`Enum ("Yes" \| "No")`	`"No"`	`N/A`	`input`	`false`
EnableChangeEditor	Whether the user can display a list of all their changes.	`Enum ("Yes" \| "No")`	`"Yes"`	`N/A`	`input`	`false`

NOTE: You can quickly demo the control locally through PCF local harness (opens new window). Just make sure you switch the _mock variable true.

Tree View General