Live Connect - Getting Started - Text

Anubhav P · yesterday

Getting started with Live Connect in ServiceNow

A practical guide to connecting your BI tools — Power BI, Tableau, Excel, and others — directly to ServiceNow data using standard SQL, without building ETL pipelines or moving data out of your instance.

Why Live Connect?

If your team wants to report on ServiceNow data in Power BI or Tableau, the instinctive answer is to extract it — pipe it to Snowflake, Databricks, or an internal data lake, and query it there. That works, but it creates a problem: the moment data leaves ServiceNow, it starts aging, and someone has to maintain the pipeline that keeps it fresh.

Live Connect is ServiceNow's answer to this. It exposes your RaptorDB Pro database as a standard SQL endpoint — your BI tool connects via a JDBC or ODBC driver, runs SQL queries, and gets back current results. No data movement, no pipeline, no staleness.

Your existing ACLs govern what each service account can see — there is no separate security model to replicate in a third-party store. And because queries push down to RaptorDB Pro, cross-table joins, aggregations, and filters run at the database, not on the BI tool side.

What it's for: Live Connect is designed for BI and analytics workloads — interactive queries, dashboards, and reports. It is read-only by design (SELECT only). It is not intended for mass data export, replication pipelines, or continuous high-frequency data feeds. For event-driven streaming, use Direct Connect (Kafka) instead.

Live Connect vs Table API

A common question is how Live Connect differs from the Table API many teams already use for integrations. They were designed for different jobs — understanding the distinction upfront prevents the wrong tool being applied to an analytics use case.

	Table API	Live Connect
Protocol	REST (per table)	JDBC/ODBC over REST
Operations	Full CRUD	Read-only (SELECT)
Scope	One table at a time	Multi-table JOINs
Row Limit	10,000 rows per call	No row limit (5-min timeout)
Availability	All instances	RaptorDB Pro only
Designed For	Point integrations, CRUD	BI tools, Analytics

The key difference: Table API is one table at a time, capped at 10,000 rows per call — fine for integrations, wrong for analytics. Live Connect pushes SQL joins, aggregations, and filters down to RaptorDB Pro, so complex analytical queries return only the result set rather than raw rows for processing elsewhere.

Core concepts

Four concepts to understand before configuring anything.

Service accounts

Live Connect connections authenticate with a service account using Basic Auth. Using a service account (rather than a personal user account) ensures dashboards continue working if the original author leaves the organisation, and allows multiple BI users to share the same controlled access without sharing individual credentials.

Table-level ACL (egress_sql)

An admin must explicitly grant the egress_sql ACL on each table before it is queryable via Live Connect. This is mandatory and cannot be bypassed — even a system administrator cannot query a table via Live Connect until it has been explicitly opened. Row-level and field-level ACLs are also enforced by default, meaning users see only the data their roles permit.

WDF token metering

Every Live Connect query consumes Workflow Data Fabric (WDF) tokens at a rate of 1 MB per token. Tokens are shared across all WDF-metered capabilities on your entitlement. There is also a 500 API calls per hour rate limit, shared across all service accounts and connections on the instance. This limit resets at the top of each wall-clock hour.

Query timeout

Any query that runs longer than 5 minutes (300 seconds) is automatically cancelled — from first byte received to last byte returned, including both execution and result streaming. No partial data is returned. Design queries with selective filters and targeted column lists; avoid SELECT * on large tables. The timeout can be extended via a ServiceNow Support case, though increasing it may impact instance performance.

Before you begin

Prerequisites: RaptorDB Pro subscription (Australia release or Zurich P8 backport). WDF token entitlement. Admin role on the ServiceNow instance. Client machine running your BI tool (Windows for ODBC; either platform for JDBC).

RaptorDB Pro is required. Live Connect is not available on RaptorDB Standard or MariaDB-based instances. Confirm your instance is on RaptorDB Pro before proceeding.
Admin access is needed for setup. Plugin installation, ACL configuration, IP whitelisting, and service account creation all require admin privileges. Coordinate with your instance admin if you do not have this access yourself.
Know your client IP addresses in advance. Live Connect requires admins to whitelist the IP address of each client machine that will connect. Gather the IPs for all users and servers — including BI tool servers for server-mode connections — before starting.

Getting started: step-by-step

Complete setup flow from a fresh instance to a working BI tool connection.

Install the SQL API server plugin. Navigate to All > Application Manager, search for "SQL API" or "Live Connect", and install the plugin. This activates the SQL endpoint on your instance. No instance restart is required.
Create a service account. In All > User Administration > Users, create a dedicated user for BI tool access. Assign it the read role for the tables you plan to expose. Use a service account rather than a personal user account so that dashboards do not break if someone leaves the organisation.
Grant egress_sql ACL on each table. Navigate to All > System Security > Access Control (ACL). For each table you want to expose, create or find the ACL record and add the egress_sql operation, granting it to the service account's role. This step is mandatory for every table — no table is queryable until explicitly opened.
Whitelist client IP addresses. Navigate to the IP restriction settings in All > System Properties and add the IP addresses of all machines that will connect to Live Connect. Connections from non-whitelisted IPs are rejected. For BI server environments (Tableau Server, Power BI Gateway), whitelist the server IP, not the end-user's machine IP.
Download and install the client driver. On the ServiceNow Store, search for "SQL API client" — this package includes both the ODBC and JDBC drivers. Install the driver appropriate for your BI tool and operating system. ODBC is typical for Windows-based tools like Power BI Desktop; JDBC works on any platform.
Configure the connection in your BI tool. Use your instance URL as the server, the service account username and password for authentication, and select the ODBC or JDBC driver you just installed. In Power BI, choose Import mode — Direct Query is not supported. Once connected, your ServiceNow tables appear as a database with columns you can query directly.
Run a test query. Start with a simple, bounded query to confirm the connection and ACLs are working:
```
SELECT number, priority, state FROM incident WHERE state = 6 LIMIT 100;
```
If you get results, the setup is complete. If the table is not found, check the ACL grant. If the connection is refused, check the IP whitelist.

Writing effective queries

Live Connect supports a rich subset of ANSI SQL — joins, aggregations, window functions, date operations, subqueries, and more. Here are the patterns that matter most for ServiceNow data.

Use DV() to resolve display values

Reference fields in ServiceNow store sys_ids, and choice fields store integers. The DV() function resolves these to human-readable labels for use in reports:


SELECT number, DV(priority) AS priority_label, DV(assignment_group) AS team
FROM incident
WHERE state IN (1, 2, 3);

Cross-table joins — where Live Connect earns its keep

With Table API you would pull incidents and users separately, then join them in your BI tool or data warehouse. Live Connect pushes the join to the database:


SELECT i.number, i.priority, u.name AS assigned_to, u.department
FROM incident i
LEFT JOIN sys_user u ON i.assigned_to = u.sys_id
WHERE i.state IN (1, 2, 3);

Aggregate at the database, not the BI tool

Push GROUP BY, COUNT, AVG, and SUM server-side so only the summary result crosses the wire:


SELECT date_trunc('month', opened_at) AS month,
  DV(priority) AS priority,
  COUNT(*) AS incident_count,
  AVG(CAST(resolve_time AS FLOAT) / 60.0) AS avg_resolve_hours
FROM incident
WHERE opened_at >= CAST(NOW() AS DATE) - INTERVAL '12 months'
GROUP BY month, priority
ORDER BY month DESC;

Querying archive data too: If you use Live Archive, archived records live in ar_incident, ar_problem, etc. You can query them with the same SQL syntax — just note that archive tables need their own egress_sql ACL grant (separate from the live table). Use UNION ALL to combine live and archive results into a single historical view.

BI tool compatibility notes

Live Connect has been tested with the following clients. A few tool-specific notes to save you time.

Power BI — use Import mode, not Direct Query. Direct Query sends a query to the data source on every user interaction (every click, every filter) — this would exhaust the 500 API calls/hour limit within minutes of a team using a shared dashboard. Import mode does a single pull; users slice and dice locally and click refresh when they need updated data.
Tableau Desktop and Tableau Server — fully supported via JDBC. For Tableau Server, whitelist the server's IP, not the desktop user's IP. Use a dedicated service account for published workbooks.
Microsoft Excel — connect via ODBC (Windows). Use Get Data > From Other Sources > From ODBC. Useful for ad hoc analysis without a full BI platform.
DBeaver and other SQL clients — ideal for exploring the schema and validating queries before embedding them in a BI tool. Connect via JDBC, then browse tables and test SQL interactively. This is the recommended way to explore which columns are available before building a report.
Looker and Looker Studio — supported. Looker's LookML can model ServiceNow tables via the JDBC connection; Looker Studio connects via the JDBC driver in the same way as other tools.

Not supported:

Power BI Direct Query mode
Data replication tools (Fivetran, dbt) — not an intended use case
DML or DDL operations (INSERT, UPDATE, DELETE, CREATE, DROP)
Parameterized queries or prepared statements
Self-hosted / hyperscaler deployments — on roadmap, not available today

Tips before you start

Explore the schema with a SQL client first. Before building Power BI or Tableau reports, connect via DBeaver and run SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'incident'; to see what columns are available. A few minutes of schema exploration prevents a lot of report-building rework.
Start with tight date filters. Develop queries with a narrow date range (for example, last 30 days) to get fast results. Expand the range incrementally only once the query logic is correct. Starting with a multi-year full-table query is the most common way to hit the 5-minute timeout unnecessarily.
Name your columns explicitly. Avoid SELECT *. Column selection is proportional to I/O cost in the columnar engine — selecting only the columns you need makes queries faster and reduces WDF token consumption.
Account for the shared rate limit. The 500 API calls/hour limit is per instance, shared across all service accounts and all scheduled BI refreshes. If three dashboards each refresh every 10 minutes, that is 18 calls/hour before anyone runs an ad hoc query. Plan your refresh schedules and service account layout accordingly.
All traffic is TLS-encrypted. All communication between the JDBC/ODBC driver and your ServiceNow instance is encrypted in transit. No additional configuration is needed — encryption is on by default.

What to explore next

Zero Copy Connectors — bring in data from external sources (Snowflake, S3, databases) without copying it into ServiceNow, then query it alongside native tables via a single Live Connect connection for unified analytics.
SQL command reference — the full list of supported SQL functions (approximately 300) is available in the product documentation. Key categories: aggregate functions (COUNT, AVG, SUM), date functions (date_trunc, date_part), string functions (CONCAT_WS, TRIM), and window functions (RANK).
Live Archive with Live Connect — if your organisation archives records using Live Archive, you can query both live and archived data via Live Connect using UNION ALL. Grant the egress_sql ACL on the ar_* tables to enable this.