Understanding the Snapshots feature

A snapshot is a DITA CMS object that captures a map at a particular point in time. You can use this snapshot to rebuild the map and the objects that it contains—topics, images, referable content, sub-maps, and so on—exactly as they were when the snapshot was created.

Note: The snapshot feature is slightly different for the Dynamic Release Management module. See the Dynamic Release Management Module User Guide if you are using this module.

When you create a snapshot for a map, the DITA CMS creates an .xml file that contains the list of all the objects in the map (and sub-maps, if any) along with their current version numbers.

For example, consider the following map, which contains a topic and a sub-map:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd">
<bookmap id="lar1397749975458" xml:lang="en-us">
    <title>Sample map</title>
    <chapter href="lar1397750021477.xml"/>
    <chapter format="ditamap" href="lar1401202413026.ditamap"/>
</bookmap>

The following code shows the contents of the snapshot file for this map. The snapshot includes the objects referenced in the topic (in this case, an image and referable content) as well as the objects in the sub-map (in this case, a task that also includes an image).

<?xml version="1.0" encoding="UTF-8"?>
			
<!DOCTYPE snapshot PUBLIC "-//IXIA//DTD IXIA DITA Snapshot//EN" "snapshot.dtd">
<snapshot id="lar1397749975458" xml:lang="en-us">
   <title>Sample map--Snapshot</title>
   <snapshotmeta>
      <resourceid base="/content/authoring/" id="lar1397749975458.ditamap"/>
   </snapshotmeta>
   <manifest>
      <snapshotref cms-status="Authoring:done" 
                   href="../../authoring/lar1397749975458.ditamap" 
                   navtitle="Sample map" 
                   rev="4" 
                   type="bookmap">

         <!-- Snapshot for topic lar1397750021477.xml and its
              image and referable-content -->

         <snapshotref cms-status="Authoring:done" 
                      href="../../authoring/lar1397750021477.xml" 
                      navtitle="Topic 1" 
                      rev="3" 
                      type="concept">
            <snapshotref cms-status="Authoring:done" 
                         href="../../authoring/lar1397660192937.image" 
                         navtitle="lock manager icon" 
                         rev="1" 
                         type="imagemeta"/>
            <snapshotref cms-status="Authoring:done" 
                         href="../../authoring/lar1398347925155.xml" 
                         navtitle="Contact Technical Support" 
                         rev="3" 
                         type="referable-content"/>
         </snapshotref>

         <!-- Snapshot for sub-map lar1401202413026.ditamap and its
              task, which also includes an image -->
         <snapshotref cms-status="Authoring:done" 
                      href="../../authoring/lar1401202413026.ditamap" 
                      navtitle="Sample sub-map" 
                      rev="3" 
                      type="bookmap">
            <snapshotref cms-status="Authoring:done" 
                         href="../../authoring/lar1397660191604.xml" 
                         navtitle="Install Tomcat on Windows" 
                         rev="3" 
                         type="task">
               <snapshotref cms-status="Authoring:done" 
                            ref="../../authoring/lar1397660191290.image" 
                            navtitle="Apache Tomcat Configuration" 
                            rev="1" 
                            type="imagemeta"/>
            </snapshotref>
         </snapshotref>
      </snapshotref>
   </manifest>
</snapshot>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE snapshot PUBLIC "-//IXIA//DTD DITA CMS Snapshot//EN" "snapshot.dtd">
<snapshot id="ddp1441205293768" xml:lang="en-us">
	<title>Sample map--Snapshot</title>
	<snapshotmeta>
		<resourceid base="/content/authoring/" id="ddp1441205293768.ditamap"/>
	</snapshotmeta>
	<manifest>
		<snapshotref cms-status="Authoring:work" 
					 href="../../authoring/ddp1441205293768.ditamap" 
					 navtitle="Sample map" 
					 rev="4" 
					 type="bookmap">
					 
			
         <!-- Snapshots for the container and container part -->

			<snapshotref cms-status="Authoring:open" 
						 href="../../authoring/kiy1441205259960.ditamap" 
						 navtitle="4.1.7" 
						 rev="2" 
						 type="container">
		
				<snapshotref cms-status="Authoring:open" 
							 href="../../authoring/klc1441205337071.ditamap" 
							 navtitle="4.1.7 {0001}" 
							 rev="5" 
							 type="containerpart"/>
			</snapshotref>
			
			 <!-- Snapshot for sub-map dsi1441206564020.ditamap -->
			<snapshotref cms-status="Authoring:work" 
						 href="../../authoring/dsi1441206564020.ditamap" 
						 navtitle="Reference Map" 
						 rev="1" 
						 type="map"/>
			
			 <!-- Snapshot for topic bhi1441205335829.xml and its
              image and referable-content -->
			<snapshotref cms-status="Authoring:work" 
						 href="../../authoring/bhi1441205335829.xml" 
						 navtitle="Topic 1" 
						 rev="2" 
						 type="concept">
				<snapshotref cms-status="Authoring:work" 
							 href="../../authoring/klg1441214607797.image" 
							 navtitle="lock manager icon" 
							 rev="1" 
							 type="imagemeta"/>
				<snapshotref cms-status="Authoring:work" 
							 href="../../authoring/ive1441214836092.xml" 
							 navtitle="Contact Technical Support" 
							 rev="2" 
							 type="referable-content"/>  
			</snapshotref>
		</snapshotref>
	</manifest>			
</snapshot>
For each object in the map—that is, the map itself as well as all the objects that it contains: topics, images, referable content, sub-maps (and their contents), etc.—the following information is kept:
  • Status of the object
  • Link to the object in the DITA CMS
  • Navtitle
  • Revision number
  • Object type

This information allows the DITA CMS to recreate the map exactly as it was when the snapshot was created. As with any DITA CMS object, you can search for a snapshot in the Content Store. You can also output a snapshot, branch it, or publish it.

Important note

To create the snapshot, the DITA CMS uses the latest released revisions of the objects in the map. Therefore, if you have locked documents in your map, the snapshot will not include these locked revisions but rather the latest released revisions of these objects.

Why use snapshots?

In previous releases of the DITA CMS, if you wanted to keep track of the different versions of a map, you had to publish the map. For example, if you wanted to be able to go back to all the versions of all the maps that you delivered to your end users, you had to publish the maps at each milestone. There are two main issues with publishing maps:
  • You need to bring the map and its objects to the final state of the Authoring cycle (for example, Authoring:done). This can be quite time-consuming for large maps.
  • When you publish a map, the DITA CMS makes a copy of the map and all its objects and stores them in the Content Store, so the size of the database keeps growing even if the volume of source content is stable.

Creating a snapshot does not create copies of the map and its objects. It's simply a text file that lists the map's contents at a specific point in time, so creating a snapshot has virtually no impact on the Content Store. Another advantage of snapshots is that you can create a snapshot from a map that is in any state, as long as the map is not locked.

When using snapshots, you can:
  • Create a branch from a snapshot: Let's say that your team is still working on the documentation for Version 10 of your product, but you need to start working on Version 11. You can simply create a snapshot of the Version 10 documentation and then create a branch from the snapshot. Since you can create the snapshot of a map from any state, the Version 10 documentation can remain in the Authoring:work status.
  • Generate the output of a snapshot: At any time you can see the content of a snapshot by generating its output. When you generate the output of a snapshot, the Output Generator retrieves from the Content Store the versions of the map and its objects as specified by the snapshot. New files are not created.
  • Keep a historical record of all your documentation releases: Every time that you release your documentation or at important milestones, you can make a snapshot of your map. This ensures that you can see the content of a specific release at any time by generating its output or return to it by branching the snapshot.
Note: While you cannot localize a snapshot directly, you can publish a snapshot and then localize the published version.