Use the Design Code Utility

Oracle Commerce includes the Design Code Utility, a suite of command-line tools that allows you to integrate Commerce with the IDE or code editor of your choice.

The Design Code Utility suite is comprised of the following:

• dcu – The core code and metadata synchronization utility.
• ccproxy – The development and debugging proxy.
• ccw – The Content Creation Wizard.
• plsu - The Page Layout Synchronization Utility, which enables you to manage and edit page layouts.

Download and install the Design Code Utility suite

Before you can use it, you must download the Design Code Utility suite and install it using Node Package Manager.

To download and install the Design Code Utility suite:

1. Log in to the Commerce administration interface.
2. Click the Design icon.
3. Under Developer, click Developer Tools.
4. Under Design Code Utility, click the Download button.
5. Save the ZIP file to a location on your local machine and extract its contents.
6. Change directories to the extracted location and run the following command to install the Design Code Utility script:

   npm install -g

The install process makes the Design Code Utility and other utility scripts available through the dcu.cmd|sh command. At this point, you can either run the dcu command via a command prompt or by configuring the integrated development environment (IDE) of your choice to run it.

On Linux systems, performing the following command will put the command line utilities on your PATH:

sudo npm link

Use the dcu to grab and upload source code and metadata

The dcu is the core code and metadata synchronization utility, which allows you to grab all of the user modifiable source code and metadata from a Commerce server, edit it as necessary in your chosen tool, and then upload it back to the server. The utilities also makes it possible to transfer content between Commerce server instances. The dcu supports these main operations:

• --grab takes a copy of all, or some of, the available user modifiable source code and metadata from the specified Commerce server and creates a directory tree on the local disk.
• --put sends the contents of a single file back to the specified Commerce server.
• --putAll sends all the files underneath a named directory back to the specified Commerce server.
• --transferAll enables the transfer of content between Commerce server instances.
• --compileLess combines all off the downloaded less resources for widgets, elements, stacks and themes and posts them to the node for compilation.
• --clean deletes all local files that have been previously created.

The basic command for grabbing files is:

dcu --grab

The basic command for uploading a single file is:

dcu --put <path to file>

For example:

dcu --put "widget/Add Product To Wish List/instances/
      Add Product To Wish List Widget/display.template"

The basic command for uploading all files under a specified directory is:

dcu --putAll <directory>

For example:

dcu --putAll theme

During each of these operations, the utility provides messages to tell you the status of the grab or upload. You can modify these basic commands with the options described in the Understand dcu options section.

Refresh previously grabbed content

When developing widgets you may find it necessary to refresh your local directory tree with the latest content from the server. While this can be done by issuing another grab, this may take a few minutes on a larger site and can be wasteful if you are only interested in specific changes. You can refresh all of the files within a specified directory by using the --refresh command. For example, the following would only refresh all of the files from the widget directory:

dcu –refresh widget

You can run incremental refreshes on the following directories:

• The application-level JavaScript directory, for example global
• The global snippets directory, for example snippets
• Individual global snippets locale directories, for example, snippets/en
• The stack directory, for example stack
• Individual stacks directories, for example stack/MyStack
• The themes directory, for example, themes
• Individual themes directories, for example theme/BlueTheme
• The global elements directory, for example element
• Individual global element directories, for example element/image
• The widgets directory, for example widgets
• Individual widget directories, for example widgets/Header
• The site settings directory.

For example, to refresh a specific stack from within the stack directory, you could perform the following command:

dcu –-refresh stack/MyStack

Generate a partial grab

For certain workflows, for example when DCU is being used as part of a continuous integration pipeline, it was be advantageous to grab only objects of a certain type. This is not the same as a refresh however as refresh requires there to have been at least one grab in the target directory. You can do a partial grab by supplying a directory with the –grab option

For example, the following would only grab only the element related content from server: dcu –--grab element

You can run incremental grabs on the following directories:

• The application-level JavaScript directory, for example, global
• The global snippets directory, for example, snippets
• Individual global snippets locale directories, for example, snippets/en
• The stack directory, for example, stack
• Individual stacks directories, for example, stack/MyStack
• The themes directory, for example, themes
• Individual themes directories, for example, theme/BlueTheme
• The global elements directory, for example, element
• Individual global element directories, for example, element/image
• The widgets directory, for example, widgets
• Individual widget directories, for example, widgets/Header
• The site settings directory

For example, to grab only a single element you could perform the following command:

dcu –-refresh element/MyElement

Transfer source code and metadata between Commerce instances

You can use the dcu to transfer source code from one Commerce instance to another. This can be useful for promoting source code from a test environment to production.

To use the transfer feature, you must execute a grab from the source instance, for example:

dcu  --grab --clean --node https://sourceInstance --user username --password pwd 

After the grab is finished, you transfer the files to the destination instance, using a command similar to the following:

dcu --transferAll path --node https://destinationInstance --user username --password pwd

The dcu takes a “best effort” approach to transferring content between instances. In general, it matches by name so that if, for example, a widget instance on the destination instance has the same name as a widget instance on the source instance, they are assumed to be the same. The matching rules for each entity type are described in the table below.

Type	Matching rules
Global elements	Matches on the <element> tag. If the element does not exist, a warning is issued.
Application-level JavaScript modules	Matches on the JavaScript file name. If the file name does not exist, it is created on the destination instance.
Text snippets	Matches on locale.
Stacks	Matches on the stack instance’s display name. If the stack instance does not exist, a warning is issued.
Themes	Matches on the theme name. If a matching theme does not exist, one is created on the target instance, using the same name and source code.
Widgets	Widgets are matched on version number and display name. If the widget does not exist, a warning is issued. Widget instances are matched on display name. If a matching widget instance does not exist, a new widget instance is created on the target instance using the same display name and source code.
Elements	Widget elements are matched on version number, display name and <element> tag. If the element does not exist, a warning is issued.
Site Settings	Site Settings are matched on display name. If a matching Site Settings group does not exist on the target server, one is created with the same name and source code.

Understand dcu options

The following table describes the options you can use with the dcu.

Option	Description
-h, --help	Provides usage information for the utility.
-V, --version	Provides the utility’s version number.
-n, --node <node>	The URL for the administration interface on the target Commerce instance, for example, https://localhost:9080. Used with --grab, --put, and --putAll. If --node is not specified, the utility attempts to use the most recently specified node.
-k, --applicationKey <key>	The application key to use to log into the target Commerce administration interface. It is recommended that you create an application key for authentication purposes. For detailed information on creating an application key, refer to the Use the application key for authentication section. It is also possible to specify the application key using the CC_APPLICATION_KEY environment variable.
-u, --username <userName> -p, --password <password>	These options are no longer available, having been replaced by the applicationKey option.
-g, --grab [<directory>]	If no directory is specified, the grab option copies all available content from the target Commerce instance into the current working directory, or the base directory if one has been specified. If a directory is specified, then only content associated with that directory will be grabbed. Note: During a grab, a new directory called .ccc is created on disk alongside the grabbed directories. This is called the Tracking Directory and holds important metadata used by the utility. Do not modify this directory.
-t, --put <path to file>	Sends the specified file back to the specified Commerce instance. The <path to file> can be either a relative or absolute path, in either Windows or POSIX format. Relative paths are relative to the base directory, which you can specify using the --base option. If the --base option is not provided, the base directory is assumed to be the current working directory. If a full path is provided, then any value specified in the --base option is ignored.
-b, --base <directory>	Specifies the base directory. This can be either a relative or absolute path, in either Windows or POSIX format.
-l, --locale <locale>	Retrieves text snippets and resources for the specified locale only. Also, the informational messages displayed by the Design Code Utility will appear in the locale specified.
-a, --allLocales	Gets text data for all locales rather than just the current locale for the target Commerce instance.
-e, --refresh <directory>	Refreshes content from the Commerce instance within the specified directory.
-c, --clean	Deletes all local files that have been previously grabbed. Used only with the --grab option.
-m, --putAll <directory>	Sends all files back to the target Commerce instance, beneath the specified directory. The <directory> can be either a relative or absolute path, in either Windows or POSIX format. Relative paths are relative to the base directory, which you can specify using the --base option. If the --base option is not provided, the base directory is assumed to be the current working directory. If a full path is provided, then any value specified in the --base option is ignored.
-x, --transferAll <path>	Transfers all files from the local machine to the specified Commerce instance, matching by name. For example, if a widget instance is called Red Footer and the utility finds a widget instance on the target that is also called Red Footer, the utility assumes they are the same.
-i, --updateInstances	Updates all instance templates, less and locale strings using their respective base assets. By default, when a base widget template, less or locale file is modified, the changes affect only widget instances that are subsequently created. When you select this option, all widget instance assets of a specific type are overwritten with their corresponding base contents. You can use this option to correct issues affecting a large number of existing instances. It is recommended to use this option sparingly.
-o, --noInstanceConfigUpdate	By default, when performing a put, putAll or tranferAll, widget instance metadata is updated on the Commerce instance. However, you may want to have widget instance configuration metadata different between Commerce instances. Use this option to suppress widget instance metadata updates.
-C, --compileLess [auto]	This option, used in conjunction with ccproxy, prepares a local copy of the rendered storefronts CSS file. The CCAdminUI endpoint ensures that all standard storefront styles are included, as well as any less files you may have created. If the active site theme is restricted, the Less Compiler also includes the current active theme in the CSS output.
-N, --noThemeCompile	When DCU puts or transfers a Less file, it will trigger a Theme recompilation. However, for large scale transfers, this can significantly increase transfer time. Therefore, specifying this option means that a Theme recompilation is not automatically triggered and, as such, you are required to manually trigger it once the transfer completes. See Manage Large Scale Transfers for further details.
-A, --autofix	This option is recommended for use on large scale transfer operations, and helps to avoid issues that may arise when transferring instances of Oracle widgets. See Manage Large Scale Transfers for further details.
-d, -delete	The delete option enables the deletion of widget instances.

Add JavaScript to existing user-created widgets

You can add JavaScript to an existing user-created widget by creating a new .js file under the widget’s /js directory and issuing a put, putAll or transferAll.

Use the ccproxy utility

The ccproxy utility is the proxy that allows you to develop and debug your code. The script allows you to route your storefront requests through a local node.js application, which intercepts certain resources and then substitutes them with a local modified version. When the server starts up, it looks at your widget, element, stack and theme metadata and then builds mappings of the server data to local files to the local files downloaded by the dcu utility.

Note: Before you can use ccproxy, you must redirect your browser HTTP traffic to the port on which ccproxy is listening. Refer to your browser documentation for information on browser-specific proxy switchers.

Work with HTTPS traffic

When using a proxy to connect to a secure HTTPS site, ccproxy automatically generates self-signed certificates. These certificates may cause a warning in the browser the first time you visit the proxied storefront. However, it is safe to proceed past this warning.

Note: The browser proxy switcher that you use must also be set up to redirect HTTP and HTTPS traffic to the ccproxy host.

The following table describes the options you can use with the ccproxy utility.

Option	Description
-h, --help	Provides usage information for the utility.
-V, --version	Provides the utility’s version number.
-n, --node <node>	The URL for the administration interface on the target Commerce instance, for example, https://localhost:9080. Used with --grab, --put, and --putAll. If --node is not specified, the utility attempts to use the most recently specified node.
-P, --port <number>	Changes the port on which the ccproxy listens. The default is 8088. Alternatively, you can set the CC_DEVPROXY_PORT environment variable.
-b, --base <directory>	Uses the directory indicated as the base directory.
-l, --list	List proxy substitution rules.
-d, --disable <list>	Specify a set of substitution rules to disable (overrides -e flag).
-e, --enable <list>	Specify a set of substitution rules to enable. Note: Substitution rules can be enabled/disabled by name (you can view the rule names using the -l flag). The -e/-d parameters will take one or more rules names as a comma separated list. e.g. $ ccproxy -e Javascript,WidgetTemplate To enable only substitution of JavaScript files and widget HTML templates.

Use the ccw utility

Commerce includes the ccw utility, a command-line tool that allows you to create new content on Commerce with the IDE or code editor of your choice. This tool allows you to create new widgets, stacks and elements, and then upload them to the server.

For detailed information on working with widgets, stacks and elements, refer to Understand widgets.

The format for invoking the ccw is:

ccw [options]

Understand ccw utility options

The following table describes the options you can use with the ccw utility.

Option	Description
-b, --base <directory>	Identifies the base directory.
-h, --help	Provides usage information for the utility.
-l, --locale <locale>	Uses the supplied locale as the default locale. Also, the informational messages displayed by the ccw will appear in the locale specified.
-n, --node <node>	The URL for the administration interface on the target Commerce instance, for example, https://localhost:9080. If --node is not specified, the utility attempts to use the most recently specified node.
-k, --applicationKey <key>	The application key to use to log into the target Commerce administration interface. It is recommended that you create an application key for authentication purposes. For detailed information on creating an application key, refer to the Use the application key for authentication section. It is also possible to specify the application key using the CC_APPLICATION_KEY environment variable.
-V, --version	Provides the utility’s version number.
-w, --createWidget	Creates a new widget.
-e, --createElement <widgetOrElementDirectory>	Create a new element - optionally under a widget directory or as child of another element.
-g, --generateMarkup [elementDirectory]	Generate template mark-up to match the supplied element including sub-elements.
-s, --createStack	Create a new stack.
-t,, --createSiteSettings	Create a new group of site settings.

Create a widget with the utility

When you create a new widget, the ccw asks a number of questions so that it may create a widget. The extension is created by calling the appropriate endpoints.

Initiate the ccw with the option to create a new widget:

ccw -w

This brings up the following wizard interface:

Understand the ccw utility widget creation questions

When creating the widget, you are prompted to answer a number of questions. The way that you answer these questions affects the way that the widget is created. The following section provides details of the questions asked during the creation of the widget.

Question	Explanation
Enter the name of the new widget	The textual name used to create the widget directory. It is also the name used when the widget is created on the Commerce instance.
Is the new widget global? (Global widgets are loaded on every page but have NO display template.)	Global widgets are a way to include common JavaScript code across every page layout in the store. A global widget can have only a single instance. Note that a global widget is not the same as a global ViewModel. Should you create observable properties in your global widget, they will not be automatically available in any ViewModel.
Does the new widget require internationalization?	Internationalized widgets require additional resource bundles, which are created if you answer yes.
Is the new widget configurable?	If you answer yes , you are indicating that the widget requires user configurable meta data. Refer to Understand widgets for information on configuring widgets.
Should the new widget contain example source code?	If you respond yes, the generated widget will contain various instructions and examples to assist those new to widget development.
Should the new widget be sent to the instance immediately?	If you respond yes, the new widget will be created as an extension on the target Commerce instance. If you answer no, the widget is created the next time you do a putAll or transferAll.
Does the new widget require fragmentation?	If you answer yes, the widget will be usable with elements.

After you have answered all of the questions, the responses are validated and a skeleton widget is created. Once the widget has been created, it is sent to the server as an extension, unless you requested that it should not. Once you get the response that the upload is successful, you can drag the widget onto a layout.

Create a simple global element with the ccw utility

When you create a new element, the ccw asks a number of questions to determine the kind of element needed. The new global element will be usable with all widget types.

Initiate the ccw with the –e option to create a global element:

ccw –e

This will bring up the following wizard interface:

Create a simple widget element with the ccw utility

New elements can also be created under widgets, provided that the widget has not already been placed on the Commerce instance. The resultant element will only be usable with that widget.

Initiate the ccw with the –e option to create a widget element and include a path to the widget the element is to be added to:

ccw –e widget/Galaxy

This will bring up the same wizard interface used for global elements.

Create a rich element with the ccw utility

Elements can also be created as children of other elements. This enables the creation of configurable rich elements similar to “Price” or “Inventory Status” in the “Product Details” widget.

Creating a rich element follows a standard pattern best thought of as a tree:

• At the top level (or root node) must be an element of type “fragment” with the single configOption “available” selected.
• At middle level, there must be one or more elements of type “container”. These must be children of the previously described top level element. Only the configOptions “available”, “actual”, “currentConfig” and “preview” should be used with container elements.
• At the lowest level (leaf nodes) must be one or more elements of type “subFragment”, “staticFragment” or “DynamicFragment”. These must be children of a container element. Only the configOptions ”border”, “collectionPicker”, “elementName”, “fontPicker”, “horizontalAlignment”, “image”, “padding”, “preview”, “richText”, “textBox”, and “wrapperTag” can be used with elements of this type.

Also, the markup for a rich element needs to be manually placed in a widget template - it cannot merely be dragged to a widget within the Design page. The markup for a rich element has the following general form:

Creating a rich element is a multi-stage process and ccw tries to make this as smooth as possible. To create a rich element with ccw:

1. Create the top level element by selecting a type of “fragment” and answering yes to the sub-elements question:
2. Create one or more child container elements by specifying the path to the previously created root element on the ccw command line:
3. Create one or more child leaf elements by specifying the path to the previously created container element on the ccw command line:

   If you do a putAll/transferAll on a directory containing multiple elements, DCU will send the leaf elements first, then the containers, and finally the top level elements.

   Note that if a user creates an elementized widget, or an element containing sub-elements using ccw and answers yes to the “example source code” question, a sample rich element will be created.

Understand the ccw utility element creation questions

When creating the element, you are prompted to answer a number of questions. The way that you answer these questions affects the way that the element is created. The following section provides details of the questions asked during the creation of the element.

Question	Explanation
Enter the name of the new element	The textual name used to create the element directory. It is also the name used when the element is created on the Commerce instance.
Please select the type of the new element	The type of the element you require. Depending on the context, the available options may vary.
Does the new element require internationalisation?	Internationalized elements require additional resource bundles, which are created if you answer yes.
Does the new element require JavaScript?	If you respond yes, a suitably formatted JavaScript file will be created and associated with the new element.
Will the new element have sub-elements?	If you respond yes, the generated element will be a rich element like the “Product Price” element using in the “Product Details” widget.
Please select any configuration options required in the new element	This enables you to select how the element can be configured by the user inside the Design page. The options displayed depend on your response to the “Please select the type of the new element” question.
Should the new element be inserted as a span (if not, it will be inserted as a div)?	This question determines how the element mark-up will be inserted in the HTML DOM.
Should the new element contain example source code?	If you respond yes, the generated element will contain various instructions and examples to assist those new to widget development. If you answered yes to the “Will the new element have sub-elements?” question, example sub-elements will be created.
Should the new element be sent to the instance immediately?	If you respond yes, the new element will be created as an extension on the target Commerce instance. If you answer no, the element is created the next time you do a putAll or transferAll.

Create a stack with the ccw utility

When you create a new stack, the ccw script asks a number of questions in order to create a stack.

Understand the ccw utility stack creation questions

When creating the stack, you are prompted to answer a number of questions. The answers provided to these questions will determine how the Site Settings are created. The following section provides details of the questions asked during the creation of the stack.

Question	Explanation
Stack name	Name of the new stack type.
Max number of variants	Maximum number of sub-regions that the stack supports.
Default variants	Number of sub-regions a new instance of the stack will have by default.
Requires internationalization	Generate additional language resources at creation time.
Include example code	If yes, generate some example template and style code.
Server Sync	If yes, automatically send the new stack to the server.

Create Site Settings with the ccw utility

Site settings are parameters that are used by the code. They are added to your site view model, and are available to all widgets. Using site settings, you can create a single setting that controls a feature used by multiple widgets. Site settings are contained within extensions. For information on working with extensions, refer to Develop Server-Side Extensions. Once you have uploaded, the site settings allow you to create custom settings in the administration interface. You can use the Admin REST API to work with site settings, as described in the REST API Site Settings documentation.

You can use the ccw utility to create a new group of Site Settings. To do this, the ccw script asks a number of questions in order to create a Site Settings group.

Question	Explanation
Site Settings name	Display name of the new Site Settings group.
Include example code	If yes, then generate some example metadata.

Understand the ccw utility Site Settings creation questions

When creating the Site Settings, you are prompted to answer a number of questions. The answers provided to these questions will determine how the Site Settings are created. The following table provides details of the questions asked during the creation of Site Settings:

Delete content with the ccw utility

The ccw utility creates widgets, stacks and elements as extensions, allowing you to delete previously created widget, stacks, or element content by deactivating and deleting the corresponding extension.

To delete the widget, stack, or element from your local disk after you have deleted the extension, issue the following command:

ccw –-grab –-clean

Use the plsu utility

The Page Layout Synchronization Utility (PLSU) enables you to manage and edit page layouts on your server. You can use the following operations with the pls utility:

• --list – Displays the names of all of the layouts on the specified server
• --delete – Deletes one or more page layouts on the specified server
• --transfer – Copy one or more page layouts from a specified server to another

List page layouts

The following command lists all of the page layouts available on a server:

plsu -–list –-node https://commerceCloudInstance –-applicationKey applicationKey

The response might resemble:

Home Layout
Collection Layout
Product Layout
Cart Layout
Cart Layout With Shipping
Checkout Layout
Checkout Layout with GiftCard
Order Confirmation Layout
About Us Layout
Contact Us Layout
Privacy Layout
Returns Layout
Shipping Layout
Error Layout
Search Results Layout
No Search Results Layout
Payer Authentication Layout
Wish List Layout
Purchase List Layout
Profile Layout
Account Based Profile Layout for B2B
Order Details Layout
Order History Layout
Wish List Profile Layout
Scheduled Order Layout
Assets Layout
Asset Details Layout

Delete page layouts

You can delete a page layout using a command similar to the following:

plsu –-delete –-name "page layout to delete" --node  https://commerceCloudInstance –-applicationKey applicationKey

You can specify the --name option more than once. Note that default layouts cannot be deleted.

Transfer page layouts between servers

You can transfer a single page layout by using the following command:

plsu --transfer --node https://commerceCloudInstance –-applicationKey 
applicationKey --name "Page Layout To Transfer" –-destinationNode https://commerceCloudInstance --destinationNode destinationApplicationKey

You can specify the --name option more than once.

To transfer all page layouts, use the following command:

plsu --transfer --node https://commerceCloudInstance –-applicationKey
applicationKey --all --destinationNode https://commerceCloudInstance
 --destinationNode destinationApplicationKey

Page layouts that do not exist on the target system will be created. Note that, unlike dcu --grab,

plsu -–transfer does not create anything on your local disk.

Certain page layout-related features may refer to other content on your Commerce instance. If this is the case, plsu will not transfer a page layout if it relies on data that is not already present on the destination system. As such:

• Widget instances used within the layout must already exist. These can be created by performing a dcu --put or --transfer before calling plsu
• Sites associated with page layouts must already exist. These can be created using the administration interface
• Audiences associated with page layouts must already exist. These can be created using the administration interface

Before transferring page layouts, plsu --transfer performs all error checking. If the utility finds missing data, no page layouts will be transferred.

Understand plsu options

The following options are available with the plsu utility:

Question	Explanation
-h, --help	Provides information to assist with running the utility.
-V, --version	Provides the utility’s version number.
-n, --node <node>	The URL for the administration interface on the Commerce instance. For example, https://localhost:9080. This is a required option. When used with --transfer, this value indicates the source instance. The destination instance should be specified by using --destinationNode.
-k, --applicationKey <key>	The application key to use to log into the Commerce administration interface. This is required for authentication. For detailed information on creating an application key, refer to the Use the application key for authentication section. You can also specify the application key using the CC_APPLICATION_KEY environment variable.
-l, --locale <locale>	Forces the default locale to the supplied value.
-d, --detinationNode <node>	The URL of the destination administration interface on the Commerce instance, for example: https://localhost:9080. This option is used with --transfer.
-a, --destinationApplicationKey <key>	The application key to use when logging into the destination Commerce administration interface. This key is required for authentication purposes. For detailed information on creating an application key, refer to the Use the application key for authentication section.
-y, --name <name>	The name of the page layout. You can use this option multiple times, and with –-delete and –-transfer. You cannot use this option with --all.
-s. --all	Specifies that all page layouts should be transferred. This option is not available with --all.
-i, --list	This lists all of the page layouts available on the system.
-e, --delete	This option, which must be used in conjunction with the --name option, deletes one or more page layouts from the Commerce system.
-t, --transfer	This option transfers one or more page layouts from one system to another. This option must be used in conjunction with --name or --all options.
-g, --ignoreVersions	This option enables plsu to transfer layouts between Commerce instances that are not at the same release version and, as such, should be used with caution.

Manage Large Scale Transfers

While DCU is primarily a developer toolchain that bridges the gap between a developer's machine and a Commerce instance, you can also use it for large scale transfers, however, there are some limitations.

The quickest and easiest way to promote widget code and assets between Commerce instances is via a database copy. The promotion of client code between two Commerce instances will typically require the use of both the plsu and dcu utilities. Note: when performing a large scale transfer you should run dcu first, this is because plsu expects all the widget instances used in the page layouts being transferred to be made available. You should also note that large scale transfers using dcu can take several hours to run, depending on the network speed and the number and size of assets being copied.

It is recommended that you should identify what has actually changed and transfer only those assets, which is a quicker method than copying all assets every time. When transferring assets between Commerce instances, it is also recommended that they are at the same release version.

New widgets and other assets should always be created with ccw and not via an extension. If new widgets are being created using an extension, the version number should be set to one and never changed. Version numbers are intended to be used with Oracle widgets only and can cause transfer issues if misused. Adding non-standard files and directories under widgets is only partly supported by dcu. When a widget is initially created on the target instance during a transferAll or putAll, any unrecognized files found under the widget directory are included in the extension. However, these non-standard additional files, such as, graphic files, cannot be changed on the server without first deactivating the corresponding extension and re-running a transferAll or putAll. Performing a put or transfer on these individual files will have no effect. Note: you can use dcu to delete unwanted widget instances, as described later in this section.

Use dcu for large scale transfers

To transfer all Design Studio assets between two Commerce instances, you would typically call dcu as shown below:

dcu –x . –n https://destinationInstance –k <destinationInstance Application Key>

However, dcu has a number of additional command line options that may be useful in large scale transfer scenarios.

The first of these is the --noThemeCompile option. By default, when dcu updates a less file, the server will trigger a Theme recompilation which can significantly slow down large scale transfers. Specifying the --noThemeCompile option will mean that no Theme recompilation is triggered and you will have to manually trigger the Theme recompilation after the transfer is complete. You can manually trigger a Theme recompilation either via the UI or by transferring a single less file with dcu when complete.

The second option to consider with large scale transfers is the --autofix option. Normally, when dcu finds a missing widget instance during a transfer, it will attempt to create a new widget instance at the requisite version and apply the changes. For user created widgets, this works as expected but for Oracle widgets on systems which may not have exactly the same widget versions, this can cause a conflict if a widget instance already exists of the same name but a different version. If you supply the --autofix option and dcu finds a conflicting widget instance, it will attempt to create that instance at the same version number as on the source instance after first renaming the conflicting widget instance. The latter assumes that the widget exists on the target system at the desired version. You may find transfers are somewhat slower when the --autofix option is used. This option can result in a lot of widget instances existing on the target system so use it with discretion. Once the DCU transfer is complete, you should review the output and check for any errors or warnings.

Use plsu for large scale transfers

When all widget and related assets have been transferred, plsu can then be called to transfer page layouts. To transfer all page layouts between two instances, you would typically call plsu as shown below:

plsu –n https://sourceInstance –k <sourceInstance Application Key> –d https://destinationInstance –a <destinationInstance Application Key> -ts

In general, it is recommended that transfers take place between Commerce instances which are at the same release version. While the plsu utility does have an –ignoreVersions option, this should be used with care. Transfers using plsu will typically take much less time than with dcu. Any missing stack instances will be created during a plsu transfer. Note: plsu does not require a grab to be run first; it does a point to point data transfer.

Use dcu to delete widget instances

In order to remove a widget instance from an Oracle Commerce instance, you would typically call dcu as shown below:

dcu -k <destinationInstance Application Key> --delete widget/WidgetName/instances/WidgetInstanceToDelete

This removes all traces of the widget instance from both the local grab directory and the Commerce instance.