Notes forms and Notes documents

Sometimes it is good to go back to some basics to explain what Notes and Domino are about. A Notes database is a schema free document store with build in message routing and document level access control mechanism. I'd like to shed some light on the nature of the schema free functionality. A Notes document (technically a note) contains any number of items. There is no need to define possible items. You put an item into a document and it is there. Items have a name, a data type, a sequence (used for replication) and an array of values. That is one of the really strong points in Domino (shared only by Adabas and FileMaker): you don't need to create a master-child table combination, but just store multiple values directly into the document. So a note is conceptually very close to a schema free XML document. The usual way to add an item to a note is to use a form. In a form the developer defines fields (which have a data type, name and rendering properties as well as processing rules: default values, transformation and validation conditions) that get mapped by name onto items. Note the difference: in a form we have fields, in the document (note) we have items A Notes form is basically a piece of RichText with fields thrown in. You can create a working form without the need for any buttons and actions, just throw in some fields and text around them and you are done. The Notes client's default function allow to open, save and close a form. When you open a form and save it a notes document is created with one item for every field in the form. Fields without content result in items with empty values.

In addition some system fields (e.g. for the user saving the form $UpdatedBy) and the field Form containing the form used to create this document is saved. The form field is the only link between the form and the document (If the form has an alias, the alias name is used - handy since different forms can share the same alias. That link can be altered.There is a standard menu option View - Switch Form... that one can use to show the same document using a different form. When a user switches the form no changes are made to the document (until saved). Fields matching existing items in name are populated with the existing item values, new fields are populated with default values if default values have been defined. That is sometimes puzzling for users since you can switch forms also in read mode and missing fields show values that are not saved back into the document. When the form is saved new and changed fields are saved back to the document. Items that have no matching fields are left as they are, they are *not* removed (the same is true if you redesign a form: it doesn't change any item in a document)



So you happily add new information into the document using a new form. What is very important here: the match between item and field is by name only. If different forms have items of the same name but different data types you will have interesting results. E.g. in one form you have a field Status as test and it contains the value "1". In another form you have the same field name but the data type Number. When you switch form the status is displayed correctly. If you don't save the document the value stays "1", but when you save it it turns into 1. The reason is that field display and entry is always text, the data type matching is done on refresh - which happens on F9 or before save is executed. So when a form loads an item into a field the item text is loaded without conversion. Try that example with "New" as value for the status field and you will understand. So a flow could look like this:

Of course View - Switch Form is just one way to alter the form. An agent or an action could update the form field or a view form formula could overwrite the form to be used when opening a document in a specific view. I like that function a lot an e.g. a purchase order could look different depending on the view it is opened with: one for the buyer, one for the controller (who wouldn't care for the detailed specs, but for all financial only). It is a very economic way for role based display.
Since the form field is the only link between form and document, one is free to use other means (read agents/actions) to update items (including removing them). So you can end up with a document, that carries a certain form name but has more or less items than the corresponding form.

So you never can be fully certain what's in a document. The old movie truth applies: "With great powers come great responsibility".