CopyContrib

Copies webs, topics, attachments, or part of them

This extension can be used to copy topics and webs. It allows to select which parts of an item is to copied.

Typical use cases are:

1. duplicate topic assets: copy attachments, comments or preference settings to another existing topic
2. deploy wiki applications: copy a selection of topics to a target web
3. workflow scenarios: separate work on a draft topic from its last approved version by creating a copy first and copy the finished draft over as a newly approved version
4. versioned webs: create a new web for each version of a product
5. merge webs: create a new web by copying a list of webs to the new web
6. publish content: from a closed quality-managed authors-only area to a public read-only web

Usage

The work horse for all operation modes is a single service script called copy. It takes a mode parameter for which a copy agent is created to perform the actual operation. The basic skeleton for a form to call the copy service looks like this:

<form action="%SCRIPTURLPATH{"copy"}%/%WEB%/%TOPIC%" method="post">
  <input type="hidden" name="mode" value="topic" />
  <input type="hidden" name="includepart" value="fields" />
  <input type="hidden" name="includepart" value="form" />

  <input type="text" name="destination" size="80" />

  <!-- more parameters -->

  <input type="submit" />
</form>

Parameters

General

Name	Description	Default
mode	select the type of operation; possible values are: topic: copy one topic or parts of it to a destination topic topics: copy a list of topic to a destination web: copy a web to a destination application: Create a web supported by a given application stub: create a stub for a given application topic
debug	boolean flag to switch on/off debug output; messages are printed to the error log of the web browser	off
dry	boolean flag to switch on/off a dry mode; if enabled none of the operations will actually be saved permanently	off
onlynew	boolean flag to enable/disable a check for the destination to already exist; an exception will be raised if enabled and the target object already; the target object will be overwritten in case it already exists and the flag is disabled; to be precise, a new revision will be created in this case	on
forcenewrevision	force the save to increment the revision counter	off
dontlog	mark this change so it doesn't appear in the statistics	off
minor	True if this change is not to be notified	off
clear	boolean flag; when enabled data on the destination will be deleted first before copying the source data; (exception: text is always cleared before copying it over); when disabled data of source and destination will be merged	off
redirectto	topic or url where to redirect the browser after a successful copy operation
nohandlers	boolean flag; when enabled plugin handlers will not be called, such as beforeSaveHander and afterSaveHandler	off

Mode: topic

Name	Description	Default
source	the source topic to be copied	%BASEWEB%.%BASETOPIC%
dstWeb	the destination web where to copy source to	%BASEWEB%
dstTopic, destination	the destination topic where to copy source to	source
includepart, includeparts	a list of parts of a topic to be copied; known part-ids are text, attachments, all, preferences, parent, form, fields, or any other custom meta data alias such as comment from MetaCommentPlugin	all
excludepart, excludeparts	a list of parts to exclude from the copy process
include<part-id>	when meta data is named as is the case for fields you may specify a regular expression in includefields that all fields must match when copying formfields
exclude<part-id>	same as include<part-id> but in reverse logic
fromrev	specify the starting revision to be copied over; if left undefined, will only the top revision be copied
torev	specify the last revision to be copied over
preservetopicinfo	boolean flag; this will try to preserve the original date and authorship of the source; note that this may not always be possible when the top revision of the target is earlier than the revision(s) to be copied over; further note, that attachments of old revisions not present in the top revision cannot be recreated on the taregt topic as they are versioned independently
trashsource	boolean flag; this will trash the source after successfully copying it to the target; note: when only parts of the topic have been copied will the rest of it get lost!	off

Mode: topics

Name	Description	Default
destination	the destination where to copy all source topics to; this can either be a web or a topic; in the latter case all source topcis will be copied to the destination
source	a list of topics to be copied	%BASEWEB%.%BASETOPIC%

All parameters of the topic mode apply to each topic in the source list.

Mode: web

Name	Description	Default
source	the source web to be copied	%BASEWEB%
destination	the destination web where to copy all topics of the source web to
template	a template web to be used in case the destination web does not exist yet and needs to be created on the base of a template	_empty
search	search expression to find topics in the source web. See QuerySearch for more information	.*
include	regular expression topics in the source web must match to be included in the copy process
exclude	regluar expression; excludes matching topics from the source web

Mode: application

Name	Description	Default
source	the source topicsto be copied	%BASEWEB%
destination	the destination web where to copy all source topicsto
template	a template web to be used in case the destination web does not exist yet and needs to be created on the base of a template	_default

Mode: stub

Name	Description	Default
source	the source topic to be copied	%BASEWEB%.%BASETOPIC%
destination	the destination topic where to copy source to	source

Examples

Copy one or more topics to a destination

Source:

separate multiple topics with a comma

Destination:

can be a topic or a web

Include parts:

Text
Attachments
Preferences
Parent
DataForm
Comments

leave unchecked to copy all

Exclude parts:

Text
Attachments
Preferences
Parent
DataForm
Comments

Options:

Allow overwrite
Force a new revision
Minor change, don't notify others
Don't log changes
Clear before copying

Advanced Options:

From Version
To Version

Preserver author and revision information

Submit

Copy a web but strip all comments

Source:

specify source web

Filter:

specify a search query

Destination:

specify destination web

Submit

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::FilterPlugin	>=5.30	Required

Change History

30 Jan 2024:	make sure all created topics start with an uppercase char
19 Jan 2024:	added support for AUTOINC targets while copying topics
12 Nov 2019:	fix copy cgi script
26 Jul 2019:	fix use of store; create a new revision when copying attachments instead of erasing anything that existed before
11 Jun 2019:	added copy perl api; added nohandlers option; fixed copying attachments
21 Nov 2018:	added trashsource to topic agent; fixed memory leaks
09 Feb 2018:	added feature to restore a subset of topic revisions
30 Jun 2017:	added application mode (by Foswiki:Main/BramVanOosterhout)
25 Sep 2015:	added support for unicode foswiki
10 Jun 2014:	improved error handling; make messages translatable
30 May 2014:	added forcenewrevision, minor and dontlog
22 Oct 2013:	initial release