Customize the Oracle Commerce Agent Console

7 Customize the Oracle Commerce Agent Console

You can perform a number of customizations and actions by extending the Oracle Commerce agent widgets.

Assumptions

Before you create widgets for your agent environment, you should be familiar with specific technology.

You should be comfortable with site administration, have experience with the following technologies and have reviewed the necessary documentation:

JavaScript
Data binding using Knockout
Bootstrap
Standard CSS and CSS Less
MVVM Architecture
Familiarity with Developing Storefront Classic Widgets for Oracle Commerce, which provides a detailed overview of how widgets work in Oracle Commerce
Familiarity with the Oracle Commerce agent console

About extensions

Oracle Commerce agent console provides tools that you can use to extend the capabilities of your system.

The tools consist of the following:

Widgets that allow you to extend the functionality of your agent's environment by accessing features that are not exposed by default. This guide focuses on describing agent console-specific widgets. For general information on other widgets, see Developing Storefront Classic Widgets for Oracle Commerce.
An extensive set of REST APIs allows external applications to make calls into the Oracle Commerce server. This guide focuses on agent-specific APIs.

Work with widgets

Widgets allow you to display content to your agents or to execute specific functions. Widgets are comprised of templates, JavaScript, CSS, locale resources and images. For detailed information on widgets and extensions, refer to the Developing Storefront Classic Widgets for Oracle Commerce guide.

When you customize widgets, you create functionality that appears on your website pages. These widgets allow you to add pre-made and pre-configured snippets of text or information to your web pages without having to recreate them for each page. Widgets also allow you to extend the functionality of your storefront by communicating with the Oracle Commerce Agent server to access a variety of features.

You can use agent-specific widgets to create a customized agent environment. Widgets are comprised of a set of resource and source files. Using these files, as well as auxiliary files that contain information such as meta-data, you can customize an agent’s environment.

The agent environment uses agent-specific widgets, as well as Oracle Cloud Commerce storefront widgets. There are separate instances for agent and storefront widgets. Note that these instances differ in the template, and sometimes the configuration properties, they use. If you delete an agent widget instance, which uses a different template than the Display template, you will be unable to recreate the widget.

Important: Please note that Oracle Commerce Agent Console, unlike Oracle Commerce Storefront, does not support application JS, global widgets, or global elements. Any element used in default widgets should be downloaded and customized.

Tasks done by widgets

The following are some general tasks that can be performed by widgets:

Agent Navigation - Enables an agent to navigate throughout the console to review a variety of data. Additionally, you can rename fields and buttons, and hide or display certain fields or navigational items.
Search - Allows an agent to search for customers, orders or returns.
Create Orders - You can display navigation, customer cart dialog, shipping details, address books, promotions, loyalty details, scheduled orders and product details, in addition to other displays.
Order Details - You can create widgets to display order details for account orders, return and exchange orders, quotes and order approvals. You can also customize carts to show subtotals and logic for payment and pricing.
Customer Details - You can create customized widgets to display account addresses and details, customer profile information, order histories, purchase lists, account contacts and other profile information.
Returns and Exchanges - You can create widgets that display or create return requests and refunds, as well as process returns. You can also create widgets that create exchanges.

This documentation provides the following information for each widget:

Description- A description of the widget.
Widget Name - The code name of the widget. The name of the widget is identified in the widget.json file. For example:
```
"javascript": "agent-order-search",
"widgetFamily": "agentOrderSearch",
"widgetType": "agentOrderSearch"
```
Display Name - The widget’s name as displayed in the Design page. The display name can also be found in the widget.json file:
```
"name": "Order Search - Agent"
```
Supported Page Type - The types of pages that the widget can be applied to. This is also identified in the widget.json file:
```
"pageTypes": ["agentOrderSearch"],
```
For information on page types, refer to Define stack meta-data in stack.json.
Layouts - The page layouts that this widget is associated with. A widget’s associated layouts are identified on the Layout tab of the Design page. For detailed information on layouts, see Create Page Layouts that Support Different Types of Shoppers.
Elements - The elements used by this widget. Each element represents a single piece of the structure of the widget. Elements can be configured as drag-and-drop sub-components, which allow you to control their location on a page’s layout. Elements are added to the widget’s display.template file and can be reviewed using the Design tab code view.
For detailed information on elements, see Fragment a Widget into Elements.

For information on Storefront widgets refer to Appendix: Layout Widgets and Elements.

Access widgets

You can review Oracle Commerce default widgets by opening the Design page on your administration server. This page displays both the layouts that are used in the agent console, but also the components, such as widgets, that are available. Click the Component tab to see the list of widgets.

Each widget displays the associated page layouts. By selecting the page layouts, you can customize the pages by adding or removing widgets. For information on working with widgets and layouts, see Appendix: Layout Widgets and Elements.

Note that widgets that are specific to the agent console contain the word “Agent”. The agent console also uses a number of widgets that are also used by the Storefront.

Extend functionality with widgets

You can customize widgets by downloading the widget source code and making modifications to the JavaScript and HTML files. For example, you could add custom JavaScript to an existing widget. Once you have made all of your changes, you then upload the widget by adding it to an extension as described in Understand Extension Features.

Important: When creating or renaming a widget, ensure that the name is less than 50 characters. Errors will occur if the widget name is greater than 50 characters.

You can also extend a widget’s JavaScript by using the JavaScript Code Layering feature that allows you to layer custom JavaScript on top of the widget. For information on the JavaScript Code Layering feature, see Use the JavaScript Code Layering User Interface feature.

Note: For a widget’s JavaScript code to be editable, ensure that the jsEditable flag in the widget.json file is set to true. By default, the flag is set to false, indicating that the JavaScript associated with the widget cannot be edited.

When you upgrade or modify a widget, you must remove any existing instances of it from the page layouts and replace it with the new widget.

Upgrade widgets

Widgets that have been deployed are not automatically updated when a newer version of the widget is released. This allows you to customize widgets without the fear of them being overwritten. To update a widget, you must remove the old widget from all of your page layouts and replace them with the new widget. Additionally, you must recreate templates or style sheets that you have customized for the new widget.

For detailed information on how to upgrade widgets, see Customize your store layouts.

Migrate widgets with multiple templates

Some widgets use more than one template. If you migrate your widgets and load the latest version of the widget, the agent-specific template is not available for newly created widget instances. To update the widget with the new version, you must ensure that the widget's new template file is recognized by the layout.

To do this, perform the following steps:

Open the widget in the administrative interface using the Settings icon.
Open the About tab. Click the Go to widget code button.
Click the Download Source button.
Unzip the file that you downloaded.
Open the /widget/widgetName/layouts/layoutThatContainsTheLayout file and copy the contents of the newer version of the widget-layoutAndVersion.template file.
For example, you might copy the widget-orderDetailsDefaultLayout_v3.template file.
Return to the administrative interface from where you downloaded the source. In the Template tab, replace the existing code with the code you have copied from the new version of the widget.template file.
Click Save.
Ensure that you update the associated layouts.

Migrate widget with multiple LESS files

If you have recently migrated, your widgets will be listed in the page layout components. However, if you use a widget in a page layout region, and then create a new widget instance, the widget instance will be created with the default template, which won't be applicable to the page layout. To update these widgets, perform the following steps:

Open the widget in the administrative interface using the Settings icon.
Open the About tab. Click the Go to widget code button.
Click the Download Source button.
Unzip the file that you downloaded.
Open the /widget/widgetName/less/ file and copy the contents of the newer version of the widget.less file.
For example, you might copy the widget-agentAccountOrderDetailsInst_v4.less file.
Return to the administrative interface from where you downloaded the source for the widget. In the Style Sheet tab, replace the code with the code you have copied from the new version of the LESS file.
Click Save.
Ensure that you update the associated layouts.

Recreate shared widgets after deletion

Some widgets also have corresponding storefront widgets. These widgets, although designed to perform similar tasks, use different templates and, sometimes, configuration properties. If an agent-specific widget is deleted, and the agent widget uses a different template than the storefront widget, you will not be able to recreate the widget from the administrative interface.

To rectify this, download the agent-specific widget and recreate the template for the instance.

Use the Agent REST API

Oracle Commerce uses REST APIs that consist of several sets of endpoints, which allow you to perform storefront, administrative and agent tasks.

These include Store, Admin, Social Wish List and Agent APIs.

The Agent API endpoints provide access to agent-specific functionality on the administration server. These endpoints can be used in conjunction with agent-specific widgets, for example to pass a response filter key in a REST call that was made from a widget.

Note that there are many similar endpoints that exist in each API. For example, each set of APIs may have endpoints for working with customers, although each endpoint differs in the functionality that they perform.

You can access a ccdebug REST client on your administration server in your test environment. This client is available at the following URL:

http://<admin-server-hostname>/ccebug

Each API is available only in certain environments. The Agent API is available only on administration servers. You can find information on endpoints in the REST API documentation, which is available through the Oracle Help Center at the following URL:

http://docs.oracle.com/cloud/latest/commercecs_gs/CX0CC/

Note that the documentation on the Oracle Help Center reflects the most recent version of Oracle Commerce. If you are using an earlier version of Commerce, the API documentation on the Oracle Help Center may include endpoints that are not available on your version.

For additional information on working with REST APIs, see Use the REST APIs.

Find additional resources

You can find additional information on working with widgets in the following documents:

Developing Storefront Classic Widgets for Oracle Commerce - Describes how to work with and implement widgets in your environment. This document contains many examples of how to implement and customize widgets.
Extending Oracle Commerce - Describes various task-specific widgets, as well as how to use REST APIs for customization.
Layout Widgets and Elements - Provides information on Storefront-specific widgets.