FolderReferences – Which folder is a document in?

Table of Contents

1. Introduction 2. Why bother? Use cases 3. Initial configuration 3.1 Views $FolderInfo and $FolderRefInfo 3.2 Enabling FolderReferences 4. Setting FolderReferences retroactively 5. Practical work with FolderReferences 5.1 Display folders of the current document 5.2 View "Document" | "Folder"5.2.1 Example for an agent or an action button 5.2.2 Postsave script for new documents 5.2.3 Creating a view 5.2.4 Refresh button for the view 5.3 Restoring the documents 5.4 Further helpful scripts 5.4.1 Delete all folders of a database 6. Implementing the example scripts 7. Known issues

1. Introduction

When documents are moved into folders, it is initially not possible to see from within the document itself which folder it resides in.

Since R5, however, there is the FolderReferences property, which makes it possible to find out, for example, which document is located in which folder. The corresponding folder references are automatically written into fields of the document as soon as the document is placed in a folder.

2. Why bother? Use cases

Template update or other modifications to the mail fileIn the past, unfortunately, many administrators have experienced during a release change (which, among other things, involves a change of the mail file template) that documents that were previously neatly filed in folders suddenly "disappeared" and were only visible in the $All view.

Merging multiple (mail) databases into onePreviously, it was very laborious to transfer, for example, the documents from mail file A into mail file B in a structured way. Here, too, FolderReferences can provide valuable services.

Safety through recoverabilityFor example, non-reproducible errors can occur in which documents suddenly no longer appear in the folders. Here too, it is possible to restore everything with a mouse click.

3. Initial configuration

3.1 Views $FolderInfo and $FolderRefInfo

In principle, 'Folder References' is possible in any database from R5 onwards. However, two hidden views from the R5 or R6 mail template are required for this:


$FolderInfo
$FolderRefInfo

These views must be copied into the database in which 'Folder References' is to be used.

3.2 Enabling FolderReferences

FolderReferences are disabled by default. Activation in a database must be done via LotusScript; there is no database option with which you can enable FolderReferences by mouse click!

Here is an example script that you can include, for instance, in an action button:


Sub Click(Source As Button)
  Dim session As New NotesSession
  Dim db As NotesDatabase
  Set db = session.CurrentDatabase
  If db.FolderReferencesEnabled Then
    If Messagebox ("Folder References are enabled." & Chr(10) & Chr(10) _
      & "Do you want to disable the Folder References?" ,1 + 32,db.title) = 1 Then
      db.FolderReferencesEnabled = False
      Messagebox "Disabled Folder References now.....", 64, db.title
    Else
      Exit Sub
    End If
  Else
    If Messagebox ("Folder References are disabled." & Chr(10) & Chr(10) _
       & "Do you want to enable the Folder References?" ,1 + 32,db.title) = 1 Then
       db.FolderReferencesEnabled = True
       Messagebox "Enabled Folder References now.....", 64, db.title
    End If
  End If
End Sub

Another option would be to place "db.FolderReferencesEnabled = True" generally in the Postopen event of the database, or to create the following If-query:


Sub Click(Source As Button)
  Dim session As New NotesSession
  Dim db As NotesDatabase
  Set db = session.CurrentDatabase
  If db.FolderReferencesEnabled Then
    Exit Sub
    db.FolderReferencesEnabled = True
  End If
End Sub

4. Setting FolderReferences retroactively

On the internet, the opinion is often mistakenly held that it is not possible to set the Folder References retroactively.

Here is an example script that you can include, for instance, in an action button:


Sub Click(Source As Button)
  Dim session As New NotesSession
  Dim db As NotesDatabase
  Dim vec As NotesViewEntryCollection
  Set db = session.CurrentDatabase
  If Not Messagebox ("Do you really want to create references of all docs in all folders?",1+32, db.title) = 1 Then
    Exit Sub
  End If

  If Not db.FolderReferencesEnabled Then
    db.FolderReferencesEnabled = True
  End If

  Forall v In db.Views
    If v.isFolder Then
      Set vec = v.AllEntries
      Call vec.PutAllInFolder( v.Name )
    End If
  End Forall

  Messagebox „Folder References are created…“, 64, db.title
End Sub

Speed:

With a mail file containing 240 folders and 182,000 documents: 22 minutes.

The test was performed by Eknori on a server:

Client 6.5 de on a laptop with P4 3.2GHz / 768 MB RAM

Server 6.5 en on P4 3.2 GHz / 2 GB RAM

Fiber optic network 1 GBit

5. Practical work with FolderReferences

5.1 Display folders of the current document

Here is an example script for an action button in a view or a folder. It displays, in a message box, in which folders the selected document is located:


Sub Click(Source As Button)
  Dim session As New NotesSession
  Dim db As NotesDatabase
  Dim collection As NotesDocumentCollection
  Dim doc As NotesDocument
  Dim szReference As String

  Set db = session.CurrentDatabase
  Set collection = db.UnprocessedDocuments
  Set doc = collection.GetFirstDocument

  Forall r In doc.FolderReferences
    If r = "" Then Goto Empty
    szReference = r & Chr(10) & szReference
  End Forall

  While Not (doc Is Nothing)
    Msgbox "Folder References: " & Chr(10) & Chr(10) & szReference, 64, db.title
    Set doc = collection.GetNextDocument(doc) 'Next document
  Wend
  Exit Sub

  Empty:
  Msgbox „No References in this document….“, 64, db.title
End Sub

5.2 View "Document" | "Folder"

Displaying FolderReferences in a view is unfortunately not possible without preparation, since @DBLookups etc. are not allowed in views.

Therefore, the folder names must first be written into a separate field in the respective documents (in the example below, the field "FolderName" was chosen).

5.2.1 Example for an agent or an action button


Dim session As New notessession
Dim db As NotesDatabase
Dim dc As NotesDocumentCollection
Dim doc As NotesDocument

Set db = session.CurrentDatabase
Set dc = db.allDocuments
Set doc = dc.GetFirstDocument
Do While Not doc Is Nothing
  If Not doc.FolderReferences(0) = "" Then
    doc.FolderName = doc.FolderReferences
    Call doc.save (False,False)
  End If
  Set doc = dc.GetNextDocument(doc)
Loop

5.2.2 Postsave script for new documents


Dim session As New notessession
Dim db As NotesDatabase
Dim uiws As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Dim newuidoc As NotesUIDocument
Dim session As New NotesSession
Dim db As NotesDatabase
Dim doc As NotesDocument

Set db = session.CurrentDatabase
Set uidoc = uiws.CurrentDocument
Set doc = uidoc.Document
If Not doc.FolderReferences(0) = "" Then
  doc.FolderName = doc.FolderReferences
  Call doc.save (False,False)
End if

5.2.3 Creating a view

Create a new view with 2 columns:

Column

e.g. Subject, sorted ascending

Column

FOLDERNAME (multi-value separator: New line),

view properties: Lines per row: 9

5.2.4 Refresh button for the view


Sub Click(Source As Button)
  Dim uiws As New NotesUIWorkspace
  Dim session As New notessession
  Set db = session.CurrentDatabase
  Set dc = db.allDocuments
  Set doc = dc.GetFirstDocument
  Do While Not doc Is Nothing
    If Not doc.FolderReferences(0) = „“ Then
      doc.FolderName = doc.FolderReferences
      Call doc.save (False,False)
    End If
    Set doc = dc.GetNextDocument(doc)
  Loop
  Call uiws.ViewRefresh
End Sub

ATTENTION: This refresh button is not a dream solution, as all documents are updated, which can take several minutes!

5.3 Restoring the documents

The following example script restores all documents back into their corresponding folders. If the folder does not exist, it is created. A prerequisite before executing the script is that the original folders are stored in the array field "FolderName".


Sub Click(Source As Button)
  Dim session As New NotesSession
  Dim db As NotesDatabase
  Dim collection As NotesDocumentCollection
  Dim doc As NotesDocument
  Dim item As NotesItem

  Set db = session.CurrentDatabase
  Set collection = db.AllDocuments
  If Not Messagebox ("Do you really want to restore all documents?", 1+32, db.title) = 1 Then Exit Sub
    Set doc = collection.GetFirstDocument()
    While Not (doc Is Nothing)
      If Not doc.FolderName(0) = "" Then
        Set item = doc.GetFirstItem( "FolderName" )
        Forall v In item.Values
          Call doc.PutInFolder (v, True)
        End Forall
      End If
      Set doc = collection.GetNextDocument(doc)
    Wend
  Messagebox "Documents have been restored", 64, db.title
End Sub

5.4 Further helpful scripts

5.4.1 Delete all folders of a database

The following example script, which you can include, for instance, in an action button, deletes all folders in a database:


Sub Click(Source As Button)
  Dim session As New NotesSession
  Dim db As NotesDatabase
  Dim view As NotesView

  Set db = session.CurrentDatabase
  If Not Messagebox ("Do you really want to delete all folders in this database?", 1+32, db.title) = 1 Then Exit Sub
    Forall v In db.Views
      If v.isFolder Then
        Set view = v
        Call view.Remove
      End If
    End Forall
  Messagebox "Folders have been deleted now.", 64, db.title
End Sub

ATTENTION: Here really ALL folders are deleted, so for example the $Inbox in the mail file as well!

6. Implementing the example scripts

Now we come to what is probably the most interesting part of this write-up.

I'll take an example that is likely to occur quite often:

Due to a release change, the mail file templates are being updated. However, the administrator wants to take all precautions – should something go wrong during the template update, all folders could potentially be 'destroyed' or the documents would no longer be in the folders.

As preparation, the admin can therefore run the following scripts:

Retroactively setting the folder references (see section 4)

Writing the folder names into the field "FolderName" (see 5.2.1)

Disable folder references and delete the items "$FolderRef", "$FolderRefFlags" and "$FolderRefID"

Now the template update can be performed without risk. All folder names are stored in the "FolderName" field of the individual documents.

Final step:

Restoring the documents (see 5.3)

7. Known issues

When FolderReferences is enabled, documents are placed in folders, and these folders are then deleted, the FolderReferences (which are IDs) remain in the documents – however, if you try to query the folders via doc.FolderReferences, you get the error message "Document has been deleted". I explain this to myself by the fact that the folder no longer exists.

Therefore, in my opinion, especially in the mail file, where folders are used a lot, appropriate precautions should be taken. Personally, I do not recommend enabling Folder References by default. Rather, I would use them as a backup and restore function (see chapter 6).

Many thanks for this tip to:

Matthias (TMC)

eMail: atnotes@gmx.de

Amazon Affiliate Link