Concepts

SetupHandler

A component registered for importing or exporint some portion of the site's configuration. Products register handlers via the GenericSetup API or via ZCML (see "Registering Setup Handlers" below).

SetupContext

The set of files representing the site's configuration, created during export and read during import.

MetaProfile

The set of SetupHandlers configured into the setup tool, defining the portion of the site's configuration which the tool knows how to export to / import from profiles. A given MetaProfile must be a proper subset of all registered SetupHandlers in the system.

SetupProfile

A coherent slice of site configuration, captured as a set of folders, scripts, templates, and data files.

BaselineProfile

A SetupProfile which, when imported, first replaces the tool's MetaProfile; it then applies each import step destructively, using its own data as the import SetupContext.

ExtensionProfile

A SetupProfile which, when imported, may register additional steps into the tool's MetaProfile (but may not remove or replace steps). It then applies each import step non-destructively.

SnapshotProfile

A profile created by exporting the site's current configuration, using the export steps in the tool's MetaProfile. The snapshot may be captured within the tool as either a zipfile or as a folder structure and files; it may also be downloaded as a zipfile.

DeltaProfile

A profile created by comparing two of the following: a registered BaselineProfile, a SnapshotProfile contained within the tool, or a SnapshotProfile created on-the-fly. The comparison UI of the tool allows the user to select one or more sections of the generated diff for inclusion in a DeltaProfile.

Use Cases

Registering Setup Handlers

Product authors register setup handlers either using the API of the GenericSetup product or via ZCML directives provided by GenericSetup. They may register export handlers and import handlers; in the case of import handlers, they may register one or more IDs of other import steps which must be run before the step / handler being registered.

For instance:

      from Products.GenericSetup.registry import registerImportHandler
      from setup_handlers import importFoo
      registerImportHandler(id='Products.MyProduct.importFoo',
                            title='Import Foo Configuration',
                            handler=importFoo,
                            dependencies=('Products.MyProduct.importBar',),
                           )

Or:

      <configure
          xmlns="http://namespaces.zope.org/zope"
          xmlns:setup="http://namespaces.zope.org/GenericSetup">
        <setup:import_handler
          id="Products.MyProduct.importFoo"
          title="Import Foo Configuration"
          handler="Products.MyProduct.setup_handlers.importFoo"
          dependencies="Products.MyProduct.importBar"
          />
      </configure>

Registering Filesystem Profiles

Product authors register setup handlers either using the API of the GenericSetup product or via ZCML directives provided by GenericSetup. A profile may be registered either as a BaselineProfile or as an ExtensionProfile. The profile data is located via the path argument / attribute, which may point either to a filesystem directory or to a zipfile. If the optional product argument / attribute is passed, then the path argument is interpreted relative to the base directory of the product; otherwise, the path is relative to the INSTANCE_HOME. The scope parameter, if passed, labels the registered profile as relevant to a particular kind of site (see "Adding a Configured Site" below).

Note that where the product is packaged as a Python Egg, the profile may be bundled within the egg file.

For instance:

      from Products.GenericSetup.registry import registerBaselineProfile
      registerBaselineProfile(id='Products.MyProduct.BarSite',
                              title='Bar Site',
                              path='profiles/bar',
                              product='Products.MyProduct',
                              scope='CMF',
                             )

Or:

      <configure
          xmlns="http://namespaces.zope.org/zope"
          xmlns:setup="http://namespaces.zope.org/GenericSetup">
        <setup:baseline_profile
          id="Products.MyProduct.BarSite"
          title="Bar Site"
          path="profiles/bar"
          product="Products.MyProduct"
          scope="CMF"
          />
      </configure>

Adding a Configured Site

The factory form for a site which uses GenericSetup to manage its configuration should present to the user, in addition to any other input widgets required, a single-select widget containing the list of BaselineProfiles registered for the approfpriate scope, and another multi-select widget containing the list of ExtensionProfiles registered for that scope.

The user should select one BaselineProfile and zero or more ExtensionProfiles, which together define the site's initial configuration.

The factory method to which the form POSTs should:

1. Instantiate the site using any relevant form data.
2. Create a setup tool within the site, passing the appropriate scope.
3. Import the selected BaselineProfile into the tool (see "Importing a Baseline Profile" below).
4. Import any selected ExtensionProfiles into the tool (see "Importing an Extension Profile" below).
5. Create a SnapshotProfile within the tool, representing the installed configuration of the site.

Installing a Third-Party Product

After instantiating a site, the site administrator may choose to install additional products, which may register additional SetupHandlers, BaselineProfiles, or ExtensionProfiles. The setup tool allows the administrator to incorporate these additional plugins: see "Inspecting the Tool's MetaProfile", "Installing a BaselineProfile", and "Installing an ExtensionProfile" below.

In the future, we hope that utilities such as the CMFQuickInstaller morph into user-friendly drivers for these mechanisms.

Inspecting the Tool's MetaProfile

The site administrator can use the "MetaProfile" tab of the setup tool to examine both the "registered" SetupHandlers and those which are currently configured into the tool's MetaProfile. The tab presents a dual-list form, allowing the administrator to add or remove registered handlers from the MetaProfile.

Creating a Snapshot

At any point in time, the site administrator may chose to create a snapshot of the site configuration, using the tool's current MetaProfile. This snapshot is captured within the tool, either as a zipfile (easier to save / migrate), or as the set of folders, scripts, and XML files which would be the contents of that zipfile.

Exporting a Snapshot

Rather than creating the snapshot as persistent data, stored within the setup tool, the administrator may choose to export the snapshot as a zipfile, which will be downloaded directly by the browser.

Comparing Profiles

The "Comparison" tab of the setup tool allows the site administrator to compare two profiles selected from the following:

• Registered BaselineProfiles
• An uploaded zipfile
• Previously captured SnapshotProfiles
• A SnapshotProfile created on-the-fly from the current site configuration.

The results of the comparison are presented to the administrator as a unified diff, with syntax highlighting, and can be saved as a file.

See also "Creating a DeltaProfile" below.

Creating a DeltaProfile

After requesting a profile comparison (see "Comparing Profiles" above), the site administrator may select one or more of the "deltas" presented in the comparison results for inclusion in a new DeltaProfile, which may then be either downloaded or stored within the tool. This DeltaProfile may be used to restore local configuration changes after upgrading a product, which may require re-importing the BaselineProfile from that product; without the DeltaProfile, the re-import would discard any local changes.

Importing a BaselineProfile

Importing a new BaselineProfile after initial site creation is a potentially risky operation: all local changes (within the scope of the MetaProfile) are likely to be lost. The setup tool should warn the administrator of this risk, and ask for confirmation before importing the selected BaselineProfile.

Importing an ExtensionProfile

Because ExtensionProfiles are "additive", they can be imported into an existing site with less risk than BaselineProfiles. The tool might still need to warn that some local changes might be lost (those directly affected by the ExtensionProfile's data).

Importing a DeltaProfile

DeltaProfiles provide a way for the site administrator to preserve local changes before importing a BaselineProfile or ExtensionProfile (e.g., after upgrading a product). The procedure here would be:

• Compare the current, on-the-fly snapshot with the snapshot created at the last import.
• Select those portions of the diff which represent "valuable" local changes, and generate a DeltaProfile from them.
• Re-import the BaselineProfile (or ExtensionProfile(s)) from the on-disk product.
• Re-import the DeltaProfile, restoring local changes.

Note that this process may still require corrections, if the local changes are such that the DeltaProfile cannot be cleanly applied.

Migrating Site Configuration

Profiles represent a set of policy choices; an exported SnapshotProfile (as a zipfile) can thus be used to move a set of policies from one site to another. The tool allows the administrator to upload a zipfile, which then behaves like any other SnapshotProfile. The exported zipfile can also be checked into a product as a BaselineProfile.

Backing Up Site Configuration

An exported SnapshotProfiles can be treated as a "full backup" of the site configuration, with subsequent DeltaProfiles functioning as "incremental backups" (assuming that they are made against the exported profile).

Content Export / Import

Although originally designed to manage site configuration rather than content, the GenericSetup framework offers several facilities supporting export / import of content (see the separate proposal, "Filesystem Export / Import of Content" for more details).

In the simplest case, some or all of the structure and content of the site may be captured as part of a BaselineProfile or ExtensionProfile, and kept as such under version control with the software. For sites whose content does not change often, this strategy may be quite attractive, allowing for both flexibility and control.

In cases where capturing the content as part of the site's profile is not reasonable (e.g., the volume of change is too high, or the persons responsible for managing changes to the content are not also familiar with the filesystem tools used to manage the software), some or all of the "content space" can still be managed separately using the facilities provided by GenericSetup. The user would, in this case, use a view on a particular folder, document, or file, which exposed the filesystem representation of that content for download, reuising the export contexts provided by GenericSetup.

The "profile" produced could then be used, for instance, to migrate the content from a staging instance to a production instance, or could be manipulated directly using filesystem tools, and then re-imported via the content's view.

Tasks Remaining

• Add API support to GenericSetup for registering SetupHandlers.
• Add ZCML support to GenericSetup for registering SetupHandlers.
• Add API support to GenericSetup for registering BaselineProfiles and / or ExtensionProfiles.
• Add ZCML support to GenericSetup for registering BaselineProfiles and / or ExtensionProfiles.
• Modify the CMF's Configured Site factory to provide UI for selecting a BaselineProfile and zero or more ExtensionProfiles.
• Extend the tool to provide appropriate warnings / confirmation for import of BaselineProfiles / ExtensionProfiles.
• Add UI for selecting importable profiles.
• Add support for registering filesystem zipfiles as profiles.
• Add support for capturing SnapshotProfiles as zipfiles.
• Add support for treating captured SnapshotProfile zipfiles as importable BaselineProfiles.
• Add support for generating DeltaProfiles to the "Comparison" tab.
• Add support for importing DeltaProfiles.
• Add "MetaProfile" tab, including UI for modifying the MetaProfile.
• Flesh out remaining CMFDefault MetaProfile items:
  • Catalog indexes and columns (WIP)
  • Membership tool settings / skeleton
  • Memberdata tool settings
  • Metadats tool settings
  • ContentTypeRegistry settings
  • CachingPolicyManager settings
  • ActionIcon tool settings
  • CookieAuthentication settings (WIP)
  • MailHost settings (WIP)
  • User folder configuration
  • Content space

Related Material

• Florent Guillaume's extension dependency proposal