Publish Changes

Understand Publishing

Retail Digital Commerce saves publishable changes to named worksets. When you want to publish changes, you publish the workset that contains them. You can publish the changes in all worksets at once, or you can pick a specific workset to publish.

This section provides details about how Retail Digital Commerce handles publishable changes. See Understand worksets to learn about how Retail Digital Commerce uses worksets to organize those changes.

Keep the following points in mind as you prepare to publish changes:

Retail Digital Commerce does not use versioning for items you edit and publish. There is only one version of each item in your system.
For example, a merchandiser changes the long description and list price of a product and then saves the changes but does not publish the workset they are saved in. Later that day, a manager changes the product’s list price again, saves the changes to the same workset and then publishes the workset. The most recent changes to the product—the merchandiser’s long description and the manager’s list price—are published.

Similarly, a single item can be saved to multiple worksets. In this case, the most recent changes to the item, no matter which workset they are in, get published first. Looking at the previous example, suppose the merchandiser saved a product’s new long description and price list in #julyWorkset and then the manager changed the product’s price list again and saved the change in #default. No matter which of these worksets is published first, the result is the same: the merchandiser’s long description and the manager’s list price are published. Then Retail Digital Commerce removes the product from the workset that has not yet published.

When you save changes to a publishable item in the administration interface, Retail Digital Retail Digital Commerce warns you if you another user saved changes to the item while you were editing it. For example, a merchandiser opens a product for editing and changes the long description and list price. While the merchandiser is editing the product, the manager opens the product, changes the list price, and saves those changes. When the merchandiser goes to save the work, Retail Digital Commerce notifies the merchandiser that someone else made changes to the item while the merchandier was editing it. The merchandiser can choose to proceed saving and overwrite the manager's changes, continue editing the item, or discard their changes.
You cannot roll back or undo published changes.
Some changes do not need to be published, and take effect on your production server as soon as you save them. These changes are described later in this topic.
Some changes must be published together to maintain the integrity of their relationships. These changes are described later in this topic.
While changes are being published, you cannot work with any publishable items in the administration interface. Retail Digital Commerce displays a Publish in Progress message dialog to inform you of this state.
Although you cannot use the administration interface, programs that implement the Retail Digital Commerce REST APIs might still attempt to update endpoints while changes are being published. During a publish operation, Retail Digital Commerce responds to all PUT or POST calls to endpoints that update publishable resources with HTTP status code 503, Service Unavailable.
You can use the Retail Digital Commerce REST API to download information about recently published worksets. This can help you keep track of which changes were published. See Publish changes using the REST API for more information.

Changes that do not Require Publishing

Not all changes you make are added to worksets for publishing. Some changes made in the administration interface take effect on your production storefront as soon as you save them. Some changes are automatically published during the next publish.

The following types of changes take effect as soon as you save them and are not added to worksets for publishing. Retail Digital Commerce lets you know you are making these types of changes by displaying a message in the changes tracker. See Understand worksets for more information.

Shopper settings, such as changes to the password policy.
Access control settings, such as changes to internal user profiles.
Inventory updates.
Account settings, for stores that support account-based commerce.
If direct price editing is enabled for your Retail Digital Commerce store, any price changes you make are available on the storefront without publishing. See Update prices without publishing for more information.
If direct catalog editing is enabled for your Retail Digital Commerce store, any catalog changes you make are available on the storefront without publishing. See Edit catalog items without publishing for more information.

The following types of changes are automatically published with the next workset or full publish that happens after they are saved. Retail Digital Commerce lets you know you are making these types of changes by displaying a message in the changes tracker. See Understand worksets for more information.

Search settings, such as index fields. Search settings to not appear in any workset changes list.
Certain changes you make to the catalog, such as creating a new product type or changing a price list group, appear as a single item called Catalog Configuration. The Catalog Configuration item appears at the top of the changes list in every workset until it is published.

Understand Dependencies

Some Retail Digital Commerce items must be published together to maintain the integrity of their relationships. For example, if you update the description of a shipping method, Retail Digital Commerce must also publish the method's associated shipping regions, even if you did not make any changes to them. When you save changes to the shipping method, Retail Digital Commerce calculates the appropriate dependencies (the associated shipping regions) and also adds them to the same workset as the shipping method you saved.

Additionally, Retail Digital Commerce performs a final check before publishing a workset and displays dependencies that are not already in the changes list on the workset's Review and Schedule page. This list is populated by changes to dependencies that are saved in two different worksets. Consider the shipping method example described above. Both the shipping method and its associated shipping regions added to the same workset. But before that workset is published, suppose another user saves changes to one of the associated shipping regions in a different workset. The shipping method whose changes are saved in the first workset is not automatically added to the changes list in the second workset. But when the second workset is published, Retail Digital Commerce displays the shipping method as a dependency on that workset's Review and Schedule page.

Understand Worksets

A workset is a named group of changes that are published together. When you want to publish changes, you publish the workset that contains them. You can publish the changes in all worksets at once, or you can pick specific worksets to publish.

Worksets help you organize changes so you can more easily track and publish related items together. For example, suppose you are working on a holiday campaign that you want to go live at the end of November. You can create a workset called #holidayPromotions. Then, users who work on Retail Digital Commerce items that support the campaign, such as promotions, and SKUs, collections, and layouts, can save their changes to this workset. Then, the workset can be published at a pre-scheduled time.

Retail Digital Commerce includes one workset, named #default. If you do not create any other worksets, Retail Digital Commerce automatically saves all publishable changes to #default.

When you save a change to a publishable item, Retail Digital Commerce automatically saves it to the active workset. If your Retail Digital Commerce environment includes multiple worksets, you can save your changes to a different workset or move saved changes from one workset to another, but all changes that require publishing are saved in at least one workset. There is no way to publish items outside of a workset.

Some Retail Digital Commerce items must be published together to maintain the integrity of their relationships. For example, if you update the description of a shipping method, Retail Digital Commerce must also publish the method’s associated shipping regions, even if you did not make any changes to them. When you look at the workset that includes the shipping method, you will notice that it also contains the associated shipping regions. If you move the shipping method to a different workset, Commerce automatically moves the associated shipping regions.

Understand who can Create and Publish Worksets

Retail Digital Commerce administrators control each internal user's access to specific administration interface pages and tasks with roles and privileges. Only users who have the Publishing privilege assigned can create and publish worksets.

Any user who can edit Retail Digital Commerce items, such as catalogs, can view their changes in the workset that contains them, and can move their changes to a different existing workset.

For more information about privileges, see Understand role-based access control.

Save Changes to Worksets

When you log into the administration interface, you see the Changes tracker at the bottom of the main menu.

The Changes tracker is displayed only to users whose profiles allow them to edit publishable items. For example, a user who can edit catalog items will see the tracker but a user who can edit only accounts will not see it.

The information the tracker displays changes, depending on where you are working in the administration interface. See Understand publishing for more information about these kinds of changes.:

When you navigate to a page where changes are always included in the next publish, the changes tracker displays the active workset as paused and notifies you that changes you make go live at the next publish.
When you navigate to a page where changes do not require publishing, the changes tracker displays the active workset as paused and notifies you that changes you make go live as soon as you save them.

Create and Edit Worksets

One default workset (named #default) comes with Retail Digital Commerce. Until you create your own worksets, all publishable changes are automatically saved in this default workset.

Remember that before you can create worksets, your Retail Digital Commerce user profile must have the Publishing privilege assigned. (See Understand who can create and publish worksets for more information.) All administration interface users who can access the Changes page can see all worksets, no matter who created them.

To create a workset:

On the Changes page, click Publishing Schedule.
Click Add to Schedule and select New Workset.
Enter a name for the workset.
The name can be up to 25 characters long and can contain only letters, numbers, hyphens (-), and underscores (_).

Although not required, it is a good idea to assign unique workset names to make them easier to identify.

Once a workset is created, you cannot change its name in the administration interface, though you can change it with the Admin REST API.
Click Create.
The new workset appears in the publishing schedule, marked as Not Scheduled. Commerce adds a # symbol to the beginning of the name of every workset.

Specify the Active Workset

Your changes are automatically saved in the active workset. Creating a new workset does not automatically make it the active workset. To make your new workset the active workset, select it from the Active Worksets dropdown list at the top of the Changes page.

Move Items to a Different Workset

You can move items from one workset to another, though you cannot simply remove them from their current workset without specifying a new home for them. If an item has dependencies, they are automatically moved to the other workset. To move items to a different workset:

On the Changes page, select a workset from the Active Workset dropdown list.
Select individual items to move or click the Select Page icon to select all the items in this workset.
See View changes in a workset to learn how to sort and filter a workset to more easily find items to select.
Click the Move button.
Select a workset to move the changes to and then click Move.

Delete a Workset

You can delete only empty worksets. If you want to delete a workset that contains items, Retail Digital Commerce lets you select a new workset for them during the delete process. If you delete the active workset, the #default workset automatically becomes the active workset. You cannot delete the #default workset.

On the Changes page, click Publishing Schedule.
Click the Delete Workset icon for the workset. If the workset is empty, simply confirm that you want to delete it.
If the workset contains changes, select a workset to move them to and then click Delete.

Keep in mind that Retail Digital Commerce automatically deletes a workset (except #default, which is never deleted) once its contents have been successfully published.

View the Contents of a Workset

To see the contents of the active workset, click it in the Changes tracker. Retail Digital Commerce displays the workset on the Changes page. To see the contents of a different workset, select it from the Active Workset dropdown list.

Each item in the workset list displays an icon you can click to see details about when changes were made and who made them:

If only one author has made changes, the author's avatar appears in the icon.
If two or more authors have made changes, the icon displays the number of authors.

Click the icon to see the names of authors who saved changes to the item since it was last published, as well as the date and time each change was made.

If an item is a member of more than one workset, the item also displays the number of worksets it belongs to. Click this link to see a list of all the worksets the item belongs to. See Understand worksets for more information about how Retail Digital Commerce publishes items that are in multiple worksets.

Filter and sort items in a workset

The filtering features let you display a subset of a workset's items. Sorting lets you display items by date, from either newest or oldest. Filtering items in a workset is useful for tasks such as selecting items to move to a different workset. However, filtering does not select specific items to publish; all items in a workset are published when that workset is published.

Select the Filter By check boxes along the left-hand side of the page to find specific types of items and changes in the workset. Filter By options include:

Author: The user who made the change.
Status: The type of change made to the item (edited, imported, new, and deleted).
Area: The type of item (catalog, design, marketing, media, pricing, and setting).
Application: The type of storefront application a design item belongs to (Storefront Classic or Open Storefront Framework).

Click Clear Filters to clear all check boxes and display all the items that were filtered out by the Filter By options.

To use the Filter Change List field, begin typing in the field. The list changes to include those items matching your criteria.

To sort the displayed items from newest or oldest, click the Sort dropdown at the top of the page and select a sort order.

Schedule Publishing

You can publish the active workset immediately or schedule a future date and time to publish it.

You can also schedule a full publish, which publishes all worksets at once.

Publish a Workset

You can publish the active workset immediately or schedule it to publish at a future time.

To schedule a publish:

Navigate to the Changes page of the workset you want to publish from the Active Workset dropdown list.
Click the Publish Workset button.
Commerce displays the workset's Review and Schedule page.

If the workset contains any dependencies, they are listed on this page.
Specify when to publish the workset:
To publish the workset right now, click Publish Immediately.

To publish the workset at a future time, click the Start Time field to display a calendar/clock widget where you can pick a future date and time. (Click Done to close the widget.) Then click Publish at Selected Time.

If another publish has already been scheduled for the date and time you choose, Retail Digital Commerce displays an error and you cannot schedule the event until you pick a date and time that does not conflict with another scheduled publish. You can reschedule a workset publish by following these steps and publishing immediately or selecting a different time to publish.

Schedule a Full Publish

A full publish targets all changes in all worksets. When a full publish runs, all unpublished worksets, even those that are not currently scheduled to publish, are published to your production storefront. When the full publish finishes, all worksets (except the #default workset) are removed from the schedule and deleted.

You can schedule a full publish to run one time, or you can create a schedule that runs full publishes at regular intervals, for example, nightly.

To schedule a full publish:

On the Publishing Schedule page, click Add to Schedule and select Full Publish... from the dropdown list.
In the Schedule Full Publish dialog, enter the following information:
- A name for the publish event. The name is optional. If you do not enter a name, Retail Digital Commerce uses the default name, Unnamed publishing event.
- If you are scheduling a one-time full publish event, set a start date and time, and ensure the Repeat field is set to None. The Stop Time field is disabled for one-time publish events.
- If you are scheduling a recurring full publish, set a start date and time, and use the Repeat menu to select a time period—hourly, daily, weekly, monthly, or yearly.
  The dates and times you specify here use the time zone you configured on the Location tab on your store's Setup settings. For information on viewing and changing the time zone, see Enter basic store information.
Click Schedule.
The new event appears on the Publishing Schedule page.

Once you have scheduled a full publish, you cannot reschedule it. You must cancel it and then schedule a new one.

Cancel a Scheduled Publish

You can cancel a scheduled workset publish or a full publish on the Publishing Schedule page.

To cancel a full publish, click the event's Delete from Schedule icon.
To cancel a workset publish, click the workset's Unschedule Workset icon.
Canceling a publish does not delete the workset, but marks it as Not Scheduled in the Publishing Schedule.

Publish Changes Using the REST API

In addition to publishing with the administration interface, you can use the Admin API to manage worksets, publish changes, and get information about recent publishing events.

You can use Admin API endpoints to perform tasks related to worksets and publishing, including:

Create and manage worksets
Specify a workset for a publishable item's changes
Publish changes
Download information about recently-published worksets

You can find detailed information about individual endpoints in the REST API documentation that is available through the Oracle Help Center. Be sure to select the version of the REST API documentation that matches the version of Retail Digital Commerce you are using.

Manage Worksets

The Worksets endpoints let you perform basic CRUD operations (create, read, update, and delete) .on worksets.

createWorkset creates a new workset with a name you specify.
deleteWorkset deletes the workset whose ID you specify. A workset must be empty before you can delete it. You can use the assignPublishingChangeList endpoint to move changes from one workset to another.
getWorkset returns the workset whose ID you specify.
listWorksets returns a list of worksets. You can control the worksets returned in the response with query parameters.
updateWorkset updates the name of the workset whose ID you specify.

Specify a Workset for an Item

When you save a change to a publishable item in the administration interface, Retail Digital Commerce automatically saves it to the active workset. Endpoints that create or edit publishable items (for example, updateProduct), however, save changes to the default workset. To save changes to a different, existing workset, the request must include the X-CC-Workset header. For example, including the following header saves changes made by the request to the workset whose ID is ws20001.

"X-CC-Workset": "ws20001"

The assignPublishingChangeList endpoint moves a publishing change list and its dependencies from one workset to another. For example, the following request moves a publishing change list from the default workset to a workset whose ID is ws20001:

POST /ccadmin/v1/publishingChangeLists/assignPublishingChangeList
  
{
  "fromWorkset": "default",
   "toWorkset": "ws100001",
  "changeListId": "ijUCLwsUEiXLLuDjGWmrQriHM_10000"
}

You get changeListId and fromWorkset by sending a GET request to /ccadmin/v1/publishingChanges endpoint. You can control the items returned in the response with query parameters.

See Understand worksets for more information.

Schedule Publishing

You can publish a workset immediately or schedule a future date and time to publish it. Use the publishChangeLists endpoint to start or schedule a publish.

The following request publishes a workset immediately.

POST /ccadmin/v1/publishingChangeLists/publish
 
  
{
     "operationType":"selective_publish",
     "worksetId" : "default"
 }

If the publish successfully starts, the endpoint returns a response similar to this:

{
  "publishRunning": true,
  "statusMessage": "A publish has been successfully initiated."
}

The following request schedules a worksheet publish for a future time.

POST /ccadmin/v1/publishingChangeLists/publish
 
{
     "operationType":"selective_publish",
     "dateTime":"2030-01-01T00:00:00.000Z",
     "worksetId" : "default",
     "eventName":"My publishing event"
 }

If the publish is successfully scheduled, the endpoint returns the repositoryId for the publishing event.

{
  "repositoryId": "300001"
}

The following request schedules a full publish, which publishes all worksets at once. When a full publish runs, all unpublished worksets, even those that are not currently scheduled to publish, are published to your production storefront. When the full publish finishes, all worksets (except the default workset) are removed from the schedule and deleted.

POST /ccadmin/v1/publishingChangeLists/publish
 
{
     "operationType":"full_publish",
     "dateTime":"2021-09-03T20:30:00.000Z",
     "eventName":"Full event"
 }

See Schedule publishing for details about publishing.

Download Information about Recently Published Worksets

You can get information about publishing events that successfully completed during the last seven days with the Publishing History endpoints. The information returned by these endpoints helps you easily understand what items were published recently and provide an audit trail of what was changed on the storefront over the past week.

The Admin API includes the following Publishing History endpoints:

GET /ccadmin/v1/publishingHistory returns an array of publishes from the last seven days. Each array includes high-level information about each publishing event in the array.
GET /ccadmin/v1/publishingHistory/{id} provides the same information as /ccadmin/v1/publishingHistory, but for a specific publishing event.
GET /ccadmin/v1/publishingHistory/{id}/changes provides detailed information about a specific publishing event.

Keep the following points in mind about how the Publishing History endpoints work:

The endpoints return information about publishing events that completed successfully. No information about failed publishing events is returned.
The endpoints do not return any information about changes made by direct catalog editing or direct price editing. For more information about these features, see Edit catalog items without publishing and Update prices without publishing.
The endpoint responses include same list of items that appear in a publishing change list. Secondary items, such as translations, are not returned in the responses.
Certain changes you make to the catalog, such as creating a new product type or changing a price list group, appear as a single item called Catalog Configuration. Endpoint responses include these changes as individual items.

GET /ccadmin/v1/publishingHistory returns an array of publishes from the last seven days. For each publishing event returned, the response includes the name and profile type of the user who started the publish, the type of publish (selective_publish when a workset is published or publish when all worksets are published at once), the name and ID of the publishing event, the start and end date and time, the number of high-level items published, the name of the workset published (for a full publish, this value is null), and the names of users who made changes that were published.

GET /ccadmin/v1/publishingHistory/{id} returns information about a specific publishing event. The response includes the same information as the /ccadmin/v1/publishingHistory response, but for the specified event only. The sample request GET /ccadmin/v1/publishingHistory/publish3002 returns details like the following in the response:

{
  "publishInitiator": "admin:User,Admin",
  "worksetName": "default",
  "eventName": "default",
  "numberOfHistoricalChanges": 1,
  "startTime": "2022-03-03T19:02:35.000Z",
  "operationType": "selective_publish",
  "id": "publish30002",
  "endTime": "2022-03-03T19:02:45.356Z",
  "publishInitiatorProfileType": "adminUI",
  "authors": [
    "admin:User,Admin"
  ],
  "worksetId": "default"
}

GET /ccadmin/v1/publishingHistory/{id}/changes returns an array of items published in a specific publishing event. For each published item returned, the response includes the ID of the publishing event, the display name and ID of the item, the name, ID, and profile type of the last author who changed the item, the date and time of the last change, the type of change (0 = update, 1 =delete, or 2 = create), the type of item changed (for example, product), an array of change details, with change time and author information for each change, and an array of the authors who changed the item.

The sample request GET /ccadmin/v1/publishingHistory/publish3002/changes returns details like the following in the response:

 "items":[
        {
            "lastName":"User",
            "authorProfileType":"adminUI",
            "displayName":"The Girl with the Dragon Tattoo",
            "author":"admin",
            "changeType":0,
            "subsystem":"OCCS-Admin",
            "assetType":"product",
            "changeDetails":[
                {
                    "changeTime":"2022-03-03T19:01:32.000Z",
                    "author":"admin"
                },
                {
                    "changeTime":"2022-03-03T19:01:39.000Z",
                    "author":"admin"
                },
                {
                    "changeTime":"2022-03-03T19:01:44.000Z",
                    "author":"admin"
                }
            ],
            "changeTime":"2022-03-03T19:01:44.000Z",
            "assetTypeDisplayName":"Product: Base Product",
            "firstName":"Admin",
            "assetId":"Product_36Exy",
            "id":"change30004",
            "authors":[
                "admin:User,Admin"
            ]
        }
    ]
}

Use query parameters with Publishing History endpoints

The Retail Digital Commerce REST APIs support a number of query parameters that you can use to control what data is returned in GET endpoint responses. You can use query parameters to filter the publishing data returned in the endpoint responses or to page through the results. These can be useful when you publish frequently or have publishes that include a large number of changes.

This section includes sample requests that show query parameters that you might find useful for the Publishing History endpoints. For complete details about how to use query parameters with the REST APIs, see REST API query parameters.

Depending on how often and how many changes you publish, the Publishing History responses can be quite large. To prevent the response from becoming too large, the number of items returned is limited by default to 250. You can override this value by using the limit query parameter to specify a different number. For example, the following call limits the number of publishes returned to 5.:

GET /ccadmin/v1/publishingHistory?limit=5

To page through the results, you can use the offset parameter. For example, suppose you have returned the first group of 250 publishes using this call:

GET /ccadmin/v1/publishingHistory

You can return the next group of 250 using the following call:

GET /ccadmin/v1/publishingHistory?offset=250

The default value of offset is 0, which means the listing begins with the first item. So setting offset to 250 means the listing begins with the 251st item. You can use limit and offset together. For example, to return the 401st through 600th publish:

GET /ccadmin/v1/publishingHistory?limit=200&offset=400

You can use the fields parameter to return only certain properties you explicitly specify. The following sample request returns an array of only the publish IDs and published workset names of the publishing events.

GET /ccadmin/v1/publishingHistory?fields=items.id,items.worksetName

You can use the exclude parameter to exclude certain properties from the response. For example, suppose you don't need to know anything about the authors for a publishing event. The following sample request excludes that information from the response:

GET /ccadmin/v1/publishingHistory/publish3002?exclude=items.authors

The following sample request returns an array that include changes made by the author Merchandising User.

GET /ccadmin/v1/publishingHistory?q=authors eq "User,Merchandising"

23 Publish Changes

Understand Publishing

Understand Worksets

Save Changes to Worksets

Create and Edit Worksets

Schedule Publishing

Publish Changes Using the REST API