﻿<?xml version="1.0" encoding="utf-8"?>

<!-- EngineVersion = Java version -->
<ApiConfig Name="Salesforce Data Cloud (Data 360)"
           Slug="salesforce-data-cloud-connector"
           Type="JDBC"
           Category="customer-data"
           Id="C89A0B30-087C-5EDF-B59D-607D0474263F"
           Version="1"
           EngineVersion="8"
           Desc="Read Salesforce Data Cloud (Data 360) with SQL. Query data graphs and lake objects from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools -- almost no coding required."
           Logo="https://cdn.zappysys.com/api/Images/logos/salesforce-data-cloud-connector.png"
           HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html">

    <VersionHistory>
      <Change Ver="1" Date="2026-09-14" Type="New">Initial JDBC Bridge catalog version. Hands-free Maven JAR download. Auth Notes and SQL examples for ODBC apps.</Change>
    </VersionHistory>
    <Template>
        <Param Name="DriverDownloadPageLink"
               Value="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-java.html" />
        <Param Name="MvnRepositoryDriverDownloadLink"
               Value="https://mvnrepository.com/artifact/com.salesforce.datacloud/jdbc" />
        <Param Name="DriverDownloadLinks"
               Hidden="True"
               Value="jdbc-0.29.0-shaded.jar=https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/jdbc-0.29.0-shaded.jar" />
    </Template>

    <Auths>
        <Auth Name="Login"
              Label="Production (login.salesforce.com)"
              ConnStr="jdbc:salesforce-datacloud://[$LoginHost$]"
              HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="com.salesforce.datacloud.jdbc.DataCloudJDBCDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. com.salesforce.datacloud.jdbc.DataCloudJDBCDriver)." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-java.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\jdbc-0.29.0-shaded.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/" />
                <Param Name="LoginHost" Label="Login host" Required="True" Value="login.salesforce.com" Desc="Salesforce login host (e.g. login.salesforce.com)." HelpLink="https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/" />
                <Param Name="UserName" Label="User name" Required="True" Desc="Salesforce integration username (not a personal mailbox if this DSN will refresh unattended)." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="Password" Label="Password" Required="True" Secret="True" Desc="Salesforce password. Append the security token if your org requires it." HelpLink="https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm" />
                <Param Name="clientId" Label="Client ID (Consumer Key)" Required="True" Desc="Consumer Key from the External Client App / Connected App." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="clientSecret" Label="Client Secret (Consumer Secret)" Required="True" Secret="True" Desc="Consumer Secret from the same app. Must match the app whose callback is https://zappysys.com/oauth." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="dataspace" Label="Data space" Required="False" Value="default" Desc="Data Cloud data space. Default is default." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Follow these steps to create a Salesforce <strong>External Client App</strong> (or a legacy Connected App) so the Data Cloud JDBC driver can authenticate. JDBC Bridge then exposes Data Cloud SQL to Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<div class="alert alert-warning">
  <strong>WARNING:</strong> As of 21 Feb 2026 Salesforce no longer lets you create new Connected Apps. Use an <em>External Client App</em>. If you already have a Connected App, you can keep using it with username/password + consumer key/secret.
  Do not use a personal employee login for unattended jobs (Power BI refresh, Linked Server, ADF). Use a dedicated integration user.
</div>
<ol>
  <li>Sign in to Salesforce Setup as an administrator.</li>
  <li>Go to <strong>App Manager</strong> (or <strong>External Client Apps</strong>) and create a new External Client App / Connected App. Enable <strong>OAuth Settings</strong>.</li>
  <li>
    <p><strong>Callback URL</strong> (Redirect URI) must be exactly:</p>
    <p><code>https://zappysys.com/oauth</code></p>
    <div class="alert alert-info">
      <strong>INFO:</strong> Use this ZappySys capture page so the authorization <code>code</code> appears in the page title and URL during the 3-legged dance.
      Do <em>not</em> use localhost, a Salesforce "try it" page, or any other URL -- those often redirect again or drop the query string, so the code is not visible.
    </div>
  </li>
  <li>Select OAuth scopes your org requires for Data Cloud query (typically includes Data Cloud / CDP query and API access). Save.</li>
  <li>Open <strong>Manage Consumer Details</strong> and copy <strong>Consumer Key</strong> (Client ID) and <strong>Consumer Secret</strong> (Client Secret).</li>
  <li>Paste username, password (plus security token if your org requires it), Client ID, and Client Secret into this Auth profile.</li>
  <li>If you complete a browser authorization, wait until the browser lands on <code>https://zappysys.com/oauth</code> and the <code>code</code> is in the title or address bar.</li>
  <li>Finish the wizard. Then click <strong>Test Connection</strong> on the DSN Main UI (the wizard does not run Test Connection).</li><li>Done. You can query from C#, Python, PowerShell, and ODBC apps.</li>
</ol>]]>
            </Notes>
        </Auth>
        <Auth Name="Sandbox"
              Label="Sandbox (test.salesforce.com)"
              ConnStr="jdbc:salesforce-datacloud://[$LoginHost$]"
              HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="com.salesforce.datacloud.jdbc.DataCloudJDBCDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. com.salesforce.datacloud.jdbc.DataCloudJDBCDriver)." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-java.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\jdbc-0.29.0-shaded.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/" />
                <Param Name="LoginHost" Label="Login host" Required="True" Value="test.salesforce.com" Desc="Salesforce login host (e.g. test.salesforce.com)." HelpLink="https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/" />
                <Param Name="UserName" Label="User name" Required="True" Desc="Sandbox integration username." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="Password" Label="Password" Required="True" Secret="True" Desc="Sandbox password, plus security token if required." HelpLink="https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm" />
                <Param Name="clientId" Label="Client ID (Consumer Key)" Required="True" Desc="Consumer Key from the sandbox External Client App." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="clientSecret" Label="Client Secret (Consumer Secret)" Required="True" Secret="True" Desc="Consumer Secret. Callback URL must be https://zappysys.com/oauth." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="dataspace" Label="Data space" Required="False" Value="default" Desc="Data Cloud data space. Default is default." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Follow these steps to create a Salesforce <strong>External Client App</strong> (or a legacy Connected App) so the Data Cloud JDBC driver can authenticate. JDBC Bridge then exposes Data Cloud SQL to Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<div class="alert alert-warning">
  <strong>WARNING:</strong> As of 21 Feb 2026 Salesforce no longer lets you create new Connected Apps. Use an <em>External Client App</em>. If you already have a Connected App, you can keep using it with username/password + consumer key/secret.
  Do not use a personal employee login for unattended jobs (Power BI refresh, Linked Server, ADF). Use a dedicated integration user.
</div>
<ol>
  <li>Sign in to Salesforce Setup as an administrator.</li>
  <li>Go to <strong>App Manager</strong> (or <strong>External Client Apps</strong>) and create a new External Client App / Connected App. Enable <strong>OAuth Settings</strong>.</li>
  <li>
    <p><strong>Callback URL</strong> (Redirect URI) must be exactly:</p>
    <p><code>https://zappysys.com/oauth</code></p>
    <div class="alert alert-info">
      <strong>INFO:</strong> Use this ZappySys capture page so the authorization <code>code</code> appears in the page title and URL during the 3-legged dance.
      Do <em>not</em> use localhost, a Salesforce "try it" page, or any other URL -- those often redirect again or drop the query string, so the code is not visible.
    </div>
  </li>
  <li>Select OAuth scopes your org requires for Data Cloud query (typically includes Data Cloud / CDP query and API access). Save.</li>
  <li>Open <strong>Manage Consumer Details</strong> and copy <strong>Consumer Key</strong> (Client ID) and <strong>Consumer Secret</strong> (Client Secret).</li>
  <li>Paste username, password (plus security token if your org requires it), Client ID, and Client Secret into this Auth profile.</li>
  <li>If you complete a browser authorization, wait until the browser lands on <code>https://zappysys.com/oauth</code> and the <code>code</code> is in the title or address bar.</li>
  <li>Finish the wizard. Then click <strong>Test Connection</strong> on the DSN Main UI (the wizard does not run Test Connection).</li><li>Done. You can query from C#, Python, PowerShell, and ODBC apps.</li>
</ol>]]>
            </Notes>
        </Auth>
        <Auth Name="JwtBearer"
              Label="JWT Bearer (External Client App)"
              ConnStr="jdbc:salesforce-datacloud://[$LoginHost$]"
              HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="com.salesforce.datacloud.jdbc.DataCloudJDBCDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. com.salesforce.datacloud.jdbc.DataCloudJDBCDriver)." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-java.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\jdbc-0.29.0-shaded.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/" />
                <Param Name="LoginHost" Label="Login host" Required="True" Value="login.salesforce.com" Desc="Salesforce login host (e.g. login.salesforce.com)." HelpLink="https://repo1.maven.org/maven2/com/salesforce/datacloud/jdbc/0.29.0/" />
                <Param Name="UserName" Label="User name" Required="True" Desc="Integration username for JWT Bearer." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="clientId" Label="Client ID (Consumer Key)" Required="True" Desc="Consumer Key from the External Client App." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="privateKey" Label="Private key (PEM)" Required="True" Secret="True" Desc="Paste the PEM private key text for JWT Bearer (e.g. -----BEGIN PRIVATE KEY-----). This is not a file path. Never ship a key in XML or source control." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
                <Param Name="dataspace" Label="Data space" Required="False" Value="default" Desc="Data Cloud data space. Default is default." HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/jdbc-setup.html" />
            </Params>
            <Notes>
                <![CDATA[<p>JWT Bearer Flow with an External Client App (current Salesforce recommendation for JDBC). No refresh-token dance; you still register the callback URL so the app is valid.</p>
<ol>
  <li>Create an External Client App in Salesforce Setup. Enable OAuth and JWT Bearer.</li>
  <li>Callback URL must be exactly <code>https://zappysys.com/oauth</code> (do not use localhost or another capture URL).</li>
  <li>Upload or generate a certificate. Download the <strong>private key</strong> as PEM (<code>-----BEGIN PRIVATE KEY-----</code>).</li>
  <li>Copy the Consumer Key (Client ID).</li>
  <li>Paste Client ID, integration username, and the full PEM into this profile. Do not check a private key into source control.</li>
  <li>Finish the wizard. Then click <strong>Test Connection</strong> on the DSN Main UI (the wizard does not run Test Connection).</li><li>Done. You can query from C#, Python, PowerShell, and ODBC apps.</li>
</ol>]]>
            </Notes>
        </Auth>
    </Auths>

    <Examples>
        <Example Default="True" Group="ODBC" Slug="list-tables" Label="List tables" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Lists tables available to this connection. Use this in Power BI or a SQL Server Linked Server to confirm the catalog before building reports.</p>]]></Desc>
            <Code>
                <![CDATA[SHOW TABLES]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-rows" Label="Select rows" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Returns rows from <code>my_catalog.MyTable</code>. Replace the identifier with your catalog object. Works in Excel, SSRS, and Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM my_catalog.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-rows" Label="Filter with WHERE" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Returns matching rows from <code>my_catalog.MyTable</code>. Swap the column and literal for your schema.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM my_catalog.MyTable
WHERE id = 1]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="join-tables" Label="Join tables" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Joins two tables on a key. Use in Azure Data Factory or SSIS when you need a combined extract.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT a.id, a.name, b.amount
FROM my_catalog.MyTable AS a
JOIN my_other_table AS b ON a.id = b.parent_id]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="group-by" Label="Aggregate with GROUP BY" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Counts rows per group. Typical Power BI import pattern before a visual.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM my_catalog.MyTable
GROUP BY status]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="having" Label="Filter groups with HAVING" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Keeps groups whose count is at least 10.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM my_catalog.MyTable
GROUP BY status
HAVING COUNT(*) >= 10]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="order-limit" Label="Order and limit" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Returns the first 100 rows ordered by a column. Useful for preview in Excel or Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM my_catalog.MyTable
ORDER BY id
LIMIT 100]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="count-all" Label="Count rows" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Returns the number of rows in <code>my_catalog.MyTable</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT COUNT(*) AS row_count FROM my_catalog.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="case-expr" Label="CASE expression" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Maps a column to labels with <code>CASE</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id,
       CASE WHEN status = 'A' THEN 'Active' ELSE 'Other' END AS status_label
FROM my_catalog.MyTable]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-list" Label="Select specific columns" HelpLink="https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/data-cloud-sql.html">
            <Desc><![CDATA[<p>Returns a column list instead of star. Prefer this in Linked Server views.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id, name, status
FROM my_catalog.MyTable]]>
            </Code>
        </Example>
    </Examples>
</ApiConfig>
