You are not logged in. Click here to log in.

codebeamer Application Lifecycle Management (ALM)

Search In Project

Search inClear

Document Tracker Configurations

This page provides information on how to use the document tracker.

From codebeamer 21.09 (EMMA), additional licensing is required to enable the Document Management module. For more information on how to obtain the license, contact the Sales Team.

Application Configuration

For document tracker-related application configuration settings, see the "documentManagement" section.

Create a Document Type Tracker

Document trackers combine the functionality of the traditional document management functionality with the flexibility of trackers. To get started, a new tracker must be created with document type.


The default configuration contains built-in fields and their configuration cannot be modified. The built-in fields are as follows:

  • Document name (Text): contains the file name by default, but can be renamed. It must be unique in a folder.
  • Document (Choice): a choice field that stores the file of the item. Can be used to upload new versions.
  • Document modified at (Date): the last modification time of the Document field.
  • Document modified by (Members): the user that uploaded the last file.
  • Size (Text): the size of the file in a human-readable format.
  • Major version (Integer): the major version of the underlying file. Set to 0 for newly uploaded files. Can be configured to increase based on the workflow. For more information, see Configure the Approval Function.
  • Document version (Integer): the minor version of the underlying file. Set to 1 for newly uploaded files and automatically increased by 1 at each update of the file.
  • Revision (Text, computed): computed as: Major version"."Document version, or example, 0.1.

Additionally, the default configuration contains the following optional fields:

  • Confidentiality level (Choice): the default options are internal and external.
  • Approved by (Member): can be configured to store the user who first or last approved the document.
  • Locked by (Member): can be used for storing the user who is locking the document.
  • Document ID (Text): to store the public identifier of the document.

Configure the Approval Function

It can additionally be extended to increase the major version of the document. To do so, add two Update item properties actions to the Approve and Complete state transitions follows:

  • Document version: Set to Value 0
  • Major version: Increased by Value 1

Configuring the Lock Function

  1. Click the Add Status… link to add a new Checked out status.
  2. Save the changes.
  3. Click State transitionin the the context menu to add the required inbound and outbound state transitions.
    • Inbound transition:
      • From: Draft
      • To: Checked out
      • Name: Check out
      • Actions: Update item properties:
        • Locked by: Set to Value Current user
    • Outbound transition:
      • From: Checked out
      • To: Draft
      • Name: Check in
      • Permitted: No one, except for Locked by
      • Actions: Update item properties:
        • Locked by: Clear
  4. Change the field configuration to prevent anyone but the Locked by user editing the item, while it is in Checked outstate.
    1. Change the Document name field permissions to Per Statusas per below:
      • Default:
      • Checked out: read for all, edit only for Locked by
    2. Change the permission settings of the Locked by field to read only, as it is only changed by workflow actions.
    3. Change the permission settings of the following fields to Same as Document name:
      • Parent
      • Status
      • Assigned to
      • Document
  5. Save the configuration.

Requiring Notes before Checking in

It is possible to configure a workflow to force filling a field before checking in a change of a document items. The field is also assisted by an additional hidden and automatic technical status that is only to make the field mandatory when checking in. The required configuration is the following:

  1. Click the Add Status… link to add a new History required status with In progress meaning.
  2. Add a new field to store the change history of the documents.
    1. Scroll to the bottom of the screen on the Fields tab of the tracker configuration and click More fields… ► New custom field… option.
    2. Fill in the details of the new field.
      • Label: Last change
      • Type: Wikitext
      • Mandatory in Status: None, except for History required
    3. Save the changes.
  3. Click State transition function and delete the existing Check in transition.
  4. Click the More… dropdown to add the required inbound and outbound state transitions for the History requiredstatus.
    • Inbound transition:
      • From: Checked out
      • To: History required
      • Name: Check in
      • Permitted: No one, except for Locked by
      • Actions: Update item properties
        • Last change: Clear
    • Outbound transition:
      • From: History required
      • To: Draft
      • Select both the Hidden and the Automatic options
      • Permitted: No one, except for Locked by
      • Actions: Update item properties:
        • Locked by: Clear
  5. Save the changes.

Publish Documents to Another Tracker

To publish documents to an audience that is different from the users of the general documents tracker, it is recommended to create a separate documents tracker. This allows the customization and fine-tuning the document sets.

  1. Create a new document tracker for public documents and save the changes.
  2. Modify the workflow of the public documents the following ways:
    • Rename Draft to Published with meaning Resolved.
    • Delete the Waiting for approval status.
    • Rename Completed to Superseded with meaning Closed.
  3. Save the changes.
  4. Configure the status transitions of your public documents the following way:
    • Rename the Draft transition from your Unset status to Publish.
    • Rename the Complete transition to Superseded.
    • Delete the Draft transition between the Published and Superseded statuses.
  5. After the changes.
    Expected workflow:
  6. Configure the internal documents tracker workflow with the following steps to publish items into the new public documents tracker:
    1. Create two new statuses:
      • Update published (meaning Resolved)
      • Published (meaning Resolved)
    2. Add a new status transition from updating the existing published documents:
      • From: Completed
      • To: Update published
      • Name: Publish
      • Actions: Update referring items ► Subject (Documents) ► Public Documents ► Published:
        • Document name: Append | - | Content of | Revision
        • Status: Set to | Value | Superseded
    3. Add another status transition to republish the document:
      • From: Update published
      • To: Published
      • Name: Publish
      • Select Hidden and Automatic
      • Actions: Create new Upstream / Downstream referring items ► Subject (Documents) ► Public Documents
        1. Set all the following fields to Copy fromtheir respective original fields:
          • Document name
          • Document
          • Document version
          • Major version
          • File name
          • Size
          • Description
    4. Add a third status transition, so it is possible to edit published documents:
      • From: Published
      • To: Draft
      • Name: Draft
    5. Save the changes.
      Expected workflow:

Enabling the Document Tracker before codebeamer 22.10-LTS (GINA) Version

In codebeamer versions before the 22.10-LTS (GINA) release, the document tracker must be enabled manually in the application configuration. From codebeamer 22.10-LTS, the feature is enabled by default.

Perform the following steps to enable the feature:

  1. Open the application configuration functionality in the System Admin menu.
  2. Add the following configuration to your existing setup:
    "documentManagement" : {
        "enabled" : true
      }
    
  3. Save the changes.