XML datasource

XML datasources allow you to fetch and display data from XML APIs, web services, RSS feeds, SOAP services, and any URL that returns XML formatted data. The system automatically parses XML structures using XPath and makes the data available to your widgets and templates.

Prerequisites

Before creating an XML datasource, ensure you have:

• A valid XML API endpoint or URL that returns well-formed XML data
• Proper network access to the XML source
• Understanding of the XML structure and namespace usage
• Authentication credentials if required by the XML API
• Knowledge of XPath expressions for complex data extraction
• Familiarity with XML schemas if validation is required

Supported XML Formats

The XML datasource supports various XML structures and standards:

Simple XML Structure:

<?xml version="1.0" encoding="UTF-8"?>
<data>
  <title>Weather Report</title>
  <temperature>22°C</temperature>
  <humidity>65%</humidity>
  <location>New York</location>
</data>

Array-like XML (Multiple Elements):

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <product>
    <id>1</id>
    <name>Laptop Computer</name>
    <price>899.99</price>
    <category>Electronics</category>
  </product>
  <product>
    <id>2</id>
    <name>Wireless Mouse</name>
    <price>29.99</price>
    <category>Accessories</category>
  </product>
</products>

Nested XML with Attributes:

<?xml version="1.0" encoding="UTF-8"?>
<company name="Tech Corp" founded="2020">
  <departments>
    <department id="IT" budget="500000">
      <name>Information Technology</name>
      <employees>
        <employee id="001" role="Developer">
          <name>John Smith</name>
          <email>[email protected]</email>
        </employee>
      </employees>
    </department>
  </departments>
</company>

XML with Namespaces:

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:corp="http://techcorp.com/schema"
      xmlns:hr="http://hr.system.com/schema">
  <corp:company>
    <corp:name>Tech Corporation</corp:name>
    <hr:employees>
      <hr:employee>
        <hr:name>Jane Doe</hr:name>
        <hr:position>Manager</hr:position>
      </hr:employee>
    </hr:employees>
  </corp:company>
</root>

SOAP Response XML:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <GetWeatherResponse xmlns="http://weather.service.com">
      <GetWeatherResult>
        <Temperature>75</Temperature>
        <Condition>Sunny</Condition>
        <WindSpeed>5</WindSpeed>
      </GetWeatherResult>
    </GetWeatherResponse>
  </soap:Body>
</soap:Envelope>

Create datasource

Go to Settings > Datasources and open the External Datasources tab. Click Add external datasource, then on the Choose a datasource type screen select XML.

Basic Configuration

1. Update Schedule Set how often the datasource updates under Refresh settings: a Simple interval or an Advanced schedule (cron). Learn more: Refresh and caching

XML Update Frequency

Consider the source system's update frequency. XML APIs from databases might update every few minutes, while report APIs might only update daily. Match your refresh frequency accordingly.

2. XML Endpoint URL In the URL field, enter the XML API endpoint or URL. The URL must:

• Return valid, well-formed XML content
• Be accessible from your server without firewall restrictions
• Use HTTP or HTTPS protocol
• Respond with proper Content-Type: application/xml or text/xml headers

Valid XML URL Examples

• https://api.company.com/data.xml - REST API returning XML
• https://weather.service.com/current?format=xml - Weather service API
• https://internal.app.com/reports/daily.xml - Internal business reports
• https://feeds.example.com/products.xml - Product catalog feed

Advanced Configuration Options

3. Advanced settings The caching options are explained in Refresh and caching. Active, Continue refreshing despite errors, Connection settings and shuffling lists (Process and filter data) are explained in Advanced datasource settings.

Authentication

If the XML source needs authentication, click Connection settings:

• For a username and password, turn on Authentication (Basic auth).
• For an API key or a token, add it under Custom headers (advanced), for example X-API-Key with your key, or Authorization with Bearer <token>.

Learn more: Connection settings

4. Save Configuration Once all settings are configured according to your XML source requirements, click Save to create the datasource.

XML Datasource Testing

After saving, check the datasource preview to ensure XML is being parsed correctly and verify the data structure matches your widget requirements. Test XPath expressions if using complex XML structures.

XML Data Structure and XPath

XML datasources provide access to XML elements, attributes, and text content through XPath expressions:

Basic XML Element Access

• Element text content: Access text within XML tags
• Element attributes: Access XML attribute values
• Nested elements: Navigate XML hierarchy structures
• Multiple elements: Handle arrays of similar XML elements

XPath Expression Examples

Simple Element Access:

<weather>
  <temperature>25</temperature>
  <condition>Sunny</condition>
</weather>

• Temperature: /weather/temperature or data.weather.temperature
• Condition: /weather/condition or data.weather.condition

Attribute Access:

<product id="123" category="electronics">
  <name>Laptop</name>
  <price currency="USD">899.99</price>
</product>

• Product ID: /product/@id or data.product.@id
• Currency: /product/price/@currency or data.product.price.@currency
• Product name: /product/name or data.product.name

Array Processing:

<employees>
  <employee id="1">
    <name>John Smith</name>
    <position>Developer</position>
  </employee>
  <employee id="2">
    <name>Jane Doe</name>
    <position>Manager</position>
  </employee>
</employees>

• First employee: /employees/employee[1]/name or data.employees.employee[0].name
• All employee names: /employees/employee/name or data.employees.employee[].name
• Employee by ID: /employees/employee[@id='1']/name

Namespace Handling:

<root xmlns:hr="http://hr.company.com">
  <hr:employee>
    <hr:name>Alice Johnson</hr:name>
    <hr:department>IT</hr:department>
  </hr:employee>
</root>

• Namespaced element: /root/hr:employee/hr:name
• Department: /root/hr:employee/hr:department

Using XML Data in Widgets

After creating the XML datasource, bind XML data to widgets using dot notation and XPath-style references:

Simple XML Values:

• Text content: data.weather.temperature, data.product.name
• Attributes: data.product.@id, data.item.@category
• Nested values: data.company.departments.IT.budget

XML Arrays and Lists:

• First item: data.products.product[0].name
• All items: data.products.product[].price (for iteration)
• Specific item: data.employees.employee[2].position

Complex XML Structures:

• SOAP responses: data.soap_envelope.soap_body.response.result
• Nested data: data.catalog.categories.electronics.items[0].specs.processor
• Namespace elements: data.root.hr_employee.hr_name (colons become underscores)

Widget Integration Examples

Data Display Widget:

• Product name: data.catalog.product.name
• Product price: $data.catalog.product.price
• Product image: data.catalog.product.image_url

Table Widget with XML Arrays:

• Employee list: Iterate through data.employees.employee[]
• Display: data.employees.employee[].name - data.employees.employee[].position

Weather Widget:

• Current temperature: data.weather.current.temperature
• Weather condition: data.weather.current.condition
• Location: data.weather.location.city

Common XML API Types

SOAP Web Services:

• Enterprise business applications
• Legacy system integrations
• Banking and financial services
• Government and public sector APIs

REST APIs with XML:

• E-commerce product catalogs
• Content management systems
• Inventory and logistics systems
• Real estate listing services

Data Export APIs:

• Business intelligence reports
• Database export services
• Analytics and metrics APIs
• Customer relationship management systems

Configuration and Settings APIs:

• System configuration data
• Application settings
• User preference APIs
• Device management services

RSS and Syndication Extensions:

• News feed extensions beyond standard RSS
• Custom content syndication
• Event and calendar feeds
• Product update notifications

XML Parsing Considerations

Well-Formed XML Requirements:

• Proper opening and closing tags
• Correctly nested elements
• Valid character encoding (UTF-8 recommended)
• Proper namespace declarations

Performance Factors:

• Large XML files may require longer processing times
• Complex XPath expressions can impact parsing speed
• Namespace resolution adds processing overhead
• Deep nesting levels increase memory usage

Data Validation:

• XML schema validation for structured data
• DTD validation for document type definitions
• Custom validation rules for business logic
• Error handling for malformed XML responses

Character Encoding:

• UTF-8 encoding recommended for international characters
• Proper encoding declaration in XML header
• BOM (Byte Order Mark) handling
• Special character escaping in XML content

Related guides

• How to create content with an XML datasource