JDBC Driver for SAP ByDesign

Build 25.0.9434

Establishing a Connection

Creating a JDBC Data Source

You can create a JDBC data source to connect from your Java application. Creating a JDBC data source based on the CData JDBC Driver for SAP ByDesign consists of three basic steps:

  1. Add the driver JAR file to the classpath. The JAR file is located in the lib subfolder of the installation directory. Note that the .lic file must be located in the same folder as the JAR file.
  2. Provide the driver class. For example: 
    cdata.jdbc.sapbydesign.SAPByDesignDriver
  3. Provide the JDBC URL. For example: 
    jdbc:sapbydesign:URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

or

jdbc:cdata:sapbydesign:URL=https://my999999.businessbydesign.cloud.sap;User=username;Password=password;ServiceType=AnalyticsService;ServiceName=servicename;

    You can use the second format above whenever there is a conflict in your application between drivers using the same URL format to ensure you are using the CData driver. The URL must start with either "jdbc:sapbydesign:" or "jdbc:cdata:sapbydesign:" and can include any of the connection properties in name-value pairs separated with semicolons.

This section documents how to provide authentication for your account and service type and then connect.

Authenticate a SAPByDesign Account

Set the following connection properties to connect to SAP ByDesign.

Connect to a Analytical Service

  • URL: Set this to the Url of your SAP ByDesign site. For example, https://test.sapbydesign.com.
  • ServiceType: If you want to retrieve the reports of a analytical service, specify ServiceType=AnalyticsService;.
  • ServiceName: The name of the service you want to retrieve data from. Only none or one service must be specified. If you want to specify a list of services, see BrowsableSchemas.

    If you're not sure what service to specify, you can always query the sys_schemas to list available services.

  • User: Set this to the username of your account.
  • Password: Set this to the password of your account.

Analytical Service Connection String Example: 

Url=https://test.sapbydesign.com;ServiceType=AnalyticsService;ServiceName=cc_home_analytics.svc;User=Test;Password=test;

Connect to a Custom Service

  • URL: Set this to the Url of your SAP ByDesign site. For example, https://test.sapbydesign.com.
  • ServiceType: If you have a custom service you want to retrieve data from, specify ServiceType=CustomService;.
  • ServiceName: The name of the service you want to retrieve data from. Only none or one service must be specified. If you want to specify a list of services, see BrowsableSchemas.

    If you're not sure what service to specify, you can always query the sys_schemas to list available services.

  • User: Set this to the username of your account.
  • Password: Set this to the password of your account.

Custom Service Connection String Example: 

Url=https://test.sapbydesign.com;ServiceType=CustomService;ServiceName=khsalesorder;User=Test;Password=test;

Connect to the ODataDataSource API

  • URL: Set this to the Url of your SAP ByDesign site. For example, https://test.sapbydesign.com.
  • ServiceType: If you want to query OData Data Source API( odata/analytics/ds) , specify ServiceType=ODataDataSource.
  • ServiceName: The name of the service you want to retrieve data from. Only none or one service must be specified. If you want to specify a list of services, see BrowsableSchemas.

    If you're not sure what service to specify, you can always query the sys_schemas to list available services.

  • User: Set this to the username of your account.
  • Password: Set this to the password of your account.

ODataDataSource Connection String Example: 

Url=https://test.sapbydesign.com;ServiceType=ODataDataSource;ServiceName=Customer.svc;User=Test;Password=test;

Authenticate with Azure AD (SSO)

If your organization uses Microsoft Entra ID (formerly Azure Active Directory) to manage user identities, you can authenticate to SAP ByDesign using Single Sign-On (SSO). This method allows users to connect without directly supplying a username or password.

To use Azure AD authentication, set the following connection properties:

  • URL: Set this to the URl of your SAP ByDesign site.
  • ServiceType: Specify the type of service: AnalyticsService, CustomService, or ODataDataSource.
  • ServiceName: Set this to the name of the service to connect to.
  • AuthScheme: Set this to AzureAD.
  • InitiateOAuth: Set this to GETANDREFRESH to allow automatic token acquisition and refresh.
  • OAuthClientId: Set this to the OAuth client ID of your SAP ByDesign application. This is separate from your Entra ID app registration.
  • SSOProperties: A semicolon-delimited string containing Azure AD configuration details. See below for supported keys.
Azure AD Connection String Example: 
URL=https://my999999.businessbydesign.cloud.sap;
ServiceType=AnalyticsService;
ServiceName=cc_home_analytics.svc;
AuthScheme=AzureAD;
InitiateOAuth=GETANDREFRESH;
OAuthClientId=SAP_APP_CLIENT_ID;
SSOProperties='AzureTenant=TENANT_ID;OAuthClientId=AZURE_AD_APP_CLIENT_ID;OAuthClientSecret=AZURE_AD_CLIENT_SECRET;CallbackURL=http://localhost:33333'

Supported SSOProperties keys:

The SSOProperties connection property contains a semicolon-delimited list of key-value pairs required for OAuth-based authentication with Microsoft Entra ID (Azure AD). These keys correspond to fields used in the OAuth 2.0 authorization code flow, which Entra ID implements for SSO. The driver uses these values to construct the necessary requests to Microsoft's identity platform.

  • AzureTenant: The Entra ID (Azure AD) tenant ID, which can be a GUID or verified domain.
  • OAuthClientId: The client ID of your Entra ID app registration. This is not the same as the SAP app client ID.
  • OAuthClientSecret: The client secret of your Entra ID app.
  • CallbackURL: (optional) The redirect URI registered in Entra ID. The default is http://localhost:33333.
  • Scope: (optional) The OAuth scopes to request during authentication.

Note: There are two OAuthClientId values:

  • The top-level OAuthClientId refers to the app registered in SAP ByDesign.
  • The OAuthClientId inside SSOProperties refers to the app registered in Microsoft Entra ID.
For details on registering a Microsoft Entra ID application, see Creating an Entra ID (Azure AD) Application

Add a new custom ODATA service

  • In the SAP ByDesign work center view, click on "Application and User Management".
  • Select "OData Services".
  • In the dropdown list, select "Custom OData Services".
  • Now you should see a list of your current custom services. To add a new one click on "New".

SAP ByDesign URL Restrictions

The SAP ByDesign driver enforces URL restrictions to avoid exceeding the maximum of allowed URI length, which causes the service to throw "URI Too Long" error"

By default, the length of the columns in the projection is limited to 1000 characters. If the columns selected in the projection surpass this limit, the driver drops the projection specification and retrieves all fields. This may impact performance because of service response delay and increased payload.

In the case of the analytical service (ServiceType=AnalyticsService), the driver throws an error indicating you must reduce the number of columns in the projection. In addition, the server-side filter length is restricted to 1000 characters for the same reasons. If the generated filter length surpasses this limit, the driver drops the additional filters and handles them client-side.

In SAP ByDesign, you can configure or disable these limitations by using the MaxSelectLength and MaxFilterLength hidden connection properties. These properties both default to 1000 characters. If your service does not have these restrictions, set the properties to -1 to disable the length limitations.

Copyright (c) 2025 CData Software, Inc. - All rights reserved.
Build 25.0.9434