COMOS Document Reference Linking: Step-by-Step Guide

Overview

Siemens COMOS is an object-oriented plant engineering platform in which every document shown in the project navigator is, in fact, a container object that points to a physical file on a disk. The COMOS database stores the metadata (name, owner, status, attributes, revision history); the actual PDF, DWG, DOCX, or any other binary payload lives as a real file under a configured base directory. This two-layer model is the source of a very common confusion: a user opens two COMOS documents that look identical and assumes COMOS has stored two copies. It has not. It has stored one physical file plus two container references.

This separation is also the key to a deliberate deduplication workflow. If test.pdf must be available both in a project-wide General Documentation folder and inside a specific Engineering Unit, the correct approach is to create two COMOS documents that share the same physical file. This article walks through three reliable methods to do exactly that:

1. Manual drag-and-drop with the As reference option.
2. Verification of the shared file path using the built-in Object Debugger.
3. Script-based bulk creation of references using the COMOS COM API and the CPLTDocument class.

All three methods are valid in COMOS 9.x and COMOS 10.x; the COM object model and the Extra > Object Debugger tool have remained stable across these releases. Specific UI labels may differ slightly between localised builds; consult the integrated COMOS help (F1) for your installed language pack.

COMOS Document Model: Container vs Physical File

Every document you see in COMOS is a logical entity of class CPLTDocument (or one of its derived classes for specific document types such as datasheets, loop sheets, or P&ID references). The class hierarchy is exposed in the COM API and the .NET wrapper. The class exposes, among others, the following properties:

The key insight is that a COMOS document is always only a container. The file itself is always in a directory on the COMOS file server. Therefore, two containers can coexist, one in General Documentation and one in the Engineering Unit, both pointing to \\fileserver\comos\proj\...\test.pdf. Editing the file through either container overwrites the same physical file; both containers will reflect the new revision the next time they are opened.

Prerequisites

Before configuring cross-unit document references, verify the following:

• COMOS client version: 9.0 SP3 or newer, or 10.0 / 10.1 / 10.2 / 10.3. The Object Debugger is available in all of these.
• Database connection: A working connection to the COMOS project database (SQL Server or Oracle, depending on deployment).
• Write permissions on the file server: The COMOS service account must have read/write access to the configured base document directory.
• Write permissions on the project: Your COMOS user must be a member of a role that includes the Edit documents and Create documents rights for both the source owner and the target owner.
• Optional for the script method: The COMOS script runtime (installed by default) and a working knowledge of VBScript or JScript syntax in COMOS.

Method 1: Manual Drag-and-Drop with "As Reference"

This is the simplest method and works for ad-hoc linking of a single document.

1. In the COMOS navigator, expand the General Documentation folder and locate the source document (for example, test.pdf).
2. Open Windows Explorer in a separate window and navigate to the same document on the COMOS file server. Note the path; you will need it to confirm that the reference succeeded.
3. In the COMOS navigator, expand the destination Engineering Unit where the reference should appear.
4. Drag the COMOS document from General Documentation directly onto the Engineering Unit in the navigator. Do not drag the file from Windows Explorer; you must drag the COMOS document object.
5. When you release the mouse button, COMOS displays the import dialog with two options: As copy and As reference.
6. Select As reference and click OK.
7. COMOS creates a new container document under the Engineering Unit. The container's Reference property is set to True.

To confirm visually, open both documents. The title bar of the COMOS document viewer should show the same underlying file path on both containers. If you used As copy by accident, the two paths will differ and you will have created a second physical file. Delete the wrong container and repeat the drag with As reference.

Method 2: Verifying Shared Files with Object Debugger

The Object Debugger is COMOS's built-in interactive shell for inspecting and manipulating live COMOS objects. It is reachable from the menu Extra > Object Debugger and is invaluable for confirming that two containers truly share the same file.

1. Open Extra > Object Debugger.
2. Drag the first COMOS document (for example, the one in General Documentation) from the navigator into Field A of the debugger. The debugger now holds a reference to that object.
3. In the Expression text box, type a.FullFileName and press Evaluate.
4. The debugger returns the absolute path of the underlying physical file. Copy this value to the clipboard.
5. Click Clear to drop the reference to field A.
6. Drag the second COMOS document (the one you just created in the Engineering Unit) into Field A.
7. Repeat the a.FullFileName evaluation.

If both evaluations return the identical absolute path, the two containers are referencing the same physical file. If they return different paths, you accidentally created a copy. Delete the duplicate and re-do the drag with As reference.

The Object Debugger also accepts a wider range of expressions. Useful follow-up diagnostics include:

• a.Owner.Name — the parent unit or folder of the document.
• — returns True if the document was imported with As reference.
• a.Status — numeric lifecycle status code.
• a.Documents.Count — number of child documents (zero in most cases, but useful when iterating units).

Method 3: Script-Based Reference Creation

For bulk operations, the manual drag-and-drop is too slow. The COMOS script engine can iterate the source collection and create a matching reference document on each target owner. The script below is written in VBScript, the language most commonly used inside COMOS attribute tabs and the Object Debugger.

Script: Create one reference document on a target owner

' Source: existing COMOS document in General Documentation
' Target: the unit that should also display the document
' Run from Object Debugger with source in field A, target in field B

Dim objSourceDoc
Dim objTargetOwner
Dim objNewDoc

Set objSourceDoc   = a   ' field A: source CPLTDocument
Set objTargetOwner = b   ' field B: target CPLTUnit or folder

Set objNewDoc = objTargetOwner.Documents.Create("CPLTDocument")

' Assign the next free document name under the target owner
objNewDoc.Name = objTargetOwner.Documents.NextName("")

' Re-use the same physical file by pointing FullFileName at the source path
objNewDoc.FullFileName = objSourceDoc.FullFileName
objNewDoc.Reference    = True

objNewDoc.Save

Set objNewDoc       = Nothing
Set objTargetOwner  = Nothing
Set objSourceDoc    = Nothing

Script: Bulk-create references on every unit that uses the source

The following variant iterates a collection of target units and creates a reference document on each. Replace colTargetOwners with the actual collection object you have built from your project query.

Dim objSourceDoc
Dim objTargetOwner
Dim objNewDoc
Dim i

Set objSourceDoc = a   ' source document

For i = 1 To colTargetOwners.Count
    Set objTargetOwner = colTargetOwners.Item(i)

    ' Skip the original owner to avoid creating a duplicate of the source
    If objTargetOwner.SystemFullName <> objSourceDoc.Owner.SystemFullName Then
        Set objNewDoc = objTargetOwner.Documents.Create("CPLTDocument")
        objNewDoc.Name         = objTargetOwner.Documents.NextName("")
        objNewDoc.FullFileName = objSourceDoc.FullFileName
        objNewDoc.Reference    = True
        objNewDoc.Save
        Set objNewDoc = Nothing
    End If
Next

Set objTargetOwner = Nothing
Set objSourceDoc   = Nothing

Running the script

1. Open Extra > Object Debugger.
2. Drag the source document into Field A.
3. If you are running the bulk variant, drag a CPLTUnits collection into Field B.
4. Paste the script into the code pane and click Run.
5. For an even more user-friendly interface, paste the script into an attribute tab on the source document. The attribute tab then exposes a button that any authorised user can click without opening the Object Debugger.

CPLTDocument Type Error and Resolution

A very common runtime error when running the script for the first time is:

Error: The object has a wrong type. Expected: CPLTDocument
Location: line that sets objNewDoc.Name (or any line that touches objNewDoc)

The error message is raised on the first line that tries to use objNewDoc, but the root cause is usually one line earlier: the Create call did not return a CPLTDocument. There are two frequent causes.

Cause 1: An extra .CObject on the source or target

Beginners sometimes write a.CObject.FullFileName or b.CObject.Documents.Create(...). The .CObject property unwraps the COMOS wrapper to the underlying COM object, but the underlying object does not expose FullFileName, Documents, or the Reference flag in the way the COMOS wrapper does. Delete every .CObject from your script. Use the COMOS-wrapped object directly.

Cause 2: The Create call returned the wrong derived class

If the target owner is configured with a custom document class in its project template (for example, CPLTDocumentUnit or a project-specific subclass), the default Create("CPLTDocument") can return an instance of the project class, which is not directly assignable to a variable typed as CPLTDocument. There are two fixes:

1. Pass the project class name explicitly: objTargetOwner.Documents.Create("CPLTDocumentUnit").
2. Or declare the variable as Object and let late binding handle the type: Dim objNewDoc with no As clause.

Diagnostic: confirm the returned class

After the Create call, run objNewDoc.ClassName in the Object Debugger. The string returned is the actual runtime class. If it differs from CPLTDocument, adjust the Create argument accordingly.

Best Practices for Cross-Unit Document Sharing

• Pick a single canonical owner. Designate one folder (for example, General Documentation) as the owner of the physical file. All other units should hold As reference containers only. This avoids the situation where two containers are both treated as authoritative sources.
• Lock down write access to the canonical owner. Users who need to update the file should do so through the canonical owner. The reference containers can be opened in read-only mode if the project template supports it.
• Use meaningful container names. The COMOS document name does not have to match the file name. Name the reference P&ID-General-test in the engineering unit and leave the file name as test.pdf. This makes the navigator easier to scan.
• Document the link in a navigator note. Add a custom attribute on the reference container that stores the SystemFullName of the source. This provides a quick "go to origin" function without depending on the built-in Reference flag alone.
• Audit periodically. The Object Debugger expression a.Reference lets you enumerate all containers in a unit and identify any that are not references but should be.
• Avoid mixing references and copies across project phases. If a project moves from FEED to EPC, regenerate the references to point at the new phase's canonical owner. Do not assume old references will follow the file.

Troubleshooting Matrix

Verification Checklist

After you have created a reference, run through the following checks before handing the work back to the project team:

1. Open both containers and confirm that the title bar shows the same physical file path.
2. In the Object Debugger, run a.FullFileName on both and compare the strings character by character.
3. Open the file from the reference container, make a small change (for example, a comment annotation in a PDF), save, and confirm that opening the canonical owner shows the same change.
4. Run a.Reference on the reference container; it should return True.
5. Verify the file count on the file server. If the number of .pdf files did not increase, the reference is genuine.

Frequently Asked Questions