Work with Your Documents

You can find and view a document by navigating to it, by searching for it, or by viewing it from a URL or unique identifier. You can also open a document from TeamForge directly into Microsoft Office applications.

What is a Document in TeamForge?

For TeamForge purposes, a document is any file that you track with a document artifact.

Any project involves some number of documents that have to be written, edited, reviewed and published. You can use a document artifact to facilitate and standardize the work you do with documents. TeamForge automatically maintains the version history of each document, including the person who posted each version, its status, and any version comments.

If you are the author, use the Review feature to track the process of getting others to evaluate your document.

To make sure everyone who needs to know about a document knows about it, associate it with a task, a code commit, or another kind of artifact.

Create a Document

You can create a document by uploading a file or by entering the text directly into TeamForge.

You can also create a document in TeamForge. TeamForge automatically detects the file extension for many common file types.

Note: To create a document, you must have the Document Admin permission, or ‘Create/View’ permission for document folders or documents.

Note: From 17.11 release, TeamForge is configured to send HTML emails to users assigned to and users monitoring the document that create. For more information, see HTML Emails for Documents.

Note: You can now be able to unmonitor the documents by clicking the link Unmonitor the Document in the emails that you receive when you create documents. For more information, see Unmonitor Documents via HTML emails.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder in which you want to create the document, and click Add Document. You can create a document in the root document folder or any other document folder.

On the Create Document page, enter a name and description for the document.

You can tag a document if you want to. Select one or more tags from the TAGS field. Your Project Administrator must have set up tags for you to add tags to your documents. For more information, see Set up Tags. You can also create new tags if you have Document CREATE/EDIT permissions. To create new tags, just type a new tag title and click Create a new tag link.

Identify the status of the document.

Draft - The document is not yet completed.

Final - The document is finished.

If you want to prevent others from editing or downloading the document, select appropriate check boxes in the LOCK DOCUMENT section.

To lock a document for editing, select Prevent others from editing.

To lock a document for downloads, select Prevent others from downloading. The download lock prevents other users from downloading the document. You must have enalbed the edit lock to make this selection.

To enable the Document Admin to edit the document, select Enable Document Admin to edit. You can choose to allow the Document Admin to unlock and edit a document after enabling the edit lock.

By default, all the locks are disabled. You must have the edit lock enabled to select the download lock. Selecting the edit lock automatically enables the Document Admin to edit the document.

To choose locks in the LOCK DOCUMENT section, you must have the Document Edit permission.

Select the document creation method.

To upload a document, select Upload From File and browse to the desired file.

To enter the content as text, select Create Online.

To upload a document from a specific URL, select Enter Document URL and provide the URL.

Note: You cannot prevent others from editing or downloading the document if you choose this URL option. Edit and download locks are not effective in this case.

Write any comments you may have about this version of the document.

Save your changes:

Click Save to save the document and return to the document list view.

Click Save and View Details to save the document and display the document details.

The Document Details Page

Each document in TeamForge has a Document Details page where you can find information about the document.

Contents

The Document Details page has these components:

Document Details - View details about the document such as the name, description, file type, and size.

Status - View the document status, including whether it is locked for editing.

Created By - Identify and contact the author of each document version.

Versions - View the version history of the document.

Change Log - View the change log of a selected document.

Associations - View any items associated with the document.

Version Comment - Explanation of changes from one version of the document to another.

Monitor - Begin or stop monitoring the document.

Edit a Document

When you are called on to help develop a document, you can edit the document online or by posting a new version.

To edit a document that is currently locked for editing, the user must have the Document Edit permission. To download a document that is currently locked for downloading, the user must have the Document View permission. A Document Administrator that have the option, Allow Document Admin to edit enabled in the LOCK DOCUMENT section or a Site Admin can also remove the edit and download locks.

Update a Document

To update a document, you can upload a new document version or change the document’s name, description, or lock status.

You can also update a document in TeamForge directly from one of the following Microsoft Office applications: Word, Excel, Project and PowerPoint.

Note: From 17.11 release, TeamForge is configured to send HTML emails to users assigned to and users monitoring the document that you update. For more information, see HTML Emails for Documents.

Note: You can now be able to unmonitor the documents by clicking the link Unmonitor the Document in the emails that you receive when you update documents. For more information, see Unmonitor Documents via HTML Emails.

Click DOCUMENTS from the Project Home menu.

Using the document free, find the folder containing the document that you want to edit.

Select the document you want to edit by clicking the document name.

On the Document Details page, click EDIT/UPDATE. You can see this button at the top right corner of the page only if you have Document Edit Permission.

On the Edit Document page, make your changes.

Update the name or description by entering new text in the appropriate field.

Change the status value, if appropriate.

To set locks, select appropriate check boxes in the LOCK DOCUMENT section.

Update a binary document by selecting Upload From File, then browsing for the updated file.

Update a text document by selecting Create Online, then editing the document text.

Enter a version comment to describe the changes made, if appropriate.

Click Save.

The document is now updated.

Change the Active Document Version

You can specify which version of a document is the active version at any time.

TeamForge stores every document version that you or any other user posts. When you open a document from the document list view, you open the active document version. When you open a document’s Document Details page, the information you see is about the active document version.

The Versions section of the Document Details page lists all document versions and indicates which one is currently active. By default, the most recently posted document version is the active version.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the document.

Select the document by clicking its name.

Tip: On the Document Details page, in the Versions section, the active document is indicate with a check in the Active column.

Select the version that you want to make the active version, and click Mark As Active.

The selected document version is now the active version.

From TeamForge 18.1, you can associate TeamForge objects such as artifacts, documents, and so on with the desired version of a document. Select the desired document version and click the Associate button on the Versions tab in the Document Details page to select and associate a TeamForge object with this document version.

Note: If you haven’t selected any document version, the current active version of the document gets associated with the object.

Find and View a Document

You can find and view a document by navigating to it, by searching for it, or by viewing it from a URL or unique identifier. You can also open a document from TeamForge directly into Microsoft Office applications.

Navigate to a Document

If you know where a document is posted, or would like to browse to see what documents are available, you can find a document by navigation.

You can get to documents from your project home page or by searching the project’s documents page.

Choose a way to find documents:

Look for a Documents window on your project home page. If your project manager has added a document component, you will find all your project documents there (see Create a Project Page Component to know how to add a “Documents” component to the project home page).

If there is no Documents component, click Documents in the project navigation bar. The List Documents page appears.

Select a documents folder.

If a documents folder contains sub folders, you can expand the document tree by clicking the arrow to the left of the folder name.

To view or save a document, click the file type icon to the left of the document name. Use the filter options to locate the document you want. Documents with file types that can be viewed in a browser, such as HTML and text, are displayed in a TeamForge window. For other file types, use the appropriate viewing software.

To view additional information about the document, click the document name.

Search for a Document

Search for a document by its title, its content, the project or folder in which it is located, its file type, its creation date, or its status.

If you don’t know which project to search, or want to search for documents and other types of items simultaneously, use global search.

To search by location: If you know the document is located in the current folder, check the Current Folder in the SEARCH CATEGORY field. Otherwise, the default Root Category searches all document folders in the project.

To search by name or description, enter the text in the SEARCH KEYWORDS field and select Search Name and Description.

To search by document content, enter the text in the SEARCH KEYWORDS field and Search Within Document.

To search by name, enter the text of the document name in the DOCUMENT NAME field.

To search all document versions, select SEARCH ALL VERSIONS.

To search by date range, enter the start and end dates for the search. Click the Calendar icon to select dates from a calendar.

To search by author, enter the user name in the CREATED OR EDITED BY field. Click the search icon to display a list of project members.

To search by document status, select one or more document statuses from the Status list box.

Click Search.

TeamForge lists the documents matching your search criteria.

Lock a Document

While you are working on a document, you can lock it to prevent others from editing or downloading it and then posting new versions to TeamForge.

You can lock a document when you create it or at any time afterward. When a document is locked, any user with the Document View permission can view or download the document. You can edit or download a locked document, if you are Site Admin or a Document Administrator that have the option, Allow Document Admin to edit in the LOCK DOCUMENT section.

On the Document Details page, confirm that the lock status is currently ‘Unlocked’.

Click EDIT/UPDATE. You can see this button at the top right corner of the page only if you have Document Edit permission.

Click Save. The document is now locked. It is presented by the Padlock icon in the document list view.

Unlock a Document

To work with a document that someone else has locked, you must unlock the document.

You can unlock a document that you have locked before. If you want to unlock a document that was locked by someone else, you must be a Site Admin or a Document Administrator that has the option, Allow Document Admin to edit enabled in the LOCK DOCUMENT section.

On the Document Details page, confirm that the document is currently locked.

Click EDIT/UPDATE. You can see this button at the top right corner of the page only if you have Document Edit permission.

On the Edit Document page, clear the check boxes in the LOCK DOCUMENT section.

Click Save.

The document is now unlocked. All project members with the Document Edit permission can now update the document.

Start a Document Review

There are a few things you have to do to get the most out of a document review.

To get a document reviewed, select the appropriate reviewers, set a due date, and explain to the reviewers what you need from them.

Before starting a document review, you must create the document in TeamForge.

Click DOCUMENTS from the Project Home menu.

In the document tree, click the title of the document you want input on.

On the Document Details page, click the REVIEW tab, then click Start a Review.

Note: If a review is already in process, Start a Review does not appear, because you can only have one review at a time.

On the Start a Review Cycle page, give the review a descriptive name.

Enter a due date for reviewers. Click the Calendar icon to select dates.

Tip: Comments are due at 12:00 midnight on the date selected. Therefore, if you want all document reviews to be completed by end of day Tuesday, select Wednesday as the review end date.

Select the required and optional reviewers. Click the Search icon to pick from a list of project members whose access permissions enable them to see this document.

Write a message to your reviewers describing the document and the type of input you need from them. Your reviewers will get this message in an automatic email that shows you as the sender.

Tip: If you add yourself to the reviewers list, you will get a copy of this email for furture reference.

Click Save.

The document is now submitted for review.

All reviewers receive an email with the details of the review, your message, and a link to the Review Details page where they can download the document and post their responses.

The document status is changed to Review and remains so until the review is closed.

Tip: To help keep track of the development of your document, associate a tracker artifact with your document review.

Read Review Responses

You can read the review responses from the email or from the Review Details page. The Review Details page is the starting point for managing all document review activities.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the desired document.

Click the title of the document.

On the Document Details page, click the REVIEW tab. A summary of all open and closed reviews appears.

Click the title of the desired review. Review comments are listed in the bottom section of the page.

You can also reach the Review Details page by clicking the link provided in any related email notification or by clicking the title of the review in the My Document Reviews section of your My Page.

Edit Review Details

At any time after a review is started, you can change the review name, the required and optional reviewers, and the due date.

When you edit review details, affected reviewers get an email notification with the details of the change.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the desired document.

Click the title of the document.

On the Document Details page, click the REVIEW tab. A summary of all open and closed reviews appears.

Click the title of the desired review. The Document Review page appears.

Click EDIT.

On the Edit Review Cycle page, make your changes.

Click the Calendar icon to select dates from a calendar.

Click the Search icon to display a list of project members from whom you can select.

Click Save.

When you add reviewers, new reviewers receive an email with the details of the review.

When you remove reviewers, removed reviewers receive an email telling them that their reviews are no longer necessary.

When you change the due date outstanding reviewers receive an email with the new due date.

Send a Reminder Email

To help project members keep track of their review obligations, you can send a reminder email to reviewers who have not yet submitted their responses.

On the Document Review page, find the outstanding required and optional reviewers.

Click SEND REMINDER EMAIL.

On the Send Reminder Email page, write a message to include in the email.

Choose whether to send the document as an attachment to the email.

Note: The URL to the document is included in the email regardless of whether the document is attached.

Click Send.

The email is sent to all reviewers who have not yet submitted responses.

Close a Document Review

After a document review is completed, close the review.

Reviews are never closed automatically. You must close any outstanding reviews on a document before you can start a new one on the same document.

Note: You can close a review even if the due date has not yet passed.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the desired document.

Click the title of the document.

On the Document Details page, click the REVIEW tab. A summary of all open and closed reviews appears.

Click the title of the desired review you want to close.

On the Document Review page, click CLOSE REVIEW.

On the Close Review Cycle page, change the document status to Final or Draft.

Click OK.

The review is now closed. Any reviewers with outstanding reviews receive email notifications that the review is closed.No additional review responses can be submitted.

Review a Document

To contribute to a review, you look at the document, consider responses from other reviewers, and post your own responses.

When you are identified as a reviewer of a document, two things happen:

You receive an email about the review. The details include the due date, whether you are a required or optional reviewer, and any message text entered by the review submitter. The email also includes a link to submit your response.

A new entry in the Documents Awaiting Review section of your My Page provides a summary of the review, including the review due date, the project in which the document is posted, and the person who is requesting your review.

Go to the Document Review page by clicking the link provided.

Click the link in the email notification you received with the review details.

Click the title of the document in the Documents Awaiting Review section of your My Page.

On the Document Review page, in the Submit a Response section in the center of the page, enter your response.

If appropriate, use the Browse button to attach a marked-up copy of the document, or another attachment.

Associate a requirements document with supporting feature requests or bugs in the tracker.

Associate a document, or a document review, with the task that requires it as a deliverable.

Associate a master document such as a product plan, with other supporting documents such as a test plan or beta plan.

Associate a product announcement document with a file release.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the document to which you want to add an association. Select the document by checking the box, then click Details.

On the Document Details page, click the ASSOCIATIONS tab.

Click Add.

In the Add Association Wizard select the items with which you want to associate the artifact:

ENTER ITEM ID - If you know the item’s ID, you can enter it directly.

To associate an object in an integration application from within TeamForge, use the [<prefix_objectid>] format. Successful associations appear hyperlinked.

Each integrated application displays its prefix on moving the mouse over the application name in the tool bar.

ADD FROM RECENTLY VIEWED - Select one of the last ten items you looked at during this session.

ADD FROM RECENTLY EDITED - Select one of the last ten items you changed.

Click Next.

You may add a comment in the ASSOCIATION COMMENT text box.

Save your work.

Click Finish and Add Another to add additional associations.

Click Finish to return to the Details page.

When an association is added to or removed from TeamForge objects such as tracker artifacts, tasks, documents, discussions, and file releases, a notification mail is sent to users monitoring these objects.

An option is provided at site level and user level to make sure whether the notification mail has to be sent or not. For more information on this, see Configure your Site’s Settings.

Click the ASSOCIATIONS tab to view a graphical representation of all the associated items. Through the Association Viewer, you can choose to view associations in the form of a list or flip over to the Trace view to explore the layers of associations (including parent/child dependencies) laid out in a timeline. You can scroll across the Trace view by dragging the mouse over the association layer or use the ‘Previous’ or ‘Next’ arrows to view all the objects as events in a timeline.

While the ASSOCIATIONS tab shows the count of the total number of associations, you can only view the most recent 500 associations when you click the ASSOCIATIONS tab in case the artifact has more than 500 associations. You can, however, browse through the Association Viewer to view older associations.

You can click on each node on the graphical association viewer to filter and display the associated items in the table below the association viewer thus matching the number of associations provided on the selected node. For example, if the node that you select for filtering is having two associations on it, the table displays the two associated items as a result of the filtering process.

Project Members with the Document Admin permission can copy and move documents. They can also create and administer documents. However, they can delete documents, only if they have the specific delete permission.

Copy a Document

If a given document belongs logically to two or more document folders, keeping a copy in each folder can help users locate it.

Copying a document can also be useful if you want to use an existing documents as a template for creating a new document. When making a copy of a document, reference to the source document is maintained in the document title and the Associations tab.

Note: Each copy must be maintained separately. Changes made to one copy are not propagated to other copies.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and select the folder containing the document that you want to copy.

Select the document you want to copy, then click Copy. The Copy Files dialog box appears.

Select the project from the Select Project drop-down list and select the document foler where you want to copy the selected document.

Click Copy.

The document copy is now placed in the selected folder, with the “Copy of ”. The reference to the source document is also maintained in the Associations section of the Document Details page.

Move a Document

You can move it to another document folder within the project or to a document folder in another project at any time. This allows you to reorganize documents as needed.

You can move one or more documents in the same operation. You cannot move a document while it has an open review.

Note: To move a document between projects, you must have document administration permission in both the source and destination projects.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and select the folder containing the document that you want to move.

Select the document you want to move, then click Move. The Move Files dialog box appears.

Select the project from the Select Project drop-down list and select the document folder where you want to move the selected document.

Click Move.

The document is now moved to the selected folder.

Delete a Document

If you no longer need a document, you can delete it. Deleting a document deletes all the document’s versions, plus the document’s details and review history.

Note: To delete documents, you must specifically have the delete permission (‘Delete/View’) for document folders or documents. This is irrespective of whether you have the Document Admin permission or not.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the document that you want to delete.

Select the document you want to delete.

Click Delete.

The document is deleted.

Delete Document Versions

Document versions can grow in number over time. You may choose to delete one or more versions of a document if you no longer need them. This saves a lot of disk space and maintenance overheads.

You can delete a document’s version only if:

you have the delete permission (‘Delete/View’) for documents. This is irrespective of whether you have the Document Admin permission or not.

the document has more than one version available.

the selected document version is not marked as an active version.

Caution: Deleting a document’s version permanently removes the version and cannot be undone. Exercise caution while deleting document versions.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find the folder containing the document that you want to delete.

Click the document’s name link to see its versions.

Select one or more document versions you want to delete from the VERSIONS tab and click Delete. A confirmation message is displayed.

Click OK to delete.

The document versions are deleted.

Project members with the Document Admin permission can create, edit, move and reorder document folders. Similarly, project members with the relevant individual permission can create, edit, delete or view document folders.

Create a Document Folder

Document folders, like file directories, allow you to organize your documents in a logical, hierarchical manner using labels that are meaningful to you and your organization.

You can create folders in the root folder or as subfolders in any other folder. There is no limit to the number of folders you can create.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and hover your mouse over the folder where you want a new document folder created. For example, hover your mouse over the Root Folder.

A settings icon shows up when you hover your mouse over a folder.

Click the settings icon and select Create New Folder from the menu.

The Create Folder dialog box appears.

In the Create Folder dialog box, enter a name for the folder.

Click Save.

The folder is created.

Rename a Document Folder

When the function of a document folder has changed, it’s a good idea to rename the folder.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and hover your moust over the folder which you want to be renamed.

A settings icon shows when you hover your mouse over a folder.

Click the settings icon and select Rename Folder from the menu.

The Edit Folder dialog box appears.

In the Edit Folder dialog box, enter a new name for the folder.

Click Save.

The folder is renamed.

Move a Document Folder

You can move a document folder within a project. You can move a folder in the following ways:

From the root folder to a subfolder.

From a subfolder to the root folder.

From a subfolder to another subfolder.

When you move a document folder, any documents and subfolders that it contains are also moved to the destination folder.

Project members monitoring the destination folder will continue to receive monitoring notifications after a folder is moved. Project members not monitoring the destination folder will not receive further monitoring notifications.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and hover your mouse over the folder that you want to move.

A settings icon shows up when you hover your mouse over a folder.

Click the settings icon and select Cut from the menu.

Using the document tree, find and hover your mouse over the folder into which you want to move the selected folder.

A settings icon shows up when you hover your mouse over a folder.

Note: You can move a folder into the root folder or into any other folder.

Click the settings icon and select Paste from the menu.

The folder is moved to the destination folder.

Reorder Document Folders

To change the order in which document folders are displayed, you can alphabetize them or reorder them arbitrarily.

By default, document folders are ordered as they were created. New document folders are added to the end of the document tree.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and hover your mouse over the foler containing the subfolders that you want to reorder.

A settings icon shows up when you hover your mouse over a folder.

Click the settings icon and select Reorder from the menu.

The Reorder Document Subfolders dialog box appears.

Organize the subfolders:

To sort them alphabetically, click alphabetize icon.

To reorder a specific folder, select it by clicking the title, then click Move Up or Move Down until the foler is where you want it.

Click Save.

Delete a Document Folder

If you no longer need a document folder, it’s a good idea to delete it. Deleting a document folder deletes all of the documents within it.

Deleting a document folder deletes all of the documents within it.

Important: Delete a document folder only if you are sure that you no longer need any of the documents within it. Move any documents that you want to save. Even if you have the Document Admin permission, you cannot delete a document folder unless you specifically have the delete permission.

Click DOCUMENTS from the Project Home menu.

Using the document tree, find and hover your moust over the folder you want to delete.

A settings icon shows up when you hover your mouse over a folder.

Click the settings icon and select Delete from the menu.

A confirmation message appears.

Click OK to delete the document folder.

Attention: If the folder contains one ore more documents that you do not have permission to delete, you cannot delete the folder.

Work with Your Documents from Microsoft Office Applications

You can use the File menu of any of the Microsoft Office applications such as Microsoft Word, Microsoft Excel, Microsoft Project, and Microsoft PowerPoint to work with documents that are stored on your TeamForge site.

Open a TeamForge Document in Microsoft Office

You can get to your Microsoft Word, Excel, Project, and PowerPoint documents in CollabNet TeamForge even if the CollabNet TeamForge web interface is not open.

Open your Microsoft Office application.

From the File menu, choose Open from CollabNet TeamForge.

In the Login window, provide the following information:

Your TeamForge user name and password.

The URL of your organization’s TeamForge installation.

Note: Do not enter the http:// or https:// before the server name.

Click Log In. The Selection Dialog window shows all of the projects, document folders, and documents that you have permission to view.

Select the document you want to open.

The document opens in your Microsoft Office application.

Save a Document to TeamForge

You can store your Microsoft Office documents in CollabNet TeamForge even if the CollabNet TeamForge web interface is not open.

CollabNet TeamForge works with Microsoft Word, Excel, Project, and PowerPoint.

Open your Microsoft application.

Open the document you want to save.

From the File menu, choose Save to CollabNet TeamForge.

In the Log in window, enter the following information:

Your TeamForge user name and password.

The URL of your organization’s TeamForge installation.

Note: Do not enter the http:// or https:// before the server name.

Click Log In. The Selection Dialog window displays all of the projects and document folders in which you have permission to create documents.

Select the document folder in which you want to save the document.

Note: Do not click on an existing document. This will prompt you to update that document.

In the Document Properties window, clear Use Filename, then enter a name in the CollabNet TeamForge Document Name field. By default, the file name is used as the document name.

Write a description for the document.

Choose whether the document is in draft or final status.

To lock the document and prevent others from editing it, select Lock Document.

Write a version comment, if appropriate.

Click OK.

The document is now saved in CollabNet TeamForge. You can see the document by going to the CollabNet TeamForge document folder that you selected.

Note: After you save a document to CollabNet TeamForge, furture saves will also save in CollabNet TeamForge. If you want to save a document to a local drive, choose Save As from your File menu.

HTML Emails for Documents

Starting from TeamForge 17.11, when you create or update a document, TeamForge sends HTML emails to users monitoring that document or the document folder.

HTML emails are formatted emails that look like a newsletter that you receive from a web service. These emails are embellished with colors, graphics, table colums, and links. HTML emails have a better look and feel and override the simple and plain features of plain text emails.

By default, the HTML email configured for documents in TeamForge contains the document details such as document id, document title, description, status, file (document name with link), project, folder and so on. Details of the fields with null values are not shown in the email.

Sample HTML email when a document is created:

The email sent when a document is updated contains the new and old values for fields such as linked file name, description, Tags, status and so on.