Publish changes using the REST API

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

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

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 Oracle 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, 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":"2021-09-03T20:30: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.