Design Applications Based on Design Element IDs: UNID and NOTEID

Notes/Domino documents are the fundamental storage units of a Domino database, and they are roughly analogous to records in a relational database. Like a record, a document is the container that holds logically related fields, such as contact information. Unlike records in a relational database, though, documents have a very loose structure and can be changed on the fly if you use either different forms to save the document or programs that add or delete items from the document. Although this open-ended architecture may seem like a convoluted and confusing methodology, it gives developers unparalleled flexibility.

Normally, a document is created when a user opens a form and saves his or her work. It is at this point that the document's structure is defined by the form that was used to create it. Each Editable, Computed, or Computed When Composed field on the form is saved as an item in the document. Additionally, an item with the name of “Form” is added to the document, and the name of the form that used to save the document is stored in this field. When the document is opened again, the Form item is used to determine which form should be used, and the underlying item values populate the fields on the form that has corresponding names. If a field has been deleted from the form, it still exists in the document—it just isn't displayed. If a different form is used to edit the document, new items may be added to the document.

When a new document is created in a database, it is assigned a NoteID and a Universal ID (also known as the UNID). Each of these values is used by Domino to identify the document. Additionally, you can access and use these values from your programs to identify and access documents.

A document's NoteID is an 8-character combination of hexadecimal values (0–9, A–F), which uniquely identifies the document within a given database. It typically looks something like 50BE. (This is what this chapter was stored in while the book was being written.) Understanding the NoteID is important because many copies of a document may exist across replica databases but each has a unique Note ID. After a Note ID has been generated, it does not change and can be used programmatically to access documents.

You can use a document's NoteID to access it by calling the GetDocumentByID method of the NotesDatabase class and passing the NoteID as a string value. The following example illustrates this process:

Dim ns As New notesSession
Dim ndbCurrent As notesDatabase
Dim ndocCurrent As notesDocument
Dim strNoteID as String
strNoteID="1A8E"
Set ndbCurrent=ns.CurrentDatabase
Set ndocCurrent=ndbCurrent.GetDocumentByID(strNoteID)

The following is a very simple program that can be added as an agent to get the NoteID of any selected document. It is displayed in an InputBox so that you can copy the NoteID and paste it if necessary.

Dim ns As New notesSession
Dim ndbCurrent As notesDatabase
Dim ndcUnprocessed As notesDocumentCollection
Dim ndocCurrent As notesDocument
Dim strTemp As String
Set ndbCurrent=ns.CurrentDatabase
Set ndcUnprocessed=ndbCurrent.UnprocessedDocuments
Set ndocCurrent=ndcUnprocessed.GetFirstDocument
strTemp=Inputbox( "NoteID=", "NoteID", ndocCurrent.NoteID)

A document's Universal ID is a 32-character combination of hexadecimal values (0–9, A–F) that uniquely identifies a document across all replicas of a database. For example, the Universal ID of the Notes document used to store this chapter is “0385294991E17D93852568FA00668B2F.” If a database has replica copies, the same document in each replica database has a completely unique NoteID, but they will all have duplicate Universal IDs. Or in other words, if two documents have the same Universal ID, they are replicas.

Be sure to understand the differences between the NoteID and the Universal ID, how they are stored in the document, and how they are replicated between databases.

As with NoteID, you can access documents by their Universal IDs by calling the GetDocumentByUNID method of the NotesDatabase class and passing the Universal ID as a string value. The following example illustrates this process:

Dim ns As New notesSession
Dim ndbCurrent As notesDatabase
Dim ndocCurrent As notesDocument
Dim strUNID as String
strUNID="6A6C0A6E10F64338852568B400661A12"
Set ndbCurrent=ns.CurrentDatabase
Set ndocCurrent=ndbCurrent.GetDocumentByID(strUNID)

The following code demonstrates how you can get the Universal ID of any selected document. It is displayed in an Input Box so that you can copy the UNID and paste it if necessary.

Dim ns As New notesSession
Dim ndbCurrent As notesDatabase
Dim ndcUnprocessed As notesDocumentCollection
Dim ndocCurrent As notesDocument
Dim strTemp As String
Set ndbCurrent=ns.CurrentDatabase
Set ndcUnprocessed=ndbCurrent.UnprocessedDocuments
Set ndocCurrent=ndcUnprocessed.GetFirstDocument
strTemp=Inputbox( "UNID=", "UNID", ndocCurrent.UniversalID)

Notes documents are the fundamental data storage units in a Notes database (they are roughly analogous to records in a relational database), and each document is assigned a unique identifier known as the NoteID. As mentioned earlier, the NoteID is an 8-character hexadecimal value that serves as a unique document identifier within a given database. This means that replica copies of a document in different databases have different NoteIDs. An example of a NoteID is 50BE.

Because each document in a database has a NoteID and Notes/Domino exposes it programmatically to formulas, LotusScript, and Java, the NoteID can be used in your applications to provide a unique system-level key to access documents. One common way this is done is to use the GetDocumentbyID method of NotesDatabase to access documents without using a view.

Table 8.1 illustrates some of the most common ways you can work with the NoteID programmatically.

As you know, Notes documents are the fundamental data storage units in a Notes database. (They are roughly analogous to records in a relational database.) Each document database is assigned a universal identifier known as the document's Universal ID.

Because each document in a database has a UNID and Notes/Domino exposes the UNID programmatically to formulas, LotusScript, and Java, it can be used in your applications to provide a unique system-level key to access documents. It is fairly common for developers to create a view with a sorted column containing the UNID of all documents, which programs then use to look up documents by their UNID. Another approach is to use the GetDocumentbyUNID method of NotesDatabase to access documents without using a view.

Additionally, when an application uses response documents, each response document automatically inherits the UNID of the parent in a field called $Ref. You can access the UNID of the parent document quickly and easily access the parent document. Table 8.2 illustrates some of the most common ways you can work with the UNID programmatically.