How to Maintain Bookmarks When a Map Engine Changes

When you change a Map Engine any Bookmarks which are based on the Map Engine may no longer work. This may happen when a Bookmark is used to save the layers on/off status in your Table of Contents. If you are planning to change your Map Engine you need to keep in mind that existing Bookmarks may no longer reference the correct layers and so will not show the layers that they should; the layers may not even exist, or their id's may have changed in the new Map Engine. At version 2.4.25 Weave now uses entry ids so that you may change layer names without breaking the linkage made with existing bookmarks. The following notes will explain this in more detail.

Step-by-step guide

The key to maintaining a functioning Bookmark is to keep the entry id for layers that are used (or might be used) in Bookmarks consistent. So if you are changing the name of a Map Engine, or even the name of the layer (as displayed in the Table of Contents) this won't matter as long as you don't change the entry id's in the toc.xml. This is shown in the example below.
As an example from a toc.xml file
```
<entry id='l_mapengine.grids_250m_grid' layer='250m Grid' label='250m Grid' checked='false'/>
```
The QGis project file, Geoserver Workspace, or ArcMap Document that is setting the display layers can now be changed and the layer name changed as long as the entry id is not changed. Following the example above, the layer is now called grid_250m, but the id has been left as l_mapengine.grids_250m_grid. If the entry was changed as shown below, any Bookmarks referring to that layer would continue to work.
Updated toc.xml file
```
<entry id='l_mapengine.grids_250m_grid' layer='grid_250m' label='250m Grid' checked='false'/>
```
If you are using layers and groups, an entry id should be used for both. The standard is to prefix group ids with a "g_" and layer ids with a "l_" , followed by Map Engine name, followed by layer name. This makes it easier to read and generally gives you a unique id across all your layers in all ToC models.
Using entry id for layers and groups
```
<entry id='g_mapengine.main_contour' label='Contours' exclusive="true">
	<entry id='l_mapengine.main_contours50cm' layer='Contours 50cm' label='Contours 50cm' checked='false' entity='lyr_contours50cm'/>
	<entry id='l_mapengine.main_contours1m' layer='Contours 1m' label='Contours 1m' checked='false'/>
</entry>
```
Weave uses entry ids so that changes can be made to the Map Engines and the bookmarks that are saved will continue to work. An entry id should not be changed once it's been set unless there is no requirement that any existing bookmarks should work.
This method of storing Bookmarks has not always been used in Weave. Prior to Weave version 2.4.25, layer information stored in bookmarks was based on the Map Engine and layer id from the ToC model. So when a Bookmark was opened the Map Engine and Layer id were read and Weave would use this information to locate the Table of Contents entry that had to be turned off or on. This would result in problems if layers were renamed.

The solution to this was to allow for a unique id to be set in the Table of Contents configuration for each entry and by doing so, remove the dependency on the Map Engine and Layer id. This meant that the underlying layer could be renamed, or even moved to a different Map Engine, and the saved bookmarks would still work. (This explains why the entry id concept was introduced to the Weave ToC model.)

Unfortunately this method of saving Bookmarks relies on the entry id's being added to the ToC model before they're saved. If this was not done then Weave goes back to the old method for a interpreting bookmarks and there's currently no way to "fix" this for older bookmarks.

Also refer to the following sections of the Weave System Administrator Guides:

Step-by-step guide

Related articles