Introduction
Sometimes, customers may need to connect to enterprise HR and finance systems like Workday. This guide explains how to configure the CData Workday JDBC Driver (build 25.0.9376.0) with Starburst’s Generic JDBC Connector to access Workday data through four different connection modes.
The CData Workday JDBC Driver supports multiple connection types, each suited for different use cases:
- SOAP Mode - Access dynamic tables from Workday Web Services
- Reports Mode - Query pre-built custom reports from Workday
- REST Mode - Use Workday’s modern REST API with 552 predefined tables
- WQL Mode - Leverage Workday Query Language for dynamic queries
This article will help you choose the right connection mode and configure it properly for your Starburst deployment.
Quick Reference: Connection Modes
| Parameter | SOAP | Reports | REST | WQL (Default) |
|---|---|---|---|---|
| ConnectionType | SOAP | Reports | REST | (omit or WQL) |
| Service | ||||
| CustomReportURL | ||||
| APIURL | ||||
| WSDLVersion | ||||
| AuthScheme=Basic | ||||
| Base Parameters | All modes require: BaseURL, Tenant, AuthScheme, User/Password (or OAuth), RTK |
*RTK value will most likely be required for k8s deployments due to how licensing works. Note that RTK is an OEM-only license feature — contact CData to confirm whether your license includes it.
Important: Basic authentication (
AuthScheme=Basic) is only supported in SOAP and Reports modes. WQL and REST modes require OAuth (AuthScheme=OAuth,OAuthISU, orOAuthJWT).
Decision Guide: Which Mode to Use?
Use SOAP Mode when:
- Need access to all Workday tables (100s of tables per service)
- Want flexible SQL queries with JOINs, WHERE clauses
- Querying specific tables like AcademicAppointee, Workers, etc.
- Data model changes frequently (WSDL auto-updates)
- MUST set Service parameter (e.g.,
Service=Human_Resources)
Use Reports Mode when:
- Have pre-built custom reports in Workday
- Reports are already web-service-enabled
- Want to leverage Workday’s report security/permissions
- Need business users to control data model (via Workday UI)
- Reports already exist in Workday or you are OK to create them
- Basic authentication is available (OAuth not required)
- Reports use only the primary business object for all columns — reports with multiple related business objects may cause query hangs (see Known Limitations: Reports with Multiple Business Objects later in this article)
Use REST Mode when:
- Want modern REST/JSON API (not SOAP/XML)
- OAuth authentication is required/preferred
- Need to access the 552 predefined REST endpoints
- Building new integrations (REST is more modern)
- Limited to tables in driver’s static catalog
Use WQL Mode when:
- Want Workday’s native query language
- Need dynamic schema discovery
- OAuth is available (required — Basic auth is not supported in WQL mode)
- Less common - typically use SOAP or REST instead
Step #1: Download and Install the JDBC Driver
Go to the CData Workday JDBC Driver page and download the driver. You can request a one-month free trial through CData by signing up with your email address.
Once downloaded, extract the archive and locate the JAR file: cdata.jdbc.workday.jar
Upload the JAR to every node of your Starburst cluster in the following folder:
/usr/lib/starburst/plugin/generic-jdbc/
You can upload it to S3 and then curl to each node:
sudo curl https://your-bucket.s3.amazonaws.com/cdata.jdbc.workday.jar \
--output /usr/lib/starburst/plugin/generic-jdbc/cdata.jdbc.workday.jar`
Then change file privileges:
chmod 777 /usr/lib/starburst/plugin/generic-jdbc/cdata.jdbc.workday.*
Step #2: Register the License
For trial evaluation, run the following command on each node:
sudo java -jar /usr/lib/starburst/plugin/generic-jdbc/cdata.jdbc.workday.jar -license
When prompted, enter “TRIAL” as the product key. This will generate a license file:
/usr/lib/starburst/plugin/generic-jdbc/cdata.jdbc.workday.lic
For production deployments, you’ll need to obtain an RTK (Runtime Key) license from CData and include it in your connection URL as the RTK parameter. The RTK value is required as license files are done on a per-node basis – if using Kubernetes, the license file will need to be generated on each node restart and won’t persist.
Step #3: Choose Your Connection Mode
SOAP Mode (ConnectionType=SOAP)
Use Case: Access dynamic tables from Workday Web Services (WSDL-based)
What You Get:
- Dynamic tables from the specified service WSDL
- Example:
Human_Resourcesservice provides 253 tables (Workers, AcademicAppointee, etc.) - Flexible SQL queries with JOINs and WHERE clauses
Required Parameters:
ConnectionType=SOAP
Service=Human_Resources # REQUIRED - must specify service name
BaseURL=https://wd2-impl-services1.workday.com
Tenant=your_tenant
AuthScheme=Basic
User=integration_user
Password=your_password
RTK=your_rtk_license_key # OEM licenses only
Valid Service Values:
While the majority of services are included by default, best practice is to include the specific services needed.
| Service Name | Included By Default? |
|---|---|
| ACA_Partner_Integrations | No |
| Absence_Management | Yes |
| Academic_Advising | Yes |
| Academic_Foundation | Yes |
| Admissions | Yes |
| Adoption | Yes |
| Benefits_Administration | Yes |
| Benefits_Partner_Program_Integrations | No |
| Campus_Engagement | Yes |
| Cash_Management | Yes |
| Compensation | Yes |
| Compensation_Review | Yes |
| Drive | No |
| Dynamic_Document_Generation | Yes |
| External_Integrations | Yes |
| Financial_Aid | Yes |
| Financial_Management | Yes |
| Human_Resources | Yes |
| Identity_Management | Yes |
| Integrations | Yes |
| Interview_Feedback__Do_Not_Use_ | No |
| Inventory | Yes |
| Learning | Yes |
| Metadata_Translations | No |
| Moments | No |
| Notification | No |
| Org_Studio | No |
| Payroll | Yes |
| Payroll_AUS | No |
| Payroll_CAN | Yes |
| Payroll_FRA | No |
| Payroll_GBR | Yes |
| Payroll_Interface | Yes |
| Performance_Management | Yes |
| Professional_Services_Automation | No |
| Recruiting | Yes |
| Resource_Management | Yes |
| Revenue_Management | Yes |
| Scheduling | Yes |
| Settlement_Services | Yes |
| Staffing | Yes |
| Student_Core | Yes |
| Student_Finance | Yes |
| Student_Records | No |
| Student_Recruiting | Yes |
| Student_Transfer_Credit | No |
| Talent | Yes |
| Tenant_Data_Translation | No |
| Time_Tracking | Yes |
| Workday_Connect | Yes |
| Workday_Extensibility | Yes |
| Workforce_Planning | Yes |
Complete Catalog Configuration Example:
connector.name=generic_jdbc
generic-jdbc.driver-class=cdata.jdbc.workday.WorkdayDriver
connection-url=jdbc:cdata:workday:ConnectionType=SOAP;AuthScheme=Basic;Verbosity=5;Logfile=/tmp/cdata.log;User=workday_user;Password=${ENV:workday_user_pw};Tenant=your_tenant;BaseURL=https://<workday url>.workday.com;Service=Human_Resources;RTK=${ENV:workday_rtk};
case-insensitive-name-matching=true
Reports Mode (ConnectionType=Reports)
Complete Catalog Configuration Example:
connector.name=generic_jdbc
generic-jdbc.driver-class=cdata.jdbc.workday.WorkdayDriver
connection-url=jdbc:cdata:workday:ConnectionType=Reports;AuthScheme=Basic;Verbosity=5;Logfile=/tmp/cdata.log;User=workday_user;Password=${ENV:workday_user_pw};Tenant=your_tenant;BaseURL=https://<workday url>.workday.com;CustomReportURL=https://wd2-impl-services1.workday.com/ccx/service/customreport2/your_tenant/your_user/Reports_as_a_Service;UseSplitTables=true;Pagesize=300;Timeout=120;RTK=${ENV:workday_rtk};
case-insensitive-name-matching=true
Working with Report Prompts
Many Workday reports require prompt values to execute — for example, a date range or an organizational filter. The driver exposes these as input columns with a _Prompt suffix. In case an SQL query is executed against the catalog without providing mandatory prompt values in the WHERE clause - the query will hang indefinitely without returning data or an error.
To discover the available prompt columns for a report, query sys_tablecolumns directly against the CData catalog. Note that this is not in information_schema — it is a CData system table:
SELECT ColumnName, DataTypeName, IsNullable
FROM CData.Reports.sys_tablecolumns
WHERE TableName = 'your_report_name'
AND CatalogName = 'CData'
AND SchemaName = 'Reports'
ORDER BY Ordinal
Once you have the prompt column names, supply them in your WHERE clause:
SELECT *
FROM "My_Report"
WHERE From_Date_Prompt = '2026-01-01'
AND To_Date_Prompt = '2026-03-31'
Additional non-prompt filters can also be included — the driver passes prompts to Workday and applies remaining conditions client-side after data is returned:
SELECT *
FROM "My_Report"
WHERE From_Date_Prompt = '2026-01-01'
AND To_Date_Prompt = '2026-03-31'
AND Department = 'Sales' -- applied client-side
Working with Reports with Many Columns
Workday reports can have hundreds of columns. Set UseSplitTables=true to avoid column count limitations in Starburst. The driver splits the report into multiple tables of 50–100 columns each, joined by the primary key:
SELECT a.Employee_ID, b.Job_Title
FROM My_Report_1 a
INNER JOIN My_Report_60 b ON a.workdayID = b.workdayID
Known Limitations: Reports with Multiple Business Objects
The CData driver performs best with reports where all columns use the primary business object. Reports that include columns from multiple related business objects — which is common in complex, production Workday reports — can cause queries to hang silently or return incomplete data.
This is a known constraint of the driver’s Reports mode. The CData documentation recommends restructuring reports so all columns reference the primary business object, but this is often not feasible for complex reports built by Workday admins. If you encounter this limitation, consider:
- Using SOAP mode instead, which handles multi-object data models natively
- Breaking the report into simpler component reports that each use a single business object
- Testing with a simplified version of the report to confirm the business object structure is the root cause
Performance and Payload Tuning
For large reports, tuning page size and timeouts can significantly affect reliability. The key parameter for controlling how much data is fetched per API call is Pagesize (not BatchSize — see Note on BatchSize in Issue 6 later in this article):
Pagesize=300 # Lower than the default of 500 to reduce per-request payload
Timeout=120 # Seconds per paging call; default is 60; never set to 0
MaxRows=100000 # Optional ceiling on total rows returned; default is -1 (unlimited)
Complete Catalog Configuration Example:
connector.name=generic_jdbc
generic-jdbc.driver-class=cdata.jdbc.workday.WorkdayDriver
connection-url=jdbc:cdata:workday:ConnectionType=Reports;AuthScheme=Basic;Verbosity=5;Logfile=/tmp/cdata.log;User=workday_user;Password=${ENV:workday_user_pw};Tenant=your_tenant;BaseURL=https://<workday url>.workday.com;CustomReportURL=https://wd2-impl-services1.workday.com/ccx/service/your_tenant/Human_Resources/v44.1/Academic_Appointee_Summary;UseSplitTables=true;Pagesize=300;Timeout=120;RTK=${ENV:workday_rtk};
case-insensitive-name-matching=true
Prerequisites:
The driver discovers available reports through a special listing report you create in Workday. Follow these steps:
- Open the Create Custom Report form in Workday
- Name the report Reports as a Service
- Set the report type to Advanced
- Select Enable As Web Service
- Clear Optimized for Performance
- Set the Data Source to All Custom Reports
- Add the following columns in the Fields tab:
Report Name,Web Service Namespace,Report Owner,Brief Description - Ensure all columns have the primary business object as their Business Object (it should have a box-and-arrow icon — if it shows an ellipsis instead, click menu → Primary Business Object → Custom Field)
- On the Filter tab, add a filter: field
Web Service Namespace, operatoris not blank - Optionally add a second filter: field
Current User, operatorin the selection list, comparison typeValue from Another Field, comparison valueAuthorized Users(recommended — limits results to reports the connecting user can access) - Save the report
To retrieve the URL for CustomReportURL:
- Open the newly created report
- Click the ellipsis (…) beside the report title
- Find the Web Services tab and select View URLs
- Copy the Workday XML link — this is your
CustomReportURLvalue
Your individual data reports must also be web-service-enabled for the driver to query them:
- Each report must have Enable as Web Service checked in Workday
- The connecting user must have permissions to access each report
REST Mode (ConnectionType=REST)
Use Case: Access Workday’s REST API with 552 predefined tables
What You Get:
- 552 static REST API tables defined in driver
- Modern REST/JSON API (not SOAP/XML)
- Top services: /staffing/v6 (80 tables), /person/v4 (57 tables), /projects/v1 (51 tables)
Note: Basic authentication is not supported in REST mode. OAuth is required.
Required Parameters (OAuth):
ConnectionType=REST
AuthScheme=OAuth
OAuthClientId=your_client_id
OAuthClientSecret=your_client_secret
BaseURL=https://wd2-impl-services1.workday.com
Tenant=your_tenant
RTK=your_rtk_license_key # OEM licenses only
Complete Catalog Configuration Example (OAuth):
connector.name=generic_jdbc
generic-jdbc.driver-class=cdata.jdbc.workday.WorkdayDriver
connection-url=jdbc:cdata:workday:ConnectionType=REST;AuthScheme=OAuth;Verbosity=5;Logfile=/tmp/cdata.log;OAuthClientId=${ENV:oauth_client_id};OAuthClientSecret=${ENV:oauth_client_secret};Tenant=your_tenant;BaseURL=https://<workday url>.workday.com;RTK=${ENV:workday_rtk};
case-insensitive-name-matching=true
WQL Mode (ConnectionType=WQL can be omitted as Default)
Use Case: Workday Query Language for dynamic queries
What You Get:
- Dynamic schema based on WQL endpoint
- Workday’s SQL-like query language
- Requires OAuth authentication
Note: Basic authentication is not supported in WQL mode. OAuth is required.
Working with Wide Tables
WQL data sources can have hundreds or thousands of columns — allWorkers, for example, has thousands. Always set UseSplitTables=true for production use. The driver creates multiple tables of 50–100 columns each, joined by workdayID:
SELECT a.academicDegree, b.yearsExperience
FROM allWorkers_1 a
INNER JOIN allWorkers_60 b ON a.workdayID = b.workdayID
Recommended Production Configuration
For production WQL deployments — particularly against wide data sources or in environments with many concurrent queries — the following settings are recommended based on real-world deployments:
| Parameter | Recommended Value | Notes |
|---|---|---|
UseSplitTables |
true |
Splits wide sources into 50–100 column tables; essential for 500+ column sources |
Pagesize |
300 |
Lowered from default of 500 to reduce memory pressure on wide rows |
MetadataFilters |
Calculated,Undefined |
Undefined columns cause query errors; Calculated columns slow queries down |
MaxRows |
100000 |
Hard ceiling on total rows; default is -1 (unlimited). Query-level LIMIT always takes precedence |
Timeout |
120 |
Applies per paging call, not per query; default is 60; never set to 0 |
ConnectionLifeTime |
1800 |
Max connection lifetime in seconds; prevents stale pooled connections |
UseConnectionPooling |
true |
Enables connection reuse to reduce handshake overhead; default is false |
PoolMaxSize |
15 |
Caps concurrent connections to avoid hammering Workday’s API; default is 100 |
PoolMinSize |
2 |
Pre-initialized connections to reduce first-query latency; default is 1 |
PoolIdleTimeout |
120 |
Seconds before an idle connection is closed; default is 60 |
Required Parameters:
# ConnectionType=WQL (or omit - it's the default)
AuthScheme=OAuth # Required — Basic auth is not supported in WQL mode
OAuthClientId=your_client_id
OAuthClientSecret=your_client_secret
BaseURL=https://wd2-impl-services1.workday.com
Tenant=your_tenant
RTK=your_rtk_license_key # OEM licenses only
Complete Catalog Configuration Example:
connector.name=generic_jdbc
generic-jdbc.driver-class=cdata.jdbc.workday.WorkdayDriver
connection-url=jdbc:cdata:workday:AuthScheme=OAuth;OAuthClientId=${ENV:oauth_client_id};OAuthClientSecret=${ENV:oauth_client_secret};Tenant=your_tenant;BaseURL=https://<workday url>.workday.com;UseSplitTables=true;Pagesize=300;MetadataFilters=Calculated,Undefined;MaxRows=100000;UseSimpleNames=true;Timeout=120;ConnectionLifeTime=1800;UseConnectionPooling=true;PoolMaxSize=15;PoolMinSize=2;PoolIdleTimeout=120;RTK=${ENV:workday_rtk};
case-insensitive-name-matching=true
Step #4: Configure the Catalog
Create a new catalog file on each Starburst cluster node:
touch /etc/starburst/catalog/workday.properties
Paste your chosen configuration from Step #3 based on the connection mode you selected.
Key Configuration Notes:
- Always set
case-insensitive-name-matching=truefor better compatibility - Use environment variables for sensitive credentials (e.g.,
${ENV:workday_user_pw}) - Enable verbose logging during initial setup with
Verbosity=5andLogfile=/tmp/cdata.log - Do not set
Timeout=0. This disables timeouts entirely, causing hung queries to appear as silent infinite hangs with no error. The default is 60 seconds; a value of 120 is recommended for production workloads with larger reports. - For development/testing, you can use
SSLServerCert=*to accept any SSL certificate (not recommended for production) - Set
UseSplitTables=truefor any Reports or WQL catalog that may expose tables with many columns. This prevents column count errors in Starburst and is strongly recommended for production. Pagesizedefaults to 500 rows per API page. Avoid increasing this value significantly — large page sizes increase memory usage and risk triggering timeouts, particularly on wide tables.
Once configured, save your changes and restart your Starburst cluster.
Step #5: Query Workday Data from Starburst
After the cluster restarts, you should see a new workday catalog in the Starburst UI.
Make sure your user has the necessary privileges in Ranger/BIAC or your authorization tool to access the catalog.
You can now query Workday data:
-- List available tables
SHOW TABLES FROM workday.default;
-- Query worker data (SOAP mode example)
SELECT * FROM workday.default.workers LIMIT 10;
-- Query custom report (Reports mode example)
SELECT * FROM workday.default.academic_appointee_summary LIMIT 10;
-- Discover columns and prompts for a specific report (Reports mode)
SELECT ColumnName, DataTypeName, IsNullable
FROM CData.Reports.sys_tablecolumns
WHERE TableName = 'academic_appointee_summary'
AND CatalogName = 'CData'
AND SchemaName = 'Reports'
ORDER BY Ordinal
Basic Authentication (SOAP and Reports modes only)
AuthScheme=Basic
User=integration_user
Password=password123
OAuth 2.0 (Required for REST and WQL; supported in all modes)
AuthScheme=OAuth
OAuthClientId=abc123
OAuthClientSecret=xyz789
OAuth ISU (Integration System Users — non-interactive, recommended for automated pipelines)
AuthScheme=OAuthISU
OAuthClientId=abc123
OAuthClientSecret=xyz789
OAuthRefreshToken=your_refresh_token
OAuth with JWT
AuthScheme=OAuthJWT
OAuthJWTCert=/path/to/cert.pem
OAuthJWTCertPassword=cert_password
OAuthJWTIssuer=client_id
OAuthJWTSubject=user_email
Azure AD (SSO)
AuthScheme=AzureAD
OAuthClientId=azure_client_id
OAuthClientSecret=azure_secret
Optional Configuration Parameters
Debugging Parameters
Verbosity=5 # Log level (1=errors only, 5=all details)
Logfile=/tmp/cdata.log # Log file location
Wide Table Parameters
UseSplitTables=true # Split wide tables into 50-100 column chunks (strongly recommended)
MetadataFilters=Calculated,Undefined # Exclude slow/error-causing column types (WQL mode)
Performance Parameters
Pagesize=300 # Rows per API page (default 500; lower for wide tables)
Timeout=120 # Seconds per paging call (default 60; never set to 0)
MaxRows=100000 # Total row ceiling for non-aggregated queries (default -1, unlimited)
ConnectionLifeTime=1800 # Max connection lifetime in seconds (default 0, unlimited)
Connection Pooling Parameters
UseConnectionPooling=true # Enable connection reuse (default false)
PoolMaxSize=15 # Max concurrent connections (default 100; cap to protect Workday API)
PoolMinSize=2 # Pre-initialized connections (default 1)
PoolIdleTimeout=120 # Seconds before idle connection is closed (default 60)
SSL/TLS Parameters
SSLServerCert=* # Accept any cert (dev/test only)
SSLServerCert=/path/to/cert.pem # Specific certificate
Troubleshooting Common Issues
Issue #1: HTTP 40005 “Invalid service”
Cause: Missing Service parameter in SOAP mode
Fix: Add Service=Human_Resources (or appropriate service name)
Issue #2: “No suitable driver found”
Cause: JAR not in classpath or wrong driver class name
Fix: Verify generic-jdbc.driver-class=cdata.jdbc.workday.WorkdayDriver
Issue #3: SSL handshake errors
Cause: Driver upgrading HTTP to HTTPS, or certificate issues
Fix: Follow these steps:
- Ensure
BaseURLstarts with<https://> - For dev/test: Add
SSLServerCert=* - For prod: Use valid SSL certificates
Issue #4: “Table not found”
SOAP Mode:
- Verify
Serviceparameter points to correct service - Check WSDL to confirm table exists in that service
- Try
WSDLVersionparameter to use different WSDL version
Reports Mode:
- Verify report is web-service-enabled in Workday
- Check
CustomReportURLis correct - Verify user has permissions to access report
REST Mode:
- Table must be in driver’s 552-table catalog
- Check if table is SOAP-only (not available via REST)
Issue #5: Query hangs indefinitely — metadata loads but no data returned
There are two distinct causes for this symptom.
Cause 1: Missing report prompts
The report requires prompt values that have not been supplied. Reports with prompts will hang silently if no matching WHERE clause filters are provided.
Fix: Follow these steps:
- Query
sys_tablecolumnsto discover prompt column names (columns ending in_Prompt). Note thatsys_tablecolumnsis not ininformation_schema— it is a CData system table queried directly:
SELECT ColumnName, DataTypeName
FROM CData.Reports.sys_tablecolumns
WHERE TableName = 'your_report_name'
AND CatalogName = 'CData'
AND SchemaName = 'Reports'
- Supply the required prompts in your query
WHEREclause:
SELECT * FROM "My_Report"
WHERE From_Date_Prompt = '2026-01-01'
AND To_Date_Prompt = '2026-03-31'
- Set
Timeout=120in the connection string so that hung queries surface as actionable errors rather than silent hangs. Never useTimeout=0in production. - Verify the report runs correctly in the Workday UI with the same prompt values before debugging the driver.
Cause 2: Report uses multiple related business objects
Reports that include columns from multiple related business objects — rather than exclusively the primary business object — can cause the driver to hang when attempting a data fetch. This is a structural constraint of the CData Reports driver and cannot be resolved through connection string tuning alone.
Fix: Follow these steps:
- Confirm whether the report uses multiple business objects by reviewing it in the Workday UI
- Consider switching to SOAP mode, which handles multi-object data models natively
- If the report must stay in Reports mode, work with your Workday admin to simplify the report structure where possible — though this is often not feasible for complex production reports
Issue #6: Queries are slow or time out on large reports
Cause: Default page size and timeout settings may be unsuitable for large or wide reports.
Fix: Tune Pagesize and Timeout. Note that Pagesize controls how many rows are fetched per API call during reads — this is the correct parameter for managing read payload size:
Pagesize=300 # Reduce from default 500 to lower per-request memory and timeout risk
Timeout=120 # Increase from default 60 if legitimate long-running pages are timing out
MaxRows=100000 # Add a row ceiling during development to prevent unbounded pulls
Note on BatchSize
BatchSize is sometimes confused with Pagesize but controls something entirely different. BatchSize specifies the number of rows per batch in write operations (inserts/updates) only — it has no effect on read queries. The default value is 0 (submit entire batch as one request). For read workload tuning, always use Pagesize, not BatchSize.
Issue #7: Authentication failures
Fix: Follow these steps:
- Verify credentials are correct
- For SOAP with Basic auth: Username format is
{user}@{tenant}(driver handles this) - For OAuth: Verify client ID/secret are valid
- Check user has appropriate Workday security permissions
- Note: Basic authentication (
AuthScheme=Basic) is only supported in SOAP and Reports modes. If using WQL or REST mode, OAuth is required.
Issue #8: Column count errors or missing columns on wide tables
Cause: Workday data sources can have hundreds or thousands of columns, exceeding limits in Starburst.
Fix: Set UseSplitTables=true in the connection string. The driver will split large tables into multiple tables of 50–100 columns each, linked by a primary key that can be used for JOINs.
Support
For CData Workday JDBC driver support: