Publishing updates to restaurant configuration -

Publishing updates to restaurant configuration

To make configuration changes available to the Toast API and Toast platform, you might need to publish them after you save them.

For example, you add a new item to a menu, or change menu prices. When you save those changes, they are not reflected on Toast POS devices or in Toast API results until you publish them.

If you manage multiple locations, then you need to make sure that you publish changes to all of the locations where the change applies.

Important

There is no rollback feature for publishing. After you publish changes, the only way to revert them is to manually change them back and then re-publish.

Which changes require publishing?

In Toast Web, most configuration changes require publishing, including the following:

Menu items and prices
Takeout and delivery
Payments
Guest engagement
Front of house

The following changes do not require publishing. When you save these changes, they are published immediately:

Under Employees > Employee management
- Employees
- Jobs
- Overtime rules
Menu inventory

Deciding when to publish changes

You publish your changes when you are ready for those changes to be visible to restaurant employees and guests.

For example, if you are making a large number of changes to your menu, you might not want to publish those changes one at a time as you save them. Instead, you would complete all of the changes and then publish them.

How to publish changes

The Toast platform provides the following options for publishing changes:

There are key differences between the behavior of the Publish Now prompt and the Publish all changes button and the behavior of the Publish Config and Publish Config V2 pages. It is important to understand those differences so you know when to use the different publishing options. The Publish Now prompt and the Publish all changes button only publish changes to the restaurant you are currently logged into (also known as the session restaurant). The Publish Config and Publish Config V2 pages allow you to specify one or more locations to publish to. The locations you select may or may not include the session restaurant. The following sections provide more information on how and when to use each of these publishing options.

Note

The Toast development team is working on an improved experience for publishing changes called the Publishing center. The Toast account > Publishing > Publishing center page will provide a centralized location where you can view information about configuration changes that are waiting to be published, have been successfully published, have failed to be published, or are scheduled to be published in the future. This feature is a work in progress and is in limited release. For more information, see Publishing center overview.

Using the Publish Now prompt and Publish all changes buttons

The Publish Now prompt appears at the top of a Toast Web page when you make a change that requires publishing, allowing you to publish that change immediately.

When you select the Publish Now prompt, the Toast platform publishes any changes you saved since the last time you published to the restaurant you are currently logged into (also known as the session restaurant).

Because the Publish Now prompt only publishes changes for the session restaurant, you should not use it if your changes affect multiple locations. To publish changes to multiple restaurants, use the Publish Config page instead.

If you want to make additional changes to the session restaurant before publishing, you can make those changes and delay selecting the Publish Now prompt until all your changes are complete. (Alternatively, you can make all your changes and then use the Publish Config page to publish them for the session restaurant.)

Some pages in Toast Web use a Publish all changes button instead of the Publish Now prompt. The Publish all changes buttons work the same as the Publish Now prompt. Selecting them publishes any changes you saved since the last time you published to the restaurant you are currently logged into (also known as the session restaurant).

An example of a Publish all changes button.

Select the Publish Now prompt or a Publish all changes button if:

The changes you made only affect the session restaurant.
You are ready for those changes to be visible to guests and employees.

Using the Publish Config page

The Publish Config page displays a publication history for your restaurant. It also allows you to publish changes for one or more locations.

You should always use the Publish Config page to publish changes to multiple restaurant locations. For more information about publishing to multiple locations, see Publishing changes for multiple locations.

To display the Publish Config page

On Toast Web, select Toast account.
Select Publishing, then select Publish Config.

For a restaurant with a single location, if you have saved changes that need to be published, the Publish Changes button is enabled. To publish all of your pending changes, select Publish Changes.

An example of the Publish Config page for a restaurant with a single location.

For a restaurant with multiple locations, the Publish Config page lets you publish one location at a time, or you can select a set of locations and publish them all at once. For more information, see Publishing changes for multiple locations.

Using the Publish Config V2 page

The Publish Config V2 page provides similar functionality to the Publish Config page but it includes additional information about changes that were published and changes that are queued up to publish. This additional information includes:

The configurations included in a publishing event, for example a menu item configuration or a discount configuration.
The fields that were changed for each configuration.
The name of the employee who saved the configuration changes.
The name of the employee who published the configuration changes.

Important

The Publish Config V2 page's performance is not fully optimized. If you have issues publishing from the Publish Config V2 page, you can publish from the Publish Config page instead.

To use the Publish Config V2 page

On Toast Web, select Toast account.
Select Publishing, then select Publish Config V2.
From the You are viewing menu, select the restaurant locations you want to view. For more information, see Filtering pages.
The Unpublished Changes section lists locations that have changes that are queued up for publishing. Select one or more locations to see details about these changes at the bottom of the page, organized into sections for each location.

Select a specific change to see more information about it in the right-hand pane. This information includes the name of the employee who saved the change.

Select Publish to publish changes for the locations you have selected.
The Published Changes section lists the locations with published changes, along with the date and time of each publish, the name of the employee who published the changes, and the number of changes included.

To see more information about changes that were published, select a row from the Published Changes table. The information appears at the bottom of the page.

Select a specific change to see more information about it in the right-hand pane. This information includes the name of the employee who saved the change, which may not be the same employee who published the change.

Below the Published Changes list are pagination controls that allow you to page through the published changes table. Because the Publish Config V2 page's performance is not optimized, it can be quicker to edit the URL of the page instead of using the pagination controls. To edit the URL, add ?page=[page-number] to the end. For example, the following URL goes to page 6 of the Published Changes list.
```
https://www.toasttab.com/restaurants/admin/configchangesv2?page=6
```

Publishing center

Publishing center overview

Note

This feature is in limited release.

To make the changes you specify in Toast Web available to restaurant employees and guests, you must first save and then publish them. The Toast account > Publishing > Publishing center page will provide a centralized location where you can view information about configuration changes that:

Are saved but not published yet (the Publish now tab).
Are added to a change set that is scheduled to be saved and published at a later date (the Publish later tab). You can also use the Publish later tab to get information about change sets that had issues during execution.
Were successfully published (the Publish history tab).
Failed to publish (the Publish history tab).

In the current version, the Publish later tab is the only tab that is available. All of the other functionality will be added over time as the publishing center goes through the development process. The Publish later tab supports the scheduled publishing feature, which allows you to queue up changes that will be published at a later date and time that you specify.

The Publish now tab currently takes you to the existing Toast account > Publishing > Publish config page, where you can manually publish changes to multiple locations using the old workflow described in Using the Publish Config page. Eventually, this tab will allow you to manually publish changes from the publishing center.

Example of the Publishing center page showing the Publish later tab

Understanding saving and publishing

To fully understand how publishing behaves on the Toast platform, you must understand the difference between saving a configuration change and publishing it. Making the changes you specify in Toast Web available to restaurant employees and guests is a two-step process that requires both, as described below:

Save your changes.

This step updates the saved database, which is a repository that the Toast platform uses to store configuration changes that are saved but not published yet. Changes stored in the saved database are not yet visible to restaurant employees and guests but they are visible in Toast Web.

Having a saved database allows you to queue up multiple configuration changes and then publish them at the same time. For multi-location restaurants, it also allows you to control when saved changes are published to specific locations (for more information on publishing for multi-location restaurants, see Using the Publish Config page).
Publish your changes.

During the publish step, changes in the saved database are transferred to the published database. The published database stores the configuration information used by Toast devices and apps. Once a change has been transferred from the saved database to the published database, it is visible to restaurant employees and guests. At this point, what you see in Toast Web and what you see on Toast devices and apps is now the same.

Manual and scheduled publishing

On the Toast platform, you have two options for publishing your changes. You can publish the changes manually when you are ready for restaurant employees and guests to see them or you can schedule them to be published at a specific date and time in the future.

Note

Your restaurant must have the Restaurant Management Essentials, Restaurant Management Pro, or Restaurant Management Enterprise package, or the multi-location module, to access the scheduled publishing feature.

Both manual publishes and scheduled publishes will eventually be incorporated into the publishing center. In this current version, however, only scheduled publishes are supported. Until manual publishing is added to the publishing center, you must continue to use the existing workflows described in Publishing updates to restaurant configuration for manual publishes.

Understanding scheduled publishing and change sets

Note

Your Toast restaurant must have the Restaurant Management Essentials, Restaurant Management Pro, or Restaurant Management Enterprise package, or the multi-location module, to access the scheduled publishing feature.

The scheduled publishing feature lets you make changes to your Toast configuration that are then saved and published at a later date and time. When you use this feature, you create change sets. A change set records updates you want to make to your Toast platform configuration. At a date and time that you specify, the updates in the change set are saved to the saved database and then immediately published to the published database, making them available to restaurant employees and guests.

A change set has two types of data:

Metadata that includes a description, publishing date, and publishing time. This information allows you to identify the change set and to control when it is saved and published. For example, in the illustration below, a change set called "Dessert price increases" has been scheduled to publish on July 21, 2023 at 2:00am.
A collection of changes that you have made using other pages in Toast Web (for example, the menu manager page) and then stored in the change set. You edit this data using special preview versions of the pages that show the existing configuration and the changes you want to make. You access the preview pages using the links in the Include changes from section of the Edit scheduled change set dialog box.

The following illustration shows the preview page for the menu manager:

As you work with change sets, here are some additional points to keep in mind:

During the time period after a change set is created but before it is published, the configuration you see in Toast Web reflects your most recently saved changes, not the changes in the change set. For example, Menu Item A costs $10. You update Menu Item A's price to $12 and add it to Change Set B, which you schedule to publish a week from now. For the next week, when you view Menu Item A in Toast Web and on Toast devices and apps, its price is $10. After Change Set B is saved and published, Menu Item A's price is updated to $12 in Toast Web and on Toast devices and apps.
The data you see in preview pages is based on currently saved data, not currently published data. For example, consider a menu item whose published name is Macaroni & Cheese. If you update the name to Mac & Cheese and then save it but don't publish it, the name you see for the menu item in a preview page is Mac & Cheese, not Macaroni & Cheese. For more information on saved data versus published data, see Understanding saving and publishing.
It is possible for changes made in between when a change set is created and when it is executed to be overwritten when the change set executes. For example, you create a change set that updates Menu Item A's price from $10 to $12 and schedule it to publish in one week. Three days after you create the change set, you update Menu Item A's price to $11 and manually publish. When the change set is executed, the $11 price you manually published for Menu Item A is overwritten by the $12 price included in the change set.

Scheduled publishing permissions

Employees that have the 6. Web Setup > 6.7 Change sets permission to the session restaurant they are logged into are allowed to use the publishing center and the scheduled publishing feature. Employees with this permission can create, delete, and edit the name and schedule for change sets. This includes change sets that were created by any employee.

The 6.7 Change sets permission only gives you permission to work with the change sets themselves. To work with the changes stored in a change set, you must have additional permissions specific to the changes you want to store. For example, to make changes to prices on the menu manager page and then store those changes in a change set, you must have the 4. Restaurant Admin > 4.5 Edit Full Menu permission to edit the menu items and the 6.7 Change sets permission to store your edits in a change set. For more information on menu manager permissions, see Menu manager permissions.

Employees that have the 6. Web Setup > 6.4 Publishing permission to the session restaurant have read-only access to the publishing center. This means they can view change sets and add changes to existing change sets but they cannot create change sets, delete change sets, or modify the names and schedules of change sets.

Scheduled publishing only replaces the properties included in a change set

A manual publish replaces an entire configuration entity in the published database with data from the saved database. For example, you change Menu Item A's name to Menu Item B and manually publish it. All of Menu Item A's properties are overwritten in the published database with data from the saved database, even though only the name was changed.

By contrast, a scheduled publish only replaces the properties of an entity that were edited and included in the change set. For example, you update Menu Item A's price from $10 to $12 and add that change to Change Set B, which you schedule to publish a week from now. When Change Set B is saved and published, only Menu Item A's price is overwritten in the saved and published databases. Menu Item A's other properties remain unchanged.

To more fully understand the potential effects of this difference, consider the following example.

A menu item has the following properties:

Name = Menu Item A 
Price = $3

On the menu item details page, a user updates the name of the menu item to Menu Item B and the price of the menu item to $4. The user saves the updated menu item but does not publish the changes. At this point, the name and price of the menu item in the saved and published databases look like this:

Saved (visible in Toast Web):
Name = Menu Item B
Price = $4

Published (visible on Toast devices and apps):
Name = Menu Item A
Price = $3

Using the menu manager, the user updates the price of the menu item again to $5. The user creates a change set for the price update and schedules it to execute in 7 days. The $5 price change only exists in the change set. It does not affect the current state of the saved and published databases.

Saved (visible in Toast Web):
Name = Menu Item B
Price = $4

Published (visible on Toast devices and apps):
Name = Menu Item A
Price = $3

Change set:
Price = $5

In 7 days, the Toast platform saves and publishes the updated price from change set. The menu item's price is updated to $5 in both the saved and published databases. However, only the price is updated because that is the only edit contained in the change set. The name change to Menu Item B continues to exist in the saved database but it has not been published yet.

Saved (visible in Toast Web):
Name = Menu Item B
Price = $5

Published (visible on Toast devices and apps):
Name = Menu Item A
Price = $5

Change set:
Executed

The user does a manual publish. At this point, the updated name from the saved database is transferred to the published database.

Saved (visible in Toast Web):
Name = Menu Item B
Price = $5

Published (visible on Toast devices and apps):
Name = Menu Item B
Price = $5

This example demonstrates that change sets only update configuration entities with the specific changes that are included in the change set. If updates are made to a configuration entity outside of a change set, those updates are applied on the next manual publish.

Change set statuses

You can view a change set's status on the Toast account > Publishing > Publishing center page. The following table describes change set status types:

Status

Description

Incomplete

The change set has a description but changes are not assigned to it yet.

Incomplete change sets may or may not have a publish date.

Not scheduled

The change set has a description and changes are assigned to it but it does not have a publish date.

Scheduled

The change set has a description, a publish date, and changes are assigned to it.

In progress

This status appears after a change set has started to save and publish. It remains in place until the publish has completed.

Published

All the changes in the change set were successfully saved and published.

Partial publish

Some of the changes in the changes set were successfully saved and published but some failed.

Most configuration entities must have already been published at least once to all the locations that use them before you can schedule updates for them. Not publishing configuration entities at least once is the most common cause of partial publishes.

For example, you create Price Level A. You must publish Price Level A to all the locations that use Price Level A before you can edit Price Level A in the menu manager and schedule those edits to be published at a future date and time.

Note

The exception to this rule is menu items. You can schedule changes to be published for a menu item that has not previously been published. For more information, see Scheduling changes for menu entities that have not been previously published.

To resolve this most common cause of partial publishes, make sure all of the entities included in the change set have been published to all locations that use them. After you do this, the change set should execute fully.

See Resolving change set errors for more information.

Note

Until additional change set development is done, other causes of the partial publish status require Toast support to resolve.

Failed

None of the changes in the change set were successfully saved and published. See Resolving change set errors for more information.

Working with change sets in the publishing center

The Publish later tab of the Toast account > Publishing > Publishing center page provides a centralized location for viewing and working with change sets.

From this page, you can:

Create a new, empty change set that you add changes to later.
Edit the description, date, and time associated with a change set.
Navigate to the preview pages associated with a change set, where you can make edits to the changes included in the change set.
Delete a change set.
See a change set's status.

Change sets on the publishing center page are sorted by publish date, newest to oldest. Change sets that don't have a publish date are shown at the top of the list.

Creating a new change set

You can create a new, empty change set from the publishing center and then add changes to it later.

To create a new change set

Access Toast Web .
Navigate to the Toast account > Publishing > Publishing center page.
Select Add change set. The Add scheduled change set dialog box opens.
Enter a description for the change set.
Select a date and time for the change set to be saved and published.

The time zone is the current time zone from your browser. Be sure to take that into account when you select the publication time. For example, if you are in the Pacific time zone, but are scheduling a change set for locations in the Eastern time zone, then to publish the change set at 4:00 AM Eastern, set the scheduled publication for 1:00 AM Pacific.

Alternatively, you can select I'll schedule this later and then edit the change set later to set its date and time.
Select Save.
Do one of the following:
- To skip adding updates to the change set, select I'll do this later. In the future, you can navigate to the change set's preview pages to add updates to it.
- To immediately add updates to the change set, select Continue to menu manager. (Currently, the menu manager is the only feature that has scheduled publishing enabled.)
  
  Make your updates on the menu manager page and then select Schedule.
  
  In the Which change set would you like to add changes to dialog box, select the change set you created and then select Add changes.

Note

It is also possible to create a new change set from the menu manager, the only area of Toast Web that currently includes the scheduled publishing feature.

Editing a change set's description, date, or time

Follow the instructions below to edit the description, date, or time associated with a change set.

To edit a change set's description, date, or time

Log in to Toast Web.
Navigate to the Toast account > Publishing > Publishing center page.
Locate the change set you want to edit in the table and select its edit button.
Update the description, date, or time and select Save.

Navigating to a change set's preview pages

A change set contains a collection of changes that you have made using other configuration pages in Toast Web (for example, the menu manager page) and then stored in the change set. You can edit the changes contained in a change set using special preview versions of the configuration pages you used to specify the changes. These preview pages show a side-by-side view of the existing saved configuration and the changes recorded in the change set.

To navigate to a change set's preview page

Log in to Toast Web.
Navigate to the Toast account > Publishing > Publishing center page.
Locate the change set whose preview page you want to view and select its edit button.
In the Includes changes from section, select the link for the preview page you want to see. Currently, the menu manager is the only page in Toast Web that supports scheduled publishing, so it is the only preview page available from the Includes changes from section.
Make your updates on the preview page and then select Schedule. The Which change set would you like to add changes to dialog box opens.
Select the change set you've been editing and then select Add changes.

Deleting a change set

When you delete a change set, the changes associated with it are not saved or published.

To delete a change set

Log in to Toast Web.
Navigate to the Toast account > Publishing > Publishing center page.
Locate the change set you want to delete in the table and select its delete button.
Select Delete change set to confirm the deletion.

Resolving change set errors

The Publish later tab lists your change sets and their statuses. For change sets that have a status of FAILED or PARTIAL PUBLISH, you can download error files that provide more information about the failures that occurred when the change set was executed. You can download these error files from two locations:

A banner appears at the top of the Publish later tab each time a publishing failure occurs and lists the most recent publishing failures. Use the Download details link for a change set to download its error files.
In the Change sets table, each change set with a FAILED or PARTIAL PUBLISH status has a download icon at the end of its row. To download error files for a change set, select its download icon.

The download icons are always available at the end of the change set rows. If you dismiss the error banner, it reappears the next time a publishing failure occurs and contains the failures that happened since the last time the banner was dismissed.

The location of the Download details link and the error file download icon

When you download the error files for a change set, one or more comma-separated value (CSV) files are downloaded to the default download location used by your browser. The name of the error file indicates the type of errors it contains:

publishing_errors-[change-set-name].csv contains errors that occurred when the Toast platform attempted to publish the changes contained in the change set. For more information, see Publishing error codes.
menu_update_errors-[change-set-name].csv contains errors that occurred when the Toast platform attempted to execute the menu updates contained in the change set. For more information, see Menu update error codes.

Columns in the error CSV files

The following table describes the columns in the error CSV files. Two of the columns, locationId and locationName, only appear in the publishing_errors-[change-set-name].csv file.

Column	Description
`errorCode`	A code for the error type. See Publishing error codes and Menu update error codes for more information.
`errorMessage`	A descriptive message about the error.
`locationId`	This column only appears in the `publishing_errors-[change-set-name].csv` file. The unique identifier, or `GUID`, of the location where the publishing attempt failed.
`locationName`	This column only appears in the `publishing_errors-[change-set-name].csv` file. The name of the location where the publishing attempt failed.
`entityType`	The type of menu entity. Supported entity types are `MENU_ITEM` and `MODIFIER`.
`entityId`	The unique identifier, or `GUID`, that the Toast platform generates for the menu entity. See Toast identifiers for more information on `GUID`s.
`entityName`	The name of the menu entity.
`targetId`	The unique identifier, or `GUID`, of location or location group that the menu entity is targeted at. See Toast identifiers for more information on `GUID`s.
`targetName`	The name of the location or location group that the menu entity is targeted at.

Publishing errors for menu items targeted at multiple locations

For menu items that are targeted at multiple locations, the publishing_errors-[change-set-name].csv file contains a row for each location where a publishing attempt was made and failed. For example, Menu Item A is targeted at a location group that has six locations. If Menu Item A has a publishing failure at three of those locations, the publishing_errors-[change-set-name].csv file will contain three rows for Menu Item A errors, one row for each location where the publishing attempt failed.

Publishing error codes

The table below describes the error codes that you may see in the publishing_errors-[change-set-name].csv file.

Error

Description

ErrorConfigNeverPublished

The menu entity has never been published to the location listed in the locationName column. Most menu entities must have already been published at least once to all the locations that use them before you can schedule updates for them. Not publishing configuration entities at least once is the most common cause of partial publishes.

Note

To resolve the ErrorConfigNeverPublished error, manually publish the menu entity to the location listed in the locationName column. You may have to manually publish to multiple locations, if the menu entity is targeted at multiple locations and it has not been published to all of them. The CSV file will contain a row for each affected location. After manually publishing, the change set should execute fully.

ErrorInternalPublishing

An internal error has occurred while publishing changes. The locationName column lists the location where changes failed to publish. Try manually publishing changes for this location or contact Toast support for further assistance.

ErrorInternalJobExecution

An internal error has occurred while executing the scheduled change set. Changes may be reflected in saved data, but no restaurant will receive published changes. Try manually publishing your changes or contact Toast support for further assistance.

Menu update error codes

Menu update errors can occur if edits are made to a menu entity after a change set that includes the menu entity was created but before the change set executes. The following table provides more information about the changes that can cause these problems and the error codes associated with them.

Error	Description
`EntityNotFoundError`	The menu item in the change set was archived and edits cannot be made to it.
`You are not permitted to access this resource`	The owner of the menu item was changed and the employee who created the change set does not have the 4. Restaurant Admin > 4.5 Edit Full Menu permission to the location or location group that now owns the menu item.
`ParameterValidationError`	This error can be caused by either of the following: The change set contains an edit to a price but that price has been deleted from the menu item. For example, the change set includes an edit to the location-specific price for the New York location, but the New York location-specific price has been removed from the menu item. The pricing strategy of the menu item has changed to a strategy that is not compatible with the pricing edit in the change set. For example, Menu Item A uses the menu-specific pricing strategy. A user adds another menu-specific price to Menu Item A and saves it in a change set to be published in one week. Before the change set executes, another user changes Menu Item A's pricing strategy to location-specific pricing. At this point, the menu-specific price defined in the change set is no longer compatible with Menu Item A's location-specific pricing strategy.
`Price was not updated because the pricing strategy for location-specific price with target {target} changed. Check the price setup for item {item guid}.`	This error can be caused by either of the following: You scheduled a change to a location-specific price that uses the base pricing strategy and, after scheduling the change, you updated the location-specific price to use a strategy other than base price. You scheduled a change to a location-specific price that uses the menu-specific pricing strategy and, after scheduling the change, you updated the location-specific price to use a strategy other than menu-specific.

Locating menu items that have errors using their GUID

The CSV files are generated when the change set fails to execute and they contain the menu item data (menu item name, target name, target ID, and so on) that existed at the time of execution. It is possible for the menu item name to be edited after the CSV files were generated, creating a situation where the menu item name shown in the error file is different from the menu item name shown in Toast Web. If this occurs, you can use the Menus > Bulk management > Items database page to search for the menu item by its GUID, which can be found in the entityId column of the errors summary file.

Scheduled publishing notes and limitations

This section discusses important notes and limitations of the scheduled publishing feature.

The time you assign to a scheduled publish is the time the changes start getting published, not the time the changes will become available. The length of time a scheduled publish takes to finish depends on the number of changes you have made and the number of locations affected.

Note

Currently, the scheduled publishing feature is available to users that have the 6. Web Setup > 6.4 Publishing permission. Users with this permission can create, edit, and delete change sets, including change sets that were created by other users. The Toast platform does not yet validate whether the user creating a change set has permission to edit the entities included in the change set.
The scheduled publishing feature does not prevent you from adding the same configuration entity to more than one change set. For example, you could a change set that modifies the price of a menu item at the start of a holiday period and another change set that reverts the price of the menu item after the holiday period has ended.
The Toast platform does not require a particular length of time in between when change sets. This means it is possible for one change set to be in the process of saving and publishing when another change set is scheduled to start.
The menu manager preview page shows the currently saved data, not the currently published data, for the menu items included in the change set. For example, consider a menu item whose published name is Macaroni & Cheese. If you update the name to Mac & Cheese and then save it but don't publish it, the name you see in the menu manager preview page is Mac & Cheese. For more information, see Navigating to a change set's preview pages.