Microsoft Dynamics 365 JDBC 6.0.0
- Last Updated:March 24, 2025
- 9 minute read
- OpenAccess SDK
- Documentation
README
Progress(R) DataDirect(R)
Progress(R) DataDirect(R) for JDBC(TM) for
Microsoft Dynamics 365(TM) Driver
Release 6.0.0
January 24, 2025
***********************************************************************
Copyright (C) 2025 Progress Software Corporation and/or its
subsidiaries or affiliates. All Rights Reserved.
***********************************************************************
CONTENTS
Requirements
Installation Directory
Data Source and Platform Support
Changes Since 6.0.0 GA
Release 6.0.0 Features
DataDirect JDBC Driver Configuration Manager
Notes, Known Problems, and Restrictions
Documentation
Installed Files
Requirements
* A supported Java Virtual Machine (JVM) must be defined on your system path.
* The installer program requires a JVM that is Java SE 11 or higher, including
Oracle JDK, OpenJDK, and IBM SDK (Java) distributions.
* The driver requires a JVM that is Java SE 8 or higher, including Oracle JDK,
OpenJDK, and IBM SDK (Java) distributions.
Installation Directory
The default installation directory for the driver is:
* Windows:
C:\Program Files\Progress\DataDirect\JDBC
* UNIX/Linux:
/opt/Progress/DataDirect/JDBC
Note: For UNIX/Linux, if you do not have access to "/opt", your user's home
directory will take the place of this directory.
Data Source and Platform Support
For the latest data source and platform support information, refer to the
Product Compatibility Guide:
https://docs.progress.com/bundle/datadirect-product-compatibility/resource/
datadirect-product-compatibility.pdf
Changes Since 6.0.0 GA
CVE-2022-41853 - Use of Externally-Controlled Input to Select Classes or Code
('Unsafe Reflection')
-----------------------------------------------------------------------------
Several Progress DataDirect JDBC drivers utilized a version of HyperSQL
Database that was vulnerable to remote code execution described in
CVE-2022-41853. All impacted drivers have been patched to fix this
vulnerability. For details on impacted drivers and fixed versions, refer to
the following KB article:
https://community.progress.com/s/article/DataDirect-JDBC-Critical-Security-
Bulletin-November-2022-CVE-2022-41853
Enhancements
------------
* The driver has been enhanced to comply with FIPS standards for data
encryption. As part of this enhancement, the driver was tested with
FIPS 140-3 enabled using a Red Hat OpenJDK 21 on a Red Hat Universal Base
Image 9 instance.
* The driver has been enhanced to support fetching data from all the
companies to which the user has access. Earlier, it supported fetching
data only from the default company of the user. You can configure
this functionality using the new CrossCompany connection property.
Feature details
- Available: Driver version 6.0.0.002159 (C5372.F001979.U001055)
* The driver has been enhanced to allow you to configure whether requests
to web services timeout when the service is unresponsive. You can configure
this functionality using the new WSTimeout connection property.
* The driver has been enhanced to use proxy server settings defined in the JVM
system properties by default. If no proxy settings are defined in the
connection string or data source, the driver will attempt to use the values
of the http.proxyHost and http.proxyPort JVM system properties to connect to
the database.
* The following connection properties have been removed from the driver:
ConnectionRetryCount, ConnectionRetryDelay, LoginTimeout, and QueryTimeout.
Changed Behavior
----------------
* The installer program now requires you to install a JRE that is Java SE 11 or
higher before running the installer. In earlier versions, the JRE used by the
installer program was included in the product. However, to avoid potential
security vulnerabilities, the installer program no longer includes a JRE.
Instead, the installer program uses the JRE in your environment to allow for
the most secure version of a JRE to be used.
Note: This change does not affect the JVM requirements for the driver. For the latest
driver requirements, refer to the Product Compatibility Guide:
https://docs.progress.com/bundle/datadirect-product-compatibility/resource/
datadirect-product-compatibility.pdf
Release 6.0.0 Features
The Progress DataDirect for JDBC for Microsoft Dynamics 365 driver supports SQL
read-write access for JDBC applications to Microsoft Dynamics 365 apps. To
support SQL access to Dynamics 365 apps, the driver creates a relational map of
the Dynamics 365 data model and translates SQL statements to Dynamics 365
requests. In addition, the driver employs a SQL engine component that provides
support to SQL constructs unavailable in Microsoft Dynamics 365. This
functionality offers a number of advantages, including support for reporting
data and metadata in a form that JDBC applications are ready to use.
* Supports SQL read-write access to the following Microsoft Dynamics 365
CRM and ERP apps.
- CRM apps
- Customer Service
- Field Service
- Marketing
- Project Service Automation
- Sales
- ERP apps
- Finance
- Retail
- Supply Chain Management
- Talent
* Supports all JDBC core functions.
* Supports the core SQL-92 grammar.
* Supports Dynamics 365 data types through data type inference.
* Supports OAuth 2.0 and NTLM authentication.
* Supports the handling of large result sets with paging and the
FetchSize connection property.
* Supports optimizing insert, update, and delete operations with the
BatchUpdateChunkSize connection property.
* Includes the DataDirect JDBC Driver Configuration Manager for quick
configuration and testing of your driver. This tool allows you to:
- Generate and edit connection URLs
- Test connect connection URLs
- Execute SQL commands for testing
- Fetch OAuth tokens without using your application
- Access connection property descriptions and the full product
documentation
DataDirect JDBC Driver Configuration Manager
The driver includes a browser-based configuration tool, the DataDirect JDBC
Driver Configuration Manager, that allows you to generate and test connection
URLs that you can use with your application. You can launch the Configuration
Manager by double-clicking on the driver jar file. Or, from the command line,
you can navigate to the directory containing the driver jar file; then, execute
the following command:
java -jar dynamics365.jar
The Configuration Manager will open in your default web browser. For more
information, refer to the user's guide for your driver.
Notes, Known Problems, and Restrictions
The following are notes, known problems, and restrictions with the 6.0.0 release
of the driver.
Connection delay
----------------
An initial connection may take a few minutes, depending on network speeds and
the amount of metadata the driver must retrieve from the service. Similar delays
may occur in the following scenarios.
* When the CreateMap connection property is set to OnChange (default) and
changes have been made to the schema on the Dynamics 365 backend
* When starting a new session with CreateMap set to Session
* When CreateMap is set to NotExist and the internal schema files specified by
SchemaMap do not exist
* When CreateMap is set to ForceNew
Using Tableau and other third-party tools
-----------------------------------------
When using third-party tools such as Tableau, network speeds and the amount of
metadata retrieved from the service can cause timeout and out-of-memory errors.
You can work around these issues in the following ways.
1. Increase timeout settings in your third-party tool. For example, Tableau
offers the following guidance for timeout errors caused by large results.
https://kb.tableau.com/articles/issue/error-extract-timeout
You may also need to increase the Java heap size allotted for your
third-party tool. This will allow the tool to manage large metadata results
sent by the service. This workaround not only avoids timeout and
out-of-memory errors on initial connection, but may also avoid these errors
on subsequent connections.
2. Establish your initial connection using the DataDirect JDBC Driver
Configuration Manager as described in "Testing connections and queries" in
the user's guide. In addition to specifying required properties, set the
SchemaMap connection property. SchemaMap specifies the location and name of
the configuration file where the map of the Dynamics 365 schema is written.
Once connected, you can use the connection string generated by the
Configuration Manager to connect via your third-party tool. However, it
should be noted that timeout and out-of-memory errors may occur on subsequent
connections, depending on the CreateMap setting. See the user's guide for
more information.
Data type metadata for COLUMN_SIZE
----------------------------------
When executing getColumns for numeric types and the boolean type, the driver
returns 0 (zero) for COLUMN_SIZE. The driver should instead return the precision
for each data type, as returned with getTypeInfo results.
ERP limitations
---------------
The Dynamics 365 ERP service does not return extensive metadata for some
objects. Therefore, you may encounter the following behaviors when using
the driver to access ERP apps such as Finance, Retail, Supply Chain Management,
and Talent.
* In some cases, the metadata of an object may erroneously indicate that a
column is nullable. Under these circumstances, when you attempt to update or
insert null data into a non-nullable column, the driver returns the error
"Object reference not set to an instance of an object."
* For some columns, the ERP service does not return the maximum length of string
values. In these circumstances, the driver uses a default of 2000 characters.
When attempting to insert or update strings that are larger than the allowable
maximum length on the backend, or strings larger than the driver default, the
string will be truncated.
* For some columns, the ERP service does not return the precision or scale of
decimal types. In these circumstances, the driver defaults to a precision of
22 and a scale of 10. When attempting to update or insert decimal values
larger than the defaults, the driver truncates the decimal value.
* We have set the status of a number of decimal columns to non-filterable
because they generate errors when used in subqueries against the ERP service.
However, a custom decimal column could be introduced that also may not be used
in subqueries. If such a decimal column is used in a subquery, the driver
returns "Cannot select a record in SubQuery. The SQL database has issued an
error."
General error message
---------------------
In some scenarios, when a connection fails, the driver returns the message
"general error" instead of passing the actual error message generated by the
service.
JTA support
-----------
JDBC distributed transactions through JTA are not supported.
Executing DataDirect shell script
---------------------------------
For UNIX/Linux users: If you receive an error message when executing any
DataDirect for JDBC shell script, make sure that the file has EXECUTE
permission. To do this, use the chmod command. For example, to grant EXECUTE
permission to the testforjdbc.sh file, change to the directory containing
testforjdbc.sh and enter: chmod +x testforjdbc.sh
JDBC methods
------------
The following notes on JDBC methods apply generally to Progress DataDirect for
JDBC drivers. Additional information on driver support for the JDBC API can be
found in the "JDBC Support" section of the product user's guide.
* The DataDirect for JDBC drivers allow PreparedStatement.setXXX methods and
ResultSet.getXXX methods on Blob/Clob data types, in addition to the
functionality described in the JDBC specification. The supported
conversions typically are the same as those for LONGVARBINARY/LONGVARCHAR,
except where limited by database support.
* When attempting to create an updatable, scroll-sensitive result set for a
query that contains an expression as one of the columns, the driver cannot
satisfy the scroll-sensitive request. The driver downgrades the type of the
result returned to scroll-insensitive.
* The DataDirect for JDBC drivers support retrieval of output parameters from a
stored procedure before all result sets and/or update counts have been
completely processed. When CallableStatement.getXXX is called, result sets
and update counts that have not yet been processed by the application are
discarded to make the output parameter data available. Warnings are generated
when results are discarded.
* The preferred method for executing a stored procedure that generates result
sets and update counts is using CallableStatement.execute(). If multiple
results are generated using executeUpdate, the first update count is returned.
Any result sets prior to the first update count are discarded. If multiple
results are generated using executeQuery, the first result set is returned.
Any update counts prior to the first result set are discarded. Warnings are
generated when result sets or update counts are discarded.
* The ResultSet methods getTimestamp(), getDate(), and getTime() return
references to mutable objects. If the object reference returned from any of
these methods is modified, re-fetching the column using the same method
returns the modified value. The value is only modified in memory; the
database value is not modified.
Documentation
PROGRESS DATADIRECT FOR JDBC FOR MICROSOFT DYNAMICS 365 DOCUMENTATION SET
-------------------------------------------------------------------------
The driver documentation set is available from the Progress Information Hub:
https://docs.progress.com/category/datadirect-microsoft-dynamics-365
You can access the online help system directly in either of the following ways.
* Via the HTML redirect in the installation Help directory
* By selecting Help from the menu in the Configuration Manager
Installed Files
When you extract the contents of the installation download package to your
installer directory, you will notice the following files that are required to
install the driver:
* Windows:
- PROGRESS_DATADIRECT_JDBC_INSTALL.exe
- DriverModules
- PROGRESS_DATADIRECT_JDBC_DYNAMICS365_6.0.0_INSTALL.iam.zip
- PROGRESS_DATADIRECT_JDBC_COMMON_6.0.0_INSTALL.iam.zip
* Non-Windows:
- PROGRESS_DATADIRECT_JDBC_INSTALL.jar
- DriverModules
- PROGRESS_DATADIRECT_JDBC_DYNAMICS365_6.0.0_INSTALL.iam.zip
- PROGRESS_DATADIRECT_JDBC_COMMON_6.0.0_INSTALL.iam.zip
When you install the driver, the installer creates the following directories and
files in the product installation directory in the default installation
directory or in an installation directory you specify, represented by
INSTALL_DIR.
INSTALL_DIR/:
-------------
LicenseTool.jar Product license file manager
ddprocinfo.exe Windows executable to start the Processor Information
Utility
ddprocinfo UNIX/Linux script to start the Processor Information
Utility
fixes.txt Information on resolved issues for Progress
DataDirect for JDBC drivers
INSTALL_DIR/Examples/Bulk/:
---------------------------
Load From File/bulkLoadFileDemo.java
Java source example for bulk loading from a CSV file
Load From File/load.txt Sample data for the example
Streaming/bulkLoadStreamingDemo.java
Java source example for bulk loading from a result
set
Threaded Streaming/bulkLoadThreadedStreamingDemo.java
Java source example for multi-threaded bulk loading
from a result set
Threaded Streaming/README.txt
Instructions on how to use the thread.properties file
Threaded Streaming/thread.properties
Properties file for the example
INSTALL_DIR/Examples/JNDI/:
---------------------------
JNDI_FILESYSTEM_Example.java
Example Java(TM) source file
JNDI_LDAP_Example.java Example Java source file
INSTALL_DIR/help/:
------------------
*.html HTML redirects to driver help systems
INSTALL_DIR/install/:
---------------------
.psc_dd_inst_reg.xml Support file for the installation logs
logs/*.* Log file generated upon installation
INSTALL_DIR/jdbcisql/:
----------------------
jdbcisql.bat Batch file to start JDBC iSQL
jdbcisql.ini Configuration file for JDBC iSQL
jdbcisql.jar Java program to start JDBC iSQL
jdbcisql.sh Shell script to start JDBC iSQL
INSTALL_DIR/lib/:
-----------------
JDBCDriverLogin.conf Kerberos configuration file used to specify the JAAS
login module
INSTALL_DIR/lib/60/:
-------------------
dynamics365.jar Dynamics 365 Driver and DataSource classes
INSTALL_DIR/NOTICES/:
---------------------
JDBC for Microsoft Dynamics 365 v6.0 notices.txt
Third party agreement information
INSTALL_DIR/pool manager/:
--------------------------
pool.jar All DataDirect Connection Pool Manager classes
INSTALL_DIR/READMES/:
---------------------
JDBC for Microsoft Dynamics 365 v6.0 readme.txt
This file
INSTALL_DIR/testforjdbc/:
-------------------------
Config.txt Configuration file for DataDirect Test
ddlogging.properties Logging properties file
testforjdbc.bat Batch file to start DataDirect Test
testforjdbc.sh Shell script to start DataDirect Test
lib/testforjdbc.jar DataDirect Test classes
INSTALL_DIR/uninstall/:
-----------------------
.com.zerog.registry.xml Support file for the uninstaller
.psc_dd_uninst_reg.xml Support file for the uninstaller
InstallScript.iap_xml Support file for the uninstaller
installvariables.properties
Support file for the Windows uninstaller
Uninstall_JDBC.exe Windows uninstaller
Uninstall_JDBC.lax Support file for the Windows uninstaller
uninstaller.jar Java uninstaller
dynamics365/*.* Support files for the uninstaller
resource/*.* Resource files for the Windows uninstaller
January 24, 2025
==============
End of README