What are document roots and what are they used for?

Document Roots can be used to create a common "root" location for a collection of documents, such as a shared network folder or a location on a website.

The main advantage of using Document Roots is that documents can easily be moved to a new location. Instead of manually updating the path for every individual document, you only need to update the path of the Document Root. As long as the document names remain unchanged, all document links will continue to work.

When Document Roots exist in a repository, they become available as options when editing a document. You can select a Document Root and then either enter the document's path relative to that root or click Browse to locate the document relative to the selected root if it is stored as a file path.

Example

Assume that your organization currently stores all documents in the following location:

D:\Our Shared Documents\Management System\Social Services Department\

In the future, you may want to move these documents to the network drive K: without having to manually update every document link in 2c8 Apps. In this case, it is beneficial to create a Document Root.

The Document Root would then be configured as:

D:\Our Shared Documents\Management System\Social Services Department\

This is because most of the documents are stored within the Social Services Department folder, which remains constant.

Creating a Document Root

To create a Document Root:

1. Click on Browser in the left-hand panel.
   
2. Double-click Document Roots in the upper section of the left-hand panel.
   
3. Click the Plus to create a new Document Root.
   

Enter a name for the Document Root, for example Social Services Department, so that it is clear which folder it represents.

Enter the path that will remain constant. In this example:

D:\Our Shared Documents\Management System\Social Services Department\

Since the documents are stored within the Social Services Department folder, this folder becomes the root location.

Your Document Root will then look similar to the following:

When creating a document, you can now select this Document Root.

In the example below, the Document Root Social Services Department has been selected. After clicking Browse, the file browser opens directly in:

D:\Our Shared Documents\Management System\Social Services Department\

From there, the document employee_handbook.docx can be selected.

The full path to the document is therefore:

D:\Our Shared Documents\Management System\Social Services Department\employee_handbook.docx

In other words:

Document Root + Relative Document Path

Change the Path of an Existing Document Root

Let's say you have created 250 documents that use the Document Root Social Services Department. If you later decide to move your documents from one network location to another, for example from drive D: to drive K:, you only need to update the Document Root itself rather than modifying all 250 documents individually.

To do this, double-click Document Roots in the left-hand panel.
Then open the Document Root by double-clicking it.
Replace:

D:\Our Shared Documents\Management System\Social Services Department\

with:

K:\Our Shared Documents\Management System\Social Services Department\

provided that the network drive is the only part of the path that has changed.

All document links in 2c8 Apps that use the Social Services Department Document Root will now point to the new location on drive K:.

Replace Existing Document Paths with Document Roots

Have you already created a large number of documents without using Document Roots? It is common to realize later that using Document Roots would have simplified document management, especially when documents need to be moved from one location to another. To help with this, 2c8 Apps includes the Match Against Document Roots function.

Let's assume that many of your documents currently point to:

D:\Our Shared Documents\Management System\Social Services Department\

and that you want to replace D: with K:, resulting in the new path:

K:\Our Shared Documents\Management System\Social Services Department\

Instead of updating each document individually, you can do the following:

1. Create a new Document Root that points to your current document location:
   D:\Our Shared Documents\Management System\Social Services Department\
   Instructions for creating a Document Root can be found earlier in this article.
2. Click on Browser in the left-hand panel and then double-click Documents.
   
    
3. A view displaying all documents will open in the browser editing area. Enable the Path column on the far right side of the browser view.
   
4. You can now see all documents and their paths. Select the documents that point to:
   D:\Our Shared Documents\Management System\Social Services Department\
5. After selecting the documents, click Match to Document Roots in the toolbar.
   The dialog displays all selected documents together with the Document Root that matches their current path. Select the matching documents and click the Check button.
   

6. The document paths have now been replaced with a Document Root. This allows you to later update the Document Root when moving your documents to a new location.

   The documents will now appear as follows, with the path replaced by a Document Root up to the specific document:
   

7. You can now update the Document Root by following the instructions in the section Change the Path of an Existing Document Root above.
   In summary, you have matched your existing documents to a Document Root, making it possible to change the root path from:
   D:\Our Shared Documents\Management System\Social Services Department\
   to:
   K:\Our Shared Documents\Management System\Social Services Department\
   without having to update each document individually.