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>john.smith@techcorp.com</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 Datasources > Click Add new in the External datasource tab > Choose the XML type.

Basic Configuration

1. Update Schedule Decide how your datasource updates from the XML source:

Select a Refresh Frequency for regular intervals (every minute, hour, day, etc.)
Specify a Cron Expression for custom scheduling based on your XML data update patterns

Example Cron Expressions for XML

0 */10 * * * * - Every 10 minutes for frequently updated APIs
0 0 */4 * * * - Every 4 hours for business data feeds
0 30 8 * * * - Daily at 8:30 AM for reports and batch updates

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.

For more information about external datasource refresh options, see the External Datasource Refreshing documentation.

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. Datasource Settings Configure datasource behavior:

Active: Enable/disable the datasource without deleting it. Useful for temporarily stopping XML data updates during maintenance
Ignore Error counter: Continue operation even if errors occur during XML parsing or fetching. Recommended for APIs that may have occasional downtime or malformed responses

4. Editor Settings Configure how the system processes XML data:

Cache external resources: Store external content (images, files, linked resources) referenced in XML locally for faster access and offline availability
Remove broken external resource references: Automatically clean up invalid links or missing resources found in XML data
Rotate cache on every update: Clear and rebuild cache with each XML refresh to ensure fresh content from the source
Exchange internal resource references: Update internal file paths when referenced content is moved or reorganized
Request settings: Configure HTTP headers, authentication, timeout, XPath parsing options, and other advanced request parameters

5. Array Processing Enable Randomize arrays to shuffle the order of XML elements when multiple similar elements exist. This is useful for:

Rotating through different product listings from XML catalogs
Creating varied content presentation from RSS-like XML feeds
Displaying random selections from large XML datasets
Ensuring different items are highlighted on each update cycle

XML Authentication and Security

For XML APIs requiring authentication or special access:

Basic Authentication: Username and password for protected XML endpoints
- Configure in Request settings with HTTP basic auth credentials
- Common for internal APIs and enterprise web services
API Key Authentication: For XML services requiring API keys
- Header Name: Authorization, X-API-Key, or custom header
- Header Value: Your API provider's key or token
- Query Parameter: Add API key as URL parameter if required
Bearer Token Authentication: For OAuth or JWT-protected XML APIs
- Header Name: Authorization
- Header Value: Bearer your-jwt-token-here
Custom Headers: Additional headers for XML API access
- Content-Type specifications for POST requests
- User-Agent identification for service recognition
- Referrer headers for APIs that check request source
- Custom authentication schemes
SOAP Authentication: For SOAP web services
- WS-Security headers for enterprise services
- Custom SOAP headers for authentication
- Session-based authentication cookies

XML Security Best Practices

Use HTTPS endpoints when available for secure data transmission
Store authentication credentials securely in request settings
Implement proper timeout values for reliable API access
Use appropriate user agent strings for API identification

6. 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)

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

Prerequisites​

Supported XML Formats​

Create datasource​

Basic Configuration​

Advanced Configuration Options​

XML Authentication and Security​

XML Data Structure and XPath​

Basic XML Element Access​

XPath Expression Examples​

Using XML Data in Widgets​

Widget Integration Examples​

Common XML API Types​

XML Parsing Considerations​