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
0 */10 * * * *
- Every 10 minutes for frequently updated APIs0 0 */4 * * *
- Every 4 hours for business data feeds0 30 8 * * *
- Daily at 8:30 AM for reports and batch updates
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
ortext/xml
headers
https://api.company.com/data.xml
- REST API returning XMLhttps://weather.service.com/current?format=xml
- Weather service APIhttps://internal.app.com/reports/daily.xml
- Internal business reportshttps://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
- Configure in
-
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
- Header Name:
-
Bearer Token Authentication: For OAuth or JWT-protected XML APIs
- Header Name:
Authorization
- Header Value:
Bearer your-jwt-token-here
- Header Name:
-
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
- 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.
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
ordata.weather.temperature
- Condition:
/weather/condition
ordata.weather.condition
Attribute Access:
<product id="123" category="electronics">
<name>Laptop</name>
<price currency="USD">899.99</price>
</product>
- Product ID:
/product/@id
ordata.product.@id
- Currency:
/product/price/@currency
ordata.product.price.@currency
- Product name:
/product/name
ordata.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
ordata.employees.employee[0].name
- All employee names:
/employees/employee/name
ordata.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