Note:
Do not use the Document Migration Utility to export or import portal folders and portal template folders.
To be able to perform the tasks listed in this appendix, you should have an understanding of the content created in Content Server for a portal, portal template, wiki documents, and wiki pages, and a detailed understanding of the Document Migration Utility and the format of its archive.
This section describes the format and how wiki documents and wiki pages work in WebCenter Portal. For more information about wiki documents and wiki pages in WebCenter Portal, see Working with Wikis in Oracle Fusion Middleware Using Oracle WebCenter Portal.
This section contains the following topics:
In WebCenter Portal you can create a wiki document within a wiki page. These documents can reside anywhere in the hierarchy of any created folders inside a portal. Wiki documents can sit alongside documents of other types, or you could choose to arrange all your wiki documents inside a single folder.
When a wiki document is created in WebCenter Portal, an HTML document is created and checked into Content Server. This wiki document contains special metadata values that tell WebCenter Portal that the document is a wiki document as opposed to a regular HTML document. These metadata values are:
dDocType = Application dDocFunction = wiki dOriginalName (document filename) = <wikiName>.htm
When you open a document in WebCenter Portal with the above metadata, WebCenter Portal will know to display it as a wiki document.
In WebCenter Portal you can create a wiki page by creating a page based on the Wiki page style. When you navigate to a wiki page you are presented with a wiki document. See Working with Wikis in Oracle Fusion Middleware Using Oracle WebCenter Portal for details on how to create wiki pages.
When a wiki page is created in WebCenter Portal the following artifacts are created in Content Server:
A wiki folder is created in the folder for the portal the wiki page is being created in; the name of the wiki folder is the same name as the wiki page name but with special characters removed:
/RootFolder/PortalFolder/wikiPageNameFolder/
When FrameworkFolders is enabled, the wiki folder is created at the following path: /Enterprise Libraries/PortalFolder/wikiPageNameFolder/
A document is created inside the wiki folder with the following metadata:
dDocTitle = document title (same name as the wiki page name with an extension of .htm)
dOriginalName = the documents filename (same as dDocTitle)
dDocFunction = wiki
dDocType = Application
xWCPageID = the name of the wiki page's JSPX page
This is best illustrated with an example. Consider that the portal in which a wiki page is being created is Marketing, and the wiki page being created is Wiki1. The following artifacts will be created in Content Server.
Folder: /Enterprise Libraries/Marketing/Wiki1
Document: /Enterprise Libraries/Marketing/Wiki1/Wiki1.htm
Attributes set for the document:
dDocTitle= Wiki1.htm
dOriginalName = Wiki1.htm
dDocFunction = 'wiki'
dDocType = 'Application'
xWCPageID = Wiki1.jspx
When you navigate to a wiki page the following occurs:
Content Server is queried for the document in the following location:
/RootFolder/PortalFolder/wikiPageNameFolder/wikiPageName.htm
If the document is found, it is displayed as a wiki document.
If the document is not found, the wiki page will display the contents of the wiki folder.
To migrate content from an existing wiki application to WebCenter Portal, perform the following steps:
These steps are described in more detail in the following topics:
When the documents tool is enabled in a portal or portal template, a folder is created in Content Server for that portal or portal template. The GUIDs of these folders must be determined in order to construct the archive to be used with the Document Migration Utility. The folder GUIDs can be determined by following steps below:
Decide if you want to import all the wiki content into a single portal or multiple portals.
Log into WebCenter Portal and create the portals, taking note of the internal name of the portals.
Ensure you are using a template that includes documents tool, otherwise you will have to enable the documents tool and setup the role permissions after portal creation.
Log into Content Server.
Ensure that the user's layout is Top Menus:
Click the user's name to display the user's Profile page.
Under User Personalization Settings check that Layout is set to Top Menu.
For each portal in which wiki content is to be imported, determine the folder GUID:
Click Browse Content.
Click on the root folder for the WebCenter Portal instance.
This is the same as the Root Folder setting in the Content Server connection.
Click the folder for the portal.
The folder name will be the same as the portal's internal name.
Click Info on the toolbar to display the folder information.
Add IsSoap=1 to the URL.
Search for the string dCollectionGUID in a Folders_g setup. For example:
<idc:field name="dCollectionGUID">05573322-E895-EDA3-8A83-07CF39CBDE05</idc:field>
When using the FrameworkFolders folder service, search for the string fApplicationGUID, for example:
<idc:field name="fApplicationGUID">WC01:8c1c6442-a258-4cd7-8cf1-adb60fc45ce2</idc:field>
Keep a note of the portal folder name and its GUID as the GUID is needed when building the archive in the next step.
To extract content from the source wiki application into an archive suitable for use with the Document Migration Utility, you'll need to write a custom application.
The custom wiki extraction tool must perform the following steps:
Each of these steps is described more fully in the following topics:
The wiki documents in the source application need to be extracted into a temporary directory on the file system and then arranged such that the file system mimics how the content is to be laid out in the target WebCenter Portal instance. If all the wiki documents are to be imported into a single portal, all of the content should be laid out under a single root folder named with the GUID of the corresponding portal folder in Content Server. If the wiki documents are to be imported into multiple portals, the content should be laid out under multiple root folders, each named with the GUID of their corresponding folder in Content Server. For more information on determining the GUID of a portal folder in Content Server, see Preparing WebCenter Portal for Importing Wiki Content.
Note that when arranging the wiki content on the file system, you should consider how that content will be used in WebCenter Portal. For example:
If wiki pages are to be created, then the wiki document for that wiki page must be located under a folder of the same name. For more information about wiki pages, see Understanding Wiki Documents and Wiki Pages.
When a folder contains a large number of contents, the rendering of that folder's contents could be impaired.
Content Server has two settings that limit the number of folders and the number of files which can reside in a folder (Maximum Folders Per Virtual Folder and Maximum Content Per Virtual Folder). When arranging your wiki content, ensure that a folder does not contain more folders than the folder limit setting or more documents than the document limit setting.
To create extracted wiki content, perform the following tasks:
Create root folders for each portal into which you will be importing the wiki documents, name the folders based on the GUID of the corresponding portal folder in Content Server.
For wiki documents for which wiki pages will be created in WebCenter Portal after import:
Create a wiki folder with the same name as the wiki document.
Place the wiki document in this folder.
Place any other documents in this folder, if required.
If there are related images and/or documents, add them to this wiki folder as well.
For any other wiki documents, create the folder hierarchy that will contain the documents.
Example:
Portal S1's folder in Content Server has a GUID of 21SD15F13B8_141D_421B_AD0e_BC54B6F16893. After import, the MarketingWiki and Tradeshows wiki pages will be created and it is expected these wiki pages will show the MarketingWiki.htm and Tradeshows.htm wiki documents.
The following shows the organized structure of the extracted wiki documents and artifacts:
21SD15F13B8_141D_421B_AD0e_BC54B6F16893 (Root portal folder)
Home.htm (Wiki document)
MarketingWiki (Folder)
MarketingWiki.htm (Wiki document)
Branding (Folder)
Presentation Dates.htm (Wiki document)
Presentations (Folder)
ProductBranding.pptx (File)
ProjectedDesigns.pptx (File)
Tradeshows (Folder)
TradeShows.htm (Wiki document)
Images (Folder)
Image.jpg (Image)
In WebCenter Portal, the wiki editor will remove any HTML tags when the wiki page is being edited. Therefore it is advisable to remove any such HTML tags in the wiki documents prior to importing them into WebCenter Portal to avoid any confusion of tags being removed when editing a wiki document after import. The following tags can be safely removed:
<html>, </html> <head>, </head> <meta>, </meta> <title>, </title> <body>, </body> <tbody>, </tbody> <thead>, </thead> <tfoot>, </tfoot> <script>, </script> <link>, </link>
Wiki pages in the source wiki application may contain URLs referencing artifacts in within the source wiki application, such as links for embedded images or to other wiki page or documents. These artifacts will be migrated to the target WebCenter Portal instance and these links will need to be updated to reference the new artifact locations in the target WebCenter Portal instance.
The following types of URLs in the extracted wiki pages need to be changed to reference the URLs of the same artifacts in WebCenter Portal:
Links to other Wiki pages
Links to embedded images
Links to documents
Follow the steps below to rewrite the URLs in the wiki documents:
In each root folder containing the contents to be imported an ExportImportData.xml document needs to be created. The ExportImportData.xml document describes the contents of the root folder and is used to drive the import when importing the content into WebCenter Portal using the Document Migration Utility.
Any metadata to be created with the document on import must be specified in the ExportImportData.xml document. In WebCenter Portal, wiki documents are stored as HTML documents but have extra metadata to identify them as wiki documents rather than normal HTML documents. Ensure the ExportImportData.xml document has this metadata specified for all wiki documents in the extracted contents. For more information about the metadata required for wiki document, see Understanding Wiki Documents and Wiki Pages.
Note:
A content ID (dDocName) is automatically generated by Content Server when a document is checked in without one being specified. If you wish your documents to have fixed content IDs, include the dDocName metadata with the document metadata in the ExportImportData.xml document. The dDocName must be unique across the whole Content Server or document check in will fail. A suggestion is to chose your own prefix for the content ID and append numbers incrementally to the end.
The ExportImportData.xml document can be generated manually for each root folder. Alternatively, you can write a custom script to traverse through the root folder contents and generate the document.
It is imperative for the structure of the contents on the file system is detailed in ExportImportData.xml document correctly. If there is a mismatch between the hierarchy of contents described in the ExportImportData.xml document and the file system, the import into the portal folder in the target Content Server will fail.
The XSD for the ExportImportData.xml document is shown below.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="groupspace-folder" type="FolderType" />
<!-- 'folders' must contain 1 or more 'folder' child elements -->
<xs:complexType name="FoldersType">
<xs:sequence>
<xs:element name="folder" type="FolderType"
minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<!-- 'documents' must contain 1 or more 'document' elements -->
<xs:complexType name="DocumentsType">
<xs:sequence>
<xs:element name="document" type="DocumentType"
minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<!-- 'attributes' must have 1 or more 'attribute' child elements -->
<xs:complexType name="AttributesType">
<xs:sequence>
<xs:element name="attribute" type="AttributeType"
minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<!-- 'folder' has to have 1 and only 1 'attributes' child element
0 or 1 'folders' child element, 0 or 1 'documents' child element -->
<xs:complexType name="FolderType">
<xs:sequence>
<xs:element name="attributes" type="AttributesType"
minOccurs="1" maxOccurs="1" />
<xs:element name="folders" type="FoldersType"
minOccurs="0" maxOccurs="1" />
<xs:element name="documents" type="DocumentsType"
minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
<!-- 'document' has to have : 1 and only 1 'attributes' child element
and nothing else -->
<xs:complexType name="DocumentType">
<xs:sequence>
<xs:element name="attributes" type="AttributesType"
minOccurs="1" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
<!-- 'attribute' element has to have a 'name' and 'value' attributes -->
<xs:complexType name="AttributeType">
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="value" type="xs:string" use="required" />
</xs:complexType>
</xs:schema>
Where:
<groupspace-folder> is the root tag that represents the portal or portal template folder.
This tag contains the <attributes> tag, which in turn contains a number of attributes about the root folder and export data. These attributes are for information purposes only; they are not used in the import.
<attributes> is used to group all the attributes of the document or folder.
This tag must contain one or more <attribute> tags. No other child tags are permitted.
<attribute> contains the metadata for a folder or document.
This tag has two attributes:
name - the Content Server metadata name
value - the value of the metadata
No child tags are permitted.
<folders> is used to group all the folders in the current folder
This tag must contain 1 or more <folder> tags. No other child tags are permitted.
<folder> is used to indicate a child folder.
This tag must have the <attributes> tag. If the folder has child folders, it will have the <folders> tag. If the folder has child documents, it will have the <documents> tag.
<documents> is used to group all the documents in the current folder.
This tag must contain one or more <document> tags. No other child tags are permitted.
<document> is used to indicate a document in the current folder.
This tag must have the <attributes> tag. No other child tags are permitted.
The following annotated example shows a partially complete ExportImportData.xml document, when FrameworkFolders is used as the folder service. Note that the example contains blank lines and XML comments that should not exist in a real ExportImportData.xml document.
<groupspace-folder>
<attributes>
<!-- Contains a set of attributes of the main portal folder -->
<attribute name="export-date" value="2011-07-22 13:02:29"/>
</attributes>
<folders><!-- only present if the portal contains any child folders -->
<folder><!-- a 'folder' tag exists for each child folder -->
<attributes>
<!-- contains the set of folder attributes, examples below -->
<attribute value="F1" name="fFolderName"/>
</attributes>
<!-- a 'folder' tag will contain the 'folders' tag if this folder contains child folders, i.e. if 'F1' has child folders -->
<folders>
<folder>
<!-- attribute tags, child folders, child documents etc -->
</folder>
</folders>
<!-- closing tag for all the folders in the current folder-->
<!-- a 'folder' tag will contain the 'documents' tag if this folder contains documents, i.e. if 'F1' has documents at its root -->
<documents>
<document>
<!-- attributes tags, see below -->
</document>
</documents><!-- closing tag for all the documents in the current folder -->
</folder>
<!-- closing tag for folder 'F1' -->
</folders>
<!-- closing tag for all the folders in the portal root -->
<documents>
<!-- only present if the folder contains any documents in the root folder -->
<document>
<!-- a 'document' tag exists for each document in the folder -->
<attributes>
<!-- contains the set of document attributes, examples below -->
<attribute name="dDocTitle" value="Doc1"/>
<attribute value="0" name="fInhibitPropagation"/>
</attributes>
</document>
<!-- closing tag for document 'Doc1' -->
</documents>
<!-- closing tag for all the documents in the portal root -->
</groupspace-folder>
In this example a custom script named convert_program traverses through a root folder called 21SD15F13B8_141D_421B_AD0e_BC54B6F16893 and creates an ExportImportData.xml document in the current working directory detailing the contents of the folder.
cd 21SD15F13B8_141D_421B_AD0e_BC54B6F16893 run convert_program
Create an archive of the extracted and manipulated wiki documents by zipping up the root portal folders. The zip archive must have the root folders inside the archive rather than just the contents of the root folders. One zip file can contain multiple root folders for different portals, or you can create one zip file for each root folder.
Example:
In the following example, wiki documents have been extracted and manipulated in a folder called 21SD15F13B8_141D_421B_AD0e_BC54B6F16893 in the folder /scratch/wikiexports and the archive to create is wsimport.zip.
cd /scratch/wikiexports zip –r wcimport.zip 21SD15F13B8_141D_421B_AD0e_BC54B6F16893/
Note:
Ensure that the archive does not exist prior to zipping up the folder contents as some zip tools will add content to the specified archive if it already exists rather than overwriting the archive.
Run the Document Migration Utility specifying the archive generated in the previous step to import the content into the target Content Server.
Log into WebCenter Portal and navigate to the portals to which content was imported and ensure the content exists.
Table D-1 describes the properties required to run the Document Migration Utility. For information on how to run the utility, see Migrating Content Using the Document Migration Utility.
Table D-1 Document Migration Properties
| Property | Description | Requirement |
|---|---|---|
|
Usage |
Specifies whether you want to import or export content to a file. Options are: |
Export and Import |
|
MDSConn |
Specifies MDS JDBC connection in the format:
|
Export |
|
MDSUser |
Specifies the MDS user name used by WebCenter Portal. |
Export |
|
MDSPwd |
Specifies password for the MDS user. Only include to avoid password prompt. |
Export |
|
ExportScopes |
Specifies the internal name of each portal/portal template with content to export. Separate multiple portal/template names with a comma. Prefix portal template names with You can obtain internal names from the About Portal and About Portal Template dialogs. Do not enter display names here. |
Export |
|
UCMConn |
Specifies Content Server URL in the format: When When |
Export and Import |
|
UCMUser |
Specifies the Content Server user name used to connect through RIDC. This user must have sufficient privileges to perform the export or import; either a user defined in an external identity store or the Content Server administrator |
Export and Import |
|
UCMPwd |
Specifies password for the Content Server user. Only include to avoid password prompt. |
Export and Import |
|
UCMSpacesRoot |
Root folder under which WebCenter Portal content is stored. The value may be set as |
Export and Import |
|
TmpDirPath |
Optional. Temporary location for data extraction. If not specified, defaults to the system |
Export and Import |
|
ArchivePath |
Document archive location. |
Export and Import |
|
ArchiveName |
Optional. Name for the document archive ( |
Export and Import |
You can use any of the following methods to migrate content using the Document Migration Utility:
Create a properties file containing all the properties required for your export/import. See Table D-1 for a description of all the properties.
Copy and paste the following properties file into Notepad or another suitable text editor, then edit according to your environment:
# Document migration properties. # Specify whether you want to export content to a file or # import content from an archive to another content repository # valid values: export | import Usage=export # Specify connection details for Oracle WebCenter Content repository: # UCMConn - Content Server URL. Format: idc://host:intradocPort # UCMUser - Content Server user name used to connect through RIDC # UCMPwd - Password for UCMUser. Only include to avoid password prompt # UCMSpacesRoot - Root folder where WebCenter Portal content is stored. Format: /foldername # Required for: Export and Import UCMConn=idc://mycontentserver.mycompany.com:9444 UCMUser=<enter Content Server admin user name here> #UCMPwd=<enter password for UCMUser here> #UCMSpacesRoot=/portalrootfolder # Specify a temp directory and name/location for the export archive # TmpDirPath -Optional. Temporary location for data extraction. # If not specified, defaults to the system temporary directory. # ArchiveName -Optional. Name for the document archive (.zip). # Default is docsexport.zip. # ArchivePath -Document archive location # Required for: Export and Import TmpDirPath=/scratch/user1/migrateMyPortalDocs/tmpdir ArchivePath=/scratch/user1/migrateMyPortalDocs/output ArchiveName=myportaldocs.zip # Specify MDS details (export only) # MDSConn - MDS JDBC connection. Format: # jdbc:oracle:thin:@host:port:SID or # jdbc:oracle:thin:@host:port/ServiceName # MDSUser - MDS schema user name used by the WebCenter Portal application # MDSPwd = Password for MDSUser. Only include to avoid password prompt # Required for: Export MDSConn=jdbc:oracle:thin:@mymdshost.mycompany.com:1521:wkcdb01 MDSUser=<enter MDS user name here> #MDSPwd=<enter password for MDSUser here> # Specify target portal for export or import. # Seperate multiple portal/template names with a comma. # Use internal names only. Do not enter display names. # Obtain internal names from "About Portal" and "About Portal Template" dialogs. # Prefix portal template names with 'spacetemplate/<template_internal_name>' # as indicated in the example. # Required for: Export ExportScopes=MyPortal1,MyPortal2,spacetemplate/MyPortalTemplate
Save the file. For example, save as myMigrationProperties.properties or similar.
Navigate to the WCP_ORACLE_HOME/webcenter/archives directory in which the Document Migration Utility, content-migration-tool.jar is located.
Run the Document Migration Utility by specifying the absolute path to your document migration properties file on the command line:
java -jar content-migration-tool.jar <absolute_path_to_migrationPropertiesFilename>
For example:
java -jar content-migration-tool.jar /home/user1/myMigrationProperties.properties
Optionally, specify logging settings using the java.util.logging.config.file parameter as described in Running the Document Migration Utility with Additional Logging.
You can optionally run the Document Migration Utility with additional logging using the java.util.logging.config.file parameter as follows:
java -Djava.util.logging.config.file=<absolute_path_to_logging_properties_file> -jar content-migration-tool.jar <migrationProperties>
Note: The java.util.logging.config.file parameter must be specified immediately after the java command and before -jar.
Where the logging_properties_file includes settings such as:
handlers=java.util.logging.ConsoleHandler.level=INFO java.util.logging.ConsoleHandler.level=FINER java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter oracle.webcenter.doclib.level=INFO