GetDocumentByKey method

Finds a document based on its column values within a view. You create an array of strings (keys), where each key corresponds to a value in a sorted and categorized column in the view. The method returns the first document whose column values match each key in the array.

Defined in
NotesView

Syntax
Set notesDocument = notesView.GetDocumentByKey( keyArray [ , exact ] )

Parameters
keyArray exact
Return value
notesDocument
Usage
If you specify a single key, the key can correspond to a value in a sorted column that is either categorized or not categorized. If you specify multiple keys, each key must correspond to a value in a sorted column that is also categorized.
This method returns only the first document whose column values match the strings you indicate. To locate all matching documents, use GetAllDocumentsByKey, or use this method followed by a GetNextDocument loop.

Examples
1. This script gets the first document in the first category that begins with "Spanish" in the By Category view of the current database.

Dim session As New NotesSession
Dim db As NotesDatabase
Dim view As NotesView
Dim doc As NotesDocument
Set db = session.CurrentDatabase
Set view = db.GetView( "By Category" )
Set doc = view.GetDocumentByKey( "Spanish" )

2. This script gets the first document in the category "Spanish leather" in the By Category view of the current database. The name of the category must be exactly "Spanish leather" except for case.

Dim session As New NotesSession
Dim db As NotesDatabase
Dim view As NotesView
Dim doc As NotesDocument
Set db = session.CurrentDatabase
Set view = db.GetView( "By Category" )
Set doc = view.GetDocumentByKey( "Spanish leather", True )

3. This script examines the By Category and Author view of the current database, which categorizes documents by category and, within each category, by author. The script gets the first document in the Expense Report category whose author is Robson Da Silva.

Dim session As New NotesSession
Dim db As NotesDatabase
Dim view As NotesView
Dim keys( 1 To 2 ) As String
Dim doc As NotesDocument
Set db = session.CurrentDatabase
Set view = db.GetView( "By Category and Author" )
keys( 1 ) = "Expense Report"
keys( 2 ) = "Robson Da Silva"
Set doc = view.GetDocumentByKey( keys )

4. This field script gets a user's full name from a field on the current document, parses the full name to find the last name, and then uses GetDocumentByKey to find the user's office phone number in the People view of the Address Book on the current machine. It places the phone number into the Phone field on the current document.

Sub Exiting(Source As Field)
Dim workspace As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Dim fullName As String
Dim lastName As String
Dim db As NotesDatabase
Dim view As NotesView
Dim doc As NotesDocument
' first parse the full name to find the last name
Set uidoc = workspace.CurrentDocument
fullName = uidoc.FieldGetText( "Name" )
lastName = Mid$( fullName, (Instr( fullName, " ") + 1 ))
' now use the last name as the key
Set db = New NotesDatabase( "", "names.nsf" )
Set view = db.GetView( "People" )
Set doc = view.GetDocumentByKey( lastName )
Call uidoc.FieldSetText _
( "Phone", doc.OfficePhoneNumber( 0 ) )
End Sub

5. (See GetAllDocumentsByKey for an easier way to do this. The only advantage to this technique is that it correctly sets the ColumnValues property in the retrieved documents while GetAllDocumentsByKey does not.) This script gets all of the documents in the category "Spanish leather" in the By Category view of the current database, and puts them in the Boots folder. The script finds the first document in the category using GetDocumentByKey, and the remaining documents in the category using GetNextDocument. The script uses the ColumnValues property in NotesDocument to check each document's column values: as long as a document's value for the first sorted column in the view equals "Spanish leather," the script places the document in the Boots folder. If the document's value for the first sorted and categorized column does not equal "Spanish leather," or if there are no more documents in the view, the script ends.

Dim session As New NotesSession
Dim db As NotesDatabase
Dim view As NotesView
Dim column As NotesViewColumn
Dim doc As NotesDocument
Set db = session.CurrentDatabase
Set view = db.GetView( "By Category" )
' get the first sorted and categorized column in the view
Forall c In view.Columns
If ( c.IsSorted And c.IsCategory ) Then
Set column = c
Exit Forall
End If
End Forall
' get the first document that matches the key
Set doc = view.GetDocumentByKey( "Spanish leather" )
' get the remaining documents that match the key
' since ColumnValues array starts at 0 for position 1,
' subtract 1 from the column position
Do While Not ( doc Is Nothing )
If ( doc.ColumnValues( column.Position - 1 ) = _
"Spanish leather" ) Then
Call doc.PutInFolder( "Boots" )
Else
Exit Do
End If
Set doc = view.GetNextDocument( doc )
Loop

Related topics
ColumnValues property in NotesDocument
GetAllDocumentsByKey method
GetNextDocument method
IsCategory property in NotesViewColumn
IsSorted property in NotesViewColumn
NotesDocument class
NotesViewColumn class