Update 23C

Revision History

This document will continue to evolve as existing sections change and new information is added. All updates appear in the following table:

Date	Module	Feature	Notes
14 SEP 2023	Open Storefront Framework	Node 18 Upgrade for Open Storefront Framework	Updated document. Feature delivered in update 23C.
14 SEP 2023	Open Storefront Framework	React 18 Upgrade for Open Storefront Framework	Updated document. Feature delivered in update 23C.
14 SEP 2023	Open Storefront Framework	Enhanced CSS Loading Techniques for OSF	Updated document. Feature delivered in update 23C.
14 SEP 2023	Open Storefront Framework	Support for Uploading Selected Assets in An OSF Application Deployment	Updated document. Feature delivered in update 23C.
14 SEP 2023	Open Storefront Framework	Support For Updating Existing OSF Assets in OSF Application Deployment	Updated document. Feature delivered in update 23C.
21 JUL 2023			Created initial document.

Overview

HAVE AN IDEA?

We’re here and we’re listening. If you have a suggestion on how to make our cloud services even better then go ahead and tell us. There are several ways to submit your ideas, for example, through the Ideas Lab on Oracle Customer Connect. Wherever you see this icon after the feature name it means we delivered one of your ideas.

GIVE US FEEDBACK

We welcome your comments and suggestions to improve the content. Please send us your feedback at oracle_fusion_applications_help_ww_grp@oracle.com.

DISCLAIMER

The information contained in this document may include statements about Oracle’s product development plans. Many factors can materially affect Oracle’s product development plans and the nature and timing of future product releases. Accordingly, this Information is provided to you solely for information only, is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described remains at the sole discretion of Oracle.

This information may not be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates. Oracle specifically disclaims any liability with respect to this information. Refer to the Legal Notices and Terms of Use for further information.

Feature Summary

B2B Commerce

Admin

Site Preview as B2B Account User

Preview By Account is an enhancement to the Commerce Cloud service that allows a page developer to preview how their site’s pages will appear to a user from a certain account with a selected set of roles. Prior to the introduction of this feature, the page designer would have no way to preview how changes would appear to a customer of a given account and roles before the pages were published to production. Preview by Account is available for both Storefront Classic and Open Storefront Framework sites.

Allows page designers to preview how a page will appear for an account user with the given roles.

Steps to Enable

You don't need to do anything to enable this feature.

Tips And Considerations

• Accounts are a feature of B2B sites, so the account and role selection elements appear only for preview of B2B sites. Preview for B2C sites is unaffected.
• This feature works in conjunction with other Preview features, including Preview by Date and Preview by Audience.
• Merchants can choose to disable this feature by raising a support ticket.

Catalog and Promotions

Limit the Child Array Properties of Certain Catalog Endpoints to Reduce Response Payloads

Oracle Commerce allows to limit the number of elements of array properties of certain catalog endpoints to improve the response time and payload size of these endpoints.

Capability Highlights

• Set a maximum count value to limit the number of elements of array properties of certain catalog endpoints.
• Endpoints: getProduct, listProducts, getCollection, and listCollections in Admin, Agent, and Storefront.
• The limited properties are childProducts, childSKUs, and filteredSKUs

This feature helps reduce response times and payload size of the mentioned endpoints.

Steps to Enable

Set the “enableChildEntitiesLimit” and “maxChildItemsCount” configuration settings by using the “updateCloudConfiguration” endpoint. The default value is false and 1000, respectively.

Tips And Considerations

Once the configuration is updated, GET/LIST category and product endpoints will retrieve only first N child items, where N is the maxChildItemsCount and will return a property childProductsCount / childSkusCount in the response payload. If the childProductsCount (or childSkusCount) is equal to the length of the child item array in the response, then all of the child items have been included in the response. If the childProductsCount is greater than the length of the child item array in the response, then there are additional child items that can be retrieved using the following Rest API's.

	Storefront	Admin	Agent
childProducts	NA	/ccadmin/v1/products?categoryId={categoryId}	/ccagent/v1/products?categoryId={categoryId}
childSKUs	/ccstore/v1/skus?q=parentProducts co "{productId}"	/ccadmin/v1/skus?q=parentProducts co "{productId}"	/ccagent/v1/skus?q=parentProducts co "{productId}"

Server-Side Extensions

Support for OAuth Authentication in SSE and CPQ interactions

SSE apps cpq-configurator-app-store and cpq-configurator-app-agent now support OAuth based authentication for CPQ interactions. Merchants can choose to use either OAuth or Basic Auth authentication in these apps. To take advantage of this feature, the merchant must use 23.7.0 version of cpq-configurator-app-store.zip and cpq-configurator-app-agent.zip. OSF uses cpq-configurator-app-store for the OOTB OSF-CPQ SSE based integration.

OAuth based authentication mechanism is recommended and performant over the basic auth.

Steps to Enable

• Merchant needs to manually register the SSE client to the CPQ instance to get clientId and client secret. 

  URI: POST: {{cpq_server}}/rest/v1/clients/

  Sample Payload :

  {

  "name" : "Occ Credentials Client ",

  "description" : "Occ Credentials Client",

  "expires" : 5000,

  "clientKey" : "occ_cred_client",

  "grantType" : "ClientCredentials"

  }

• Register the following SSE environment variables CPQ_CLIENTID, CPQ_CLIENTSECRET and CPQ_USETOKEN using the below Commerce Admin doCreateExtensionVariable Rest API. CPQ_USETOKEN must be set to true to use OAuth authentication. Please refer to the following REST API documentation for more information: https://docs.oracle.com/en/cloud/saas/cx-commerce/cxocc/op-ccadmin-v1-extensionenvironmentvariables-post.html

• Download 23.7.0 version of cpq-configurator-app-store zip or cpq-configurator-app-agent from Administration Console. Unzip it, perform npm install and create a zip of it.

• Upload the zipped SSE to SSE server using the Commerce Admin doSSEFileUploadMultipart REST API. Please refer to the following REST API documentation for more information: https://docs.oracle.com/en/cloud/saas/cx-commerce/cxocc/op-ccadmin-v1-serverextensions-post.html

Node 18 Upgrade for Server-Side Extensions

With this release, the version of Node.js used by server-side extensions (SSEs) is being upgraded to the latest long-term support version of Node.js 18LTS. In our testing, we have not found any incompatibilities. But, there are steps you should take to prepare ahead of time. The main risk for incompatibility is outdated npm libraries that may be used by your SSEs. Before your sites are upgraded to 23C(or beyond), you will need to verify that you’re using the latest version of each npm library and identify any changes that need to be made to your SSEs. If you have determined any issues with your SSEs as a result of the update to Node.js 18LTS, you should address them before the update. It is your responsibility to test your updated SSEs locally before your non-production update and push the updated code to non-production and production as part of the update process.

Server-side extensions are upgraded to latest long-term support version of Node.js.

Steps to Enable

You don't need to do anything to enable this feature.

Open Storefront Framework

Node 18 Upgrade for Open Storefront Framework

With commerce 23.08 version upgrade, there is an upgrade of Node version to 18LTS. Open Storefront Framework is also being upgraded to the latest long-term support version of Node.js 18LTS. With this version of Node.js we did not find any incompatibilities in OOTB features.

However, there are steps you should take to prepare ahead of time:

1. There can be a risk for incompatibility, where outdated NPM libraries that may be used by any customizations.

2. Before upgrading your OSF workspace to the latest version, you will need to verify that you’re using the latest version of each NPM library and identify any changes that need to be made.

3. If you have determined any issues with your code or tests as a result of the update to Node.js 18LTS, you should address them.

4. It is your responsibility to test your updated code locally before your non-production update and push the updated code to non-production and production as part of the update process.

Open Storefront Framework is upgraded to latest long-term support version of Node.js.

Steps to Enable

You don't need to do anything to enable this feature.

React 18 Upgrade for Open Storefront Framework

With OSF 5.0.0, the version of React used by Open Storefront Framework is being upgraded to the latest long-term support version of React 18. React 18 includes major out-of-the-box improvements like automatic batching, new APIs like startTransition, and streaming server-side rendering. With this React update, there are a few backwards incompatible changes made in Server side rendering, Client side rendering and hydration functionality. The following are some changes that have affected our framework:

• The server side streaming API renderToNodeStream has been replaced with renderToPipeableStream.
• The renderToString has limited Suspense support and does not support streaming.
• The client rendering API's ReactDOM.render and ReactDOM.hydrate has been replaced with createRoot  and hydrateRoot.
• As window object is not available during Server side rendering, any reference to it in the widgets will cause server side rending for those widgets to be skipped.

In our testing we have found that testing libraries like Jest also have to be upgraded for tests to continue to function.

With OSF 5.0.0, we have updated our reference implementations to accommodate these changes. If you have determined any issues with your code or tests as a result of the update to OSF 5.0.0, you should address them. It is your responsibility to test your updated code locally before pushing the updated code to non-production and production as part of the update process.

Open Storefront Framework is upgraded to latest long-term support version of React. React 18 includes major out-of-the-box improvements like automatic batching, new APIs like startTransition, and streaming server-side rendering.

Steps to Enable

You should upgrade your OSF version to 5.0.0

Enhanced CSS Loading Techniques for OSF

With this feature, merchants can define CSS at page and widget level in addition to making them site-specific. This is enhancement to existing site- specific CSS feature.

OSF developers can now define granular CSS for pages and widgets instead of maintaining large CSS files. Shoppers will experience faster page load times as CSS for pages and widgets will be loaded on demand.

Steps to Enable

Configuring Page level CSS:

1. Create a new “styles” folder under assets folder of an application.
2. Create a new CSS file within the new “styles” folder. The file name should follow the below guidelines.

1. Should start with either the keyword "pageType" or "route" to define behavior based on page type or route type.

1. To define CSS based on pageType, use the following file format “pageType$$<page-type>”.css. e.g., pageType$$home.css for home page.
2. To define CSS based on route, use the following file format “route $$<page-route>”.css. e.g., pageType$$contactus.css for contactus page.

Tip: Developers might want to choose route format when they would like to define different CSS files for pages of the same type but have different routes. e.g., There can be multiple article pages like Contact Us and Shipping and can have different CSS files.

2. To configure site specific CSS, use the following file format: “pageType$$<page-type>$$<site-identifier>”.css. e.g., pageType$$home$$siteUS.css for home page of US Site.
3. To customize the separator( $$) used in the filename, override the predefined constant "PAGE_SITE_CSS_SEPARATOR" present in the packages\core\common\commerce-utils\constants\page-site-css.js.
4. Create a "config.json" file under the "styles" folder with the above entries.

Precedence Order for Page level CSS:

• If two CSS files are created for a page, one with "pageType" in its name and the other with "route", the styles within the "route" file will take precedence over the styles in the "pageType" file.
• If the config.json file contains multiple site-level CSS files and multiple page-level CSS files with rankings, it's essential to note that these rankings won't affect the overall sorting. The ranking is solely used to sort between different site-level CSS files and different page-level CSS files, not across all entries. In any case, the page-level CSS files will always take precedence over the site-level CSS files, regardless of their rankings.

Configuring Widget level CSS:

Split the contents of the large overridden CSS files into multiple files specific to each site, such as "siteCA.css," for every widget.

1. Add a new property "enableSiteCSSOnWidget" in the application's package.json.
2. Create a new “sites” folder under assets folder of an application and widget specific folders with CSS files. e.g. sites>login>login.css.

Tip: Developers might want to create site specific CSS file for widgets too. They have to create different CSS files for different sites. e.g. sites>login>siteUS.css.

3. Create a new file “widget-site-css-config.js” within the application in following path “src>plugins>components>substitution>widget”. These folders might have to created if there are not present. The file content should be in the below format.

export const widgetSiteCSSConfig = {

site1: {

widget1: () => import("path to widget CSS file"),

widget2: () => import("path to widget CSS file")

},

site2: {

widget1: () => import("path to widget CSS file"),

widget2: () => import("path to widget CSS file")

}

}

4. Alias the OOTB widget-site-css-config.js with the new widget-site-css-config.js in application package.json. e.g., "@oracle-cx-commerce/react-components/widget/widget-site-css-config": "@oracle-cx-commerce/core-commerce-reference-store/src/plugins/components/substitution/widget/widget-site-css-config"

Tips And Considerations

• When defining widget level CSS in widget-site-css-config.js, entries for all sites must be created even though the same CSS is used in all sites.

• When the CSS files are large, Shopper might experience page flickering when navigating between pages. To solve this, developers can implement a custom page loader functionality by creating “index.jsx” in the following path under an application “src/plugins/components/substitution/place-holder” and alias it in the in application package.json. e.g., "@oracle-cx-commerce/react-components/page/page-placeholder": "@oracle-cx-commerce/core-commerce-reference-store/src/plugins/components/substitution/place-holder/index.jsx"

• To display a blank page instead of a page loader during page transitions, set the "pageSiteCSSDisplayMode" property to "blank" in the application's package.json.

Support for Uploading Selected Assets in An OSF Application Deployment

Previously when an OSF developer updated assets or added new assets, they had to upload and deploy  the complete application. With this feature, developers can update existing assets or upload new assets by uploading only the selected assets instead of the whole application. A new CLI command and a REST API was introduced for this feature.

When using the CLI, developer can choose to upload assets either in the form of zip containing the assets or refer to a JSON file with the list of assets. Sample command usage can be as below

• yarn upload-assets --zipFile <full-path-to-zip-file>

The format of the zip-file is same as the one used in uploadApplication REST API. The zip file should only contain asset changes

• yarn upload-assets --selectiveAssets --assetsDataFromFile <full-path-to-json-file>

The format of JSON file can be found in the Tips and Considerations section

When using the REST API uploadSelectedAssets, developer can upload the selective changes in zip format. The format of the zip-file is same as the one used in uploadApplication REST API. For more information on these REST APIs, please refer to REST API documentation.

Both the CLI and REST API support the “keepUnpublishedChanges” option which gives developers an ability to skip updates to an existing asset if it has unpublished changes. Its set to false by default.

Makes it easier for OSF developers to deploy small changes to their application without having to do a full deployment. This also provides a way of preventing a deployment from overwriting recent changes made in Design Studio by business users.

Steps to Enable

You don't need to do anything to enable this feature.

Tips And Considerations

• When developers upload a new asset using this feature, they need to make sure that the implementation for the asset already exists.

• The JSON file containing the assets data can be created anywhere and the full file path of the file needs to be provided as the value for the assetsDataFromFile command argument.

• The JSON file should contain only valid assetTypes like pages, components, containers, slots and styles, else error will be thrown. Below is an example input data file for the assetsDataFromFile argument. A JSON file can be created with the below JSON data and that file path can be passed as value to the assetsDataFromFile argument. If there are multiple files inside a component or slot, required files can be uploaded by adding those file names in an array and if all the files need to be uploaded then an empty array needs to be passed. JSON below.

{

"pages": ["home.json"],

"containers": [cart-container.json"],

"slots": {

"header-with-notification-device-slot": [

]

"checkout-header-with-notification-device-slot": [

"config.json",

"structure.json"

]

},

"components": {

"back-button": [

"config.json"

]

},

"styles": ["customStyling.css"]

}

Support For Updating Existing OSF Assets in OSF Application Deployment

Previously when an OSF application was deployed without the reset option, only new assets would be created and existing assets would be left untouched. This meant that in order to promote updates to existing assets, every deployment needed the reset option to remove the existing application and its assets first.

With this feature there are the following two new options supported by the OSF deploy command and uploadApplication endpoint that the deploy command uses:

• updateExistingAssets – The ability to update existing assets. Its set to false by default for backwards compatibility purpose.
• keepUnpublishedChanges - The ability to skip updates to an existing asset if it has unpublished changes. Its set to false by default for backwards compatibility purpose.

Details of the OSF CLI options and associated endpoint query parameters are as follows:

New Option in OSF Deploy Command	New query parameter in uploadApplication endpoint	Description
--updateExistingAssets	updateExistingAssets (false by default)	If specified will update existing assets
--keepUnpublishedChanges	keepUnpublishedChanges (false by default)	If specified, any asset with unpublished changes will not be updated.

There will be additional feedback provided for existing asset changes during the deployment process for the below scenarios:

• If an existing asset can be updated then an informational message (only seen with --verbose mode enabled) will report that an asset will be updated:
  • <assetType> '<assetName>' located in <file> updated.
• If an existing asset cannot be updated due to unpublished changes then a warning will be logged:
  • <assetType> '<assetName>' has unpublished changes, skipping updates.

NOTE: the –keepUnpublishedChanges option is unsupported with the –reset option: it won’t prevent a reset even if there are unpublished changes.

Makes it easier for OSF developers to deploy small changes to their application without having to do a full reset deploy. This also provides a way of preventing a deployment from overwriting recent changes made in Design Studio by business users.

Steps to Enable

You need to specify the above new options in the OSF deploy command (or via the above new query parameters if invoking the uploadApplication endpoint directly) to take advantage of these features which are otherwise disabled by default.