DataSource

DataSource fetches and caches data from API endpoints, versus APICall which creates, updates or deletes data.

Key characteristics:

• Conditional loading: Use when property to prevent fetching until dependent data is ready
• Built-in caching: Prevents unnecessary requests and provides instant data access
• Polling support: Automatically refetch data at specified intervals
• Data transformation: Process and filter responses before components use the data

Preventing the DataSource from Executing

Prevent the DataSource from executing until the specified condition in the when attribute is true.

<DataSource
  id="userProfile"
  url="/api/users/{selectedUserId}/profile"
  when="{selectedUserId}" />

Structural Sharing

DataSource uses a technique called "structural sharing" to ensure that as many data references as possible will be kept intact and not cause extra UI refresh. If data is fetched from an API endpoint, you'll usually get a completely new reference by json parsing the response. However, DataSource will keep the original reference if nothing has changed in the data. If a subset has changed, DataSource will keep the unchanged parts and only replace the changed parts.

When you initiate the refetching of data (e.g., with the refetch method or setting the pollIntervalInSeconds property) and you retrieve data structurally equal with the cached data instance, DataSource will not fire the loaded event.

By default, structural sharing is turned on. If you do not need this behavior, set the structuralSharing property to false.

Behaviors

This component supports the following behaviors:

Properties

body

Set the optional request body. The object you pass is serialized as a JSON string.

completedNotificationMessage

Set the message to display when the data fetch completes.If the property value is not set, no completion message is displayed.

This property customizes the success message displayed in a toast after the finished API invocation. The $result context variable can refer to the response body. For example, you can use the following code snippet to display the first 100 characters in the completed operation's response body:

 <DataSource
  id="ds"
  url="/api/shopping-list"
  completedNotificationMessage="Result: {JSON.stringify($result).substring(0, 100)}" />

credentials

Controls whether cookies and other credentials are sent with the request. Set to "include" to send credentials in cross-origin requests (requires Access-Control-Allow-Credentials: true header on the server).

Available values:

Important: When using credentials="include" for cross-origin requests, the server must respond with the Access-Control-Allow-Credentials: true header, and the Access-Control-Allow-Origin header cannot be * (it must be a specific origin).

Example: Fetching user authentication status with credentials

<DataSource 
  id="authStatus"
  url="https://api.example.com/auth/status"
  credentials="include"
/>
<Text>{authStatus.value.authenticated ? 'Logged in' : 'Not logged in'}</Text>

errorNotificationMessage

This property customizes the message displayed in a toast when the API invocation results in an error. Use the $error context object to get the error code ($error.statusCode) optional message ($error.message), or details coming from the response body ($error.details). For example, you can use the following code snippet to display the status code and the details:

 <DataSource
  id="ds"
  url="/api/shopping-list"
  errorNotificationMessage="${error.statusCode}, ${error.message} {JSON.stringify($error.details)}" />

NOTE: While we support Microsoft/Google-style and RFC 7807 errors, not all response shapes can be accounted for. Because of this, there is an attribute available in the configuration file called errorResponseTransform under appGlobals. This exposes the error response using the $response context variable. Here is an example on how to use it (note that this is evaluated as a binding expression):

Error looks the following coming from the backend:

{
  code: number,
  error: string
}

This is how to transform it in config:

{
  "appGlobals": {
    "errorResponseTransform": "{{ statusCode: $response.code, message: $response.error }}"
  }
}

headers

Set request headers. Pass an object whose keys are header names and values are header values.

id

This property is required.

Set the ID used by other components to access the retrieved data in the valueproperty of a DataSource, or status info in the loaded and error properties.When no id is set, the component cannot be used programmatically.

inProgressNotificationMessage

Set the message to display when the data fetch is in progress. If the property value is not set, no progress message is displayed.

method

default: "get"

Set the HTTP method.

Available values: get (default), post, put, delete, patch, head, options, trace, connect

nextPageSelector

When using DataSource with paging, the response may contain information about the previous and next page. This property defines the selector that extracts the next page information from the response deserialized to an object.

pollIntervalInSeconds

Set the interval for periodic data fetching. If the data changes on refresh, XMLUI will re-render components that refer directly or indirectly to the DataSource. If not set or set to zero, the component does not poll for data.

prevPageSelector

When using DataSource with paging, the response may contain information about the previous and next page. This property defines the selector that extracts the previous page information from the response deserialized to an object.

queryParams

Append optional key-value pairs to the URL.

rawBody

Set the request body with no serialization. Use it to send a payload that has already been serialized to a JSON string.

resultSelector

Set an optional object key to extract a subset of the response data. If this value is not set, the entire response body is considered the result.

The selector can be a simple dot notation path (e.g., value.results) or a JavaScript expression that processes the data (e.g., results.filter(item => item.type === 'active')). The selector has access to standard JavaScript functions like map and filter, and operates on the full response body.

Here is a sample response from the HubSpot API.

{
    "results": [
        {
            "id": "88903258744",
            "properties": {
                "company": "HubSpot",
                "createdate": "2025-01-03T23:38:47.449Z",
                "custom_notes": "Nice guy!",
                "email": "bh@hubspot.com",
                "firstname": "Brian",
                "hs_object_id": "88903258744",
                "lastmodifieddate": "2025-02-18T23:13:34.759Z",
                "lastname": "Halligan (Sample Contact)"
            },
            "createdAt": "2025-01-03T23:38:47.449Z",
            "updatedAt": "2025-02-18T23:13:34.759Z",
            "archived": false
        },
        {
            "id": "88918034480",
            "properties": {
                "company": "HubSpot",
                "createdate": "2025-01-03T23:38:47.008Z",
                "custom_notes": null,
                "email": "emailmaria@hubspot.com",
                "firstname": "Maria",
                "hs_object_id": "88918034480",
                "lastmodifieddate": "2025-01-03T23:38:59.001Z",
                "lastname": "Johnson (Sample Contact)"
            },
            "createdAt": "2025-01-03T23:38:47.008Z",
            "updatedAt": "2025-01-03T23:38:59.001Z",
            "archived": false
        }
    ]
}

This resultSelector builds an array of the properties objects.

<DataSource
  id="contacts"
  url="http://{DOMAIN}/{CORS_PROXY}/api.hubapi.com/crm/v3/objects/contacts?properties=firstname,lastname,email,company,custom_notes"
  resultSelector="results.map(item => item.properties )"
  headers='{{"Authorization":"Bearer not-a-real-token"}}'

This List uses the array.

<List data="{contacts}" title="Hubspot Contacts">
  <Card gap="0" width="20em">
    <Text fontWeight="bold">
      {$item.firstname} {$item.lastname}
    </Text>
    <Text>
      {$item.company}
    </Text>
    <Text>
      {$item.email}
    </Text>
    <Text>
      {$item.custom_notes}
    </Text>
  </Card>
</List>

This resultSelector filters the array of the properties objects to include only contacts with non-null custom_notes.

<DataSource
  id="contacts"
  resultSelector="results.filter(contact => contact.properties.custom_notes !== null).map(contact => contact.properties)"
  url="http://{DOMAIN}/{CORS_PROXY}/api.hubapi.com/crm/v3/objects/contacts?properties=firstname,lastname,email,company,custom_notes"
  headers='{{"Authorization":"Bearer not-a-real-token"}}'
  />

This Table uses the filtered array.

<Table title="HubSpot contacts" data="{contacts}">
  <Column bindTo="firstname" />
  <Column bindTo="lastname" />
  <Column bindTo="company" />
  <Column bindTo="email" />
  <Column bindTo="custom_notes" />
</Table>

structuralSharing

default: "true"

This property allows structural sharing. When turned on, DataSource will keep the original reference if nothing has changed in the data. If a subset has changed, DataSource will keep the unchanged parts and only replace the changed parts. If you do not need this behavior, set this property to false.

transformResult

Set an optional function to perform a final transformation of the response data. If this value is not set, the result is not transformed.

url

This property is required.

Set the URL.

Events

error

This event fires when a request results in an error.

Signature: error(error: Error): void

• error: The error object that occurred during the request.

loaded

The component triggers this event when the fetch operation has been completed and the data is loaded. The event has two arguments. The first is the data loaded; the second indicates if the event is a result of a refetch.

Signature: loaded(data: any, isRefetch: boolean): void

• data: The data loaded from the fetch operation.
• isRefetch: Indicates whether this is a result of a refetch operation.

Exposed Methods

inProgress

This property indicates if the data is being fetched.

Signature: get inProgress(): boolean

isRefetching

This property indicates if the data is being re-fetched.

Signature: get isRefetching(): boolean

loaded

This property indicates if the data has been loaded.

Signature: get loaded(): boolean

refetch

This method requests the re-fetch of the data.

Signature: refetch(): void

value

This property retrieves the data queried from the source after optional transformations.

Signature: get value(): any

Styling

This component does not have any styles.