When importing, you can select a single archive file, identified by the extension odarc. The Developer validates the archive structure when you initiate the import process. Therefore, you cannot choose to import only specific pieces of an archive; you must import the entire archive as a unit.
Next, you specify the Library location into which the contents of the archive are to be imported. You can browse to select an existing folder or type a new folder name, including Library path if necessary, to create a new folder for the imported material.
Finally, you have the option to overwrite existing documents or not. You should choose the overwrite option if the archive contains updated versions of documents that are already in your Library. In contrast, you might choose not to overwrite existing documents to import only new documents from an archive containing some documents that are new and some that are already present in your Library. Skipping the existing documents in this way speeds the import process.
In general, the import process writes the contents of the archive file to your Library in the selected location, re-creating the documents and their Library structure as necessary, as well as links to and from the documents. A summary message appears if some of the documents you selected could not be processed. Clicking the View activity log link in the message displays a list of the results for each document.
The specific results of importing an archive depend on the contents of the archive, the existing contents and structure of the Library, and the specified import options, as detailed next.
- The Library folder structure represented in an archive corresponds to the absolute folder structure relative to the root of the Library from which the archive was created. During import, this folder structure is created relative to the import location specified in the Import dialog box. Therefore, to exactly reproduce the folder structure of the Library from which the archive was created, you should select the root ("/") as the import location.
- If the Library folder structure represented in an archive already exists in the specified import location, the contents of the archive folders are written to the existing Library folders, which has the net effect of merging the corresponding folders. Otherwise, the archive folder structure is created in the specified location.
- For the purpose of overwriting during import, documents are identified solely on the basis of Document ID, not title, language, or any other document property; location in the Library is also not important. Therefore, for a given document in an archive, the following three situations can arise:
No document with the same ID exists in the Library - The new document is created in the specified import location.
A document with the same ID exists in the Library but overwrite is not selected - The archive document is skipped.
A document with the same ID exists in the Library and overwrite is selected - The document is overwritten in its current Library location, regardless of the selected import location. That is, documents are never moved within the Library when they are overwritten during import.
- For the purpose of re-creating links during import, documents are again identified solely on the basis of Document ID; location in the Library is not important. Therefore, if a document links to a child document with a given ID and a document with the same ID as the child already exists in the Library (or is imported at the same time as the parent), the link is re-created. If no such child document exists, a broken link results.
- If the imported content includes new documents that were stored in the System folder, the new documents are always imported into the System folder and not in the folder specified for the import.
The following information summarizes the results of import for different combinations of import options:
- New content with new folder structure
Overwrite: NA
Results: New folder structure is created in the specified Library location; new documents are created in these folders
- New content with existing folder structure and root folder selected as the import location
Overwrite: NA
Results: New documents are created in the existing folder structure (the folders are merged).
- Existing content with new or existing folder structure
Overwrite: No
Results: Existing documents that are not overwritten are not imported.
- Existing content with new or existing folder structure
Overwrite: Yes
Result: Existing documents are overwritten in their current Library locations.
- Mixture of new and existing content with new or existing folder structure and the root NOT selected as the import location
Overwrite: Yes
Result: New folder structure is created in the specified import location, and new documents are created in these folders; existing documents are overwritten in their current Library locations.
- Mixture of new and existing content with existing folder structure and the root selected as the import location
Overwrite: Yes
Result: Existing documents are overwritten in their current Library locations, and new documents are created in the existing folder structure.
- Selecting Cancel during import stops processing after completion of the current document and displays a message with a link to a list of the documents that have already been imported. Click the View activity log link in the message to display a list of the results for each document.
Also note that, during import, the Developer identifies all roles used in the imported content. It then compares these roles to the master role list of the same language. If any of these roles is not included in the appropriate master role list, the Developer attempts to add the role to the role list. If the role cannot be added to the list, for example, if the master role list is open in an editor, the role is still kept in the content but is not included in any role list. You can later update the master role list to include these roles, if desired.
Multi-user Considerations
- For a document to be overwritten during import, it must be checked out. Therefore, before initiating the import process, you should ensure that any documents that must be overwritten are either checked out to you or checked in to the server. If you plan to import an archive while offline, you must check out all such documents before going offline.
However, if a document that needs to be overwritten is not checked out and you are online, the Developer automatically checks the document out to you and replaces it with the corresponding document from the archive. If the document cannot be checked out, for example, if it is open in another editor or checked out to another user, it is skipped.
Note that, if a document in the archive existed in the Library but had been deleted, overwriting moves the document from Deleted view to Library view, thus restoring the document. The document is restored in its original location, regardless of the selected import location.
Also note that, if the Developer needs to add roles to a master role list during import, this master role list must be checked out. If the role list is not checked out and you are online, the Developer automatically checks it out to you and adds the necessary roles. If the role list cannot be checked out, for example, if it is open in an editor or checked out to another user, the roles are kept in the imported content but are not added to the role list. You can later update the master role list to include these roles, if desired.
After you complete the import process, you should check in all affected documents (new and overwritten) to make them available to other authors and add the changes to the Developer's version control system. If a document was overwritten, its version number is incremented only if its contents have changed. That is, if a document in the archive was identical to the same document already in the Library, overwriting on import does not affect the document's version history.
To import content:
- On the Tools menu, point to Import and choose Documents.
- Set the import options.
To exactly reproduce the folder structure of the Library from which the archive was created, select the root ("/") in the Import content to field.
- Click Import to execute the process.
The import tool analyzes and processes the selected archive, adding the archive documents and re-creating their relative folder structure in the specified Library folder.
If any errors occur, they are written to an activity log, and a Partial Import message box appears. You can click the View activity log link to view the results of the import or click OK to close the message box.