Applications Systems

Using ODBC User Experience Monitor in SAM with Oracle over TCP/TLS (DSN‑less Oracle connection strings)

Attempting to use a PowerShell .NET Oracle provider connection string directly in the ODBC User Experience Monitor may fail with Oracle errors. Use macros such as ${Node.DNS}, ${Node.Caption}, ${N=SwisEntity;M=DNS}, and ${UserNotes} inside the ODBC UX Connection String.

First published date

3/11/2026 5:23 PM

Last published date

3/11/2026 5:23 PM

Overview

This article describes how to configure the ODBC User Experience Monitor in SolarWinds Server & Application Monitor (SAM) to connect to an Oracle database over TCP/TLS using a DSN‑less connection string.

It also clarifies:

  • Why a connection string that works in PowerShell (.NET Oracle provider) may fail in the SAM ODBC User Experience Monitor.

  • Which variables are actually supported in the Connection String field for ODBC UX.

  • How to avoid maintaining multiple tnsnames.ora files on each polling engine.

Product section

Server Application Monitor

Cause

  • An Oracle ODBC DSN‑less connection string is misconfigured with server= instead of Dbq=.

  • The PowerShell string tests successfully with a different provider (System.Data.OracleClient), but that syntax is not valid for the Oracle ODBC driver used by ODBC UX.

  • Attempting to use node/entity macros that are not supported in the ODBC UX Connection String field.

    1. Mixing provider types

    Initially using a .NET Oracle provider connection string in PowerShell:

    $Assembly = [System.Reflection.Assembly]::LoadWithPartialName("System.Data.OracleClient")
$OracleConnectionString = "SERVER=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(Host=10.5.4.200)(Port=50991))
                                      (CONNECT_DATA=(SERVICE_NAME=CECLDV)));uid=...;pwd=...;"

    This works with System.Data.OracleClient using the SERVER= keyword.

    The ODBC User Experience Monitor, however, uses:

    • System.Data.Odbc → Oracle ODBC driver (e.g. Oracle in OracleOdbcDriver).

    The Oracle ODBC driver expects ODBC‑style keywords (e.g. Driver=, Dbq=, Uid=, Pwd=), not SERVER=. Simply copying the .NET provider connection string into ODBC UX is invalid.

    2. Incorrect ODBC keyword (server= instead of Dbq=)

    In the failing case, the ODBC connection string is effectively:

    Driver={Oracle in OracleOdbcDriver};
server="(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = ...)(PORT = 50991))
                  (CONNECT_DATA = (SERVER = DEDICATED)(SERVICE_NAME = CECLDV)))";
Uid=...;
Pwd=...;

    For Oracle ODBC, the correct key is typically Dbq=, which can accept either:

    • A TNS alias (resolved via tnsnames.ora), or

    • A full (DESCRIPTION=...) connect descriptor.

    Because the driver doesn’t know how to interpret server=... in this context, it fails to build a valid connect descriptor and returns ORA‑12560 / Driver's SQLSetConnectAttr failed.

    3. Unsupported variables in ODBC UX Connection String

    Per ODBC UX documentation, only these variables are supported inside the Connection String field:

    • ${IP} – IP address of the database server (node)

    • ${USER} – credential username

    • ${PASSWORD} – credential password

    Node/SwisEntity macros such as:

    • ${Node.DNS}

    • ${Node.Caption}

    • ${N=SwisEntity;M=DNS}

    • ${UserNotes}

    are not expanded in this field and are passed as literal text. This is a current product limitation; a feature request has been logged to extend support.

    Community usage on THWACK reinforces this pattern. For example, in a PostgreSQL ODBC UX thread, the connection string uses only ${IP}, ${USER}, ${PASSWORD} and no node macros:

    Driver={PostgreSQL Unicode};Server=${IP};Port=5432;DataBase=<MYDB>;Uid=${USER};Pwd=${PASSWORD};

Resolution

Part A – Oracle client / ODBC prerequisites (high‑level)

  1. Install a TCP/TCPS‑capable Oracle client with ODBC on the polling engine (or agent host):

    • Ensure it includes the Oracle ODBC driver (32‑ or 64‑bit as needed).

  2. Configure Oracle client for TCP or TCPS (DBA task):

    • Ensure tnsnames.ora and sqlnet.ora (and wallet, if using TCPS) are correct on the polling engine.

    • Verify you can connect via sqlplus or a simple Oracle client from that same host.

    • If you see ORA‑28759, the wallet path/permissions are wrong and must be fixed by the Oracle DBA/security team before SAM can succeed.

  3. Optionally, create a System DSN pointing to either:

    • A TNS alias, or

    • A connect descriptor (if you prefer DSN‑based configuration).

Note: Detailed Oracle TLS/wallet configuration is outside SolarWinds Support scope and must be handled by the customer’s Oracle DBA/security team.

Part B – Configure the ODBC User Experience Monitor with a DSN‑less Oracle connection string

  1. Open the ODBC User Experience Monitor component

    • In SAM, edit the application template or assigned component.

    • Ensure the bitness (x86 or x64) matches the installed Oracle ODBC driver on the polling engine.

  2. Set the credential

    • Use a credential that has permission to connect to the Oracle database (same user as your working sqlplus/PowerShell test, if applicable).

  3. Use a DSN‑less connection string with Dbq=

    Example 1 – Hard‑coded host and service name

    Driver={Oracle in OracleOdbcDriver};
Dbq=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=d00632-d-02803.fcpd.fcbint.net)(PORT=50991))
                  (CONNECT_DATA=(SERVICE_NAME=CECLDV)));
Uid=${USER};
Pwd=${PASSWORD};

    • Driver must exactly match the Oracle ODBC driver name as seen in ODBC Data Source Administrator.

    • Dbq contains the full (DESCRIPTION=...) connect descriptor.

    • ${USER} and ${PASSWORD} are replaced by the component’s assigned credential.

    Example 2 – Using ${IP} instead of hostname

    Driver={Oracle in OracleOdbcDriver};
Dbq=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=${IP})(PORT=50991))
                  (CONNECT_DATA=(SERVICE_NAME=CECLDV)));
Uid=${USER};
Pwd=${PASSWORD};

    • This avoids hard‑coding the host, but may not be compatible with strict TLS/SSL certificate checks if the cert is bound to the FQDN rather than the IP.

  4. Save and test the component

    • Use Test in the component editor.

    • If the Oracle client and connection string are correct, the test should succeed and return your query’s numeric result.

Part C – Variable usage and template strategy

  1. Supported variables in ODBC UX Connection String

    • Supported:

      • ${IP}, ${USER}, ${PASSWORD}.

    • Not supported (current limitation):

      • ${Node.DNS}, ${Node.Caption}, ${N=SwisEntity;M=DNS}, ${UserNotes}.

  2. Recommended template strategy

    • Create one ODBC UX template with a parameterized, DSN‑less string, for example:

      Driver={Oracle in OracleOdbcDriver};
Dbq=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=${IP})(PORT=50991))
                  (CONNECT_DATA=(SERVICE_NAME=CECLDV)));
Uid=${USER};
Pwd=${PASSWORD};

    • Assign this template to multiple nodes.

    • For databases with different ports or service names, use Manage Assigned Application Monitors to override the Connection String per assignment instead of cloning the entire template.

Additional Notes

  • If the same DSN‑less connection string works in PowerShell but not in ODBC UX, verify:

    • You are not accidentally using the .NET Oracle provider syntax in ODBC UX.

    • You are using Dbq= and ODBC‑style keywords.

    • The correct Oracle ODBC driver and bitness are installed on the polling engine.

  • Any persistent Oracle errors like ORA‑28759 or other wallet/certificate issues must be resolved by the Oracle DBA/security team, not by SolarWinds Support.

References and Supporting Documentation

SolarWinds Documentation

THWACK Community Threads

These references provide both official product behavior and real‑world examples to support the configuration steps and limitations described in this article.