1 of 16

CWCM

CWCM: Site Packaging Import Process User

Manual Version 1.2

18/07/2012

2 of 16

DOCUMENT HISTORY

Version Date Author Description Action(*) Confidentiality Pages

1.0 14/04/2010 IDS Creation C High 15

1.1 14/12/2010 IDS Aligned version history U High 16

1.2 18/07/2012 IDS Changed to template EC 2012 U High NA

(*) Action: C= Creation, I=Insert, U=Update, R=Replace, D=Delete

3 of 16

TABLE OF CONTENTS

1. Introduction 4

1.1 Site Packaging functionalities 4

1.2 Permissions 4

2. The Export Process 5

2.1 Sequence of actions 5

2.2 Options available for an export process 5

3. The Import Process 7

3.1 Sequence of actions 7

3.2 Uploading an archive 7

3.3 Triggering an Import Process 8

3.4 Downloading the results of the import process 10

3.4.1 Import report 12

3.5 Specifying the Link groups options of an Import Process 12

3.5.1 Link group issues 12

3.5.2 Link group strategies 13

3.5.3 Links matching 14

3.5.4 Link group mappings 14

3.5.5 Specification of strategies in a file 15

3.5.6 Inserting the specification file inside the archive 16

4 of 16

1. INTRODUCTION

1.1 Site Packaging functionalities

The aim of the site packaging is to provide the means to transfer a subsite with its content to another system, which is not necessarily a WSK system. In this destination system users can change the subsite and its content and transmit it back to the source system. Meanwhile the subsite may also have been modified on the source system.

More concretely, site Packaging deals with:

externalizing a subsite and its content, i.e. creating an archive or site package, which contains all necessary information concerning the subsite and its content. This operation is referred to as an “export” or a “Site Packaging Export”. The export operation can not export full domains.

Copying the archive to another machine (optional).

Internalizing the archive in a system on the target machine1, i.e. from the archive recreating the externalized subsite and its content inside that target system. This operation is referred to as an “import” or a “Site Packaging Import”.

The name of the exported subsite can be modified during the import process. This is especially useful when a subsite is exported and imported on the same system.

Refer to the document “UM.custom.webmaster” for Site Packaging Export functionalities.

The exact content of a site package is described in the document “Pivot Format and Package Structure Definition for Site Packaging”, which provides a technical insight. It is not necessary to read this document to

understand and to use the basic site packaging functionalities.

In the WCM Starter kit, there exist another “Export” and another “Import” which allow a user to export and import file(s). Those “Export” and “Import” processes have nothing to do with the “Site Packaging Export” and the “Site Packaging Import” processes which allow some users to export and import a subsite.

In the remaining of this section, unless explicitly stated otherwise, “Import” or “the import process” will refer to the “Site Packaging Import Process”, and “Export” or “the export process” will refer to the “Site Packaging Export Process”.

1.2 Permissions

A user can launch the site packaging export on subsites for which he is a web master.

Only a root webmaster can import site packages on his system.

The intended audience of the present document are the Root Web Masters.

In this document we will focus on the Import Process, and we will briefly recall some aspects of the Export Process

when appropriate, among others the options available when triggering an Export Process.

1 The target machine may be the machine on which the Export Process occurred, or another

machine onto which the archive has been copied.

5 of 16

2. THE EXPORT PROCESS

2.1 Sequence of actions

The “Export Process” is part of the following sequence of actions:

Triggering the “Export Process”.

Downloading the resulting reports and/or archive.

Checking the resulting reports and/or archive.

The downloaded archive can be transmitted to another system. This other system may be a WSK system, where its

root webmaster will import it, or another type of system.

The transmission of the archive can occur via e-mail, via FTP, a USB key, a CD-ROM…

2.2 Options available for an export process

For recall, the export process provides the following options:

Export Content the document inside the selected subsite and its child subsites and folders will be exported.

Export XSL the XSL documents referred from the XML objects inside the subsite will be exported

the XSL documents inside the subsite in the parallel Site Manager structure will

also be exported

Export Prototypes the prototype files existing inside the

subsite in the parallel Site Manager structure will be exported.

Export Plain Linkgroups all plain link groups which are referenced

from the XSL documents inside the subsite will be exported

all plain link groups which are referenced from the XSL documents referred from the XML objects inside the subsite will be exported

Export Menu Linkgroups all menu groups which are referenced

from the selected subsite or child subsites are exported

Export Category

Linkgroups

all categories which are referenced from

the subsite or its contained documents are exported

all categories which categorizes a plain

link group or menu group referenced by

6 of 16

an XSL which is located inside the subsite or referenced from an XML document inside the subsite

all categories which categorizes a plain link group or menu group referenced by

the selected subsite or its child subsites

7 of 16

3. THE IMPORT PROCESS

3.1 Sequence of actions

The “Import Process” is part of the following sequence of actions:

Uploading the archive.

Performing the “Import Process”.

Checking the resulting reports and/or archive.

3.2 Uploading an archive

To be able to perform this action any subsite must be selected in the left pane.

Select “File|Site Packaging|Upload Package” in the menu bar.

Like this:

A screen similar to the following one will appear:

8 of 16

You can browse on your machine and select the archive you want to upload or directly type the path of the archive in the text box.

Click on “Ok” to upload the archive on your system.

After the upload the text box is emptied and you can upload another site package or click “Cancel” to return to the

navigation screen.

3.3 Triggering an Import Process

To import an uploaded site package, you must first select its destination. Walk in your tree of subsites and select the subsite or domain into which you intend to import the archive.

Then select “File|Site Packaging|import Package” in the menu bar.

Like this:

9 of 16

At this point, a screen similar to the following one will appear:

The list of the archives you have uploaded is displayed. Archives other users uploaded are not accessible.

You can delete an archive you don’t need anymore by clicking the “Delete” button. Be careful when deleting,

because the deletion is direct and unrecoverable.

After the selection of one of the available archives, you must decide if you want to rename it or not.

Filling in the “Rename to” box allows you to import the root subsite of the archive with another name than the original one. The original name is the name of the subsite during the export process.

10 of 16

You must then define the action to be performed.

The available actions are:

Simulate Import: if you select this action, the Import Process is executed without actually importing the

archive, i.e. only the report associated with the import is created.

Import: if you select this action, the Import Process is executed.

Performing an import simulation allows you to test the import as often as necessary until you are sure the import will

not mess with your system. For instance, you may not be sure of the effect of an import concerning your link groups. It will indicate any conflicting link group ids.

Clicking on one of the buttons “Simulate Import” or “Import” triggers the Import Process itself. If another import

process that you or another root webmaster have started, is still running, the import process is not launched. A message will inform you about this. You have to wait till the process finished before retrying.

The Import Process, like the Export Process, is asynchronous. When the process is completed, a notification is sent to

your Documentum inbox and e-mail to your mailbox to inform you about the situation.

3.4 Downloading the results of the import process

When the Import process is completed, if you select “File|Site Packaging|import Package” in the menu bar once again, you will see a new folder which contains the report associated with the import just completed. The folder name

will contain the import launch date and time inside its name.

It looks like this:

11 of 16

When the import process is initiated the new entry appears almost immediately and stays empty until the Import

Process is completed.

If you click on the new entry (“import-16-04-10_15-32-06_078” in our example), you will enter a folder-like

hierarchy and see the following screen appear:

12 of 16

By checking the report and then clicking on “Download”, you can download the report on your machine and view it.

You can delete a report or a complete folder you don’t need anymore by clicking the “Delete” button. Be careful

when deleting, because the deletion is direct and unrecoverable.

3.4.1 Import report

An XML report is available.

It details each step of the import process. It is actually a tracing of the Import Process.

The XML report contains:

A set of “msg” elements.

Each “msg” element contains some informative text, e.g. the name of the archive.

A set of “object” elements.

Each “object” element includes information concerning an object that has been exported. It includes other elements, among them the “success” element.

The content of the “success” element is a text that can be either “true” or “false”.

The report may also contain elements called “warning”, “error”, and “fatal”.

You should parse all “success” elements in the report, and make sure that their content is “true”.

You should also check if there are some “warning”, “error” and/or “fatal” elements inside the report.

3.5 Specifying the Link groups options of an Import Process

The “Simulation” and “Rename subsite to” options described in section 3.3 are not the only ones available for an Import Process.

You may also specify in details the behavior of the Import Process concerning the Link Groups.

In this section, when we refer to « Link Groups », we mean in fact « Link Groups » and/or « Category Groups ». It makes the text easier to read. When we want to refer to Link Groups only, we will use the terms “Plain Link Groups” and/or “Menu Groups”.

First, it is necessary to explain some issues concerning link groups.

3.5.1 Link group issues

Every link group has a specific identifier, called lg_id. This lg_id is unique in one WSK system, but not across several

WSK systems. Exchanging site packages with link groups in them between several WSK systems can lead to link group id conflicts, i.e. the lg_id of a link group in the site package is already used by another link group in the target system. We will clarify this further with an example.

13 of 16

Let us assume on our system a link group is defined with a lg_id 13745. Another system also contains a link group with this same lg_id 13745. This may be the result of a site package transfer between the two systems, or purely a coincidence.

A webmaster of the other system launches the Export Process and sends us the site package that contains the link group with lg_id 13745, because the link group options “Export Plain Linkgroups”, “Export Menu Linkgroups” and “Export Category Linkgroups” have been selected and the link group was referred from an object inside the exported

subsite.

This is called a link group id conflict. If a lg_id on the system on which the import is performed is equal to some

lg_id in the imported archive those link groups are in conflict.

Several usage scenarios can lead to this link group id conflicts.

A first usage scenario is the site packaging roundtrip:

A subsite is exported on our system, the link group options being selected

The resulting archive is transmitted to another system, on which it is imported and edited

The subsite on the other system is exported, the link group options being selected

The resulting archive is transmitted to our system, on which it is imported.

In such a scenario, the link groups are in conflict because they originate from the same Link Group (although their contents may differ). In such a situation, we would probably wish to merge the contents on the Link Groups, in

some way.

In another usage scenario the link groups may be in conflict by chance, because WSK systems choose their lg_id’s

randomly when a user creates a link group. The Link Groups are two distinct Link Groups, and are not related. In such cases, we would probably wish to have two separate Link Groups on our system at the end of the Import process.

3.5.2 Link group strategies

To deal with the link group id conflicts, you can define a set of so-called strategies.

Each strategy is an association between a Link Group in the archive and a behavior. The behavior describes what

the Import Process will do in case of a conflict concerning the link group.

This allows you to decide the behavior of the Import Process when a conflict occurs, Link Group (in the archive) per

Link Group.

There are 6 possible behaviors.

“merge-new”: the links of the Link Group in the archive are added at the end of the existing links in the

Link Group existing on the system.

“merge-overwrite”: each link in the Link Group on the system “matching” a link in the Link Group in

the archive is replaced by the matching link in the archive.

“merge-ignore”: each link in the Link Group on the system “matching” a link in the Link Group in the archive is kept as is, i.e. the matching link in the Link Group in the archive is ignored.

“new”: first, a new (empty) Link Group is created on the system. Second, each link of the Link Group in the archive is inserted in the newly created Link Group, in the same order they exist in the Link Group in

the archive.

14 of 16

“overwrite”: the links in the existing Link Group on the system are erased. They are replaced by the links existing in the Link Group in the archive.

“ignore”: the existing Link Group on the system is not modified. The links existing in the Link Group in the archive are not taken into account.

The merging strategies “merge-new”, “merge-overwrite” and “merge-ignore” are only applicable if the conflicting link groups are from the same type, i.e. plain link group, menu group or category group.

If you try to use the merging strategies on conflicting link groups of different types the system will fall back on the “new” strategy.

For conflicting link groups of the same type the default behavior is “merge-new”, for conflicting link groups of a

different type “new”. If a conflict occurs and no strategy is specified for the Link Group involved in the conflict, the default behavior is used.

If there is no conflict, a new Link Group is created on the system using the lg_id provided in the archive.

3.5.3 Links matching

The “merge-overwrite” and “merge-ignore” strategies try to match the links between the existing link group and the link group to import

The following definition has been chosen:

a link in a Category Group is “matching” a link in another Category Group if the links have the same subject.

a link in a Plain Link Group is “matching” a link in another Plain Link Group if

o Both links have a non-empty subject and have the same subject, or

o At least one of the links has an empty subject and they have the same title.

a link in a Menu Group is “matching” a link in another Menu Group if

o Both links have a non-empty subject and have the same subject, or

o At least one of the links has an empty subject and they have the same title.

3.5.4 Link group mappings

In each strategy, it is also possible to remap a lg_id to one existing in the target system in order to merge two

link groups with a different lg_id.

You can decide that a Link Group in the archive whose lg_id is (say) 13745 is in conflict with an arbitrary Link

Group on the system having the same type as the Link Group in the archive using a so-called mapping2.

The use of such a mapping is a generalization which allows you to provoke a conflict. This is useful when a link group

has changed its lg_id during a roundtrip scenario (strategy “new”) and it is necessary to merge it with the original link

group with the old lg_id.

With or without mapping, we still have the basic idea of applying a strategy when a conflict occurs.

2 The mapping is specified by providing the lg_id of the arbitrary Link Group on the system, together

with the lg_id of the Link Group in the archive (13745 in our example).

15 of 16

Remember a conflict may only occur between Groups having the same type. This implies you can only map a Plain Link Group on a Plain Link Group, a Menu Link Group on a Menu Link Group, or a Category Group on a Category Group.

3.5.5 Specification of strategies in a file

For each strategy, you must specify:

The lg_id of the link group in the archive

The associated behavior.

Additionally, you can specify the lg_id of a link group on the system to provoke a conflict.

The strategies are defined in an XML file contained in the site package.

The reports of an import simulation indicate what will happen when you import a site package with a specific

strategies file.

3.5.5.1 Example

Here follows an example of XML strategies file, and the definition of its elements.

<?xml version="1.0" encoding="UTF-8" ?>

<strategies>

<strategy type="new">

<lg>123456</lg>

</strategy>

<strategy type="merge-new">

<lg>234567</lg>

<mapping>147258</mapping>

</strategy>

</strategies>

3.5.5.2 Element definition

Element or

Attribute Name

Data Type Size Mandatory Repeating Notes

type String N/A Yes No Possible values:

merge-

new

merge-

overwrite

merge-

ignore

new

16 of 16

overwrite

ignore

lg Integer N/A Yes No the lg_id of a link group, menu or

category group in the site package

mapping Integer N/A No No a valid lg_id of an

existing link group in the

target WSK system

3.5.6 Inserting the specification file inside the archive

To apply the strategies to resolve the link group id conflicts, you must add the strategies file to the site package.

Perform the following steps to do so:

Download the site package to your local machine.

Create or edit a specification file.

Unzip the archive.

Add or update the specification file. Its name must be “mta_str.xml” and it must be located inside the

archive in the folder where the file named “mta_arc.xml” exists.

Zip the archive with the same name as before.

Upload it (as described in.3.2). Note the existing archive will be overwritten if the same name is used.

If necessary, perform an import simulation with uploaded site package

Inspect the report to see whether the expected result is achieved, otherwise upload the same site package with another strategies file “mta_str.xml”

Import the site package as described in 3.3.