Enhancements

• ORDS now supports user-defined REST Resource Handlers powered by the Oracle Database Multilingual Engine (MLE) for JavaScript—the ORDS.DEFINE_HANDLER procedure now includes a new 'mle/javascript' p_source_type for MLE JavaScript modules stored directly in the Oracle database. See in the docs.
• In the Database Actions' Data Pump Import Wizard, users can now select Buckets from within a specific Compartment from the available drop-down fields.
• The ORDS Interactive Installer will now display a list of options for TNS Net Service names:
  • the first [1-9] TNS Net Service names in alphabetical order
  • [S] to specify a database connection, and
  • [T] to specify an optional TNS Net Service name
• ORDS now supports SODA for Java version 1.1.23.
• Reports generated in Data Studio's Data Analysis reports will now show the Aggregation Operator (Aggregate Method) used.

Bug Fixes

• 36482753 The ORDS Bequeath Protocol connection option (e.g., -DuseOracleHome=true) in Oracle Database 19c is unsupported. Users will be notified of the error when attempting this connection type while upgrading/installing ORDS in a 19c database.
• 36479584 While installing ORDS, users were incorrectly permitted to specify the SID for a Pluggable Database (PDB). An error message directing users to enter the Container Database's (CDB) SID will now appear.
• 36415532 When deleting a Transactional Event Queue Topic with a specified topic name using the related db-api DELETE endpoint, users would receive a 200 Response Code when deleting a non-existent topic. Instead, a 400 Response Code will be returned.
• 36503852 Reduced overhead and improved object/memory allocation; fix related to logging levels.
• 36414466 We've improved response time and lower latency in ORDS OAuth2.0 Authorization Token endpoints.
• 36544146 When an OAuth2.0 client lacking the appropriate Role obtains an Access Token and later attempts to perform an operation on a protected resource, the client receives a "500 Internal Server Error" Response Status code. This has been corrected; clients lacking appropriate Roles will now receive a "401 Unauthorized" Response Status code.
• 36543457 OAuth2.0 clients that received a 500 Response Status code incorrectly in some instances when an Authentication Token was expired and a new one was required. Clients will continue to receive the previous 401 codes, triggering a new OAuth2.0 token refresh.
• 36507662 Use of the db-api endpoint "/_/db-API/stable/database/{pdbs}" returns in the response body numerous JSON properties. When used, Keystores would be visible in the "job_action" property. We've omitted this property from the response body.
• 36479201 When updating or installing ORDS in an Oracle Database 19c, with the bequeath connection system property set, users observed an error if the target container did not exist in their local database installation. Error messaging has been updated.
• 36515948 Chapter 4.2 of the ORDS Developer's Guide updates the ORDS PL/SQL Package Reference documentation. We've updated this chapter to include the newly introduced mle/javascript parameter type (p_source_type = mle/javascript). Complete descriptions and code examples are now available for reference.
• 36358014 Users reported that recently visited Data Studio pages failed to display in the Database Actions' Pinned & Recently Visited tab of the LaunchPad.
• 36444382 JSON Workshop failed to reload when navigating to/from the JSON Collection dashboard.
• 36450727 Users reported that Analytic Views from within the Data Analysis Tool of Data Studio would not display, forcing the user to refresh the browser.
• 36501085 When tabbing through the Data Quality action of a Data Studio Analytic View, users cannot tab (FN + F2 followed by tabbing) to access Information and Download icons.
• 36505051 While in Data Studios' Analytic View, users observed the Report Filters overwriting previous selections.
• 36496474 From within the Data Analysis tool of Data Studios, users reported that the "Explain Plan - Diagram View" icon would reduce in size after subsequent interactions.
• 36395517 Users reported being unable to view Analytical Views when toggling between Query and Analytic View modes within Data Studios' Data Analysis tool.
• 36493241 JAWS Voice Assistant users experienced an issue cycling through specific Header fields when navigating in Data Studio's Data Analysis tool.
• 36459064 Users reported that the Data Analysis query pane disappeared when switching schemes in the Data Analysis Tool of Data Studio.
• 36533783 The Enable Sharing Wizard has been moved to the Provider and Consumer (main page) dashboard for the Data Share tool of Data Studio.
• 36533785 Data Load Studio users were unable to see Database Links from within the Load Data Database Wizard. A browser reload temporarily corrected this issue.

Supported Java Version

Oracle REST Data Services requires Java 11 or 17. The supported Java Runtime Environments are:

• Oracle Java 11
• Oracle Java 17
• Oracle GraalVM Enterprise Edition for Java 11
• Oracle GraalVM Enterprise Edition for Java 17

Please consult the documentation for the minimum supported Application Server versions for ORDS.

Support

• Supported by Oracle Support under your current Oracle Database Support license for Oracle REST Data Services production releases.
• Log Oracle REST Data Services bugs and issues using My Oracle Support.
  • For problems specific to SODA for REST, file a service request using "Oracle XML Developers Kit" as the product.
  • For all other problems, use "Oracle REST Data Services" as the product.

Note - Autonomous Database Shared Subscribers

If you are running a customer-managed ORDS for your Autonomous Transaction Processing, Autonomous Data Warehouse, or Autonomous JSON Database, you must upgrade your customer-managed ORDS to the version used in your Autonomous Database Shared environment. Failure to do so could lead to service disruptions.

To determine the version of ORDS in your Autonomous Database Shared database run this query:

select ords.installed_version from dual;

				

Documentation

General

• Documentation for this release is provided on the oracle.com web site. Click here to view the documentation and related information.
• Documentation on using SODA for REST is provided on the oracle.com web site. Click here, navigate to the documentation section and access the book titled 'SODA for REST'.

Getting Started

• A tutorial on getting started with developing RESTful Services is included in the ORDS product documentation, in the book titled 'Oracle REST Data Services Quick Start Guide'.

Known Issues

Oracle Database may report 'ORA-01031: insufficient privileges' for queries that involve CURSOR expressions

In a number of cases, ORDS executes queries which include a CURSOR expression. An issue has been found executing these queries for some schemas in Oracle 18c and Oracle 19c databases. Depending on the roles and privileges involved, the issue does not occur for all schemas, which can give the impression that the issue is intermittent. Refer to RDBMS bug 29049673 for more information. The issue is manifest as follows in the exception returned:

ORA-00604: error occurred at recursive SQL level 1

ORA-01031: insufficient privileges
			

This is a problem with view-merging of nested cursors introduced in Oracle 18.1 database. Please use the following as a workaround:

alter system set "_fix_control"='20648883:OFF';

		

Oracle Database DATE and TIMESTAMP values

ORDS interprets Oracle Database DATE and TIMESTAMP values (which do not possess a time zone) into the time zone of ORDS. These values are then represented in the RFC3339 UTC format.

In a future release Oracle Database DATE and TIMESTAMP values will not by default be interpreted into any time zone. These values will be represented in the ISO 8601 "yyyy-mm-ddThh:mm:ss[.sss]" format. Oracle Database TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE values will remain represented in the RFC3339 UTC format.

SQL Developer Web

• DATE, TIMESTAMP, TIMESTAMP WITH TIMEZONE values downloaded from the Worksheet Query Result in the JSON format are not presented in the Internet Datetime format.

JDBC Array values

ORDS passes array values to the Oracle Database in a number of cases, for example arrays are used to pass the request headers and form fields during PL/SQL Gateway calls. Oracle JDBC Driver 18.3 and later supports an improved mechanism for passing array values, however this feature is only supported on Oracle Database 12c and later. Thus ORDS uses existing deprecated and less efficient APIs for passing array values when connecting to 11G databases, and the improved mechanism when connected to 12c and later. Customers experiencing problems with passing large array sets (for example OutOfMemory exceptions) are encouraged to upgrade from 11G to a newer database version to mitigate these issues.

Autogenerated REST Endpoints

• AutoRest resources support the OAuth 2.0 Client Credentials flow only.

RESTful Services

• Application Express workspaces do not support first party authentication, and therefore do not support the /sign-in/ interactive sign in form. Accessing /sign-in/ in APEX workspaces will produce a 404 status.

Support For mod_plsql logmeoff

• The mod_plsql logmeoff mechanism is not supported reliably by modern browsers and it is not provided by ORDS. The only way to end a HTTP Basic Authentication session is to close the Browser.

Feedback

• At Oracle REST Data Services on oracle.com you will find links to forums and social media channels where you can discuss topics with the ORDS community around the world and leave feedback for the development team.
  • In the forums, be sure to use clear subject lines to initiate a thread. Provide a complete and clear description of the issue, including steps to reproduce the issue.
  • Try to avoid using old, unrelated threads for a new issue.

Important Concepts to Keep In Mind

Revised Command Line Interface and Configuration Directory Structure

Command Line Interface

The java commands serviced from the WAR file are no longer supported. Attempting to run the following:

java -jar ords.war standalone

Will result in an error message, referring you to the docs. Instead you would run:

ords --config /path/to/config serve

Installation & Configuration

The ORDS program or script in the bin directory can be used to perform installs, changes to your configuration, changing the database passwords for your connection pools, and for creating ORDS users. To see a list of commands:

ords --help

    

Configuration Files Directory Layout

If upgrading from a previous version of ORDS, your existing configuration directory for ORDS and the files contained therein will be migrated to a new layout for versions 22.1 and higher.

You may migrate your settings using the ORDS migrate command, or you may perform a 22.1 install which will prompt ORDS to migrate your existing ORDS configuration to the new mapping for you.

ORDS standalone and default pool configuration settings are in a settings.xml file in a global subdirectory.

Connection pools are in a databases subdirectory. The intital database pool is named 'default' and has a '/' mapping pattern.

Subsequent pools will created such that the name of the pool also defines the mapping pattern.

SQL Developer Web

SQL Developer Web (SDW) is an ORDS hosted web application giving Oracle Database users the SQL Developer desktop experience in their browser.

SQL Developer Web provides a development interface for building and maintaining your ORDS based REST APIs, AUTOREST Enabled database objects, OAuth3 Clients, ORDS Privileges and Roles, as well as a SODA for REST graphical interface. For the best possible experience developer REST APIs for ORDS, we recommend you use SQL Developer Web.

For consistent representation of date values in SQL Developer Web, ORDS should be run in the UTC timezone. This is set automatically when using the ords command line interface. When deploying ORDS to Apache Tomcat or WebLogic Server the user.timezone may have to be set explicitly before starting the container.

-Duser.timezone=UTC

		

SQL Developer Web requires the Database API be enabled.

SQL Developer Web's DBMS_SCHEDULER interface requires database version 12.2 or higher.

Upgrading ORDS in the database

If you have previously executed script, ords_installer_privileges.sql, to grant your administrator user privileges to perform the install or upgrade, then you must execute the script again on that same user that you provided because additional grants have been added to this script. Note: This script does not apply to the SYS user account.

 

Earlier Release Versions

For information on Issues Fixed and New Features introduced for earlier versions please refer to the release notes for those versions.