9780764526114 chapter 6 managing and deploying applicatio

Lotus Notes and Domino 6 Programming Bibleby Brian Benz, Rocky Oliver and Richard SchwartzWiley Publishing, Inc.. (c) 2003. Copying Prohibited.

Reprinted for Satyendra K. Jha, [email protected]

Reprinted with permission as a subscription benefit of Books24x7,http://www.books24x7.com/

All rights reserved. Reproduction and/or distribution in whole or in part inelectronic,paper or other forms without written permission is prohibited.

http://www.books24x7.com/

Table of Contents Chapter 6: Managing and Deploying Application Projects..........................................................1

Projects, Applications, and Databases..................................................................................1Understanding applications..............................................................................................1Understanding projects....................................................................................................1

Templates..............................................................................................................................2Template files...................................................................................................................2Template names..............................................................................................................3Design inheritance...........................................................................................................5

Multidatabase Projects...........................................................................................................7Multiple design inheritance...............................................................................................8

Working on a Development Team.......................................................................................10Application Deployment.......................................................................................................12Summary..............................................................................................................................13

i

Chapter 6: Managing and Deploying ApplicationProjectsBy Richard Schwartz

Most programmers are used to working with a development environment that organizes projectscontaining source files, object files, and executable files. Programmers who work with the Notes Cand C++ APIs do work this way, but most Notes and Domino development doesn't use those tools.So, for the most part, source files, executables, and separate data files or database systems areforeign concepts to Notes and Domino programmers. This chapter explains the concepts that Notesand Domino work with to organize projects and deploy applications.

Projects, Applications, and DatabasesNo consistent terminology exists for describing a unit of work in a Notes and Domino environment.The words application and database are sometimes interchangeable, and sometimes not, and theword project has a variety of meanings. This is somewhat unfortunate, but it really is unavoidable.It's also not unique to Notes and Domino. The following sections try to eliminate some of theconfusion surrounding these terms.

Understanding applications

Chapter 3 described the NSF file as a container for both the data and the code of a Notes andDomino application. Notes and Domino programmers often use the words database and applicationinterchangeably, and in most cases, a Notes or Domino application consists of just a single NSFfile. But this is not always the case. An application is a solution to some process or problem that iscomprised of one or more databases. A database is a single NSF file that contains data and codethat performs work. So in this and other chapters, the word application is used to refer to somesolution that is one or more databases, and a database is a single NSF file.

The fact that Notes and Domino applications store code in NSF files implies that multiple NSF filesmight be involved in one application. Just as complex applications built in traditional programminglanguages, such as C or BASIC, sometimes spread their code across multiple EXE and DLL files,Notes and Domino applications sometimes spread their code across multiple NSF files, with eachfile containing code that provides a portion of the application's functionality — and usually that NSFfile also stores the data used by that portion of the applications' code.

The fact that Notes and Domino applications store data in NSF files implies that one NSF file mightalso be used in multiple applications. Application designers usually don't want to store duplicatecopies of the same data, because it can be very hard to ensure that all copies are kept in synch.Many applications built with the traditional tools share use of a data file or SQL table. Notes andDomino developers share information by using a common NSF file to store data that is shared bymore than one application.

Understanding projects

Because this chapter is supposed to be about projects, it would probably be helpful to define whatthe word project means. In most traditional application development environments, a project is acollection of source files that are grouped together so that automated tools can be used to build oneor more software components — and a component can be a complete application, an executableprogram, or a library of code used by executable programs. Domino Designer, however, does notprovide tools for organizing files into projects this way, so there is no single definition of project thatall Notes and Domino programmers agree upon.

For the purposes in this book, a project is a group of one or more related application features, eitherfor a single application or for a group of related applications, programmed in one or more designelements in one or more NSF files. Although this is a general definition, it can still be useful. ADomino project might be a new application, a set of new applications, a set of new features for anexisting application, or a set of new features shared by many applications. Domino projects can be

Reprinted for [email protected], IBM John Wiley & Sons (US), Wiley Publishing, Inc. (c) 2003, Copying Prohibited

http://www.books24x7.com//viewer.asp?bkid=6059&destid=60#60

developed directly in the database(s) that are used by the users, but it is a better developmenttechnique to perform your development in templates, and use these templates as a basis for thedatabases that comprise your final application.

TemplatesIt is often the case that an organization wants to deploy several applications that all use the samecode, but have each application maintain its own data. Several different workgroups, for example,may each want their own private application for maintaining employees' weekly status reports.Every NSF file, however, contains code and data, so meeting this common requirement bydeploying an NSF file for each group implies that there will be many copies of the actual code. It isimpractical, of course, to ask a programmer to duplicate code manually whenever a new version ofan application needs to be deployed. It is even more impractical to have a programmer manuallyupdate many copies of the same code in order to implement new features or fix bugs. Notes andDomino programmers use templates to automate these processes.

On TheWeb

A new feature scheduled for inclusion in Notes and Domino 6 was withdrawnshortly before the product shipped allows NSF files to share a single copy oftheir code physically. This feature, known as Single Copy Template, isexpected to be added to Notes and Domino 6 in the first maintenancerelease, which should be known as 6.0.1. When this feature is released, abrief description of it will be added to the ndbible.com Web site.

Template files

Templates are files that have the same internal structure as NSF files, but have names that usuallyend in NTF (but that isn't necessary). Because they have the same internal structure, they are alsocontainers for notes. They are primarily used as containers for Design notes, but they may alsocontain Data notes. For instance, you may have an application that has a centralized keyworddatabase. You have developed the application using templates, and then you create the applicationdatabases from the templates. If you have created the keyword documents in the template versionof the keyword database, they are automatically placed in the corresponding keyword applicationdatabase.

You can choose a template when you create a new database file by choosing File → Database →New from the menu of the Notes client or Domino Designer program. See Figure 6−1, and note thatthe bottom half of the New Database dialog box contains a list of templates that are available on themachine where Domino Designer is running. The combo box labeled Template Server can be usedto choose from a list of templates that are available on any Domino server in the network.

Lotus Notes and Domino 6 Programming Bible 2


http://ndbible.com

Figure 6−1: The template list in the New Database dialog box is used to choose the desiredtemplate.When you select a template in the New Database dialog box, fill in all the fields required for a newNSF file, and click OK, a new NSF file is created. The new database contains copies of all theDesign notes and Data notes in the template file. (The Access Control List (ACL) note is not,however, a copy of the template's ACL. See Chapter 10 for more information about how ACLs fordatabases are created.)

Developers who need to deploy multiple applications that use the same code should always createa template file and use the template to create the database files for the applications.

Template names

Every NSF and NTF file has two names, and an optional third name, used for three differentpurposes. The first name is, of course, the filename used as a unique identifier on the hard drive ofa Notes client or Domino server. The second name is Title, which you set in the New Databasedialog box (as shown earlier) and can be seen or modified on the Database Basics (the leftmost)tab of the Database Properties dialog box (see Figure 6−2).




Figure 6−2: The database titleThe title of an NSF file is shown to users in the Open Database dialog box, accessed by choosingFile → Database → Open in the Notes client or Domino Designer. The names shown in the scrollinglist of templates in the New Database dialog box, as previously shown in Figure 6−1, are the titles ofthe NTF files.

The third name that any NSF or NTF file might have is a Master Template name. You view andmodify this name on the Design tab (the one with a small picture of a t−square and triangle) of theDatabase Properties dialog box (see Figure 6−3).



Figure 6−3: The Master Template propertiesAs you can see in the figure, there is a Database is a Master Template check box and a TemplateName field.

Note The term Master Template is new in Notes and Domino 6. In previous releases, the term thatwas generally used was Design Template.

The Master Template name is used to manage design inheritance, which is described in the nextsection of this chapter. Any NTF or NSF can be designated as a Master Template.

Design inheritance

You can create NSF files from a template, but what happens when the code in the templatechanges? Because the code in the NSF file is a new copy of the code in the template, you need away to resynchronize the copy with the original. Design inheritance is Notes and Domino's solutionto this problem.

Every NSF file can be set to inherit its design from a Master Template. Figure 6−4 shows theDesign tab of the Database Properties dialog box for a database that was created from the MasterTemplate shown in Figure 6−3.



Figure 6−4: Design inheritance propertiesNotice that there is a check box labeled Inherit Design from Master Template followed by a fieldlabeled Template Name. The content of this field is StdR6DocLibMS, which matches the valueshown in the Database is a Master Template field shown in Figure 6−3. The match between thesetwo settings controls inheritance.

You can manage inheritance automatically or manually. Automatic inheritance occurs only fordatabase files that are stored on Domino servers. But replicas of a database that users keep on thehard drive of their workstations or laptops receive design changes from replicas on servers via thenormal client−server replication process, so this restriction does not create problems. Automaticinheritance on servers is managed by the design task, which is normally scheduled to run onservers in the early morning hours.

You can manually initiate design inheritance for any NSF file that inherits from a Master Templateby opening the database in the Notes client or in Domino Designer, and choosing File → Database→ Refresh Design from the menu. A design refresh request does the same thing that theserver−based design task does, but for the one requested database only, — which can be on anyserver, or on the user's local hard drive.

When you initiate a design refresh, the system prompts you for the name of a server to search for amatching template. You can specify Local if the Master Template that you want to use is on yourown PC's hard drive, or the name of any Domino server in your network. The system then searchesthe selected server, looking for any NTF or NSF file that has the Database is a Master Templatebox checked in its properties, with a template name that matches the Inherit Design from MasterTemplate name in the database that you are refreshing. The system then examines every designelement in the database, and determines whether it needs to be refreshed.

Normally, every design element in an NSF is eligible to be refreshed from the database's MasterTemplate, and if there are any differences between the version in the NSF and the one in the



template, the design note from the template overwrites the design note in the NSF. In two cases,however, design elements in an NSF will not be refreshed from the Master Template; these twocases are listed here:

Case one: Any design element can be set with a property that prevents it from ever beingoverwritten by either an automatic or manual design refresh. Figure 6−5 shows the DesignProperties dialog box, which you open by selecting a design element in Domino Designerand choosing Design → Properties from the menu. Notice the Prohibit Design Refresh orReplace to Modify check box. This box should be checked for any design element in an NSFthat you want to disconnect from its Master Template. You can use this feature to prevent acustomization made directly in a design element of an NSF from being automaticallyreplaced with the generic version of the design element from the template.

Figure 6−5: Design element inheritance properties

•

Case two: Design elements can also be set to inherit from an alternate template instead offrom the database's Master Template. You accomplish this in the Design Properties dialogbox. Enter the name of the alternative template into Inherit from Design Template field,which you can see in Figure 6−5 just above the Prohibit Design Refresh or Replace toModify check box.

•

You might use this feature to add one or more common design elements to many applications thatwere created from several different Master Templates. Design replace, and automatic and manualdesign refreshes honor this setting, and search for a database that has the Database is a MasterTemplate box checked and a matching template name.

Multidatabase ProjectsChoosing whether to build a project in one NSF file, or divide it into multiple NSF files is one of thefirst things a Notes or Domino developer has to do when beginning a project. Many factors mightenter into this decision, but the following guidelines can help you make this decision.

Consider using a single NSF file in the following situations:

It is useful to make all documents part of a single response hierarchy.•

All the data stored with the application are unlikely to be useful to any other application.•



All users of the application are likely to need access to all the data.•

Consider using multiple NSF files in the following situations:

The application stores hundreds of thousands of some types of documents, and smallernumbers of other types of documents.

•

Some of the data in the application is of a generic nature and may be useful to otherapplications.

•

Some of the data in the application needs to be accessible only via the Notes client, or onlyvia a browser, and other data needs to be accessible via the Notes client and a browser.

•

There are differing security requirements for subsets of the data within the application. Somedocuments are required to be read−only, while an individual or groups of users edit otherdocuments.

•

Multiple design inheritance

Multidatabase projects are sometimes managed via multiple design inheritance, in which databasesinherit design elements from templates that inherit some of their design elements from othertemplates. An NTF file that is a Master Template file can also inherit some its own design elementsfrom other Master Templates. You can use a chain of multiple design inheritance to create acommon set of features that are shared by all the applications in a project. For example, a projectmight consist of two NSF files: one for employee status reports, and the other for project plans. Bothof these applications may need to support Manager's Comments documents.

Create two template files named Ch6−B−Status.NTF and Ch6−B−Plans.NTF by choosingFile → Database → New from the Domino Designer menu. Fill in the filenames andappropriate titles for each NTF.

1.

Open the Database Properties dialog box, check the Database is a Master Template box onthe Design tab, and type Ch6EmpStatusTemplate and Ch6ProjectPlansTemplate,respectively, in the Template Name field.

2.

Next create another template called Ch6−B−Comments.NTF, in this case without changingthe template selection in the New Database dialog box from its default of None. Open theDatabase Properties dialog box, check Database is a Master Template on the Design tab,and type Ch6MgrCommentsTemplate in the Template Name field.

3.

To set up an inheritance chain for this project, create a form in Ch6−B−Comments.NTF, adda text field called Subject and a rich−text field called Body to the form, and save it asManager Comments | Response.

4.



Cross−Reference The basic steps for creating a form and adding fields to it are covered inChapter 2.

Close the form and copy it from the Forms index, and then paste it into both Ch6−B−Status.NTFand Ch6−B−Plans.NTF. After pasting the form, the dialog box shown in Figure 6−6 appears.

Figure 6−6: The Inheritance dialog boxClicking Yes in this dialog box tells Domino Designer to set the properties for the ManagerComments form so that it is inherited from Ch6MgrCommentsTemplate, as shown in the DesignProperties dialog box (see Figure 6−7).

Figure 6−7: Inheritance of the Manager Comments formIf you make changes to the Manager Comments form in Ch6−B−Feeback.NTF, and then refresh thedesigns of Ch6−B−Status.NTF and Ch6−B−Projeects.NTF, the copies of the Manager Commentsforms in those templates are updated with your changes.




On TheWeb

A set of three files demonstrating this technique can be found on the companion Website at www.wiley.com/compbooks/benz. These files were created using theinstructions from the preceding section.

Working on a Development TeamA great irony of the Notes and Domino world for the past dozen or so years has been the fact thatalthough Notes and Domino are great tools for developing applications that help people collaborate,Domino Designer did not provide much help for programming teams that needed to collaborate. Inpast releases of Notes and Domino, the only way teams of programmers could be sure that two ormore people weren't trying to modify code in the same design element at the same time was todivide applications into multiple template files and assign individual programmers to each of thetemplates. There are other third party tools that helped manage a multi−developer environment, butthere was no clean way to do it in Notes/Domino itself. Notes and Domino 6 finally addresses thisproblem.

New Feature Notes and Domino 6 supports locking for documents and design elements. Designelement locking enables a programmer to claim exclusive rights to edit any designelement in an NSF or NTF file. A master lock server must be designated for the file,and a check box in the Database Properties dialog box must be enabled to activatethis feature.

To set up a project for team development, you need to do the following:

Make replicas of each NTF or NSF file in the project on a server so that all team memberscan access them.

•

Open each NTF or NSF and open the Access Control dialog box by choosing File →Database → Access Control. Click the Advanced tab on the left side of the dialog box,change the Administration Server setting from None to Server, and then fill in the name of aserver in the dialog box, as shown in Figure 6−8.

•



http://www.wiley.com/compbooks/benz

Figure 6−8: Setting the Administration Server for design locking

Open the Database Properties dialog box for each NTF or NSF, click the Design tab, andthen click the check box labeled Allow Design Locking, as shown in Figure 6−9.

•



Figure 6−9: Setting the design locking property

After completing this setup, you can select any design element in the NTF or NSF files, right−click,and select Lock or Unlock. When a design element is locked, other programmers will not be allowedto work with it until either you or someone else with manager access (see Chapter 10) to thedatabase file unlocks it.

You can even set locks on design elements when working with a local replica of the NSF or NTF fileon a laptop that is not connected to any server. In such cases, the lock is created provisionally. It ismade permanent the next time the programmer replicates his laptop with a server. If someone elselocked the design element in the interim, the lock can't be made permanent. The server then sendsan e−mail to the programmer, who needs to wait until the lock is released, and then manuallymerges his changes into the design element.

Tip To minimize the possibility of losing a provisional lock, replicate the NSF or NTF file directlywith the Administration server immediately before and immediately after setting the lock.

Application DeploymentMany organizations have strict procedures for deploying applications to Domino servers. Forexample, some organizations require that programmers submit their applications for testing by aquality assurance team, and then turn them over to system administrators for deployment onservers. There are good reasons for this, mostly having to do with security and operations policy.Programmers are given enormous power over an organization's data and systems. Policies andprocedures that control deployment of new applications and changes to existing applications




establish checks and balances over the power given to programmers. The larger the organization,the greater is the need for these checks and balances in order to keep programmers from(deliberately or accidentally) compromising the security or reliability of critical systems.

Policies and procedures for Notes and Domino application deployment may be quite elaborate, butthe underlying technical requirements are actually simple. Deployment involves the following steps:

Create the NSF files for the application from the template files by choosing File → Database→ New from the menu of the Notes client or Domino Designer. (If you did your developmentwork directly in the NSF files, this would be a good time to create a set of templates bychoosing File → Database → New Copy from the menu and selecting the Database Designonly Option in the Copy Database dialog box.

•

Set up the Access Control Lists for the NSF files. (See Chapter 10 for more informationabout database security.)

•

Replicate the NSF files to a Domino server, or e−mail them to somebody who has thepermissions required to do so.

•

Set up any data in documents that your application's code requires in order to functionproperly.

•

SummaryThis chapter discussed Notes and Domino applications, projects, databases, and templates. Youlearned that

Domino applications can consist of a single NSF file or multiple NSF files.•

Domino Designer does not define a project the way most traditional development tools do.•

Because NSF files are containers for both code and data, it is often the case that anorganization needs to deploy many NSF files containing the same code but different data.

•

Domino programmers can maintain their code in template files.•

Database files can inherit all or part of their design elements from other database filesdesignated as templates.

•

NTF files can inherit parts of their design elements from other NTF files.•

Design elements can be locked and unlocked to coordinate the work of programmers on thesame team.

•

Application deployment technically requires just a few simple steps, but in manyorganizations a formal process must be followed in order to satisfy important policies andprocedures.

•




The next chapter covers the standard templates that ship with Notes and Domino.




9780764526114 chapter 6 managing and deploying applicatio

Documents