Oracle REST Data Services 24.2

Release Notes

Version 24.2.2.187.1943

Date: July 2024

Enhancements

  • New 5xx HTTP error response code (Docs) have been added to assist more intelligent log monitoring and alarms.
    • Status Code Descripton
    570 Account Is Locked The database account is locked.
    571 Database Connection Error Database connection failed with a network-related error. This can be caused by database listener issues (ORA-12514, ORA-12506, ORA-12529, ORA-12516), configuration errors, certificate mismatch or network connectivity issues.
    572 Recoverable Database Connection Error ORDS was unable to make a connection to the database. This can occur when the database is overloaded.
    574 Database Credential Error Database credential error such as invalid username/password or expired password.
    577 Database Limit Exceeded Database space or system resource limit exceeded.
    578 Database Internal Error Database internal error occurred.
  • OCI Monitoring - Easily create ORDS alarms using OCI Monitoring Services via sample script in [ords product folder]/examples/ords-metrics directory..
  • standalone.access.log.retainDays - Configure ORDS standalone for the number of days before access log files are overwritten.
  • Passing Java Options parameters for ORDS CLI - Example: ords --java-options "-Djava.util.logging.config.file=logging.properties" config list
  • Installer - ords config "WARNING" messages to include guidance for when a non-SYS user attempts to update/install ORDS, when a current APEX installation exists at the CDB Root (Common) level. User will be met with the following guidance:
    • WARNING: Procedure APEX_ADMIN could not be added to allow list. The function or procedure is a common object. You must execute the following as a common user: begin APEX_230200.wwv_flow_listener.sync_ords_gateway_allow_list; end;
    • WARNING: ORDS migrated 0 entry points from APEX to ORDS PL/SQL Procedure Gateway Allow List.
  • ORDS standalone updates the embedded Jetty Web Sever to version 10.0.21.
  • SQL Developer Web / Database Actions
    • Data Pump
      • Previous jobs and their associated output files can now be deleted.
      • Import Wizard
        • DBMS credentials can be used to access OCI Buckets for accessing DMP files
        • Buckets from any Compartment level are now accessible
        • Auto-generated Import Patterns for DMP Files
        • Automatic mapping for Schemas and Tablespaces
        • "Append Timestamp to Log and Job Names" toggle option
    • SQL Worksheet, support for importing Newline Delimited JSON (NDJSON), or .ndjson files Charts and Data Modeler now offer product Walkthroughs (Tours)

Bug Fixes

ORDS Core

  • Bug 36810147 Incorrect API called by DISPATCHABLESERVLETSCHOOSER under high load
  • 36781514 ORDS cache is affecting templates with multiple handlers
  • 36477051 ORDS would not recognize cache.metadata.time property when the unit
  • 36538129 ORDS logs will now display the relevant User-defined exception and a 555 (User-Defined Resource Error) Status Code where a mime-type string = empty.
  • 36576308 When updating to ORDS latest, a user's default tablespace names would not update to the user's latest input.
  • 36169206 ORDS install failing for OCI Base database service, ORDS generated password not strong enough
  • 36581137 Intermittent 400 Bad Request response status codes on their REST-enabled PL/SQL procedure while under heavy load
  • 36563688 Offset and Limit query parameters were not accepted when used with ORDS Resource Handlers with a p_source_type => 'mle/javascript'.'
  • 36592165 Interactive Installer will now prompt for password when configuring gateway connections
  • 36435220 ORDS will now return a 400 Bad Request Response Status code in cases where the client provides illegal request arguments. Example cases include:
  • 36496276 ORDS will now return a 555 User-Defined Resource Error Response Status code in cases where an ORDS Resource Handler contains an illegal source type (i.e. ,p_source_type).
  • 36485688 Base64 JWTs that can not be decoded, will display a 401 Invalid base64 Character Request Response Status code instead of returning a 500

SQL Developer Web / Database Actions

  • 36496046 When protecting auto-REST enabled endpoints, ORDS would fail to append a trailing slash to the resource URI, resulting in a 404 Not Found.
  • 36217041 The drag-and-drop INSERT utility did not display all columns of the target table when selecting the "UPDATE" option.
  • 36660287 Auto-REST enabled PL/SQL procedures failed when input parameters matched SQL reserved words.
  • 35876230 Auto-REST enabled objects' privileges not including Label and Description parameters, breaking Three-legged Oauth (Authorization Code Flow and the Implicit Flow)
  • 35441260 Signing in to SDW via host/ords/schema/sign-in would return an "Invalid Credentials", despite the successful authentication.
  • 36557174 Documentation links were inoperable in the JSON list item of the Development category on the Database Actions Launchpad.
  • 36573083 Setting language preferences in Database Actions to the preferred language, some tabs and their options would remain in English.
  • 31901655 Unexpected Symbol Error, related to the Classification clause when executing the CREATE ATTRIBUTE DIMENSION statement.
  • 36394754 Data Studio's Data Load tool would present the incorrect File System Tour or not present the Tour.
  • 36383321 Target Table Name in Data Studio's Data Load tool would display as [object Object].
  • 36379155 Data Studio's Data Load "Register to Cloud Link" Wizard will display, "The current user does not have the privilege to register table [table name] as a cloud link"
  • 36318919 Unable to add a Data Studio Cloud Store location due to unreadable file/s in target object storage.
  • 36496567 "Show info" and "Clear Search" icons were inoperable while performing a Data Analysis in query mode in Data Studio
  • 36249051 Reset Zoom, Show Info, and Clear Search buttons were inoperable when performing a Data Analysis (in Query mode) from within Data Studio
  • 34952408 When editing settings in Data Studio's Link Data from Cloud Store Location wizard, the Partition Column selection field would unexpectedly reset to "None"
  • 34872422 The "Newlines included in data values" checkbox was not present when loading data from within Data Studio's "Load Data from Local File" wizard.
  • 36267569 While toggling schemas of an Analytic View (Data Studio), and then visiting the Data Quality Page, the browser page failed to load.
  • 35490843 Installing the Data Studio's Add-in for Excel, after setting up a connection to an Autonomous Databases, the sign-in prompt was unavailable
  • 36354028 Overlapping of some longer table names when reviewing a job's Job Report via the kebab menu of Table and View Loads (from within Data Studio's Data Load dashboard).
  • 36383674 Job/Card Slider would remain in a loading state after executing an Ingest job from Data Studio's "Load Data from Local File" Wizard and then searching for that latest job
  • 35334199 "ORA-20290: Manifest element objectName is incompatible with element objectNames" in Data Studio's Cloud Store when loading data in .xslx format
  • 36272707 When selecting "Insert into Table" in Data Studio's "Load Data from File System" Wizard, Target Column names were incorrectly altered to resemble double-quoted Source column names.

Supported Java Version

Oracle REST Data Services requires Java 11,17 or 21. The supported Java Runtime Environments are:
  • Oracle Java 11
  • Oracle Java 17
  • Oracle Java 21
  • Oracle GraalVM Enterprise Edition for Java 11
  • Oracle GraalVM Enterprise Edition for Java 17
  • Oracle GraalVM Enterprise Edition for Java 21

Note that graphql support requires 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.