2

Publishing Documents

• Why global/SITE Controller?
• Planning to configure the global/SITE Controller
• Using the publishing cycle
• Understanding the global/SITE phases
• Making ongoing configuration changes

Why global/SITE Controller?

The global/SITE Controller is used to manage the process of accumulating a logically consistent set of data, and replicating it to a set of systems in a controlled way.

The basic process involves:

• Capturing files from one or more sources and storing them on the global/SITE Controller
• Distributing those files to a set of servers

  In order to define related sets of files, including where and how they are distributed to different servers, you establish relatively static relationships among a set of objects.

  Those relationships are the key to achieving your goal in updating your file sets on the set of systems. The global/SITE Controller helps you manage the various steps in the process of moving the files through the pre-defined states of publishing, whether it is updating or delivering the files.

Naming global/SITE objects

In order to discuss the basic global/SITE Controller processes, it is important to understand the terminology. These terms define the fundamental global/SITE elements, and correspond to the issues you need to consider when planning the organization of your publishing systems, deciding what you want to do in configuring the global/SITE Controller, and managing and delivering your content.

• A section contains information that tells the global/SITE Controller how to get a set of files that it collects from a source. Editions contain versions of sections, which reference the changed files.
• A publication is one or more sections to be published together to one or more subscribers. An edition of a publication is a set of section/version pairs.
• A distributor is a remote global/SITE Controller that provides access to additional systems. A publisher can deliver publications directly to subscribers, or deliver to a distributor which then delivers the publication to the subscribers.

Planning to configure the global/SITE Controller

Before you begin configuring the global/SITE Controller, it is a good idea to consider what you need, and plan what you are going to do. This helps save time since you can set things up initially in the way that will be most efficient for you.

You need to define:

1. Where you are going to look for new content
2. Where you are going to put it

   You can use any file as content if you can specify a path to a server, and directory name, and method of access for the file. This is where you tell the global/SITE Controller to look for the content. The global/SITE Controller collects the content from the source, and stores it as a version of a section. The global/SITE Controller saves sections as a combination of the content to store, and the directions for collecting the content.

   Once you have defined the content (that the global/SITE Controller stores as a version of a section), you can later distribute the content to one or more subscribers. The subscribers are where you are going to put the content. However, before you can publish the content, you need to know who your subscribers are, and provide a path for delivering the content to them. This process of taking content from one place that you define, and putting it somewhere else that you define, using a prescribed set of steps, is referred to as the publishing cycle.

   In the terminology of the global/SITE Controller, a publication delivers one or multiple sections to one or more publication subscribers. The publication forms a single logical unit that the global/SITE Controller uses to move all of the individual parts through the publishing cycle in a controlled fashion.

   The key to configuring a global/SITE Controller is:

• Determine what the logical publications are.
• Determine which sections each publication includes.

  For example, one of your publications may be a quarterly report. This publication may include sections such as: Word from the CEO, Company Mission Statement and Goals, Investors, Customer Listing, Investments this year, Profits, Projections, and Summary. Another publication might be an monthly marketing update or a weekly recruiting listing. You may find that some sections, such as Company Mission and Goals, are useful in more than one publication.

  Although you decide about the publication first, when you are using the global/SITE Controller, it makes sense to define the sections first, and then define the publication. Before proceeding further, you need to plan the overall organization of the publications, and the sections per publication.

Defining Publications

Each publication defines two major relationships:

1. The sections that are published together
2. The set of targets or subscribers that receives the content from a given section

   The publication, organizes the sections you have defined. It is this publication that is propagated, or delivered, to the target servers, or subscribers. For example, a publication can be defined as your web site (www.yoursite.com) which is composed of many separate sections (www.yoursite.com/cgi-bin, www.yoursite.com/marketing, and so on).

Creating the publication

You need to assign a unique name to each publication. This name is an identifier, and shows up in almost all screens to identify publications in almost everything else you do from this point on.

For our example, assume you are creating a publication called WebPub1. You use the New Publication screen. (From the navigation pane on the left side of the global/SITE graphical interface, click Add a Publication.)

Note: In the global/SITE Controller, the screen name appears in the application title bar, across the top of the browser interface, and is not included on most screens shown as figures in this chapter. The screen names are shown in the figure caption for each screen.

Figure 2.1 The New Publication screen

There is a field for the name of the publication, and an optional description. You can set or change the Pause Edition Delivery options now, or later. They specify whether the publication delivery process pauses automatically at certain points in the process.

To add a publication

1. In the Name box, type the name of the publication you are adding.
2. In the Description box, type a description. This is optional, for your own use.
3. If you want the publication to pause during the publishing process, under Pause Edition Delivery, click any check box that applies. You can check one, two, or all three.

   When you publish this publication, the process will pause as you have directed it to.

   Note that you do not have to decide on the publication options now. You can set them at a later time with the Pub. Options screen. For more information about delivery pauses, and other publication options, refer to the help on the Publication Options screen.

4. Click the Add button to complete the addition. The global/SITE Publication List screen displays, with your new publication listed at the bottom.

   Once you have added the publication, your newly created publication appears in the list on the Publications List screen.

   

   Figure 2.2 The Publications List screen.

5. Click the publication name (WebPub1 in this example) in this list to view the Publication Editions screen for details of your publication.

   

   Figure 2.3 The Publication Editions screen

Using the Publication screens

The Publication screens are the center of operations for nearly all configuration activities and content delivery for a publication. The Publication Editions screen is the first you will see. It has four major tabs that correspond to the four main areas of information: Editions, Sections, Subscribers, and Pub. Options. Click any tab to display a detail screen of the same name for dealing with that aspect of your publication. Each detail screen shows the same four tabs. You can click any one, to view a different area of your publication.

• The Publication Editions screen shows details of your editions and is used to deliver content from sections to subscribers.
• The Publication Sections screen shows section details for a specific publication, and is used to manage sections.
• The Publication Subscribers screen lists the subscribers for the publication, and is used to define where the section content will be delivered.
• The Publication Options screen is where you set options for the delivery process, including edition delivery pauses.

  Before delivering content, you need to inform the global/SITE Controller where to get it. You do that by clicking the Sections tab, and using the Publication Sections screen.

  

  Figure 2.4 The Publication Sections screen

Defining sections

A global/SITE Controller section includes both data and a path to it.

Before you begin to set up the global/SITE Controller, you should answer some basic questions. Start by working backwards:

1. You have a server (subscriber); what data needs to be managed?
2. How many sections do you need?

   Remember that different roots (/path1/part1, /path2/part2) must have different sections.

   A section contains all the files and directories at a given path. A section can stop at any specified subdirectories, known as exceptions. These exceptions exclude the listed directories or files from a particular section.

3. What will you name each section?

   Remember that in order to create a section, you must have a unique name for it. This name is unique among all sections, within all publications.

4. What is the path to each section?

   You must be able to identify the specific directory path on the server that is the source of the section's content. Remember that, in all cases, the directory path for all section sources must already exist on the specified servers.

5. Do you have authority to access the information?
   You need to provide authorization access by specifying the user ID and password for access to the server where the content is stored.

Defining a simple section

The first step, once you have a publication, is creating sections. Updating these sections is one of the most frequent tasks that you will perform. To create a section, you:

• Give the section a name.
• Specify the server where it can be found.
• Provide access settings; the user ID and password to access the server.
• Define the location of the content with a path.

  Once you have created the section, you have several options, including testing the connection, creating exceptions to the section, or creating an initial version of the section on the global/SITE Controller. The following text in this section of the guide introduces all of these tasks.

Example

This example shows how to create a new section called WebContent1, which gets its content from the directory /home/webcontent on the system python using the FTP account website.

1. Start by selecting the Sections tab for your new publication.
   The Publication Sections screen displays.

   

   Figure 2.5 The Publication Sections screen

2. Since there are no sections yet, you need to create one: click the Create New Section button.
   The Create a New Section screen displays.

   

   Figure 2.6 The Create a New Section screen

To create a section

1. In the Section Name box, type a unique name for the section that you want to add. The name cannot contain double quotes, slashes, or angle brackets. You cannot change the name of a section later. For our example, type WebContent1.
2. In the Staging Server box, type the name of the server (node name or IP address) that is the source of the content for this section that you want to add. This is also referred to as the source or content server.
3. In the Description box, type a description for the section. This is optional, to provide mnemonic assistance.
4. To include this section in editions of the publication, leave the Enabled check box checked (the default). If you want to create the section now, but disable it for the publication, clear the check box. You can change this later.
5. Leave the Transfer Method set at FTP.
6. In the User ID box, type the User ID (FTP user name) you use to access the server you specified in step 2.
7. In the Password box, type the user password (FTP password) that matches the User ID you specified in step 6, and allows access to the server.
8. In the Path box, type the specific directory path for this section on this staging server. The section includes all the files and directories at the given path. If you want to exclude a subdirectory, you must specify it as an exception, using the Section Details screen.
9. To complete the addition of this section, and add it to the publication, click Create.

   If there are no errors, the Section Detail screen displays, showing the source detail for this section.

Testing your section

Once the section is created, you may want to try a test connection on the newly defined section to confirm whether basic FTP access can be established. Test Connection verifies that the user ID, password, and path information are valid, by connecting to the specified system.

To test your section connection

1. On the Section Detail screen, click the Test Connection button.
   The Connection Test screen displays.

   The Connection Test screen displays the test results generated by clicking the Test Connection button. The Test Results table lists the name for the source server and the path for the section, and the success or failure of the test connection. The left side shows what is being tested, the right side shows the result.

   

   Figure 2.7 The Connection Test screen

Creating a section version

Now that you have created a section, you may also want to try creating an initial version of the section on the global/SITE Controller.

To create a version

On the Section Detail screen:

1. Click the Get New Version button.

   The global/SITE Controller goes through the process of gathering data from the specified location and storing an initial version of it.

   For more information, refer to the later section, Getting new content.

Modifying your section configuration, later

Once you have created a section, you can return to the Section Detail screen later to change parameters if necessary.

To change your section parameters

1. On the Publication Editions screen, click the Sections tab.
   The Publication Sections screen displays.

   The Publication Sections screen lists all sections for a publication.

   

   Figure 2.8 The Publication Sections screen with one section listed

2. Then click the name of the section you want to work on.

   This displays the Section Details screen where you can make changes.

   

   Figure 2.9 The Section Details screen, Source tab

3. Press the Update button to save any changes you have made to the settings on this screen.
   Use the Revert button to ignore any changes made since the screen was brought up.

Defining exceptions

Once you have created a section, you may want to create an exception to the section. Exceptions instruct the global/SITE Controller, when the specified path is encountered, to disregard any subdirectories in that directory. An exception is a way of excluding a subdirectory from being published as part of a section.

To create an exception path, you use the Section Detail screen after the section is created. You can use the New Exception box on the Section Detail screen to enter a directory path that will be treated as an exception.

Example

In our example, the source directory /home/webcontent contains a subdirectory /home/webcontent/images that we want to manage with a separate section.

Assuming you have already created your initial section, start at the Section Detail screen for it (in our example, it is WebContent1).

Figure 2.10 The Section Detail screen, add a new exception

To create an exception

Start at the Section Detail screen.

1. In the New Exception box, type the name of the directory you want to exclude. For this example, it is /home/webcontent/images.
2. Click the Update button.
3. Finally, create a new section, such as WebImages, which specifies /home/webcontent/images as its source.

Tip: In all cases, the directory path for all section sources and subscribers must already exist on the specified servers. The global/SITE Controller does not create them. It can create any subdirectories, but it cannot create the initial root path.

A little more about exceptions

You may have questions about directory paths when you are setting up multiple sections that use exception paths. The typical situation is that one section's exception is another section's root. In that context, it may seem like the global/SITE Controller should create the exception path, but it does not. That path must already exist, or you must first create it manually on the subscriber.

Example

Say that section1 goes to /root/section1. It seems reasonable that /root/section1 must already exist. You cannot assume you have permission to make it, especially on NT servers where it might be virtual.

Loading initial content into sections

At this point, you can update the content for a section from its staging source, or you can create an edition.

To update the content of a section

1. Start at the Publication Sections screen, where you see your sections listed.

   

   Figure 2.11 Publication Sections screen, showing two sections

2. Click the Get New Version of Selected Sections button to begin the process of gathering new files from those sections.
   The Section Progress Display screen displays, where you can monitor the progress of that process.

   This is discussed in more detail in the section Displaying status.

   Remember, it is still necessary to specify the destination for section in order to actually publish any content.

   

   Figure 2.12 The Section Progress Display screen

Specifying the subscribers for section content

Now we reach the heart of the matter: configuring subscribers. In the example, you have defined your web site as a group of sections, and created a single publication to conveniently manage them as the logical group they are.

You also have one or more web servers that need to receive that content. You need to specify the exact relationship between each section and each web server. Again, the publication provides that connection.

A subscriber is the server that receives your publication. To the global/SITE Controller, a subscriber describes a single system that is the target for delivering the contents of one or more of the sections belonging to a publication.

Specifying a subscriber

1. From any of the Publication detail screens, click the Subscribers tab.
   The Publication Subscribers screen displays. In our example, there are no subscribers.

   

   Figure 2.13 The Publication Subscribers screen

2. Click the Add a Subscriber button.
   The Add Subscriber screen displays.

   

   Figure 2.14 The Add Subscriber screen

To add a subscriber

Using the Add Subscriber screen:

1. In the Subscriber Name box, type the name of the subscriber that you want to add. This information is optional; the data you enter is displayed in various screens that list subscribers for the publication. If it is not filled in, the server name/user ID pair is used instead.
2. In the Server box, type the name of the server for the subscriber. This is the node name (or IP address) for the server.
3. If you will publish to this subscriber directly, leave the global/SITE Distributor box set at None, which is the default. If you intend to publish content to this subscriber through a secondary global/SITE Controller, or distributor, select that distributor from the global/SITE Distributor box. Note that to select a distributor, you must have already added it. For more information on setting up a global/SITE distributor, see the following section, Defining a distributor.
4. Leave the Transfer Method set at FTP, the default.
5. In the User ID box, type the user ID that you use to access the server specified in step 2.
6. In the Password box, type the user password that matches the User ID specified in step 5, and that allows access to the server in step 2.
7. Below the password is a list of sections associated with this publication. A path must be specified for those included. In our example, we have created two sections, and they are both listed.

   Under Include Section

   · Leave the check box checked (the default), for each section that you want included in the edition published to this subscriber.

   · In the Destination Path box, type in a specific destination path for each section on the subscriber.

   · For any sections that you do not want to go to this subscriber, clear the check box.

8. When you have specified whether each section will be included for this subscriber, click Add. This completes the addition of this subscriber, and adds it to the publication.

   Once the subscriber is created, you can use the Test Connection button to verify that the global/SITE Controller can successfully log into the specified server using the user account, and locate the specified path(s). This is a good thing to do at this point, and at any time that you make changes to the subscriber definition.

Defining a distributor

If you will be using a secondary global/SITE Controller to distribute to remote subscribers, you will need to set up distributors. You use the Add a Distributor screen to set up and add a new global/SITE distributor. (From the navigation pane, click Add a Distributor.) Our sample shows the information that you will add.

Figure 2.15 The Add a Distributor screen, with information entered

To add a distributor

1. In the Host Name box, type the unique identifier host name or IP address of the global/SITE Controller that you want to function as a distributor.
2. In the Description box, type in an optional description. This is makes it easy for you to identify the distributor.
3. In the global/SITE Identifier box, type the unique, pre-assigned identifier for the global/SITE Controller that you are adding as a distributor.
4. In the Key Phrase box, type in the key phrase that is shared by the pair of publisher and distributor. Both the publisher and the distributor must have the same Key Phrase.
5. Click Add to complete the addition.
   The global/SITE Distribution List screen displays, with the new distributor added at the bottom of the list.

   

   Figure 2.16 The List Distributors screen shows the new distributor

   Once you have your distributors set up, you can easily specify a distributor for any subscriber that you add. Use the Add Subscriber screen.

   

   Figure 2.17 The Add Subscriber screen, adding a distributor

To add a distributor with a subscriber

1. Add the subscriber as you did earlier in To add a subscriber.
2. At the global/SITE Distributor box, select the distributor that you want to use for this subscriber.
   Simply click the down arrow at the right of the box, and choose the subscriber you want from the available subscribers listed.
3. Complete the rest of the screen, and click Add. This completes the addition of this subscriber, with a distributor specified.

   Once you have added the subscriber and distributor, you may want to try a test connection to verify that the global/SITE Controller can successfully log into the remote server. Test Connection verifies that FTP access can be established with the distributor using the user ID, password, and path information that you have provided.

To test your remote connection

1. On the Subscriber Detail screen, click the Test Connection button.
   The Connection Test screen displays.

   

   Figure 2.18 The Connection Test screen for the distributor

   The Connection Test screen displays the test results generated by clicking the Test Connection button. The Test Results table lists the paths for the subscriber's website and the source server and the success or failure of the test connection. The left side shows what is being tested, the right side shows the result.

Using the publishing cycle

So far, we have discussed how content is organized into sections, how sections are organized into publications, and where those publications go. Now we need to look at the process of capturing a consistent set of content to be published to one or more servers (subscribers).

Within the publication cycle, there are two independent activities:,

1. Updating the contents of sections from their staging sources
2. Publishing the contents of some or all the sections for a publication

   These two activities are typically executed sequentially, but they need not be.

Getting new content

To gather new content, the global/SITE Controller makes a copy of the content on the specified source server. The copy is stored as a version of the section. For ease in tracking, versions are numbered, starting with 1 the first time a new section is updated.

There are four ways to update a section's content at any time; both display the Section Progress Display screen.

• The first is from the Publication Sections screen, by clicking the Get New Version of Selected Sections button.
• The second is from the Section Detail screen, where you can click the Get New Version button.
• The third is to click Create Edition from the Publication Editions screen, and select the Get new version option.
• The fourth is to click the Deliver Edition button from the Publication Editions screen, and select the Create new Edition option.

  

  Figure 2.19 The Section Progress Display screen

  In all of these cases, the global/SITE Controller examines the directory tree specified by the combination of its staging server name, FTP user ID, and path. The global/SITE process ignores any exception directories on the path, and compares the content to the highest version number currently in the global/SITE Controller's versioned section. This process gathers any new files, or any files with different (not necessarily newer, just different) modified times, or a different size, and stores them in the global/SITE Controller. The number of new or changed files is what is displayed on the Update Progress screen.

  If the global/SITE Controller determines that the set of files is identical to the latest version in the global/SITE Controller's versioned section, then no new version will be created.

  The Section History tab on the Section Detail screen lists all versions currently stored in the section.

  

  Figure 2.20 The Section Detail screen, Section History tab

  In the example, we have already stored an initial version, 1. You can view the contents of that version by clicking the number under the Version heading.

  

  Figure 2.21 The Section File Listing screen

  Keep in mind that multiple publications can share a single section. For instance, the WebImages section used in the preceding example was intended for use by numerous publications.

  Creating the very first version of a section may take some time, as all of the data from the source must be copied to the global/SITE Controller and converted into its stored form in the section. However, subsequent updates should be faster, as they first compare the date and time of all the files on the staging source with those stored in the latest version in the section. Only new files, and those that have different timestamps or sizes, are copied into the section.

  A final way to update section content is as the first part of the edition delivery process. (That is discussed later in this chapter.)

  The next section reviews the publication process step-by-step so that you can better understand how the global/SITE Controller works.

Tip: An important reason not to update section content automatically as part of the content delivery process is so that the content being delivered is not inadvertently different from what is expected. When you update sections prior to delivery, the exact contents of that version are frozen, and remain independent of any possible changes made to the files on the staging server for that section.

Publishing new content

The publication process includes a number of distinct phases. The overall flow of the content distribution phase of the publishing cycle can be seen like this:

• Create the edition
  Define an edition and establish the publication settings that control this specific distribution process.
• Deliver the edition
  This runs the global/SITE Controller through a series of phases that result in the specified edition being published to all subscribers.

  There are two methods of creating a new edition. You can create a new edition automatically as part of a publication delivery, after you first check all section staging servers for new content. Alternately, you can perform the section update and edition creation process separately. This allows you to have more precise control over exactly what content is delivered.

Create the edition

The preparation phase involves defining exactly which version of each section in the publication will be published. This set of section versions defines an edition.

Once an edition has been established, the global/SITE Controller creates a snapshot of all the parameters necessary to complete the rest of the process.

To manually create a new edition

1. From the Publication Editions screen, click the Create New Edition button.
   The Create New Editions screen displays.

   

   Figure 2.22 The Create New Editions screen

   You can use the remove version option from the Version box to have the publication delivery process remove from the subscribers all the files from the last published edition.

   The Create New Editions screen displays all the sections in the publication, with a box listing the existing version. You can click the arrow at the right of the box to view additional versions, or to create new versions, or remove existing versions. The displayed version is always the latest existing version (with the highest version number). You can accept the default version of all sections by clicking the Create Edition button.

2. Select the version you want for each section, and click the Create Edition button.

   The Publication Editions screen displays, where you see the newly created edition added to the list. The new edition in turn lists each section it contains, and which version of that section will be delivered.

   The global/SITE Controller automatically assigns both version and edition number, and simply increments each to the next higher value whenever a new one is created. Most listings also display the date and time they were created.

   From the Publication Editions screen, you can click the section name in the edition listing to view the Section Detail screen for that section. Click the version number and date for a section to view the Section File Listing screen for that version of that section.

Displaying status

At this point, we are ready to proceed with the publishing process. Some of the publishing phases can be lengthy, and are therefore designed as asynchronous processes.

In order that you can follow what is going on, the overall publication status is always displayed wherever the publication is listed. On the Publication Detail screen, for example, you can see that it is currently Idle. You can also see that in the overall publication list screen. Click the publication status in either of those screens to display the delivery details screen.

Figure 2.23 The Publication Editions screen showing Idle status

During the Idle state, the screen refreshes itself infrequently. Once the delivery process has started, however, it automatically updates more frequently, and more detailed delivery status is available.

Of course, you can use the Refresh or Reload button on your browser at any time to update it on demand.

1. Click the Deliver Edition button.
   The Deliver Edition screen displays.

   

   Figure 2.24 The Deliver Edition screen

   The Deliver Edition screen shows that neither path has anything published to it yet. The Edition field defaults to the latest edition, in this case, edition 1.

2. Click Deliver Edition. This starts the delivery process.
   The Publish Progress Display screen displays.

   

   Figure 2.25 Publication Progress Display, status: WANSync

   On the Publish Progress Display screen you can observe the overall publication status change through multiple states, reflecting the individual subscriber path states in the detail list.

   Note that Figure 2.25 shows details from an early phase in the process, and the details are about the sections. Figure 2.26 shows details from a later phase of the process, and those details are about the subscriber path.

   

   Figure 2.26 Publication Progress Display; Status: CommitPhaseDone

The Cancel button

Sometimes either the section update process (getting new content) or publication delivery process need to be stopped before they complete. Perhaps a section source or subscriber becomes unavailable during the process, and there is no point in proceeding further until the problem is corrected.

Whenever the publication state is not Idle, three control buttons are displayed on the detail status screens.

The Cancel button stops all processing activity, and places the publication into a Cancelled state. If the publication has not yet reached the CopyPhase, this resets the publication to Idle.

Canceling the copy phase puts the publication into a CopyPhaseCancelled state which allows two options:

• Proceed with any subscribers that have successfully completed the copy phase for all paths.
• Reset the entire publication to Idle without completing any subscribers.

  Any subscribers that are not in the gsCopyDone state will not be committed. Committed means that the files are moved from the temporary subdirectory to a permanent directory on the subscriber.

  During transitions of the publishing cycle, you may need to know what is going on, what the status of the publication is, or how to tell if something has stalled or if it is still progressing. Table 2.1, The global/SITE Controller phases of publication, lists the various activity or transition states, gives information on what should be happening, and includes suggestions on how to proceed if it is stalled, and when to start over.

Understanding the global/SITE phases

During various processing activities, the overall state of the global/SITE controller is displayed at two levels of detail:

• The overall state of the publication, (which is often the synthesis of the section and subscriber path states).
• The detailed section or subscriber path state, whichever object is being processed

  The overall state determines what other actions the user can perform, including the ability to proceed or stop when error conditions arise.

  During a publication delivery with no errors, and no pauses specified on the Publication Options screen, the normal sequence of states follows this progression:

• Idle
  The publication is in a stable state, either ready for updating or publishing.
• UpdatingSections
  When this has been specified as part of the delivery. If an edition was specified with pre-existing section versions, this is skipped.
• PublicationPreparation
  Brief state which prepares some data structures for the rest of the process.
• WANSync
  A very brief state, unless distributors are involved. The process may be paused here. If there are distributors, they are updated with changes prior to publishing. If there are no distributors, there is nothing to change, and the state is extremely brief.
• CreateChangeTrees
  Files are prepared for quick and efficient transmittal to subscribers.
• CopyPhase
  Changed files are copied to temporary sub-directories for the subscribers. The process may be paused here after the copy phase.
• CommitPhase
  Changed files are moved from the temporary sub-directories to their final location at the path you specified, and obsolete files are removed from subscribers.

  You can stop the entire process at any point by clicking the Cancel Delivery Control button. If you do this during the CopyPhase, you can then complete the publication cycle--for any subscribers that have already had all section files copied to them--by clicking the Continue or Complete Delivery Control button.

  A Cancel used in any other phase just allows the publication to be reset to the Idle phase where it can be restarted from the beginning.

  Table 2.1, The global/SITE Controller phases of publication, which follows, describes what is happening to the process during several publication state and detail state combinations.

  Keep in mind that in all stages up to the copy stage, the status is reporting on sections for each distributor. After that, the copy and commit phases deal with the subscriber path.

  The global/SITE Controller phases of publication

  Overall Publication State	Section or Path State	Description
  Idle	N/A	All configuration actions are possible. Must be in this state to initiate section update or content delivery process.
  CreatingEdition, EditionReady	N/A	Only in these states briefly during the creation of a new edition.
  UpdatingSections	gsReposStageUpdate	In this state when performing the potentially lengthy process of determining which files to fetch from section source, and fetching them.
  Idle	gsReposStageUpdateDone	If section update is done separately from delivery, success returns to Idle.
  UpdatingSectionsIn-complete	mix of gsReposStageUpdateDone, gsReposStageUpdateFailed and Cancelled	When multiple sections are being updated, not all completed.
  UpdatingSectionsFailed	gsReposStageUpdateFailed	All section updates failed.
  PublicationPreparation	N/A	A brief phase which constructs a work list for each global/SITE publisher and distributor from the configuration database.
  PubPrepDone	gsStable	Successful completion of publication preparation.
  PubPrepFailed, PubPrepSuspended	N/A	An error message is displayed, typically a distributor was not reachable. The delivery cannot proceed. Cancel resets the pub state to Idle so it can be retried.
  WANSync	gsWanCDir	The changes necessary to bring each distributor up-to-date are created on the publisher global/SITE Controller.
  WANSync	gsWanCDirDone	The set of changes is transmitted to each distributor.
  WANSync	gsWanSync	Each distributor is updating its section(s) with the received changes.
  WANSyncDone	gsWanSyncDone	Ready to proceed to CreateChangeTrees.
  WANSyncSuspended	gsWanSyncDone	Will proceed to CreateChangeTrees after Continue or Complete is clicked. Only stops here when the corresponding Pub. Option is set.
  WANSyncCanceled	some canceled	User clicked Cancel during phase. Cannot proceed with delivery. Reset publication to Idle and restart.
  WANSyncFailed	gsWanCDirFailed	An error is displayed for the specific cause, typically lack of disk space on the publisher to store the temporary change file.
  WANSyncFailed	gsWanSyncFailed	An error occurred while the distributor was updating its sections, typically lack of disk space on the distributor.
  CreateChangeTrees	gsCreateCDir	The set of files necessary to update a set of subscribers from the current edition to the new edition is extracted from the section and stored on each global/SITE Controller.
  ChangeTreesDone	gsCreateCDirDone	Ready to proceed to CopyPhase.
  ChangeTreesCanceled	Canceled	The process was canceled by the user. The publication cannot proceed further. It must be reset to Idle and started over.
  ChangeTreesFailed	gsCreateCDirFailed	An error, typically lack of disk space, will be displayed. The delivery process cannot proceed.
  CopyPhase	gsDataCopy	Each global/SITE Controller copies new and changed files to temporary subdirectories on each subscriber
  CopyPhaseDone	gsDataCopyDone	Ready to move to CommitPhase
  CopyPhaseSuspended	gsDataCopyDone	Will proceed to CommitPhase after clicking Continue or Complete. User selected the Publication Option to stop at this point.
  CopyPhaseCanceled	canceled plus various	User stopped subscriber path copies in progress, as well as those not started yet, by clicking the Cancel control. Only subscribers that successfully completed the copy phase for all sections can proceed to CommitPhase if the Continue or Complete control is clicked. Clicking Reset sets the publication state back to Idle without completing any deliveries.
  CopyPhaseFailed	gsDataCopyFailed	An error is displayed for the specific cause, typically communication failure or lack of disk space on the subscriber.
  CommitPhase	gsDataCommit	The copied new and changed files are being renamed from their temporary subdirectories to their final location.
  CommitPhaseDone	gsDataCommitDone	The publication proceeds to update the configuration database and set its state back to Idle.
  CommitPhaseCanceled	canceled plus others	The Cancel control was clicked, which stopped all commits in progress, as well as any not yet started. Avoide this if possible, as it leaves any incomplete subscribers in an indeterminate state.
  CommitPhaseFailed	gsDataCommitFailed	Error message indicates the problem, usually a communication failure.

Making ongoing configuration changes

After you initially define a publication, various situations can arise that require changes to the configuration. This section provides overviews of a few of these situations:

• One or more subscribers may be unavailable during one or more publication cycles.
• A subscriber path has been removed permanently from a publication.
• A section has been removed from a publication.
• Other configuration changes may be required.

Unavailable subscribers

For various reasons, you may have a given subscriber offline during a publishing cycle. In order to avoid having those subscribers fail during the process, you can mark them offline, or unavailable.

Marking a path offline, and back online

You can use the Subscriber Detail screen to disable paths for individual sections.

Figure 2.27 The Subscriber Detail screen

To disable a section for a particular subscriber

For each subscriber that is off line, you need to exclude all sections. On the Subscriber Detail screen:

1. Clear the check box next to each section.
2. When you have cleared the check boxes for each section, click the Save Changes button.

   Any sections you have marked this way are ignored by the attempt to publish. And each must be returned to Include status before you can publish to it again.

To re-enable a section for a particular subscriber

For each subscriber that was off line, when it returns online, you need to include all sections in order to publish to it. On the Subscriber Detail screen:

1. Click a check into the checkbox next to each section.
2. When you have checked the check boxes for each section that you want to include, click the Save Changes button.
   All sections with a check mark will be included in the next published edition.

   You can also use the Deliver Edition screen to disable the path for a section. Clear the Include check box for each subscriber on a path to keep that subscriber from receiving the edition.

   

   Figure 2.28 The Deliver Edition screen

To disable a subscriber for a particular edition delivery

For each subscriber that is off line, you need to exclude the subscriber from the publication, for each section, before attempting to deliver the edition. On the Deliver Edition screen:

1. Clear the checkbox next to each offline subscriber, for each section listed.
2. When you click the Deliver Edition button, that subscriber will not receive the edition.

   Any subscribers/sections that you have marked this way will be ignored by the attempt to publish this edition. Each must be returned to Include status before you can publish to it.

To enable a subscriber for a publication

For each subscriber that was off line, when it returns online you need to include each subscriber for each section before you can publish to it. On the Deliver Edition screen:

1. Click a check into the checkbox next to each subscriber, for each section.
2. When you have checked the check boxes for each section that you want to include, click the Deliver Edition button.

   All subscriber sections with a check mark will be included in the next published edition.

To synchronize subscribers

If you run one or more publishing cycles while a subscriber is offline, the offline subscriber almost certainly has a stale version of the content. This can cause problems with future edition delivery, if you are not careful.

In a single publishing cycle, each section can change by only a single version. For example, if section A previously published version 5, and the new version is 7, that is fine, but that means all subscribers must contain either version 5, or version 7 (that is, up-to-date already, and not needing to change). If another subscriber for section A contains version 4, when you click the Deliver Edition button on the Deliver Edition screen, you will get an error message.

If you have out-of-date subscribers, you must bring them up-to-date before publishing a new edition. To do this, you run a publishing cycle to bring the stale subscriber paths up-to-date. The simplest way to do this is to re-publish the currently published edition to the entire publication. Even though all subscribers are listed in the Delivery Detail screen, no action will be taken because they are already up-to-date.

Tip: It is perfectly fine to skip multiple versions in a given publication. For example, the currently published version for section A in the publication is 7, and a subscriber currently contains version 2. This can be published in a single cycle, going directly from version 2 to version 7, as opposed to going from version 2 to 3, then 3 to 4, and so on.

To check the current version for each subscriber

If you are concerned about out-of-date subscribers, you may want to check on your sections for subscribers to a particular publication before publishing a new version.

Start with the Publication Subscribers screen (the Subscribers tab).

Figure 2.29 The Publication Subscribers screen

The Publication Subscribers screen displays the currently published version for each subscriber if all paths are up-to-date.

Or you can use the Subscriber Detail screen, which shows the edition published to each path (as does the initial Edition Delivery screen).

Figure 2.30 Subscriber Detail screen

Freeing up disk space by deleting editions and unused versions

Depending on the amount of change between versions, sections will occasionally need to be purged of old versions to recover disk space. This is a two step process:

1. You can delete editions using the delete button on the Publication Editions screen (Editions tab) of the publication detail screen.

   · You cannot remove the last published edition,
   and its listing does not show a delete button.

   · You should not remove any other editions that you may still want to rollback to at some point, or to publish to other subscribers.

2. Once you have deleted all unnecessary editions, go to the Section Detail screen and click the Section History tab, then click the Remove Unused Versions button.

   

   Figure 2.31 The Section Detail screen, History tab

   It may take a while for this process to complete if you have large sections. This process removes any versions that are no longer referenced by the remaining editions. Because distributors store versions of the publication's sections, this function also attempts to contact any distributors that contain versions of the section and remove the unneeded versions there, too.

Removing a subscriber from a publication

The publication retains information about the last published section version on a subscriber until the subscriber is deleted, for example, if version 3 section A was last published to the subscriber. If that information becomes invalid, it may be necessary to remove the subscriber.

To remove a subscriber from a publication

On the Publication Subscribers screen:

1. In the Subscriber list, locate the publication you want to remove.
2. Click the delete button to its right.

   

   Figure 2.32 The Publication Subscribers screen

   This removes all knowledge of that subscriber from the publication. It does not remove any files from the subscriber itself.