1. Using Oracle Commerce
  2. Publish Changes
  3. Publish changes using the REST API

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.

This section applies to both OSF and Storefront Classic. This section applies to Open Storefront Framework (OSF) and Storefront Classic.

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 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.

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",
  "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 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"