Skip to main content

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.

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:

  1. 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
  2. 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
  3. Bearer Token Authentication: For OAuth or JWT-protected XML APIs

    • Header Name: Authorization
    • Header Value: Bearer your-jwt-token-here
  4. 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
  5. 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)

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