Certified Lotus Professional: Application Development Study Guide 0782126685, 9780782126686, 9780585477411

Citation preview

Certified Lotus Professional: Application Development Study Guide

Cate McCoy

SYBEX®

Certified Lotus Professional: Application Development Study Guide

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Certified Lotus Professional: Application Development Study Guide

Cate McCoy

San Francisco • Paris • Düsseldorf • Soest • London Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Associate Publisher: Neil Edde Contracts and Licensing Manager: Kristine O’Callaghan Acquisitions and Developmental Editor: Jill Schlessinger Editors: Susan Berge, Emily K. Wolman Production Editor: Molly Glover Technical Editors: Paul Tronnier, Eric S. Lewis, Wes Cameron Book Designer: Bill Gibson Graphic Illustrator: Tony Jonick Electronic Publishing Specialist: Susie Hendrickson Proofreaders: Nancy Riddiough, Andrea Fox, Laurie O’Connell Indexer: Lynnzee Elze CD Coordinators: Kara Eve Schwartz, Erica Yee CD Technicians: Keith McNeil, Kevin Ly Cover Designer: Archer Design Cover Photographer: Natural Selection Copyright © 2001 SYBEX Inc., 1151 Marina Village Parkway, Alameda, CA 94501. World rights reserved. No part of this publication may be stored in a retrieval system, transmitted, or reproduced in any way, including but not limited to photocopy, photograph, magnetic, or other record, without the prior agreement and written permission of the publisher. Library of Congress Card Number: 2001087091 ISBN: 0-7821-2668-5 SYBEX and the SYBEX logo are either registered trademarks or trademarks of SYBEX Inc. in the United States and/or other countries. Screen reproductions produced with FullShot 99. FullShot 99 © 1991-1999 Inbit Incorporated. All rights reserved. FullShot is a trademark of Inbit Incorporated. The CD interface was created using Macromedia Director, COPYRIGHT 1994, 1997-1999 Macromedia Inc. For more information on Macromedia and Macromedia Director, visit http://www.macromedia.com. SYBEX is an independent entity from Lotus Corporation, and not affiliated with Lotus Corporation in any manner. This publication may be used in assisting students to prepare for a Certified Lotus Professional exam. Neither Lotus Corporation, its designated review company, nor SYBEX warrants that use of this publication will ensure passing the relevant exam. Lotus is either a registered trademark or trademark of Lotus Corporation in the United States and/or other countries. TRADEMARKS: SYBEX has attempted throughout this book to distinguish proprietary trademarks from descriptive terms by following the capitalization style used by the manufacturer. The author and publisher have made their best efforts to prepare this book, and the content is based upon final release software whenever possible. Portions of the manuscript may be based upon pre-release versions supplied by software manufacturer(s). The author and the publisher make no representation or warranties of any kind with regard to the completeness or accuracy of the contents herein and accept no liability of any kind including but not limited to performance, merchantability, fitness for any particular purpose, or any losses or damages of any kind caused or alleged to be caused directly or indirectly from this book. Manufactured in the United States of America 10 9 8 7 6 5 4 3 2 1

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Software License Agreement: Terms and Conditions The media and/or any online materials accompanying this book that are available now or in the future contain programs and/or text files (the “Software”) to be used in connection with the book. SYBEX hereby grants to you a license to use the Software, subject to the terms that follow. Your purchase, acceptance, or use of the Software will constitute your acceptance of such terms. The Software compilation is the property of SYBEX unless otherwise indicated and is protected by copyright to SYBEX or other copyright owner(s) as indicated in the media files (the “Owner(s)”). You are hereby granted a single-user license to use the Software for your personal, noncommercial use only. You may not reproduce, sell, distribute, publish, circulate, or commercially exploit the Software, or any portion thereof, without the written consent of SYBEX and the specific copyright owner(s) of any component software included on this media. In the event that the Software or components include specific license requirements or end-user agreements, statements of condition, disclaimers, limitations or warranties (“End-User License”), those End-User Licenses supersede the terms and conditions herein as to that particular Software component. Your purchase, acceptance, or use of the Software will constitute your acceptance of such End-User Licenses. By purchase, use or acceptance of the Software you further agree to comply with all export laws and regulations of the United States as such laws and regulations may exist from time to time. Software Support Components of the supplemental Software and any offers associated with them may be supported by the specific Owner(s) of that material but they are not supported by SYBEX. Information regarding any available support may be obtained from the Owner(s) using the information provided in the appropriate read.me files or listed elsewhere on the media. Should the manufacturer(s) or other Owner(s) cease to offer support or decline to honor any offer, SYBEX bears no responsibility. This notice concerning support for the Software is provided for your information only. SYBEX is not the agent or principal of the Owner(s), and SYBEX is in no way responsible for providing any support for the Software, nor is it liable or responsible for any support provided, or not provided, by the Owner(s). Warranty SYBEX warrants the enclosed media to be free of physical defects for a period of ninety (90) days after purchase. The Software is not available from SYBEX in any other form or media than that enclosed herein or posted to www.sybex.com. If you discover a defect in the media during this warranty period, you may obtain a replacement of identical format at no charge by

sending the defective media, postage prepaid, with proof of purchase to: SYBEX Inc. Customer Service Department 1151 Marina Village Parkway Alameda, CA 94501 (510) 523-8233 Fax: (510) 523-2373 e-mail: [email protected] WEB: HTTP://WWW.SYBEX.COM After the 90-day period, you can obtain replacement media of identical format by sending us the defective disk, proof of purchase, and a check or money order for $10, payable to SYBEX. Disclaimer SYBEX makes no warranty or representation, either expressed or implied, with respect to the Software or its contents, quality, performance, merchantability, or fitness for a particular purpose. In no event will SYBEX, its distributors, or dealers be liable to you or any other party for direct, indirect, special, incidental, consequential, or other damages arising out of the use of or inability to use the Software or its contents even if advised of the possibility of such damage. In the event that the Software includes an online update feature, SYBEX further disclaims any obligation to provide this feature for any specific duration other than the initial posting. The exclusion of implied warranties is not permitted by some states. Therefore, the above exclusion may not apply to you. This warranty provides you with specific legal rights; there may be other rights that you may have that vary from state to state. The pricing of the book with the Software by SYBEX reflects the allocation of risk and limitations on liability contained in this agreement of Terms and Conditions. Shareware Distribution This Software may contain various programs that are distributed as shareware. Copyright laws apply to both shareware and ordinary commercial software, and the copyright Owner(s) retains all rights. If you try a shareware program and continue using it, you are expected to register it. Individual programs differ on details of trial periods, registration, and payment. Please observe the requirements stated in appropriate files. Copy Protection The Software in whole or in part may or may not be copyprotected or encrypted. However, in all cases, reselling or redistributing these files without authorization is expressly forbidden except as specifically provided for by the Owner(s) therein.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

This work is dedicated to my brother, Alex, who is the very model of courage and commitment.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Acknowledgments

It is indeed an understatement to say that the creation of a book is a team effort...it gets a little better to admit that it is a Herculean team effort, and no author stands alone. I’ve had the pleasure of working with, learning from, and leaning on a very professional group of wonderful Sybexers. Thank you for all the hard work! Additionally, Mark Sayewich contributed foundation material for the 511 chapters of the book and Susan Bulloch started the ball rolling in the very early goings. Last but not least, my family and friends deserve acknowledgment for always standing by me as I live my dreams.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Introduction

Hello! In the following pages, you’ll find everything you need to know not only to pass the Certified Lotus Professional Domino Application Developer certification exams but also to build good Notes and Web applications. This study guide has been designed from the ground up to teach you, then test you on the essential concepts of Notes, as well as the nuances that distinguish the beginners from the advanced Notes programmers. We hope that this book will be both a test preparation guide as well as one of the most useful Lotus Notes Domino reference guides on your shelf. When you complete your exam track, you will be an advanced Domino programmer. Good luck with your goals!

Lotus Certifications Lotus offers a series of certifications for power users, programmers, and system administrators. This book will help prepare you for two Lotus certifications in the application developer track:


Certified Lotus Specialist




Certified Lotus Professional Domino Application Developer

By acquiring the Certified Lotus Specialist certification, you demonstrate the fundamental skills required to build and maintain Lotus Notes Domino applications. When you continue on and pursue the Certified Lotus Professional certification, your skills advance to the level of demonstrating in-depth knowledge of Lotus Notes Domino application architecture and security.

Certified Lotus Specialist To receive your Certified Lotus Specialist (CLS) certification, you must pass the 191-510 Domino R5 Designer Fundamentals exam. The criteria for this exam are as follows: Exam

191-510 Domino R5 Designer Fundamentals

Length of exam

60 minutes

Number of questions

40

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xx

Introduction

Passing grade

70%

Competencies tested

–Client –Database –Design Elements –Formulas

To become a CLS, you need to pass the 510 exam. To accomplish this goal, you should study this book as test preparation and work with the Domino Designer for a few months. It is recommended that you design and build at least one comprehensive Domino application prior to taking the 510 exam.

Certified Lotus Professional Domino Application Developer You can receive your Certified Lotus Professional (CLP) certification by passing three exams:


191-510 Domino R5 Designer Fundamentals




191-511 Domino R5 Application Security and Workflow




191-512 Domino R5 Application Architecture

In addition to the CLS certification 510 exam criteria outlined in the preceding section, the exam requirements are as follows: Exam

191-511 Domino R5 Application Security and Workflow

Length of exam

60 minutes

Number of questions

45

Passing grade

70%

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Introduction

Competencies tested

–Creating Workflow Applications –Monitoring/Maintaining/ Troubleshooting Workflow Applications –Planning and Designing Workflow Applications –Security: Maintaining/Monitoring/ Troubleshooting Problems –Security: Planning/Design –Security: Setting up/Configuring/ Implementing/Enabling

Exam

191-512 Domino R5 Application Architecture

Length of exam

60 minutes

Number of questions

45

Passing grade

74%

Competencies tested

–Designing –Implementing and Maintaining –Planning

To reach CLP status, you need to be a CLS and then pass the 511 and 512 exams. You will benefit in your preparation for these exams by using this book as a study guide. In addition, you should have six months of experience using Domino Designer with the creation of several solid applications to your credit. It is essential that you have a hands-on working knowledge of Domino Designer to be successful with the 511 and 512 exams.

What Does This Book Cover? This book covers everything you need to know to pass the Lotus application developer CLS and CLP Domino Application Developer series of exams: 191-510, 191-511, and 191-512. You will learn how to plan, design, develop, and secure Lotus Notes Domino applications.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxi

xxii

Introduction

The chapters in the book are organized to sequentially cover the 510, 511, and 512 exams, with four chapters devoted to each exam. Since Lotus tests similar material on each of the exams but to different technical depth, there is overlapping coverage in the chapters. Each chapter covers the content to the depth tested on the exam. The 510 exam is broad and expansive, while the 511 exam is targeted and specific, and the 512 exam deep and comprehensive. Studying all the chapters will not only position you to pass the exams, it will push your skills to the next level. The individual competencies measured in a chapter are listed at the beginning of each chapter. Please read them before working through the material. These competencies will appear on your test results when you take the actual exam. This book’s chapters are outlined in the following sections, and they split the material covered into modules that focus on an overall learning concept.

Exam 510: Domino Designer Fundamentals The 191-510 exam covers all the foundation concepts needed to start building Domino applications. Chapter 1: Notes Databases: Core Concepts A Domino application is built as a Notes database. This chapter provides an introduction to the container that is a Notes database including how to create, configure, and maintain one. Chapter 2: Design Elements: Gathering, Storing, and Retrieving Data Interactive database applications are geared toward managing user data. This chapter focuses on how to build forms, configure fields, and create views as the essential design elements required to capture and present data to users. Chapter 3: Presenting, Navigating, and Processing Notes Data With data captured from users, an application becomes user friendly through the strategic use of outlines, pages, navigators, and framesets. This chapter presents information on the design elements that make an application come together for users. Agents that process data are also covered. Chapter 4: Formulas: Adding Code to an Application Lotus Formula Language is a core programming skill required to build successful Domino applications. This chapter shows you how and where to write formula code for your applications.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Introduction

Exam 511: Domino Application Security and Workflow The 191-511 exam focuses on building a secure application and on the components needed to add workflow capabilities. Chapter 5: Server and Database Security The Domino approach to security starts at the server level and gets more specific within a database. This chapter teaches you the essential settings needed for a secure application server and a secure database. Chapter 6: Client Security As a product that can be used to build both Web client and Notes client applications, security needs to be considered from both perspectives. This chapter explains the options available, and in some cases, unavailable, for securing both Web and Notes applications. Chapter 7: Design Element Security The design elements in a database are the building blocks of the application. This chapter looks at the security options that can be added to forms, form contents, views, and agents to protect the data stored in an application. Chapter 8: Workflow Applications The Notes product is a workflow tool that lets you build applications that support distribution, routing, and collaboration. This chapter explains all the pieces you need to build workflow applications and highlights how to make them work in applications.

Exam 512: Domino Application Architecture The 191-512 is an advanced exam that tests your knowledge of the internal requirements necessary for building robust Lotus Notes Domino applications. Chapter 9: Application Planning Planning a Notes application is ground zero for building a good application. In this chapter, you’ll learn the thought process you need to apply to tailor a Domino solution to a business problem. Chapter 10: Application Design Designing the structure of an application involves making design element choices and fitting the problem at hand to the tool you’ve chosen. This chapter teaches you how to design a successful Notes application. Chapter 11: Application Coding The Domino Designer integrated development environment supports the use of Simple Actions, Formula Language, JavaScript, LotusScript, and Java as coding vehicles. This chapter examines how to make a good coding choice and where to write the appropriate types of code.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxiii

xxiv

Introduction

Chapter 12: Application Security Securing an application involves several levels of protection from server and database down to the field level. In this chapter, you’ll consider an application from top to bottom and learn about the security options available for protecting your application. Each chapter ends with review questions that are specifically designed to help you retain the knowledge presented. To really nail down your skills, read each question carefully and, without looking at the options provided, try to answer the question in your own words. Then, review the answer options one at a time, ruling out any obviously wrong answers and matching the potential correct answers to your own thoughts. Be sure to choose the most correct and complete answer, keeping in mind that a given answer may provide only a partial solution. In addition to the chapters, we’ve provided practice exams in Appendices A, B, and C so you can test yourself on the concepts presented in the chapters. And the glossary is a great resource for understanding key terms introduced throughout the book.

Where Do You Take the Exam? Lotus offers its exams through two independent testing organizations:


Sylvan Prometric Testing Centers 800-74-LOTUS (800-745-6887) www.2test.com




CATGlobal Centers www.catglobal.com

To register for a Lotus exam, do the following: 1. Determine the number of the exam you want to take. This book pre-

pares you for the application developer series: 191-510, 191-511, and 191-512. 2. Register with a test center. At this point, you will be asked to pay in

advance for the exam. At the time of this writing, the exams are $100 each and must be taken within one year of payment. You can schedule exams up to six weeks in advance or as soon as one working day prior

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Introduction

to the day you wish to take one. If something comes up and you need to cancel or reschedule your exam appointment, you must do so at least 24 hours in advance. 3. When you schedule the exam, you’ll get instructions regarding all

appointment and cancellation procedures, the ID requirements, and information about the testing-center location.

Tips for Taking the Application Developer Exams The standard exams are timed, multiple-choice tests. You must schedule a test in advance, and depending on the testing-center location requirements, up to 24 hours advance registration may be necessary. Many questions on the exam have answer choices that at first glance look identical—especially the syntax questions! Remember to read through the choices carefully because close doesn’t cut it. If you get commands in the wrong order or forget one character, you’ll get the question wrong. So, the best approach is to combine this study guide with a hands-on approach to building an application. Unlike Microsoft or Novell tests, the exam has answer choices that are very close to one another syntactically, and although some syntax is dead wrong, it is usually just subtly wrong. Some other syntax parameter choices may be right, but they’re shown in the wrong order. Some of the questions do split hairs, and Lotus is not at all averse to giving you classic trick questions. Also, never forget that the right answer is the Lotus answer. In many cases, more than one appropriate answer is presented, but the correct answer is the one that Lotus recommends. Here are some general tips for exam success:











Arrive early at the exam center, so you can relax and review your study materials. Read the questions and all the answers carefully. Don’t jump to conclusions; instead, read and digest the material being presented. Make sure that you’re clear about exactly what each question asks. Don’t leave any questions unanswered. They count against you. When answering multiple-choice questions that you’re not sure about, use the process of elimination to get rid of the obviously incorrect answers first. Doing this greatly improves your odds if you need to make an educated guess.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxv

xxvi

Introduction




If you are unsure about a question, choose the best answer and mark the question for review at the end of the exam so that you make it through all the exam questions in the time allotted. Then, review the marked questions when you have completed all the questions.

After you complete an exam, you’ll get immediate, online notification of your pass or fail status, a printed Examination Score Report that indicates your pass or fail status, and your exam results by section. (The test administrator will give you the printed score report.) Test scores are automatically forwarded to Lotus, so you don’t need to personally send your score to them. File your passing result sheet, given to you by the test administrator, in a safe place.

How to Use This Book This book can provide a solid foundation for the serious effort of preparing for the CLS and CLP Domino Application Developer series of exams. To best benefit from this book, use the following study method: 1. Take the assessment test immediately following this introduction. (The

answers are at the end of the test.) Carefully read over the explanations for any question you get wrong, and note which chapters the material comes from. This information should help you plan your study strategy. 2. Study each chapter carefully, making sure that you fully understand

the information and the test competencies listed at the beginning of each chapter. Pay extra close attention to any chapter where you missed questions in the assessment test. 3. Answer the review questions related to that chapter. (The answers appear

at the end of the chapter, after the review questions.) Note the questions that confuse you, and study those sections of the book again. 4. Take the practice exams in this book. You’ll find one for each exam

(510, 511, and 512) in Appendices A, B, and C, respectively. The answers appear at the end of the exam. 5. Before taking the exam at a testing center, try your hand at the bonus

practice exam that is included on this book’s CD. The questions in this exam appear only on the CD. This will give you a complete overview of what you can expect to see on the real thing. 6. Remember to use the products on the CD included with this book. The

electronic flashcards and the EdgeTest exam preparation software have been specifically picked to help you study for and pass your

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Introduction

xxvii

exam. Study on the road with the electronic book in PDF, and be sure to test yourself with the electronic flashcards.

The electronic flashcards can be used on your Windows computer or on your Palm device.

7. Make sure to review the Key Terms list at the end of each chapter.

To learn all the material covered in this book, you’ll have to apply yourself regularly and with discipline. Try to set aside the same time period every day to study, and select a comfortable and quiet place to do so. If you work hard, you will be surprised at how quickly you learn this material. All the best!

What’s on the CD? The CD included with this book contains all the complete text of the book in PDF as well as bonus material designed to help you pass the Lotus suite of exams.

The EdgeTest Test Preparation Software The test preparation software, provided by EdgeTek Learning Systems, prepares you to successfully pass the 191-510, 191-511, and 191-512 exams. The test engine includes all the questions from the book, plus an additional bonus practice exam that appears exclusively on the CD. You can take the assessment test, test yourself by chapter or competency, take the practice exam that appears in the book or on the CD, or take an exam randomly generated from any of the questions.

Electronic Flashcards for PC and Palm Devices We extracted 20 key concepts from each chapter to create true/false electronic flashcard questions that can be downloaded to your PC or a handheld computer such as a Palm device so you can study anywhere you find a spare minute. With 80 questions for each exam, these flashcards are great for solidifying facts that were presented in the chapters and that are tested on the exams. With 12 chapters, that’s 240 questions covering a wide range of essential Lotus Notes Domino information.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxviii

Introduction

CLP: Application Development Study Guide in PDF You can read this book as a PDF file, which is great for working offline or even in an airplane (which is where I’m writing this… this technology stuff is great!). For your convenience, the Adobe Acrobat Reader is included on this book’s supplemental CD.

Sample Chapter from Notes and Domino R5 Developer’s Guide to Building Applications We’ve included a sample chapter in PDF from Matt Riggsby’s book Notes and Domino R5 Developer’s Guide to Building Applications (Sybex, 2001) for you to check out. This chapter discusses the structure and placement of scripts, fundamental LotusScript syntax, debugging and error handling, and the Domino object model.

How to Contact the Author I’d love to hear about your progress on your Lotus exam goals and about the business projects that you are solving using Lotus Notes Domino. You can reach me at [email protected] or through AlphaPoint’s R5 Web site at www.alphapointsys.com. Happy computing!

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test 1. An application you’re writing interacts with Microsoft Excel on a field

level, exchanging sales forecast figures for the budget. A named range of cells interacts with a field on your form. What field type is the field on your form? A. Text B. Number C. Rich text D. Editable 2. You’ve encrypted a local replica of your mail file. Which of the following

will be used to decrypt the database when you access it? A. Your public key B. Your private key C. The server’s public key D. The server’s private key 3. You’ve created four fields on your form that are enabled for

encryption. You’ve also created four separate secret encryption keys. How many keys are needed to encrypt the document? A. One B. Two C. Three D. Four

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxx

Assessment Test

4. You’re in the process of creating a set of actions that can be reused on

multiple pages and forms. Where should you create these? A. Resources B. Subforms C. Navigators D. Pages 5. You’re creating a page that will be used as the home page for your

Web site. Which of the following kinds of content should you avoid adding to the page? A. Horizontal rules B. Graphics C. Hotspot links D. Fields 6. You’ve decided to use the Generate Default Outline button to create

a new outline. Which of the following will not be automatically added to the outline that is created? A. Views B. Forms C. Pages D. Placeholders for future data-design elements added to the database 7. You’re designing an interface that will allow a user to navigate through it

using clickable links. When the user clicks a link on one area of the screen, you want data to automatically appear on another area of the same screen. Which design element can be used to achieve this effect? A. Tables B. Views C. Framesets D. Embedded forms

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xxxi

8. You’re developing a database that will be used by Web clients and

Notes clients. Which of the following database settings forces you as a programmer to add a Submit button to every input form? A. Allow Soft Deletions B. When Opened In A Browser: Launch Designated Doclink C. Web Access: Require SSL Connection D. Web Access: Use JavaScript When Generating Pages 9. You’ve written an agent in a Mail-In database that will send users a

document to edit. When they’re done editing, they’ll click a button on the document that will automatically mail it back to the Mail-In database. Each user who receives the document needs only to modify their own portion of the document, and when the document is back in the Mail-In database, everyone will be able to read the entire document. What kind of security can be put in place to best support this selective editing? A. Hide When attributes on the portions of the document B. Controlled access sections for each user’s information C. Form access list security D. Encryption of the Mail-In database 10. You’ve added several signable fields to a controlled access section in a

form. At what point will a digital signature be added to the document? A. When the document is created B. When the document is edited C. When the document is saved D. When the document is mailed

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxxii

Assessment Test

11. You’re using an Author field named DocAuthors that has the value

“CN=Cate McCoy/OU=HR/O=AlphaPoint/C=US”. If you code an input translation event using @Name([OU1]; DocAuthors), what value will be stored in the DocAuthors field? A. Cate McCoy B. HR C. AlphaPoint D. US 12. You’re coding an input validation event formula to limit the length of

the ProdCode field to 1–3 characters. Which formula should you use? A. @If(@Length(@Trim(ProdCode))=3;@Success;@Failure

(“Error!”)) B. @If(@Length(@Trim(ProdCode))4;@Success;@Failure

(“Error!”)) D. @If(@Length(@Trim(ProdCode))4;@Success;@Failure

(“Error!”)) 13. You’ve created an application that implements parallel distribution to

the marketing, sales, and accounting groups. In what order will the information be distributed to the groups? A. Marketing, sales, and accounting B. Accounting, marketing, and sales C. Sales, marketing, and accounting D. None of the above

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xxxiii

14. You’re building a view that will show standing orders that need to be

filled five days before the promised FillDate, which is a field on the Order form. Which of the following view selection formulas will display Order forms meeting this criteria? A. SELECT form = “Order” & @Now >=

@Adjust(FillDate;0;0;5;0;0;0) B. SELECT form = “Order” & @Now >= @Adjust(FillDate;0;

-5;0;0;0;0) C. SELECT form = “Order” & @Now >= @Adjust(FillDate;0;0;

-5;0;0;0) D. SELECT form = “Order” & @Now >= @Adjust(FillDate;0;0;-5) 15. You’ve created a shopping cart form in your Web application that col-

lects user credit card information. To heighten security on the database, you want to use SSL. How should you go about doing this? A. Place the database in the SSL directory on the Domino server. B. Place the database in the HTML directory on the Domino server. C. Enable the database property Web Access: Require SSL Connection. D. Create the shopping cart form using hidden fields for the credit

card numbers. 16. You’re designing a database that contains two forms and will list all users

and groups in the ACL with Author access. People who create documents using one type of form should not be allowed to create documents using the other type of form. Which of the following can help you accomplish this? A. Readers field B. Authors field C. Readers and Authors fields used together D. Encryption

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxxiv

Assessment Test

17. You’ve created an invoice application that sends a copy of invoices to

managers for approval. After the invoice has been approved, an e-mail is sent to the application’s creator with a document link to the original invoice, stating the results. Which workflow model is being used? A. The send model B. The share model C. The hybrid model D. None of the above 18. You’ve created an application that requires certain users to be grouped

together and referred to by a single name for security purposes. You do not have appropriate privileges on the Domino Directory to create groups. Which of the following can you create instead? A. Person groups B. Server groups C. New users D. Roles 19. You’ve enabled SSL for your database, and the system administrator

has enabled SSL on the server. The Web users log in with x.509 client certificates. All the Web users are part of the WebUsers group in the Domino Directory, and this group has Editor access to your database. The advanced ACL setting for maximum Internet access is set to Author. The database’s default ACL setting is Reader. What access do users in the WebUsers group have to the database? A. No Access B. Editor C. Author D. Reader

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xxxv

20. You’ve accessed a database to which you have Editor rights. The data-

base contains documents that contain encrypted fields of data, but you don’t have the encryption key. Which statement best describes your ability to work with the encrypted documents? A. You can read the documents but not edit them. B. You can edit the documents. C. You cannot read or edit the documents. D. You cannot open the documents. 21. You’re constructing a view that will include documents in either the

Product Profile form or the Vineyard Profile and that contain a field called Region that has a value of “France.” Which of the following view selection formulas will accomplish this task? A. SELECT (Form = “Product Profile” | Form = “Vineyard

Profile”) & Region = “France” B. SELECT (Form = “Product Profile” OR Form = “Vineyard

Profile”) AND Region = “France” C. SELECT (Form = (“Product Profile” | “Vineyard

Profile”)) & (Region = “France”) D. SELECT (Form = Product Profile & Region = France) |

(Form = Vineyard Profile & Region = France) 22. You’ve added an Authors field to the form you’ve designed and cre-

ated a formula that will set the field’s value with the name of the user who creates the document. What effect will this have on the document after it is saved? A. The document can only be read by the user who created it. B. The document can only be deleted by the user who created it. C. The document can only be edited by the user who created it. D. The document can only be mailed by the user who created it.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxxvi

Assessment Test

23. You’re designing a main document and response document that will

share the same value for the CompanyName field. At a minimum, which two things must you do in order for the field to be inherited into the response document from the main document? A. Mark the field property to allow inherited values, and use a Com-

puted When Composed field value type for the CompanyName field on the response document. B. Mark the database property to allow inheritance. C. Enable field exchange between the two documents. D. Mark the form property to allow inherited values, and use a Com-

puted When Composed field value type for the CompanyName field on the response document. 24. You’re building a series of 15 forms, which can be grouped into three

sets. In order for these forms to appear in an organized manner in the Notes client Create  Document menu, which of the following can you do? A. Precede the name of each form with a special character to group

the views into three major categories B. Name the forms using a backslash ( \ ) in the name to create three

major categories C. Add a keyboard shortcut to each of the form names D. Build a floating pop-up menu to show one set of forms at a time 25. You’ve noticed that the setting Run Restricted LotusScript Agents in

the ORG2741 server document is blank. What effect does this have on users when they run agents on the server? A. No users can run restricted LotusScript agents on the server. B. Only users with Designer access can run restricted LotusScript

agents on the server. C. Anyone can run restricted LotusScript agents on the server. D. Only the system administrator can run LotusScript agents on the

server.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xxxvii

26. You’ve created a custom template from a very heavily used database so

that you can separate where the programmer coding takes place from where the user interaction with data takes place. You put everything in place to make this happen; however, your production database does not seem to be inheriting automatically from your template database. What is a likely cause of this problem? A. The template alias name is exactly the same in the template prop-

erties as it is in the production database properties. B. The template does not have an NTF file extension. C. One of the databases is stored locally while the other is stored on

the Domino server. D. The production database does not have an NSF file extension. 27. You’re having trouble getting the Product view to categorize correctly

based on the value contained in the InventoryCount field. InventoryCount is defined as a Computed For Display number field. The column in the view is also set to display totals. What is the likely cause of your problem? A. Columns using totals cannot be categorized. B. The InventoryCount field contains the wrong data type. C. Computed For Display fields cannot be used to categorize a view. D. Number fields cannot be used to categorize a view. 28. You’ve developed a workflow application that will be used by remote

users. The documents will be mailed to remote users, and then they will act on them. Which of the following is an advantage to the information distribution method you’ve chosen? A. Users only need to access one database: their mail database. B. Users can use a Web client to access the information. C. Server disk space is reduced. D. Forms do not need to be stored in the document.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xxxviii

Assessment Test

29. You have just taken over an application that contains a lot of LotusScript

code. The prior programmer had been working on the following code, which is intended to create new Product Profile documents. It does not currently work. Which of the following code lines needs to be added to create a valid db reference variable? Dim session As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument Set doc = New NotesDocument ( db ) doc.Form = "Product Profile" doc.Save(True, True) A. db = session.CurrentDatabase B. Set db = session.CurrentDatabase C. db := session.CurrentDatabase D. Set db = New session.CurrentDatabase 30. You’ve decided to create a Mail-In database to use in a workflow

application. In order to receive mail, what has to be done? A. A Mail-In database document must be created in the Domino

Directory. B. A Mail-In database document must be created in the Mail-In database. C. A Person document must be created in the Domino Directory. D. A Person document must be created in the Mail-In database. 31. You’re coding an application that will need to guarantee that all data

entered by the user is examined and validated before it is stored in the NSF file. Both Notes clients and Web clients will use the application. Which of the following events would allow execution of JavaScript validation code in both types of clients? A. Exiting B. onBlur C. onClick D. onReset

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xxxix

32. Your organization has decided to use Domino as an application plat-

form and Microsoft Exchange as its mail platform. You have several applications currently in development that require the ability to send documents to people as an e-mail. Which of the following can be used to provide seamless messaging between the two software platforms? A. Domino Enterprise Connection Services B. Lightweight Directory Access Protocol C. Simple Mail Transfer Protocol D. Hypertext Transfer Protocol 33. You’ve built an application that is very graphic-intensive. Before rolling it

out to the production server, you want to tweak the performance with database settings. Which of the following will improve the performance for Notes users? A. Web access: Use JavaScript when generating pages. B. Don’t overwrite free space. C. Display images after loading. D. Disable transaction logging. 34. You’ve coded an application that will be used from a Web client, and

you want to force the server to authenticate the Web user. Which of the following URL command formats should be used for this purpose? A. http://Host?OpenDatabase&login B. http://Host/DatabaseDirectory/

DatabaseFileName?Open&login C. http://Host/DatabaseDirectory?OpenServer&login D. http://Host?OpenServer&login

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xl

Assessment Test

35. You’re planning a database that will be used by approximately 10 end

users with Web browser clients who will be updating customer profiles while making telemarketing calls. The users will need to have secure access to the application, so you want them to log in to identify themselves, which means they need to be added to your server’s Domino Directory. Which of the following license types makes sense? A. Lotus Notes for Collaboration. B. Domino per-user Client Access License (CAL). C. Domino per-server Client Access License (CAL). D. No license is needed for Web browsers. 36. You’ve made a change to the ACL on a database on one server and

notice that the ACL changes are not propagating to the replicas located on remote servers. What is the likely cause of this problem? A. The originating server is not listed in the ACL of the replicating

database with Manager access. B. The originating server is not listed in the ACL of the replicating

database with Designer access. C. The servers are not configured to allow replication of ACLs. D. The option to prohibit Design Refresh for the ACL is enabled for

the remote servers.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xli

37. You’re planning to roll out changes to a database that is used by Lotus

Notes clients on a server in Anquila and a server in San Juan. You’ve made your change in the San Juan database template. The servers replicate with one another once a day. You’ve set up a design environment that includes databases that inherit from templates, and all the necessary components are replicating. To guarantee that changes are available to users immediately, you copy and paste the design elements from the templates on each of the servers to the production databases on each of the servers. What is the net effect 24 hours after you do the copy and paste? A. Duplicate copies of the design elements that were copied and

pasted exist in the production database and in the template. B. Duplicate copies of the design elements that were copied and

pasted exist in the template but not in the production database. C. Single copies of the design elements that were copied and pasted

exist in the production database and in the template. D. The changes you copied into the production database were over-

written by the Design task and no longer exist. 38. You’re troubleshooting a view in a database that is used from the

Web. For some reason, not all the action buttons you programmed are displaying. What is a likely cause of this problem? A. Action buttons are not supported on the Web. B. These particular action buttons are coded with JavaScript. C. Hide When attributes are marked to hide when reading. D. The action buttons are coded with System Actions.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xlii

Assessment Test

39. You’ve set up default replication on your manager’s local mail file with

the server, and you’ve explained replication several times to your manager. This afternoon your manager did a demo for a colleague to show off the awesome capabilities of Domino’s replication facility. During the demo, your manager selected all the e-mails in the local mail file’s Inbox (25 of them) and deleted them, saying out loud, “Watch as I replicate my mail database with the server and retrieve those Inbox messages again.” When the replication finished, both the manager and the colleague were astonished. What did they see in the Inbox? A. All 25 of the Inbox messages were back, as intact as they were

before the replication. B. All 25 of the Inbox messages were back but had today’s date as the

new received date. C. Of the 25 Inbox messages, only the ones that the manager had not

yet read reappeared in the Inbox. D. No messages appeared in the Inbox. 40. You have Editor access to a database that contains the Accounting

Approval form. The form contains an Authors field that contains the group name AccountingAP. You are not a member of the AccountingAP group. Which of the following is true regarding the AccountingApproval form? A. You cannot create or edit documents based on the form. B. You can create but not edit documents based on the form. C. You cannot delete documents based on the form. D. You can create and edit documents based on the form.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xliii

41. You’ve placed a $PublicAccess field on a form, given it a value of “1,”

and granted Reader access to the default entry in your database’s ACL. You’ve also enabled the privilege to write public documents for the default entry. What effect does the $PublicAccess field have on documents created with the form? A. The documents will be able to be read by users with No Access. B. The documents will be able to be edited by users with Depositor

access. C. The documents will be able to be edited by users with Reader

access. D. The documents will be able to be read by users with Reader access. 42. You’re designing an application that will be used over the Internet

through Web browsers. You would like to guarantee that application performance will be optimized, given that most of your users will be connecting from their homes using a modem. Since you’ve made heavy use of graphics in the application, you have turned on the database property to display images after loading. Will this setting improve Web browser performance? A. Yes B. No C. Only when a modem is used D. Only when TCP/IP connection is used 43. You’re building a calendar view to track the delivery vehicles for

WineMaster Distributed Ltd., and you want to include a button on the calendar to show one day at a time. Choose the correct way to code this from the options provided here: A. @Command([CalendarFormat] ; “1” ) B. @Formula[CalendarFormat ;1] C. @Command([Calendar] ; “1” ) D. @CalendarFormat( “1” )

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xliv

Assessment Test

44. The workflow application you’re designing will contain forms that

will trigger events based on field state transitions. Which of the following workflow models is most appropriate given that you do not plan to give users access to the database that stores the documents? A. Push B. Pull C. Combination of push and pull D. None of the above 45. You’re coding an application that requires a connection between a

Web browser and relational data stored on a server that is separate from the Domino server but available over a network connection. Which of the following can be used to achieve this? A. Agents B. CGI script C. Java code D. LotusScript 46. You need to code a custom message on a Web form to present a nice

message to the user after form submission and take the user to a specific document after they’ve submitted the current document. Which of the following languages can help you do this? A. HTML B. Formula Language C. LotusScript D. JavaScript

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Assessment Test

xlv

47. Your user ID is listed directly in the ACL on a database, given the

access level of Author, and assigned to the [ProductCreators] role. You also are a member of the MarketingManagers group, which has Editor access and is associated with the [ProductEditors] role. Which of the following rights do you have in the database? A. Author access and the [ProductCreators] role B. Author access and the [ProductEditors] role C. Editor access and the [ProductCreators] role D. Editor access and the [ProductEditors] role 48. Your application will be replicating between two servers. Only certain

users should be allowed to read some of the documents in the database, so you’ve added Readers fields to the appropriate forms and populated them with the group names for the appropriate users. With the help of your system administrator, the database replicates between the two servers once a day. Unfortunately, none of the documents seem to be showing up on the target server from the source server. What might explain this? A. Replication is not enabled in both directions. B. The target server is not listed in the Readers field of the documents. C. The source server is not listed in the Readers field of the documents. D. The target server is not in the database’s ACL.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

xlvi

Assessment Test

Answers to Assessment Test 1. C. External interactions with OLE applications require that the Notes

field doing the data exchange is of the rich text data type. Although number data is an attractive option and may well be what the data is in Excel, Notes needs the field on the form to be rich text. The field may be either Editable or Computed. See Chapter 10 for more information. 2. B. A database is encrypted with a user’s public key and decrypted with

the same user’s private key. See Chapter 5 for more information. 3. A. One key can be used to encrypt all the fields that have been enabled

for encryption; however, you can apply as many as you like. To decrypt the data, a user only needs one of the four keys. See Chapter 7 for more information. 4. A. Actions created in the Shared Resource area of the Design Panel can be

stored once and reused over and over by linking to them. This reduces maintenance and storage space in a database. See Chapter 3 for more information. 5. D. Fields cannot be added to pages; fields are valid only on forms. Since

pages do not collect or present user data, fields are not allowed in the page design element. See Chapter 3 for more information. 6. C. Pages are not automatically added to a default outline. However,

forms and views are added since they both contain or display user data. Likewise, placeholders for future views and forms and folders added to the database are added to the bottom of the outline. See Chapter 3 for more information. 7. C. The content for each frame in a frameset can be controlled indepen-

dently of the other frames. Indeed, the concept behind a frame is that when you click a link in one frame, the content is displayed in a target frame. See Chapter 3 for more information.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Assessment Test

xlvii

8. D. The database property to use JavaScript when generating pages

allows multiple buttons to appear on a form and requires that the programmer provide a Submit button. With this option disabled, Notes generates a Submit button automatically but does not show any of your programmed buttons. See Chapter 1 for more information. 9. B. Controlled access sections with security specific to each user will do the

trick of allowing the specified users to edit the information but allow everyone to see the information. Hide When attributes may actually work, but controlled access sections are better since they apply a user’s name to an editable area on the form. Form access lists will not limit security on parts of a document, only on an entire document. Finally, encrypting the Mail-In database will not help in Edit mode because at that point the form is in their mail file. See Chapter 12 for more information. 10. C. When a document contains signable fields in a controlled access

section, the digital signature is attached to the document when the document is saved. See Chapter 6 for more information. 11. B. Using the OU, or organizational unit, keyword on the @Name function

suppresses the component label and returns just the organization unit. There is only one organization unit in this hierarchical name, and OU1 returns the first one found. See Chapter 4 for more information. 12. B. First, the ProdCode field is stripped of extraneous blanks. Then, the

length is checked with @Length and is compared to a number. The comparison operator for “less than” is !=

Less Than and Greater Than and Not Equal To and Not Equal To

=

Less Than or Equal To and Greater Than or Equal To

& | !

And and Or and Not

The + operator is also used for concatenating two string operands.

Reserved Words There are five keywords, or reserved words, in Formula Language, as described in Table 4.2. These keywords have an associated behavior when used in a formula. By convention, reserved words appear in uppercase, and Notes will convert them to uppercase for you automatically. TABLE 4.2

Formula Language Reserved Words Reserved Word

Description

FIELD

Used to assign a new value to an existing field on a document or to create a new field on the document.

DEFAULT

Does the same thing as the FIELD variable except that if no field exists, one is created and the default value event is used to populate the field.

REM

Used to add remarks or comments to a formula.

ENVIRONMENT

Used to set or get (read or write) values to the notes.ini file.

SELECT

Used to identify the set of documents to display or process.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

167

Formula Syntax The rules of syntax for how to combine operators, reserved words, variables, and constants determine whether the formula will execute. A typical Notes Formula Language statement is arranged like this: @function_name(optional_arguments) where the function name is always preceded with an @ symbol. A formula may have arguments or parameters passed to it that determine its behavior or what value is returned by the formula. As an example, examine the syntax of the Notes @BrowserInfo formula: @BrowserInfo("JavaScript") This formula is used to investigate properties of the Web browser being used to access the Domino application. JavaScript is one of the parameter values that can be passed to the formula to determine if the browser supports JavaScript. @BrowserInfo returns a 1 or a 0 to signal true or false on the question of supporting JavaScript.

If a formula allows more than one optional argument, the arguments are separated with semicolons (;).

Formula Programming

T

here are more than 500 formulas in Domino’s Formula Language. Some of these act as methods and return a result while others act more like subroutines and simply carry out a sequence of steps. Let’s consider the formulas in groups that define their activity: 

Commands that simulate Notes client menu activities (@Commands)



Statements that involve conditional logic (@If statements)



Formulas that return state information



Formulas that process data



Formulas that manage list data



Formulas for user and database interaction



Web client caveats

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

168

Chapter 4



Formulas: Adding Code to an Application

@Commands @Commands account for more than half of all @ functions, and are often considered as a language unto themselves. @Commands are geared toward carrying out a sequence of steps that would normally be initiated from the Notes client menu. For example, to save a document while in Edit mode in the Notes client, you would use the menu sequence File  Save. You can code an @Command to do this same task using the following command: @Command([FileSave]) The keyword @Command signals Notes that what is about to follow in the parentheses is a command that should be passed directly to the Notes processing engine to execute as a subroutine sequence. Some @Commands also open dialog boxes as a side effect of the command. For instance, when a document is in Edit mode in a Notes client, executing @Command([FileCloseWindow]) closes the currently open window but first prompts the user to ask whether the document should be saved.

When the FileCloseWindow command is used in combination with other commands, it will always execute last, overriding the default of left-to-right execution of formulas.

Names of @Commands As you can see from the FileSave example, most @Commands are named in a way that resembles the menu sequence that is used in a Notes client to invoke the task. This gives you a basic understanding of the types of @Commands that might exist: Since there is a good probability that if a task can be done in a menu, an @Command exists, as well. How will you know what commands are available? Well, there are far too many to memorize, so don’t even try! Take the approach of thinking about the Notes client menu and the tasks you can do there and then locating an @Command that has a similar name.

The Domino Designer R5 help file is the best source of information on @Commands.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

169

@Commands and the Web Typically, a Submit button placed on a Web input form will execute the commands @Command([FileSave]) and @Command([FileCloseWindow]) sequentially to save the document to the Domino server. However, not all @Commands are valid in the Web client. Since many of the @Commands actually simulate Notes client menu tasks, a great many commands do not work in the Web environment. When the database supports JavaScript, however, @Commands like FileSave and FileCloseWindow become active in a Web client. Table 4.3 describes the subset of @Commands that can be used in a Web application. TABLE 4.3

Web @Commands @Command

Description

CalendarFormat

Displays a calendar view with a specified number of days.

CalendarGoTo

Jumps to a specific day in a calendar view.

Compose

Creates a new document using a named form.

EditClear

Deletes the currently open document—be careful!

EditDocument

Toggles a document from Read to Edit mode.

EmptyTrash

Removes documents marked for deletion from the database.

FileCloseWindow

Closes the open window.

FileOpenDatabase

Opens a named database.

FileSave

Saves a document currently in Edit mode.

Folder

Copies or moves a document to a folder.

MoveToTrash

Marks a document for deletion.

NavigateNext

Opens the next document in the view.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

170

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.3

Web @Commands (continued) @Command

Description

NavigateNextMain

Opens the next main document in the view.

NavigatePrev

Opens the previous document in the view.

NavigatePrevMain

Opens the previous main document in the view.

OpenDocument

Opens the selected document in the view in Read mode.

OpenFrameset

Opens a named frameset.

OpenHelpDocument

Opens a help database or help document.

OpenNavigator

Opens a named navigator.

OpenPage

Opens a named page.

OpenView

Opens a named view.

RemoveFromFolder

Takes a selected document out of a folder.

ToolsRunMacro

Invokes a named agent.

ViewChange

Opens a named view.

ViewCollapse

Collapses a selected category in a view.

ViewCollapseAll

Collapses all categories in a view.

ViewExpand

Expands a selected category in a view.

ViewExpandAll

Expands all categories in a view.

ViewRefreshFields

Recalculates computed fields on a document in Edit mode.

ViewShowSearchBar

Displays the full text search bar.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

171

Most of the @Commands that work on the Web are only valid if the database property Use JavaScript When Generating Pages is enabled.

URL Syntax An @Command can be invoked from a URL in a Web client. To do this, the command is formatted differently than when it is used in Click events of buttons or in a Notes client. Compare the two statements below: @Command([OpenPage] ; “HomePage” ) and http://10.0.0.1/winemaster.nsf/HomePage?OpenPage Both of these statements open the page named element entitled HomePage; however, one of them can be used in a URL while the other would be placed in an action button on a form or a view. In the URL syntax, the host name and database precede the command, and the command is formatted as named_element?command. To read this statement, think of the question mark as the command directive; then look at the text following the question mark as the action and the text before the question mark as the named element that will be acted upon.

There are over 400 @Commands in Domino Release 5.0.5. To research an @Command, learn more about what it does, investigate required or optional parameters, refer to the Domino Designer help file.

Conditional (@If) Statements Conditional logic has long been the mainstay of a programmer’s world. You are constantly comparing values and taking an action based on whether the value meets expected criteria. For example, if today is Monday, you might pop up a “Welcome to a New Week!” message on the screen. To do this, you need to test to see if the day is Monday, and then take an action if the test evaluates to True.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

172

Chapter 4



Formulas: Adding Code to an Application

Thus, the goal of a conditional statement is to put forward a condition to test, allow for an action to be taken if the condition is true, and provide a default action if the test condition results in a false statement. The @If formula is the Formula Language equivalent of an if-then-else statement in other programming languages. The syntax of the statement is: @If (condition ; action ; default_action) where condition is the test that evaluates to a True or False value (also referred to as a 0 or a 1), action is the task to carry out if the condition evaluated to True, and default_action is the task to execute if the condition evaluated to False.

Where Do You Code @If Statements? @If statements can be coded as field values, input translation events, input validation events, view columns, window titles, and so on. Figure 4.2 shows an example of an @If statement that is coded in a field’s default value event. FIGURE 4.2

An @If example

Reading an If Statement In Figure 4.2, the field on the document named WineColor is being used to determine the value for the ServingTemperature field on the same document. To read this statement to yourself (either silently or out loud!) to derive its complete meaning, it would go like this: If the wine color is red, then set the value of the ServingTemperature field to the string “Serve at room temperature.”, otherwise set the value of the ServingTemperature field to the string “Serve chilled.”.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

173

Condition-Action Pairs The simplest expression of an @If statement contains one condition, one action, and one default action. To test multiple conditions in one statement, you can use up to 99 condition-action pairs in an @If statement The @If statement must always end with a default action. With multiple condition-action pairs in an if statement, when the first true condition is found, the action associated with the condition executes. The statement then ends execution without evaluating any remaining condition-action pairs.

In other programming languages, multiple condition-action pair behavior is coded in a Case or Switch statement.

Figure 4.3 shows an example of multiple condition-action pairs, again using the WineColor and ServingTemperature fields on a document as well as an additional field, WineType. FIGURE 4.3

Condition-action pairs

The logic of what happens when the formula in Figure 4.3 executes is that if the WineColor field contains the value “Red”, the string value “Serve at room temperature.” is returned to the ServingTemperature field, and execution of the statement stops. On the other hand, if the WineColor field contains a value other than “Red”, the condition evaluates to False, and the next condition-action pair in the @If statement is attempted. An additional point to note in the formula presented in Figure 4.3 is the use of the Boolean & (and) operator in the third condition-action pair. The condition can be a simple test or a complex test. In this case, two conditions must be true in order to execute the associated action.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

174

Chapter 4



Formulas: Adding Code to an Application

Forcing True or False Conditions When programming @If statements, there may be times when you need to force a condition to evaluate to True or to False. Domino provides four statements that can be used to do this, as shown in Table 4.4. TABLE 4.4

Statements That Force True or False Statement

Description

@False

Evaluates to False, which is also the integer 0

@No

Evaluates to False, which is also the integer 0

@True

Evaluates to True, which is also the integer 1

@Yes

Evaluates to True, which is also the integer 1

Input Validation One of the most common uses of an @If statement is to test values entered by a user during editing to see if valid values were provided. Building a robust application means that you have to add a lot of error checking to protect the integrity of the data being collected. Validating Values in the Notes Client The input validation event on editable fields is provided to test values in a Notes client using two special functions, @Success and @Failure. These two functions are only valid in the input validation event. The @Success formula returns a True value as an action, meaning that whatever condition was tested in the if statement was true and passed validation. The @Failure formula is an example of programming by side effect. It not only returns a False value for the condition, which fails validation; it also pops up a message box window in the Notes client with a text message for the user. Figure 4.4 shows how an input validation event can be coded.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

FIGURE 4.4

175

Coding an input validation event

Figure 4.5 shows what the user will see if the document is saved without providing a value in the WineType field. Notice that the message box is presented with one button, the OK button, and a default window title message of “Field Contains Incorrect Value”. When the user clicks the OK button, the cursor is placed in the field that triggered the error condition. FIGURE 4.5

An input validation event message box

Input validation field events fire when a document is saved or refreshed.

Validating Internet Addresses Another type of validation that can be done on data is to verify an Internet mail address typed by a user. The @ValidateInternetAddress in R5 is a special function dedicated to this task. This formula can be used with an @If statement. The syntax for this function is: (@ValidateInternetAddress([KEYWORD]; Address))

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

176

Chapter 4



Formulas: Adding Code to an Application

where the two possible keywords determine which standard Internet format to use to compare to the provided e-mail address. The keywords and their descriptions are presented in Table 4.5. TABLE 4.5

@ValidateInternetAddress Keyword Options Keyword

Description

[Address821]

RFC821 Address Format (e.g., [email protected])

[Address822]

RFC822 Address Format (e.g., "McCoy, Cate (New York)" )

State Information Coding conditional statements often involves checking the state of a piece of information and taking an action based on the state. If you’re confused by the term “state” used here, consider the example of a light switch in your home. It has two states: on or off. To check the state of something is to determine its current setting. Many functions in Domino return information about the state and environment in which the formula is executing, and these can be used in the condition portion of an if statement. Among the functions that return condition-testable information are: 

Boolean functions



Client platform information



User information



Document information



Database information

Boolean Functions Boolean functions are formulas that return a True or False value, or (for those of you more comfortable in the binary world) the value evaluates to a 1 or a 0. Table 4.6 describes the Boolean functions available. Most of the

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

177

functions start with the prefix “Is”, which is a good clue that the formula returns a True or False value. TABLE 4.6

Boolean Functions Function

Question Asked by the Function

@Begins

Is a substring located at the beginning of a target string?

@Contains

Is a substring contained in any part of a target string?

@Ends

Is a substring located at the end of a target string?

@IsAgentEnabled

Is the named agent currently enabled?

@IsAppInstalled

Is Designer/Admin/Client installed on the current machine?

@IsAvailable

Is a named field available on the document?

@IsCategory

Is the current row in the view a category?

@IsDocBeingEdited

Is the current document being edited?

@IsDocBeingLoaded

Is the current document being loaded?

@IsDocBeingMailed

Is the current document being mailed?

@IsDocBeingRecalculated

Is the current document being recalculated?

@IsDocBeingSaved

Is the current document being saved?

@IsDocTruncated

Has the current document been truncated?

@IsError

Did the system set an error flag to True?

@IsExpandable

Is the current row in the view expandable?

@IsMember

Is the value in question a member of the list?

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

178

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.6

Boolean Functions (continued) Function

Question Asked by the Function

@IsModalHelp

Is the current document a modal help document?

@IsNewDoc

Has the current document never been saved?

@IsNotMember

Is the value in question not a member of the list?

@IsNumber

Is the value in question a number?

@IsResponseDoc

Is the current document a Response document?

@IsText

Is the value in question a text string?

@IsTime

Is the value in question a date/time value?

@IsUnavailable

Is a named field not in the document?

@IsValid

Do all fields on the form successfully pass validation using their input validation events?

Boolean functions are generally used in conjunction with an @If statement, as demonstrated by Figure 4.6. In this example, an input validation formula checks the field’s value to see if the field contains the string “Fucito Family”. FIGURE 4.6

Testing a field

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

179

Client Platform Information When a user accesses your application, you can use functions to determine what the environment is and how the user’s client is configured. Table 4.7 presents functions that can be used to detect client platform information. TABLE 4.7

Client Platform Functions Function

Description

@BrowserInfo

Detects information about the client type being used.

@ClientType

Detects whether a Notes client or Web client is being used.

@LanguagePreference

Detects language preference specified by the user.

@Locale

Detects the language name for the language preference.

@Platform

Detects the version of Notes Domino currently being used.

@Zone

Detects the time zone of the current computer.

When coding applications used in the Notes client and the Web client, @ClientType can be a handy function. By determining if the user is using a Web client, you can use an @if statement to take a set of actions that differ from the set of actions taken if the user is using a Notes client. The return value of the @ClientType function is either the string “Notes” or “Web”.

A good time to use the @ClientType function is when choosing a subform to load into a form dynamically at runtime using a formula.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

180

Chapter 4



Formulas: Adding Code to an Application

The @BrowserInfo formula contains many keywords as parameters that provide detailed information about the type of client. The valid keywords are shown in Table 4.8. TABLE 4.8

@BrowserInfo Keywords Keyword

Description

BrowserType

Returns a keyword describing the type of browser: "Microsoft", "Netscape", "Compatible", "Unknown"

Cookies

Returns 1 if cookies are supported in the browser; otherwise returns 0

DHTML

Returns 1 if DHTML is supported in the browser; otherwise returns 0

FileUpload

Returns 1 if file upload is supported in the browser; otherwise returns 0

Frames

Returns 1 if frames are supported in the browser; otherwise returns 0

Java

Returns 1 if Java applets are supported in the browser; otherwise returns 0

JavaScript

Returns 1 if JavaScript is supported in the browser; otherwise returns 0

Iframe

Returns 1 if frames are supported in the browser; otherwise returns 0

Platform

Returns browser’s OS: "Win95", "Win98", "WinNT", "MacOS", "Unknown"

Robot

Returns 1 if the browser might be a Web robot; otherwise returns 0

SSL

Returns 1 if SSL is supported in the browser; otherwise returns 0

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.8

181

@BrowserInfo Keywords (continued) Keyword

Description

Tables

Returns 1 if tables are supported in the browser; otherwise returns 0

VBScript

Returns 1 if VBScript is supported in the browser; otherwise returns 0

Version

Returns the version number of the browser; returns -1 if unknown

@BrowserInfo is not valid in view selection formulas.

User Information Every user who logs in to a Domino application, accesses a server, or opens a database has a username and information associated with the user. Domino provides several formulas that retrieve information about the current user and their security privileges in the current application. Table 4.9 describes the functions used to retrieve user information. TABLE 4.9

Retrieving User Information Function

Description

@Name

Retrieves a user’s hierarchical name or a portion of it

@UserAccess

Determines a user’s security access to the current database

@UserName

Retrieves the user’s primary or alternate hierarchical name, where 0 returns the primary and 1 returns the alternate

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

182

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.9

Retrieving User Information (continued) Function

Description

@UserNameLanguage

Retrieves the code that identifies the language preference of the user for their primary and alternate names

@UserNamesList

Retrieves the current user’s name as well as a list of groups and roles the user is a member of for the current database

@UserPrivileges

Returns a text list of privileges associated with the current user

@UserRoles

Returns a text list of the roles containing the current user

The user can be an individual user or a server.

The @Name and @UserName functions are often used together, as shown in the view selection formula example in Figure 4.7. This selection formula is coded to only show documents in the view where the EmployeeName field contains the name of the current user of the database. FIGURE 4.7

@Name and @UserName example

Usernames are based on the user ID that was issued, and a hierarchical username can have many parts. Examine one type of hierarchical name for a user ID: CN=Cate McCoy/OU=Human Resources/O=AlphaPoint/C=US

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

183

CN, OU, O, and C are known as component tags that identify the user’s common name, organization unit, organization, and country, respectively. The component labels can include other components, such as G for given name and I for initials. The components available depend on how the user ID was set up when it was created. The @Name function can retrieve all or part of this ID’s name using keyword parameters in the formula. The keywords available are described in Table 4.10. TABLE 4.10

@Name Keywords Keyword

Description

[A]

Returns the administration management domain name.

[Abbreviate]

Returns the user’s name without the component labels.

[Address821]

Formats the name using the RFC821 e-mail address format.

[C]

Returns the country portion of the user ID.

[Canonicalize]

Returns the ID with all component labels.

[CN]

Returns the common name portion of the user ID.

[G]

Returns the first name, or given name, of the user.

[HierarchyOnly]

Returns the user ID without the common name.

[I]

Returns the initials associated with the name.

[LP]

Returns the LocalPart part of an RFC822 Internet address.

[O]

Returns the organization portion of the user ID.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

184

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.10

@Name Keywords (continued) Keyword

Description

[OUn]

Returns the organization unit portion of the user ID. Note that an ID can have up to four organization units, so n is 1, 2, 3, or 4.

[P]

Returns the private management domain name for the ID.

[PHRASE]

Returns the Phrase part of an RFC822 Internet address.

[Q]

Returns the generation portion of an ID (e.g., “Jr.”, “III”).

[S]

Returns the last name, or surname, of the user.

[ToKeyword]

Returns the user ID without the common name in reversed order with backslashes: Country\Organization\ Organization Unit.

Document Information When a document is created and stored, in addition to the fields you coded on a form, Domino stores many internal fields describing key document attributes. These internal fields can be queried to uncover document information. The information available is dependent on whether you are working with an open document or a document that is selected in a view but is unopened. Open Document Properties Internal values associated with a document when it is opened for reading or editing describe properties of the document itself as a stand-alone piece of

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

185

information. Table 4.11 describes the functions available for inspecting document properties. TABLE 4.11

Open Document Properties Function

Description

@Accessed

Returns the date and time when the document was last read or edited.

@AttachmentLengths

Returns the file size of attachments in the current document.

@AttachmentNames

Returns the names of attachments in the current document.

@Attachments

Returns the number of attachments in the current document.

@Author

Lists names of users who have edited the document.

@Created

Returns the date and time when the document was created.

@DocFields

Lists all the names of the fields in the document.

@DocLength

Returns the size of the document.

@DocumentUniqueID

Returns the unique ID for current document; this value is unique across all databases.

@FormLanguage

Returns the default language associated with the form.

@InheritedDocumentUniqueID

Returns the unique ID for the current document’s parent.

@Modified

Returns the date and time when the document was last edited.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

186

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.11

Open Document Properties (continued) Function

Description

@NoteID

Returns the unique Note ID for the document; this value is unique within the database.

@Responses

In Window Title event, shows number of responses to document.

Document Properties in a View When a document is presented in a view, a second set of document properties becomes available. These properties are used in view selection formulas and in view columns, and they often describe document relationships. Table 4.12 describes the functions that are available in views to process documents. TABLE 4.12

Document Properties in a View Function

Description

@AllChildren

Used in a view selection formula to include a document’s children

@AllDescendants

Used in a view selection formula to include a document’s children and any descendant documents of the child documents

@DocChildren

In a column, returns the number of children for the document

@DocDescendants

In a column, returns the number of all descendants of the document

@DocLevel

Returns the hierarchy and position level of the document in view (e.g., 1.1, 1.2)

@DocNumber

Returns the entry number of the current document

@DocParentNumber

Returns the entry number of the current document’s parent

@DocSiblings

Totals the number of entries at the same position level

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

187

When @AllChildren and @AllDescendants are used in view selection formulas, they are always placed at the end of the formula and preceded by the pipe symbol ( | ). Figure 4.8 demonstrates this. FIGURE 4.8

View selection criteria

The formula executes from left to right; it takes the set of documents that result from everyone to the left of the vertical bar and then adds the descendants, or children, to that set of documents. Thus in Figure 4.8, all main documents created with the form “formOrder” are selected, and then all Response and Response to Response documents are added to the set of main documents.

Database Information Every Notes application is a Domino database. You can use functions to detect information about the application database at runtime. Table 4.13 shows the functions that retrieve current database information. TABLE 4.13

Database Information Function

Description

@DbExists

Determines if the named database exists

@DbManager

Returns a list of users, servers, and groups with Manager access

@DbName

Returns the server name and operating system filename for the database

@DbTitle

Returns the title of the database

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

188

Chapter 4



Formulas: Adding Code to an Application

Processing Data Many of the functions used in Domino are used to reformat or modify data that was entered during document editing. Data in Notes takes on three basic data types: 

Text



Numbers



Date/Time values

Text Data Far and away, the majority of data stored in documents is text data. Several @ functions are available to help improve the integrity of the stored data either as the users enter it or as it is being saved. Table 4.14 presents the bulk of the text processing functions. TABLE 4.14

Text Processing Functions Functions

Descriptions

@DeleteData

Removes stored data from a document

@Left

Returns a specified number of characters from the left

@LeftBack

Searches from right to left for a specified number of characters

@Length

Returns the length of a text string

@Like

Compares one string to another using multiple wildcard matches

@LowerCase

Converts a string to all lowercase

@Matches

Compares one string to another using individual wildcard matches

@Middle

Substrings a text string based on position

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.14

189

Text Processing Functions (continued) Functions

Descriptions

@MiddleBack

Substrings a text string based on position, right to left

@ProperCase

Puts initial caps on each word in a string

@Repeat

Repeats a character or string a specified number of times

@Replace

Replaces part of a string with a substitute string

@ReplaceString

Replaces words in a string with a substitute string

@Right

Returns a specified number of characters from the right

@RightBack

Searches from left to right for a specified number of characters

@Text

Converts a value to a text string

@TextToNumber

Converts a text string to a number value

@TextToTime

Converts a text string to a date/time stamp value

@Trim

Removes leading, trailing, and redundant spaces

@UpperCase

Converts a string to all uppercase

@Word

Returns a word from a string based on a separator character

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

190

Chapter 4



Formulas: Adding Code to an Application

Numbers Processing numbers requires a solid bench of mathematical functions, and Notes has just that. Table 4.15 shows the set of mathematical functions available. TABLE 4.15

Number Functions Function

Description

@Abs

Calculates absolute value

@Acos

Calculates arc cosine

@Asin

Calculates arc sine

@Atan

Calculates arc tangent

@Atan2

Calculates arc tangent of a tangent

@Cos

Calculates cosine

@Exp

Raises e (approx. 2.7) to a power

@Integer

Returns the integer portion of a number

@Ln

Calculates natural logarithm

@Log

Calculates base 10 common logarithm

@Max

Calculates a maximum number given several numbers

@Min

Calculates a minimum number given several numbers

@Modulo

Performs remainder division.

@Power

Raises a number to a power

@Random

Generates a random number in a range

@Round

Rounds a number

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.15

191

Number Functions (continued) Function

Description

@Sin

Calculates sine

@Sqrt

Calculates square root

@Sum

Calculates the sum of a set of numbers

@Tan

Calculates tangent

Mathematical functions can operate on a discrete (single) value or on a list of values.

Dates and Times Date/time arithmetic and parsing is a challenging task in many languages. Domino has a suite of functions that make dealing with this type of data straightforward. The Date/Time field type stores its data value as 64K float numbers that can be manipulated with @ functions. Table 4.16 shows the functions available for managing date/time data. TABLE 4.16

Date/Time Functions Function

Description

@Adjust

Performs date/time arithmetic

@Date

Returns the date portion of the date/time stamp

@Day

Retrieves the day portion of a date

@Hour

Returns the hour portion of the date/time stamp

@Minute

Returns the minute portion of the date/time stamp

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

192

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.16

Date/Time Functions (continued) Function

Description

@Month

Retrieves the month portion of a date

@Now

Returns the current date/time stamp

@Second

Returns the second portion of the date/time stamp

@Time

Returns the time portion of the date/time stamp

@Today

Returns the date portion of today’s date/time stamp

@Tomorrow

Returns the date portion of tomorrow’s date/time stamp

@Weekday

Returns an integer denoting the weekday of the date

@Year

Retrieves the year portion of a date

@Yesterday

Returns the date portion of yesterday’s date/time stamp

Today, Yesterday, and Tomorrow are also reserved keywords that evaluate to the same values as @Today, @Yesterday, and @Tomorrow, respectively.

Date Formulas Some care needs to be taken when using formulas like @Today and @Now that evaluate to different values depending on when they execute. Consider the case of placing the @Today formula in the Value event of a computed text field. Each time the document is opened in Edit mode, the formula is recalculated. This type of behavior can be a major performance hit, especially when used in a view selection formula, since each document recalculates as the view is opening. This might be fine for views with 100 documents, but when the view has 10,000 documents, the views are very slow to open. In general, avoid using formulas in view columns or selection criteria where the formula constantly recalculates itself.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

193

Date Arithmetic The @Adjust function is the workhorse that performs date and time arithmetic. For instance, if you want to calculate the date two years, seven months, four days, and one hour from right now, the following @Adjust function will do it: @Adjust(@Now ; 2 ; 7 ; 4 ; 1 ; 0 ; 0 ) The seven parameters to the @Adjust function represent the date/time stamp to be adjusted and then six placeholders for year, month, day, hour, minutes, and seconds to be adjusted. Positive numbers add to the date while negative numbers subtract from the date.

Errors with Data Types Formula Language doesn’t require you to declare the data type of a variable when you use it. That means that the language itself is doing implicit conversions where possible to carry out concatenation and math functions on data. If you try to combine two data types that can’t be implicitly converted by Notes, you will see an error message. The possible error messages include: 

Incorrect data type for operator or @Function: Text expected



Incorrect data type for operator or @Function: Number expected



Incorrect data type for operator or @Function: Time/Date expected

The formula either has an incorrect data type for one of the variables involved or the operator is invalid for the type of data. The field that generated the error is generally identified in the error message, as well.

Managing Lists A list in Notes contains multiple values separated by a distinct character. The data in a list can be of any data type. Many pieces of data in Notes are stored internally as lists, including internal fields like @Author and @DocFields. The example below uses the @DocFields function, which returns a list of all the fields in a document: FIELD AllTheFields := @DocFields

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

194

Chapter 4



Formulas: Adding Code to an Application

This statement creates a new field on the document called AllTheFields and stores in the field the names of all the fields in the document. If there were 25 fields on the document where this formula ran, AllTheFields would contain 25 elements of data.

The first element in a list is known as element 1, meaning lists are indexed from the number 1.

List Separator Characters A list in Notes contains multiple data items, or elements. A special character separates each element in the list. In some cases, the character will be a colon, while in others it will be a semicolon. It is valuable to understand which character is used at which point in time. Generated by Notes In the example above, AllTheFields contains a list formatted as elements separated by semicolons. Typical contents would be similar to those shown below. ProdCode ; WineType ; WineColor ; WineRegion Like the result of @DocFields, the separator character for list data generated by Notes is the semicolon. Generated at Runtime by a Formula The separator character differs when you, as a programmer, create a list using a formula. In this case, the list separator is a colon. For example, the following formula creates a new field on the document and populates it with a list that contains three elements: FIELD GlassTypes := “Fluted” : “Goblet” : “Cordial” Generated at Form Creation To muddy the waters just a bit more, if you add a field to a form and mark it to allow multiple values, you can choose the list separator. Figure 4.9 shows the area in the field’s Properties box where this is set.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

FIGURE 4.9

195

Fields allowing multiple values

To know your list separators, be aware of how the list was created.

Processing List Data Domino provides a set of functions to manage lists, turn strings into lists, turn lists into strings, pull elements out of a list, and more. Table 4.17 presents the list functions available. TABLE 4.17

List Functions Function

Description

@Elements

Returns the number of elements in a list

@Explode

Converts a text string into a list

@Implode

Converts a list into a text string

@IsMember

Returns a 1 or a 0 if an item is a member of a list

@IsNotMember

Returns a 1 or a 0 if an item is not a member of a list

@Keywords

Compares two lists and returns the values found in both lists

@Member

Returns the position of an item in a list (elements count up from 1)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

196

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.17

List Functions (continued) Function

Description

@Subset

Returns a sequence of elements in a list

@Unique

Removes redundant values from a list

User and Database Interactions One of the key points about programming an interactive application is that users often provide information dynamically through the use of dialog boxes. These dialog boxes are generally modal, meaning they pop up and won’t go away until the user clicks a button. To program this type of interaction in a Notes client, several formulas come in handy.

Prompting the User for Input The @Prompt formula can do something as simple as popping up a message box with an OK button or something as complex as taking input from a user based on a list of coded choices. How @Prompt behaves is entirely dependent on its button keyword choices. @Prompt Keywords The button keyword is the first parameter of the @Prompt, and it determines how many buttons are displayed, which buttons they are, and whether user input is required. Table 4.18 summarizes the valid options for the button keyword and describes the behavior created by the keyword choice. TABLE 4.18

@Prompt Button Keywords Keyword

Description

[LocalBrowse]

Displays a text message, a browse button, an input field to search for an operating system file, and OK and CANCEL buttons

[Ok]

Displays a text message with an OK button

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.18

197

@Prompt Button Keywords (continued) Keyword

Description

[OkCancelCombo]

Displays a text message, a list of choices in a dropdown box, and OK and CANCEL buttons

[OkCancelEdit]

Displays a text message, a user input box, and OK and CANCEL buttons

[OkCancelEditCombo]

Displays a text message, a list of choices in a dropdown box, and OK and CANCEL buttons, and allows users to add choices

[OkCancelList]

Displays a text message, a list of choices, and OK and CANCEL buttons

[OkCancelListMult]

Displays a text message, a list of choices, and OK and CANCEL buttons, and allows users to choose more than one selection from the choice list

[Password]

Displays a text message, a user input box, and OK and CANCEL buttons, and user input is masked with asterisks as it is typed

[YesNo]

Displays a text message with YES and NO buttons

[YesNoCancel]

Displays a text message with YES, NO, and CANCEL buttons

Selecting Data from a List Two formulas in Notes are used to present choices to a user based on data stored in documents: @Picklist and @DbColumn. One use of these formulas would be if you wanted to have users choose a product to sell from your company’s product list. The product list changes over time, so it’s a good idea to keep this type of data in a document so that users are able to maintain their own data. If they maintain the data, then presenting choices to them using formulas becomes a self-maintaining task.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

198

Chapter 4



Formulas: Adding Code to an Application

@Picklist and @DbColumn do the same job, so it’s useful to point out the features of both that might influence which one you use in a given situation. 

@Picklist 

Provides fastest possible list of values in a view



Retrieves a column value from the view based on the row selected



Has no limit on the amount of data retrieved from a source view



Retrieves information each time the formula runs



Shows the entire view in a scrollable dialog box





Supports the “Starts with…” type-ahead on first-column sorted views

@DbColumn 

Retrieves a specific column based on field name or column number



Retrieves a column value or any field in the document



Limits the amount of data retrieved from a source view to 64KB



Can cache information for multiple lookups



Shows one column from the specified view in a dialog box

@Picklist and @DbColumn Keywords As you’ve noticed with other functions, a keyword can determine how a formula works as well as the value that the function returns. @Picklist has a keyword that determines whether the list presented to the user will come from a custom view created by a programmer or from the Domino Directory or a database’s Access Control List. @DbColumn has a keyword parameter that controls from where Notes retrieves the column of values: a Notes data source or an ODBC data source. The default is Notes, while ODBC allows your application to read data from an external relational data source.

Looking Up a Data Item Have you used a phone book recently to look up someone’s phone number? If so, then the concept of looking up a data item should be a familiar one. The @DbLookup formula is often used in a Notes field to search for a data item and populate the field with the search result.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

199

The way a lookup works is that you provide a search key, which is used to find a piece of data that corresponds with the key. In the phone book example, the key you provide is a last name, and the piece of data you hope to find that corresponds to that key is the person’s phone number. Here’s an example of how the @DbLookup formula can be coded in a field’s value to look up an associated value: @DbLookup("Notes":"NoCache";@DbName;"CountryInfo";CtryCode ;"CtryName") In this example, a lookup is done from the current document into a view named CountryInfo in the current database. The name of the current database was calculated using the @DbName formula. The @DbLookup statement passes in the value of the field CtryCode as a parameter to the view, and when a document is located in the view that contains a matching CtryCode, the value of whatever is stored in the “CtryName” field is returned. @DbLookup Keywords In the same way that @DbColumn can retrieve values from an ODBC data source, @DbLookup can retrieve ODBC values as well. To do this, the “Notes” keyword parameter is replaced with ODBC. The ODBC keyword allows Notes to look up data values in Read mode from an external relational data source.

Release 5.0.5 @ Functions You’ve now taken a look at the most often used functions in Formula Language. To summarize and complete your knowledge of Formula Language, the complete list of @ functions available in Domino as of Release 5.0.5 is presented in Table 4.19. That list is followed by a discussion of the functions that are new in R5 and of those that are not supported in the Web browser. TABLE 4.19

Release 5.0.5 @ Functions Function

Brief Description

@Abs

Calculates absolute value.

@Abstract

Condenses the contents of a field.

@Accessed

Returns the date and time when the document was last read or edited.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

200

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@Acos

Calculates arc cosine.

@AddToFolder

Moves document from the second folder into the first folder.

@Adjust

Performs date/time arithmetic.

@All

With SELECT, retrieves all database documents.

@AllChildren

In a view selection formula, includes a document’s children.

@AllDescendants

In a view selection formula, includes a document’s children and any descendant documents of the child documents.

@Ascii

Converts a string to an ASCII compliant string.

@Asin

Calculates arc sine.

@Atan

Calculates arc tangent.

@Atan2

Calculates arc tangent of a tangent.

@AttachmentLengths

Detects file size of attachments in the current document.

@AttachmentNames

Returns names of attachments in the current document.

@Attachments

Returns number of attachments in the current document.

@Author

Returns a list of names of users who have edited the document.

@Begins

Is a substring located at the beginning of a target string?

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.19

201

Release 5.0.5 @ Functions (continued) Function

Brief Description

@BrowserInfo

Detects information about the client type being used.

@Certificate

Retrieves a user or server public key from Domino Directory.

@Char

Returns IBM 850 Code Page (e.g., char(13) is a LineFeed).

@CheckAlarms

Checks for alarms in the mail file.

@ClientType

Determines whether a Notes client or a Web client is being used.

@Command

Calls one of over 400 menu-type commands.

@Contains

Is a substring contained in any part of a target string?

@Cos

Calculates cosine.

@Created

Returns the date/time stamp when the document was created.

@Date

Returns the date portion of the date/time stamp.

@Day

Retrieves the day portion of a date.

@DbColumn

Returns a column of values from a view.

@DbCommand

Executes a SQL SELECT statement.

@DbExists

Detects whether the named database exists.

@DbLookup

Retrieves a value based on a key value.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

202

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@DbManager

Returns a list of users, servers, and groups with Manager access.

@DbName

Returns the server name and operating system filename for the database.

@DbTitle

Returns the title of the database.

@DDEExecute

Executes a Dynamic Data Exchange command.

@DDEInitiate

Initiates Dynamic Data Exchange.

@DDEPoke

Pushes a value to a Dynamic Data Exchange target application.

@DDETerminate

Terminates Dynamic Data Exchange.

@DeleteDocument

Deletes a document.

@DeleteField

Deletes the stored data associated with a field in a document.

@DialogBox

Opens a custom dialog box form.

@Do

Creates a block structure for execution of multiple statements.

@DocChildren

In a column, returns the number of children for the document.

@DocDescendants

In a column, returns the number of all descendants of the document.

@DocFields

Lists all the names of the fields in the document.

@DocLength

Returns the size of the document.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.19

203

Release 5.0.5 @ Functions (continued) Function

Brief Description

@DocLevel

Returns the hierarchy and position level of the document in view (e.g., 1.1, 1.2).

@DocMark

Used with an agent, marks and saves a document as processed.

@DocNumber

Returns the entry number of the current document.

@DocParentNumber

Returns the entry number of the current document’s parent.

@DocSiblings

Totals the number of entries at the same position level.

@DocumentUniqueID

Returns the unique ID for the current document; this value is unique across all databases.

@Domain

Defines the current user’s mail domain.

@EditECL

Administrators use this to set an ECL.

@EditUserECL

Opens user dialog to modify an ECL.

@Elements

Returns the number of elements in a list.

@EnableAlarms

Toggles the user alarms on or off.

@Ends

Is a substring located at the end of a target string?

@Environment

Sets or retrieves a value for the notes.ini file.

@Error

Generates an error condition testable by @IsError.

@Exp

Raises e (approx. 2.7) to a power.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

204

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@Explode

Converts a text string into a list.

@Failure

Used in input validation to display an error message.

@False

Evaluates to False, which is also the integer 0.

@Fontlist

Returns a list of available fonts in a Notes client.

@FormLanguage

Returns the default language associated with the form.

@GetDocField

Retrieves the value of a field for a specific document.

@GetPortsList

Retrieves the enabled/disabled port settings for the Notes client.

@GetProfileField

Retrieves a profile field from a document.

@HardDeleteDocument

Permanently removes documents from a database.

@Hour

Returns the hour portion of the date/time stamp.

@If

Opens a conditional if-then-else programming statement.

@Implode

Converts a list into a text string.

@InheritedDocumentUniqu eID

Returns the unique ID for the current document’s parent.

@Integer

Returns the integer portion of a number.

@IsAgentEnabled

Is the named agent currently enabled?

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.19

205

Release 5.0.5 @ Functions (continued) Function

Brief Description

@IsAppInstalled

Is Designer/Admin/Client installed on the current machine?

@IsAvailable

Is a named field available on the document?

@IsCategory

Is the current row in the view a category?

@IsDocBeingEdited

Is the current document being edited?

@IsDocBeingLoaded

Is the current document being loaded?

@IsDocBeingMailed

Is the current document being mailed?

@IsDocBeingRecalculat ed

Is the current document being recalculated?

@IsDocBeingSaved

Is the current document being saved?

@IsDocTruncated

Has the current document been truncated?

@IsError

Did the system set an error flag to True?

@IsExpandable

Is the current row in the view expandable?

@IsMember

Is the value in question a member of the list?

@IsModalHelp

Is the current document a modal help document?

@IsNewDoc

Has the current document never been saved?

@IsNotMember

Is the value in question not a member of the list?

@IsNumber

Is the value in question a number?

@IsResponseDoc

Is the current document a Response document?

@IsText

Is the value in question a text string?

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

206

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@IsTime

Is the value in question a date/time value?

@IsUnavailable

Is a named field not in the document?

@IsValid

Executes all input validation formulas on a form; returns True if all fields passed validation and False if any failed validation.

@Keywords

Compares two lists and returns the values found in both lists.

@LanguagePreference

Detects the user’s language preference.

@LaunchApp

Launches Designer/Admin/Client.

@Left

Returns a specified number of characters from the left.

@LeftBack

Searches from right to left for a specified number of characters.

@Length

Returns the length of a text string.

@Like

Compares a string to another string using multiple wildcard matches.

@Ln

Calculates natural logarithm.

@Locale

Detects the language name for the language preference.

@Log

Calculates base 10 common logarithm.

@LowerCase

Converts a string to all lowercase.

@MailDbName

Returns the operating system filename of a user’s mail database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.19

207

Release 5.0.5 @ Functions (continued) Function

Brief Description

@MailEncryptSaved Preference

When mail is sent, should saved mail be encrypted?

@MailEncryptSent Preference

When mail is sent, should sent mail be encrypted?

@MailSavePreference

When mail is sent, should it be saved, filed, etc.?

@MailSend

Signals Domino to automatically mail a document to addresses specified in SENDTO field.

@MailSignPreference

When mail is sent, should mail be signed?

@Matches

Compares a string to another using individual wildcard matches.

@Max

Calculates a maximum number given a set of numbers.

@Member

Returns the position of an item in a list (elements count up from 1).

@Middle

Substrings a text string based on position left to right.

@MiddleBack

Substrings a text string based on position right to left.

@Min

Calculates a minimum number given a set of numbers.

@Minute

Returns the minute portion of the date/time stamp.

@Modified

Returns the date/time stamp when the document was last edited.

@Modulo

Performs remainder division.

@Month

Retrieves the month portion of a date.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

208

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@Name

Retrieves a user’s hierarchical name or a portion of it.

@NameLookup

Searches for specified usernames across all Domino Directories and returns a list.

@Narrow

Converts double-byte characters to singlebyte characters.

@NewLine

Adds a carriage-return line feed to a text string.

@No

Evaluates to False, which is also the integer 0.

@NoteID

Returns the unique Note ID for the document; this value is unique within a database.

@Now

Returns the current date/time stamp.

@OptimizeMailAddress

Condenses a mail address by compressing out domains.

@Password

Scrambles a value.

@PasswordQuality

Rates the complexity of a field using a password data type.

@Pi

Returns the constant value 3.14159265358979.

@PickList

Allows a user to choose a value from a list derived from a view.

@Platform

Returns the version of Notes Domino currently being used.

@PostedCommand

Executes a specified @Command as the last statement in a series.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.19

209

Release 5.0.5 @ Functions (continued) Function

Brief Description

@Power

Raises a number to a power.

@Prompt

Prompts the user for input or a response using a message box.

@ProperCase

Puts initial caps on each word in a string.

@Random

Generates a random number in a range.

@RefreshECL

Updates the ECL from the administration ECL.

@RegQueryValue

Retrieves a value from the Windows OS Registry database.

@Repeat

Repeats a character or string a specified number of times.

@Replace

Replaces part of a string with a substitute string.

@ReplaceSubstring

Replaces words in a string with a substitute string.

@Return

Stops execution of the formula and returns a value.

@Right

Returns a specified number of characters from the right.

@RightBack

Searches from left to right for a specified number of characters.

@Round

Rounds a number.

@Second

Returns the second portion of the date/time stamp.

@Select

Returns a value based on a position variable.

@Set

Assigns a value to a temporary variable.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

210

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@SetDocField

Sets a field value given a document unique ID.

@SetEnvironment

Sets a value in the notes.ini file.

@SetField

Sets a value to a field variable in a document.

@SetProfileField

Sets a value for a profile field in a document.

@SetTargetFrame

Sets the target frame for a given named element.

@Sign

Adds an electronic signature to a mailed document.

@Sin

Calculates sine.

@Soundex

Returns the soundex code for a character.

@Sqrt

Calculates square root.

@Subset

Returns a sequence of elements in a list.

@Success

Evaluates to True, which is also the integer 1.

@Sum

Sums a set of numbers.

@Tan

Calculates tangent.

@Text

Converts a value to a text string.

@TextToNumber

Converts a text string to a number value.

@TextToTime

Converts a text string to a date/time stamp value.

@Time

Returns the time portion of the date/time stamp.

@Today

Returns the date portion of today’s date/time stamp.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

TABLE 4.19

211

Release 5.0.5 @ Functions (continued) Function

Brief Description

@Tomorrow

Returns the date portion of tomorrow’s date/ time stamp.

@Trim

Removes leading, trailing, and redundant spaces.

@True

Evaluates to True, which is also the integer 1.

@Unavailable

Makes a field unavailable in a document (deletes it).

@UndeleteDocument

Retrieves a document that was deleted through a soft delete.

@UpperCase

Converts a string to all uppercase.

@URLGetHeader

Retrieves header information from an HTTP URL.

@URLHistory

Retrieves URL history in the Notes client Web browser.

@URLOpen

Opens a URL in the Notes client Web browser.

@UserAccess

Detects a user’s security access to the current database.

@UserName

Retrieves the user’s primary or alternate hierarchical name, where 0 returns the primary and 1 returns the alternate.

@UserNameLanguage

Retrieves the code that identifies the language preference of the user for their primary and alternate names.

@UserNamesList

Retrieves the current user’s name as well as a list of groups and roles the user is a member of for the current database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

212

Chapter 4



Formulas: Adding Code to an Application

TABLE 4.19

Release 5.0.5 @ Functions (continued) Function

Brief Description

@UserPrivileges

Returns a text list of privileges associated with the current user.

@UserRoles

Returns a text list of the roles containing the current user.

@V2If

Returns a conditional statement to use in Release 2 databases.

@V3UserName

Returns a UserName statement to use in Release 3 databases.

@V4UserAccess

Checks user access to an R4-format database.

@ValidateInternetAddre ss

Check an e-mail address to see if is standard Internet format.

@Version

Returns the version of Domino Notes being used.

@ViewTitle

Retrieves the name of the current view.

@Weekday

Returns an integer denoting the weekday of the date.

@Wide

Converts single-byte characters to doublebyte characters.

@Word

Returns a word from a string based on a separator character.

@Year

Retrieves the year portion of a date.

@Yes

Evaluates to True, which is also the integer 1.

@Yesterday

Returns the date portion of yesterday’s date/ time stamp.

@Zone

Detects the time zone setting of the current computer.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Formula Programming

213

Functions New in Release 5 New functions and features are added to each new release of the evolving Notes product. For example, several functions, such as the @Name function examined earlier, received new keyword parameters that enhanced its functionality. The following functions, which are described in Table 4.19, are new in Release 5 of Domino. @AddToFolder

@LanguagePreference

@SetTargetFrame

@BrowserInfo

@LaunchApp

@UndeleteDocument

@FontList

@Locale

@UserNameLa

@FormLanguage

@NameLookup

@UserNamesList

@HardDeleteDocument

@Narrow

@ValidateInternetAddress

@IsAppInstalled

@PasswordQuality

@Wide

These new aspects to the product are tested on the Lotus certification exams.

Functions Not Supported by Web Browsers While a majority of @ functions can be invoked from a Web browser, some cannot. As a general rule, consider that functions that deal with Domino security and those that open dialog windows in a Notes client do not translate to the Web. Below is a list of functions that are not available in a Web client. @Certificate

@DocParentNumber

@MailSavePreference

@DbCommand

@DocSiblings

@MailSend

@DDEExecute

@Domain

@MailSignPreference

@DDEInitiate

@Environment

@PickList

@DDEPoke

@GetPortsList

@Platform

@DDETerminate

@IsAgentEnabled

@Prompt

@DeleteDocument

@IsCategory

@Responses

@DialogBox

@IsDocBeingMailed

@SetEnvironment

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

214

Chapter 4



Formulas: Adding Code to an Application

@DocChildren

@IsExpandable

@Unique

@DocDescendants

@IsModalHelp

@URLGetHeader

@DocLevel

@MailDbName

@URLHistory

@DocMark

@MailEncryptSavedPreference

@UserPrivileges

@DocNumber

@MailEncryptSendPreference

Summary

F

ormula Language is a core component of Domino programming. Its simpler syntax makes it a good choice for beginning programmers. As precompiled code units, Formula Language statements generally execute faster and complete a task in a minimum number of code lines. In addition, there are many places in Designer where Formula Language is the only valid programming choice. Formula Language comprises @Commands and @ functions, and this chapter has given you a foundation in how to read and code formula statements as well as exposed the power they bring to an application. In addition, examples of syntax were presented, and features new in R5 were highlighted.

Key Terms Before taking the exam, you should be familiar with the following terms: @If @Command temporary variables field variables URL syntax

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

215

Review Questions 1. Abbie designed a frameset that she plans to have users open with an

@Command. Where can this kind of @Command be used? A. Action button B. Field default value formula C. URL D. View selection formula 2. Boris will be coding a formula to open a document, put the document

into Edit mode, refresh the fields on the document, print the document, save the document, and then close the document. This involves several @Commands. Which of the commands will execute last, regardless of where it’s placed in the combination of formulas? A. FileSave B. FileCloseWindow C. EditDocument D. FilePrint 3. Charlotte is using an Author field named DocAuthors that has the

value “CN=Cate McCoy/OU=HR/O=AlphaPoint/C=US”. If she codes an input translation event using @Name([CN]; DocAuthors), what value will be stored in the DocAuthors field? A. Cate B. McCoy C. Cate McCoy D. CN=Cate McCoy

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

216

Chapter 4



Formulas: Adding Code to an Application

4. Daniel has a button on the MY DOCUMENTS folder labeled “Add

Document To PROJECTS Folder”, which moves the current document out of the current folder and into the PROJECTS folder. Which of the following functions is likely to have been coded to create this behavior? A. @AddToFolder(“PROJECTS” ; “MY DOCUMENTS”) B. @AddToFolder(PROJECTS ; MY DOCUMENTS) C. @AddToFolder(PROJECTS) D. @AddToFolder(CURRENT) 5. Elisabeth has coded two enrollment subforms: one for use from a Web

client and one for internal Notes users. The subforms are named EnrollWeb and EnrollNotes, respectively. Which of the following formulas will include the appropriate subform at runtime? A. @If(@ClientType = “Notes” ; “EnrollWeb” ; “EnrollNotes” ) B. @If(@ClientType = “Notes” ; “EnrollNotes” ; “EnrollWeb” ) C. @If(@Browser

= “Notes” ; “EnrollWeb” ; “EnrollNotes” )

D. @If(@Browser

= “Notes” ; “EnrollNotes” ; “EnrollWeb” )

6. Floyd wants to remove leading, trailing, and redundant blanks from

user text input before it is stored in the database. Which of the following functions should he use in the input translation event? A. @Trim B. @LeftTrim C. @RightTrim D. @AllTrim 7. Georgeann wants a formula that will calculate the date two weeks

from today. Which of the following will do this for her? A. @Adjust(@Today;0;0;2;0;0;0) B. @CalendarFormat(14) C. @CalendarFormat(2) D. @Adjust(@Today;0;0;14;0;0;0)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

217

8. Homer wants to retrieve the first word in the WineDescription field.

Which of the following formulas will NOT do this? A. @Word(WineDescription; 1; “ “) B. @Left(WineDescription; “ “) C. @Middle(WineDescription; 1; “ “) D. @Right(WineDescription; “ “) 9. Isabella wants to add a new field called DueDate with a value of

tomorrow’s date to all existing project documents. Which of the following formulas will help with this task? A. FIELD DueDate := @Tomorrow B. DueDate = @Adjust(@Now; 0; 0; 1; 0 ; 0 ; 0) C. DueDate := Tomorrow; D. FIELD DueDate := @Adjust(@Now; 0; 0; @Tomorrow; 0 ; 0 ; 0) 10. Jared enabled the database property for soft deletion in his database

and set an expiry time of 48 hours. He wants to code a button that will retrieve deleted documents prior to the expiry time. Which formula will do this? A. @DeleteData B. @HardDeleteDocument C. @DeleteDocument D. @UndeleteDocument 11. Kristen wants to make sure all the Reseller names in her application

are stored in uppercase. Which event and formula should she use? A. @ProperCase in the input translation event B. @ProperCase in the input validation event C. @UpperCase in the input translation event D. @Upper in the input validation event

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

218

Chapter 4



Formulas: Adding Code to an Application

12. Lenny wants to use the @BrowserInfo function to determine informa-

tion about the client using his application. In which of the following formula areas will this function not return meaningful data? A. View selection B. Button C. Field D. Window title 13. Millicent’s formula is trying to add a text string to a number and store

it back in a number field. Which of the following error messages might this generate? A. Error! B. Incorrect data type for operator or @Function: Date expected C. Incorrect data type for operator D. Incorrect data type for operator or @Function: Number expected 14. Nickolas wants to check the e-mail address being collected as the data

input staff adds new contact records to the contact management system. Which of the following techniques can he use to do this? A. Input translation event with the @ValidateInternetAddress

formula B. Input validation event with the @ValidateInternetAddress formula C. View selection formula with the @ValidateInternetAddress

formula D. View form formula with the @ValidateInternetAddress formula 15. Olive needs to use the correct keyword to add a new value to a docu-

ment. Which one of the following will help her? A. FIELD B. REM C. DEFAULT D. SELECT

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

219

16. Pablo has multiple functions combined in a field’s default value event.

Which of the following must be used to separate the functions? A. Colon B. Semicolon C. Comma D. Carriage return 17. Quianna is passing multiple parameters to a single function. What

separator character does she need to use between the parameters? A. Colon B. Semicolon C. Comma D. Carriage return 18. Rick is creating a temporary variable that contains a list of five elements.

What separator character does he need to use between list elements? A. Colon B. Semicolon C. Comma D. Carriage return 19. Sally wants to call an agent from a formula. Which of the following

will let her do this? A. @OpenAgent B. @Command([ToolsRunMacro]) C. @ToolsRunMacro D. @Command([OpenAgent])

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

220

Chapter 4



Formulas: Adding Code to an Application

20. Thurman is using the URL http://10.0.0.1/winemaster.nsf/

HomePage?OpenPage. Which of the following is equivalent to this URL behavior? A. @Command([OpenPage] ; HomePage ) B. @Open(“HomePage”) C. @Command([OpenPage] ; “HomePage” ) D. @OpenPage(“HomePage” ) 21. Uma is using the function @Command([EditClear]) in a Web application.

What effect will this have? A. Clears all input fields of any values. B. Clears all input fields of any non-default values. C. Deletes the currently open document. D. None; this command doesn’t work in the Web client. 22. Virgil goes by the name Chip at work. The Domino system administrator

has set up his user ID in a way that allows him to use his nickname. Which @UserName formula can be used in Domino to allow Chip to use his nickname in e-mails? A. @UserName(0) B. @UserName(1) C. @UserName(Primary) D. @UserName(Alternate) 23. Whitney wants the Product Profile form to open in a specific frame

when a button is clicked. Which formula can she use to do this? A. @SetFrame B. @SetTargetFrame C. @Command([OpenFrame]) D. @OpenFrame

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

221

24. Xuan wants the window title of the Product Profile document to show

how many Response documents are associated with the current parent Product Profile. Which formula will do this? A. @Responses B. @AllResponses C. @Children D. @AllChildren 25. Yulanda wants the information in a user’s ID name to display in a

view column but does not want the actual user’s name to appear. Which of the following keyword parameters, when used with the @Name function, will do this? A. [Address821] B. [CN] C. [Canonicalize] D. [HierarchyOnly] 26. Zachery’s Web input form is collecting a user’s e-mail address in the

editable field UserEmail. When the data is saved on the Domino server, he’d like to check to see if the e-mail address is valid. Which of the following techniques will help him do this? A. An input validation event for the UserEmail field using

@ValidateInternetAddress B. An input translation event for the UserEmail field using

@ValidateInternetAddress C. A default value event for the UserEmail field using

@ValidateInternetAddress D. A JavaScript onBlur event for the UserEmail field using

@ValidateInternetAddress

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

222

Chapter 4



Formulas: Adding Code to an Application

Answers to Review Questions 1. A. An action button can be used to open named elements; the command

would be invalid when used in a field’s default value, a Web client’s URL, or a view selection formula. 2. B. When the FileCloseWindow command is used in combination

with other commands, it will always execute last, overriding the default of left-to-right execution of formulas. 3. C. Using the CN, or common name, keyword on the @Name function

suppresses the component label and returns just the common name. The common name consists of the first and last name of the user. 4. A. The @AddToFolder function moves documents from the second folder

into the first folder, removing it from the second folder altogether. 5. B. The @ClientType function returns either “Notes” or “Web”. If the

condition of the @If is true, the action fires. In this case, if the ClientType is Notes, then the EnrollNotes subform is used. 6. A. The @Trim function removes leading, trailing, and redundant

blanks from a text string. 7. D. The seven parameters to the @Adjust function represent the date/

time stamp to be adjusted and then six placeholders for year, month, day, hour, minutes, and seconds to be adjusted. Positive numbers add to the date while negative numbers subtract from the date; in this example, 14 days are added to today’s date. 8. D. @Right searches from the end of the string and moves forward

to the beginning, so this formula would return the last word in the WineDescription field using the space as the separator character. 9. A. The keyword FIELD is used to create a new field or update the value

of an existing field. The Formula Language assignment symbol is :=, not just =. @Tomorrow cannot be used as a parameter to the @Adjust formula in the position placeholders.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

223

10. D. The @UndeleteDocument formula works in a database where soft

deletions have been enabled. This formula recovers documents marked for deletion by a user before the expiry time is reached. 11. C. The input translation event fires as a document is saved, converting

whatever the user entered into a new format. The @UpperCase formula converts data to uppercase. 12. A. @BrowserInfo can’t be used in a view selection formula. 13. D. When data types or operators are combined incorrectly, Notes will try

to tell you what data type it was expecting. In this case, the field the data is being stored in is a number field, so the error message will identify this as the expected data type. 14. B. The @ValidateInternetAddress formula can be used in an input

validation event together with @Success and @Failure to test whether an e-mail address matches popular Internet mail standards. 15. A. The FIELD keyword is used to assign a new value to an existing

field on a document or create a new field on the document. 16. B. Multiple functions are combined with a semicolon separating

them. 17. B. If a formula allows more than one optional argument, the arguments

are separated with semicolons. 18. A. When a programmer creates a list in code, the list separator character

is a colon. 19. B. The @Command([ToolsRunMacro]) invokes a named agent. 20. C. The URL syntax calls out the command name after the question

mark and the named element name before the question mark, so the correct format for an @Command is answer C. 21. C. The EditClear command deletes the currently open document, so

be careful out there!

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

224

Chapter 4



Formulas: Adding Code to an Application

22. B. The 1 is an index into the options for the @UserName function. 0

designates the primary name while 1 designates the alternate name. 23. B. The @SetTargetFrame function specifies the name of the frame to

use to display an object. 24. A. The @Responses is valid in a Window Title event ONLY and

returns a count of how many Response documents are associated with the parent document. 25. D. The HierarchyOnly tag will suppress the common name from the

hierarchical username and will show only the remaining information like OU, O, and C. 26. A. @ValidateInternetAddress can be used in the input validation

event combined with the @Success and @Failure functions to produce an error or pass the validation. JavaScript events do not allow @ functions to be coded.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Exam 511: Domino R5 Application Security and Workflow

Copyright ©2001 SYBEX, Inc., Alameda, CA

PART

Il

www.sybex.com

Chapter

5

Server and Database Security LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Calendaring and Scheduling
Database Access: ACL changes
Database Access: Roles
Databases: Access Control List
Databases: Groups
Databases: Roles
Determine Notes security levels: database level
Determine Notes security levels: server level

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

T

he database is the outermost container of an application, holding all the design and data components inside. This outer shell and the server it resides on are the first line of defense for application security. In this chapter, you’ll examine the security components that can be applied to the server and the databases that reside on a server. In addition, calendaring and scheduling security will be examined as a database issue.

Server Security

T

he server has two levels of protection it can offer to Domino: hardware and software.

Hardware Security The typical server craves a cold, dark, lonely room, which is okay since we don’t expect a server to excel at relationship skills. The biggest threat to server security comes from malicious human contact. The following tips can help reduce the risk of physical security breaches: 

Locate the server in a room in a low-traffic area.



Secure the server room with a locked door.







Air-condition the room to discourage human presence and to keep the physical hardware from operating in an overheated situation. Remove the monitor from the Domino server and administer the server remotely. Add a keyboard password to the server.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Server Security

229

Software Security With the hardware side of the server under control, the next level of security issues for a server is the software side. Accessing a Domino server from a Web client may involve a firewall and definitely requires appropriate privileges in the Domino Directory.

Firewalls Whenever Domino is used as a Web server, the issue of protecting the internal information is a real concern. Most companies place a software firewall between the private Domino server and the public Internet. A firewall is a software configuration that controls access between two networks. Firewalls generally prevent access to servers behind the firewall by blocking access to most TCP/IP ports, opening up selected ports for certain types of communication traffic. A Domino server communicates using one TCP/IP address with the clients accessing it on one of two ports: port 80 or port 1352. For Notes-only traffic (server-to-server and server-to-client), Domino transmits information using the Notes Remote Procedure Call (NRPC) on port 1352. For Internet and intranet traffic, Domino uses the HTTP communications protocol, which defaults to port 80. If the firewall blocks ports 80 and 1352, the outside world cannot access closed ports on the Domino server using either a Web browser or a Notes client.

Domino Directory Configuration The system administrator can configure several settings in the server document of the Domino Directory that will affect the security provided by the server. Of particular interest are server settings for HTTP access and agent capabilities. HTTP Access For access from Internets and intranets, the following settings modify server access: Allow Anonymous HTTP Connections If the option is set to Yes, users do not need to log in unless the database they are accessing prevents Anonymous access. If this option is set to No, users are required to log in when they access any database on the Domino server.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

230

Chapter 5



Server and Database Security

Allow Anonymous Notes Connections If the option is set to Yes, users can use the http://ServerName/?OpenServer command to display a list of databases on the server. If any database allows Anonymous access, an unauthenticated user can open it. If this option is set to No, users must authenticate to access a database and the ?OpenServer command does not work. Server-Based Agents Running agents on a server requires special privileges that are configured in the Agent Restrictions area of the Domino Directory. Three privileges can be granted through the use of these fields in the server document: Run personal agents To restrict who can run personal agents, individual usernames and group names can be added to this field. If the field is left blank, all users and groups can run personal agents. Run restricted LotusScript/Java agents Restricted agents are agents that have restricted access to the Domino server and to the server’s operating system. To specify who can run restricted agents, individual usernames and group names can be added to this field. If the field is left blank, all users and groups are denied the ability to run restricted agents. Run unrestricted LotusScript/Java agents Unrestricted agents are agents that have unrestricted access to the Domino server and to the server’s operating system. To specify who can run unrestricted agents, individual usernames and group names can be added to this field. If the field is left blank, all users and groups are denied the ability to run unrestricted agents.

Password Quality The decryption strength required for a Notes password is determined when a system administrator creates a user ID. The levels are described in terms of a number that describes the relative strength from weak to strong, where the longer the password is, the stronger it is. Typically, sensitive IDs, like the cert.id, are protected with a password quality of 16, while user IDs use a lower strength. Tips for increasing the strength of a password include using mixed-case words; combinations of letters, numbers, and punctuation; and a sentence or

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Security

231

phrase instead of a single word. The phase is often referred to as a passphrase. Table 5.1 lists the password-quality scale. Password-Quality Scale

TABLE 5.1

Numeric Quality

Meaning

0

Password is not required and is optional.

1

Any password, regardless of complexity, is valid.

2–6

Weak password using only letters.

7–12

Strong password requiring letters and numbers.

13–16

Complex password.

Passwords are case sensitive, and the maximum length allowed is 63 characters.

When the server is adequately protected, the next level of concern is database security. Having access to the Domino server does not guarantee you access to a database. Let’s look at the issue of database security next.

Database Security

D

o you remember the last time you parked your car in a parking garage that required you to leave the key in the car? Did you leave the normal key for the attendant or the valet key? The concept behind the valet key is that it limits access to the ignition of the car, blocking access to the trunk and glove box. Different types of people are given different types of keys. The concept of different types of keys and different levels of trust for different users is implemented in every Domino database using three mechanisms: 

Access Control List



Groups



Roles

Let’s examine each in turn.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

232

Chapter 5



Server and Database Security

Access Control List The Access Control List, or ACL, is a list of users, groups, and servers defined in the Domino Directory who are granted or denied privileges to the database. The term access control level, also ACL, is often used to describe a user’s privilege to a database.

An ACL can contain individual usernames, database Replica IDs, server names, groups, and hierarchical names with a wildcard character.

Privilege Levels Seven privilege levels can be associated with a user, server, or group in a database’s ACL. Table 5.2 describes the seven levels. TABLE 5.2

Access Control List Privilege Levels

Level

Description

No Access

No authority to access a database

Depositor

Ability to create and save new documents

Reader

Ability to read content and navigate an application through hot links

Author

Reader privileges plus the ability to modify documents you created

Editor

Author privileges plus the ability to modify documents created by other users

Designer

Editor privileges plus the ability to make programming design changes

Manager

Designer privileges plus the ability to delete databases, change ACL security settings, and modify replication settings

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Security

233

Each user or group is associated with one of the privilege levels. To make the association, a name in the ACL is highlighted and an access level selected using the drop-down list at the top-right corner. This is depicted in Figure 5.1. FIGURE 5.1

Access Control List

Replicating Privilege Levels For a privilege level to replicate from one server to another, the server must be listed in the ACL with Manager access. If the server is not listed in the ACL, ACL changes will not replicate. If any access lower than Manager is used for a server involved in replication, the ACL changes do not replicate.

The ACL on Local versus Server As you can see from the ACL discussion so far, the Domino Directory is intricately involved in database security. An issue exists, however, which is that the Domino Directory is located on a Domino server and, therefore, provides the best security coverage specifically for server-based databases. For databases stored locally, a user’s access defaults to Manager since they have complete control over their local machine. This lack of server-security enforcement at the local level can lead to confusion when database replicas are involved. One would hope that changes

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

234

Chapter 5



Server and Database Security

made locally would replicate to the server, but this is not necessarily the case. Imagine the situation where you replicated the Domino Directory itself locally, then deleted all the Person documents from it. Would you want those changes to replicate? No, definitely not! However, since you have Manager access to any database you create, you are certainly able to delete the documents from the local replica of the Domino Directory. They would not, however, replicate. To prevent users from going down the garden path of thinking they were able to do something like this at the local level, a special advanced database security option can be enabled. The advanced option provides the ability to enforce a consistent access control, and it is located in the Advanced area of a database’s ACL as shown in Figure 5.2. FIGURE 5.2

Consistent access control

With this option enabled, the database will enforce the ACL at the local level rather than allowing Manager access to it.

Additional ACL Permissions Once a user is granted one of the seven basic access privileges, several additional permissions can be applied within the privilege level to fine-tune what the user can do in the database. The additional permissions are as follows: 

Ability to create documents



Ability to delete documents



Ability to create personal agents



Ability to create personal folders/views



Ability to create shared folders/views



Ability to create LotusScript/Java agents



Ability to read public access documents



Ability to write public access documents

Each access level is given a combination of the additional permissions automatically. Some of the additional permissions can be enabled or disabled depending on the access control privilege assigned. Table 5.3 describes the access privilege and its associated optional permissions. If not listed as an

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Security

235

additional optional permission in the table, the permission is automatically associated with the privilege level. TABLE 5.3 Privilege Level

Optional Additional Permission Levels

Designation

Additional Permission

Manager

Automatic Optional Automatic Automatic Automatic Automatic Automatic Automatic

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

Designer

Automatic Optional Automatic Automatic Automatic Optional Automatic Automatic

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

Editor

Automatic Optional Optional Optional Optional Optional Automatic Automatic

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

Author

Optional Optional Optional Optional Denied Optional Automatic Optional

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

236

Chapter 5



Server and Database Security

TABLE 5.3 Privilege Level

Optional Additional Permission Levels (continued)

Designation

Additional Permission

Reader

Denied Denied Optional Optional Denied Optional Automatic Optional

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

Depositor

Automatic Denied Denied Denied Denied Denied Optional Optional

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

No Access

Denied Denied Denied Denied Denied Denied Optional Optional

Ability to create documents Ability to delete documents Ability to create personal agents Ability to create personal folders/views Ability to create shared folders/views Ability to create LotusScript/Java agents Ability to read public access documents Ability to write public access documents

If a user has been denied the ability to create personal views, a view can still be created; however, it will be stored in the DESKTOP5.DSK file and not the NSF.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Security

237

Groups Groups accessible to all users are created in the Domino Directory and, therefore, are usable across an entire server and a domain of servers. Generally, a system administrator creates and maintains a group. A power user may also co-own a group and have author rights to it to maintain the users within the group.

Determining a User’s Access Level Are you confused about which privilege level Domino grants if there are conflicting entries? The flowchart shown in Figure 5.3 and the description here should help! FIGURE 5.3

Determining access level

Is the username explicitly listed in the Access Control List?

Yes

Apply the specific privilege level associated with the username.

Yes

Apply the highest privilege level of all groups in which the user is a member.

No

Does the user belong to one of the groups listed in the Access Control List?

No Is this a Web user?

Yes

Apply the privilege level associated with the Anonymous Access Control List entry.

No Apply the privilege level associated with the -Default- Access Control List entry.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

238

Chapter 5



Server and Database Security

Is the username explicitly listed in the Access Control List? If a username is listed in the ACL, the access privilege associated with the user’s username is the access they receive. Does the user belong to one of the groups listed in the Access Control List? If a username is not explicitly listed in the ACL, Domino will check to see if the user is a member of any of the groups listed in the ACL. If the user is a member of one or more groups, Domino assigns the user the access rights of the highest group. Is this a Web user? If this is a Web user and they have not authenticated with the server (logged into the server), then Domino looks for a special entry in the ACL called Anonymous. An unauthenticated user is added to a special group called Anonymous. This entry is not mandatory in a database and is only used by Web users. If the Anonymous entry does not occur in the ACL, then the access specified for the -Default- entry will be used. If all else fails. If you get to this point without any matches, then the user will be granted the access that has been assigned to the -Defaultentry, which appears in the database.

If a user is listed in a group that is assigned the No Access privilege level, the user is prevented from accessing the database regardless of the high privilege level in other groups.

Roles Roles are a powerful design feature that designers can use to provide special functionality for users. Unlike groups, which are created in the Domino Directory at the server level, roles are created at the database level. This makes roles a very flexible design feature for programmers since they don’t have to get the system administrator involved for the creation and management of roles. There are three steps to working with roles: 1. Create the role in the database ACL. 2. Assign users to the role in the database ACL. 3. Use the role in design elements and code for added security.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Security

239

Creating Roles To create a role, the Roles area of a database’s ACL is used, as shown in Figure 5.4. FIGURE 5.4

Creating roles

Role names can be up to 15 characters long and will be automatically surrounded by square brackets in a database.

The use of roles can be a time-saver because it is easier to work with a collection of users than to add and delete individual users in the ACL and in the code in your application.

Replication and Roles Servers can only replicate data they can read, so roles can affect whether data replicates. If a role is used to limit access to information in a database, the role should contain the server name in all cases so that the data can still be replicated.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

240

Chapter 5



Server and Database Security

Database Encryption

In addition to the security offered to a database through the ACL, databases can be encrypted by a user for further protection. To encrypt a database, a user must have Manager access. A database can be encrypted using the Encryption Settings button shown in the database properties, as shown in Figure 5.5. FIGURE 5.5

Encryption Settings button

The database encryption schema is based on dual keys: a public key and a private key. A database is encrypted with a user’s public key. To decrypt a database, the private key in a user’s ID file is used. Local databases can be encrypted using one of three strengths: strong, medium, and simple. The difference between the strengths is security protection, access speed, and data compression abilities. Table 5.4 describes the strength of the keys and Figure 5.6 shows where the strength can be set. TABLE 5.4

Encryption Strengths Strength

Description

Strong

Data is protected at the maximum level, which in turn slows down data access; data is not compressed.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Encryption

TABLE 5.4

FIGURE 5.6

241

Encryption Strengths (continued) (continued) Strength

Description

Medium

Data is protected at a medium level, which offers faster data access than strong encryption but slower access than simple encryption; data is not compressed.

Simple

Data is protected at a minimum level, which speeds data access and allows data to be compressed.

Encryption Strength setting

When a new copy or a new replica of a database is created, database encryption is not carried forward. You do, however, need to be the user who encrypted the database to make the replica or new copy.

Secure Socket Layer When a database developer enables the database property to use Secure Socket Layers (SSL), data that is transmitted between a Domino server and a Web browser is encrypted. The system administrator must configure the server to allow SSL traffic for the SSL database option to function properly. Figure 5.7 shows the SSL option enabled for a database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

242

Chapter 5



Server and Database Security

FIGURE 5.7

SSL database setting

You must have Manager access to enable the SSL setting.

Calendaring and Scheduling

Another database security issue is calendaring and scheduling. The calendar can be used to record meetings, appointments, To Do tasks, and other time-related activities. Since the Domino calendar is stored in a user’s mail database, security mechanisms are needed to allow users to grant individual access to their calendars. This security mechanism is the Calendar Profile. For calendaring and scheduling to work correctly, a user must configure the following information: 

Mail file owner



Delegation profiles

Both types of information are set using the Preferences option on the Tools action button. Both the Mail and Calendar areas contain the Tools action button, and both are shown in Figures 5.8 and 5.9. FIGURE 5.8

Preferences dialog—Calendar

FIGURE 5.9

Preferences dialog—Mail

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Calendaring and Scheduling

243

Mail File Owner When you set up the Notes client for the first time, it will automatically add your username and hierarchical certificate information as the owner of the mail file. Figure 5.10 shows this setting. FIGURE 5.10

Mail file owner

Domino uses the information in this field to determine if you are sending a mail message from your mail file or if someone else is sending mail on your behalf. The information in this field appears in the From: field of a mail memo that is sent from your user ID.

If one user takes over the job and mail file of another user, the information in this field needs to be manually changed by the user.

Delegation Profiles Delegation profiles in a mail database allow a user other than the mail file owner to manage mail activities and the calendar. Two types of delegation profiles can be configured: 

Mail Delegation



Calendar Delegation

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

244

Chapter 5



Server and Database Security

Mail Delegation Users can delegate privileges on their mail, To Do tasks, and calendars at four levels: 



Read Mail, Calendar And To Do Documents Read Mail, Calendar And To Do documents, And Send Mail On My Behalf



Read, Send And Edit Any Mail, Calendar And To Do Document



Delete Mail, Calendar And To Do Documents

Each of these privilege levels can be granted to one or more users through the Mail Delegation tab of the Preferences dialog, shown in Figure 5.11. FIGURE 5.11

Mail Delegation

By selecting the down arrow for each entry, you can select Names, Groups, or Servers from the Domino Directory. These sections are described below. Read Mail, Calendar And To Do Documents This option allows delegates to read mail, calendar entries, and To Do documents and is the basic privilege level granted.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Calendaring and Scheduling

245

Read Mail, Calendar And To Do Documents, And Send Mail On My Behalf This provides the same functionality as the basic privilege level above, but these delegates can additionally send mail as if they were the owner of the mail database. Mail sent by delegates still states that it is from you, but in the header of the document an additional field titled “Sent By” indicates the name of the delegate actually sending the mail. Read, Send And Edit Any Mail, Calendar And To Do Document This access level gives the same privileges as the basic privilege level above, but with the additional ability to edit any document in the mail database. Delete Mail, Calendar And To Do Documents This access level grants delegates the same rights as the basic privilege level above and adds the ability to delete mail.

Calendar Delegation The Calendar Delegation tab controls who can read or edit the calendar. The two control sections determine Read access or Author and Editor access, as shown in Figure 5.12. FIGURE 5.12

Calendar Delegation

For both types of access, you are given the option to allow anyone to read or create/edit calendar entries, or to select specific users. Radio buttons toggle between these settings, and the down arrow is used to select users from the Domino Directory as needed.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

246

Chapter 5



Server and Database Security

In most cases it is a very good idea to give all users the ability to read your calendar. This will allow the Domino server to track your busy time in a global database called BusyTime.nsf. The BusyTime database stores calendar information for all users that have made their calendars available. Domino uses this database to help schedule meetings based on user availability.

Group Calendars You can add a group calendar to a form in a Notes application using the menu options Create  Embedded Element  Group Scheduler. The group calendar displays the individual calendars of several users side by side in a condensed format as shown in Figure 5.13. FIGURE 5.13

Embedded Group Scheduler

For a group calendar to include individual calendars, each individual involved in the group calendar must allow other users to read their calendar by configuring the calendar delegation profile in the mail preferences. For more detailed information, individual calendars can be opened from the group calendar by clicking on a person’s name to display that user’s calendar.

Troubleshooting Calendar Problems Calendaring and scheduling is a global activity performed at the database level. Since it involves the interaction between servers, users, and network resources, problems are inevitable. The most common types of calendaring and scheduling problems are as follows: 

Profile replication conflicts



Connectivity issues



Access control problems



Performance concerns

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Calendaring and Scheduling

247

Calendar Profile Replication Conflicts If the busy times shown on a calendar defy logic, for example 1:00 A.M. to 4:00 A.M., its pretty safe to assume there’s a problem. This may happen if a user’s calendar profile is in a replication conflict state due to a change made locally and another made on a server. To fix the problem, the user needs to edit and re-save the Calendar Profile document.

Calendar Connectivity Issues If a calendar consistently returns the message “Information not available,” one of two things may be the problem. First, the user may not have made their calendar available to free-time lookups. To do this, the user must edit and save the Calendar Profile document. Second, there may be network connectivity problems. Between a user’s client and the server, there are several possible points of failure at the network level including the multiple servers that a request may have to pass through. The system administrator can research connectivity problems using log files and server console messages to help pinpoint the problem.

Calendar Access Control Problems The “Information not available” message can also occur if the person whose calendar you’re trying to access is off-limits to you. A user can set the Calendar Profile and Delegation Profile to limit access. In addition, if the user’s calendar sits on a server that is not accessible or if a server in the connection path is not accessible, the “Information not available” message can be returned. To determine if the servers are the culprit, you can trace the connection using the Notes client or with the help of the system administrator and the log files.

Performance Concerns If calendar lookups are failing for many users and if multiple servers are involved, performance problems may occur and time out a lookup. To solve the problem, an administrator may choose to set up a gateway server dedicated to handling calendaring and scheduling lookups.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

248

Chapter 5



Server and Database Security

Summary

In Domino’s top-down approach to security, server and database security are the first two lines of defense. A server contains many databases and the databases contain user data. At the server level, you can protect from global problems through the use of a firewall. At the database level, you can control who gets into the database and therefore into the data. In this chapter you have examined the ways in which you can protect a server and the databases it contains.

Key Terms Before taking the exam, you should be familiar with the following terms: Access Control List (ACL) encryption group private key public key role Secure Socket Layer (SSL)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

249

Review Questions 1. Adrian has created a Notes form that includes an embedded calendar

control for group scheduling. What does Adrian need to do to allow users to drill down and open an individual calendar from the group calendar? A. Complete a group calendar profile. B. Add the group Anonymous to the ACL of the individual’s mail file. C. Enable the option in the calendar profile allowing everyone to

write to the calendar. D. Nothing; this is the default behavior of a group calendar. 2. Blanche is building an e-commerce site that she would like protected

with SSL connections. What should she do at the database level to make this happen? A. Enable the database property Web Access: Require SSL Connection. B. Enable the database property Web Access: Use JavaScript When

Generating Pages. C. Enable the form property Web Access: Use JavaScript When

Generating Pages. D. Enable the form property Web Access: Require SSL Connection. 3. Carl has encrypted his mail database on the server. When he made a

local replica copy of the database, what happened to the encryption? A. The encryption on the new replica was reduced to simple encryption. B. The new replica database was not encrypted. C. The new replica database was encrypted at the same encryption

strength. D. The new replica database was encrypted with the server’s ID.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

250

Chapter 5



Server and Database Security

4. Desiree is in the WineReviewers group in the ACL for the WineMaster

database. The WineReviewers group has Reader access. She is also listed individually in the ACL with Editor access. Which of the following is she able to do? A. Read existing documents without create or edit capabilities. B. Create new documents but not edit any existing documents. C. Create new documents and edit documents she created. D. Create new documents and edit any existing documents. 5. Eduardo is listed explicitly in the Access Control List of a database

with Editor access and is also a member of two groups in the ACL: the Administrator group, which has been given Manager access, and the PowerUsers group, which has Reader. What access level will Eduardo be given when he tries to access the database? A. Manager B. Editor C. Reader D. None of the above 6. Fredricka has unchecked Dana’s ACL permission to create personal

folders/views, but Dana can still create views. What is wrong? A. Nothing; this is expected behavior. B. Dana needs to be removed from the Create Folder group in the

Domino Directory. C. Dana needs to be removed from the Create Folder role in the

database. D. A DBCACHE flush is needed on the server hosting the database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

251

7. Gerald has been given the right to run personal agents on his organi-

zation’s server. When he tries to create a personal agent in one of his databases, he receives an error message. What is he missing? A. He must have Designer access to the database. B. He must update the database signature for the right to take effect. C. He must refresh the cache on the server. D. He must have permission to create personal agents in the database. 8. Helena wants to protect the server at the network level. What can she

implement for her organization to do this? A. Firewall B. Domino Directory without agent access C. Virus protection D. Limit physical server access 9. Isaiah wants to enable password-quality checking on his server. At

what point does he set the password quality? A. When creating a new server B. When creating a new database C. When creating a new user D. When creating a new document 10. Janice does not want unauthenticated Web users to access her application.

What change should she make to the ACL to make this happen? A. Add an Anonymous entry with Default access. B. Add an Anonymous entry with No Access. C. Add a Default entry with No Access. D. Add a Default entry with Depositor access.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

252

Chapter 5



Server and Database Security

11. Which of the following would be illegal for Keith to add to the ACL

of a database? A. Users with x.509 certificates B. Replica ID C. Users with Notes IDs D. Hierarchical names with a wildcard character 12. Lacy is listed in a database’s ACL as Manager and in a group on the

ACL that has No Access as its privilege level. What is Lacy’s privilege level? A. Manager B. No Access C. Reader D. Unknown 13. Marc has authenticated with the Domino server by providing a user-

name and password. At what point will he next be challenged? A. Database ACL B. Form access list C. View access list D. Group 14. Nedra wants to allow users to run a shared agent in her database.

What minimum access privilege should she grant? A. Editor B. Author C. Reader D. Depositor

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

253

15. Oren has Editor access to a database. Which of the following permis-

sions is not automatically granted to the Editor privilege level? A. Ability to create documents B. Ability to create personal agents C. Ability to read public access documents D. Ability to write public access documents 16. Patsy is troubleshooting a set of servers that are not replicating correctly.

To pull data from one server to another, what privilege level is required? A. Depositor B. Reader C. Author D. Manager 17. Quentin wants to allow unauthenticated Web users to access his appli-

cation. Which of the following should he add to the ACL to allow this to happen? A. A Default entry B. A Manager entry C. An Anonymous entry D. A $WebUsers entry 18. Raul has Designer privileges on a database. Which of the following

can’t he do? A. Create forms. B. Read documents. C. Edit documents. D. Create roles.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

254

Chapter 5



Server and Database Security

19. Shannon wants to encrypt a database. What minimum access privilege

does she need? A. Manager B. Designer C. Editor D. Author 20. Tyler wants to edit his own documents. What minimum privilege does

he require? A. Manager B. Designer C. Editor D. Author 21. Uma wants to require Web users to use a SSL connection to her data-

base. How can she do this? A. Use the server property Web Access: Require SSL Connection. B. Use the database property Web Access: Require SSL Connection. C. Use the form property Web Access: Require SSL Connection. D. Use the view property Web Access: Require SSL Connection. 22. Vern noticed that the Run Restricted LotusScript Agents field is blank

in the NTSERVER1 server document. What does this mean? A. No one can run restricted LotusScript agents on the server. B. Only users with Designer access can run restricted LotusScript

agents on the server. C. Anyone can run restricted LotusScript agents on the server. D. None of the above.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

255

23. The cert.id Wendi uses on the Domino server is protected by a password-

quality checking level of 16. Which of the following passwords is invalid for level 16? A. W3w0nR5! B. J0hnGr1sHam1sAGR8tWriter C. UrL8 D. WhatBeautifulEyesYouHave 24. Xavier needs to identify which database stores users’ free-time infor-

mation. Which of the following should he choose? A. FreeTime.nsf B. BusyTime.nsf C. Time.nsf D. AvailableTime.nsf 25. Yolanda needs to assign one of her users the minimum access level

required so the user can create personal agents in a database. Which access should she assign? A. Depositor B. Reader C. Editor D. Designer 26. Zachery is unable to make ACL changes to a database on the ORG2741

server. Which minimum privilege level is required to do this? A. Manager B. Designer C. Editor D. Author

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

256

Chapter 5



Server and Database Security

Answers to Review Questions 1. D. The calendar profile option to allow everyone to read the calendar

must be enabled for group calendars to work. If this option is enabled, the default behavior of a group calendar allows users to drill down and open the calendars of individual users. 2. A. To require that an SSL connection is used to access a Web applica-

tion on a Domino server, the database property Web Access: Require SSL Connection must be enabled. Without this option enabled, users can access the database with either an SSL connection or a TCP/IP connection. 3. B. When making a new copy or new replica of an encrypted database,

encryption does not carry forward. You do, however, need to be the user with the private encryption key to make the new replica or new copy. 4. D. The most specific privilege assigned in the ACL is granted, and in

this case, that is Editor access, which comes with the ability to create new documents and edit existing documents. 5. B. If a username is explicitly listed in the Access Control List of a

database, this will be the access this user receives. 6. A. Even if the Create Views privilege is not set, users can still make

new views, or folders; however, the view index will be stored in the DESKTOP5.DSK. 7. D. Along with having permission on the server to run personal agents,

users must have permission to create personal agents in the database. 8. A. A firewall protects a server at the network-traffic level. 9. C. Password-quality strength is set when a new user ID is created. 10. B. By setting Anonymous to No Access, Web users without usernames

and passwords receive the No Access privilege level. 11. A. Users who have x.509 certificates but no Notes ID cannot be listed

in the ACL.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

12. B. A group with No Access overrides individual and other group

accesses. 13. A. The database ACL is the second level of security after the network level. 14. C. A minimum of Reader access is required to run a shared agent. 15. B. The ability to create personal agents is an optional privilege for users

with Editor access to a database. 16. B. Reader access is required to pull data; Manager access is required to

push out ACL changes; Editor access is required to modify documents. 17. C. Adding an entry for Anonymous to an ACL will trap Web access by

users not explicitly listed in the ACL. 18. D. Manager access is required to change the ACL and create roles. 19. A. Manager access is required to encrypt a database. 20. D. Author access provides the ability to create new documents and

edit documents you created. 21. B. The property Web Access: Require SSL Connection is a database

property. 22. A. The default for this field is blank, which means that no users can

run restricted agents on this server. 23. D. This phrase contains no numbers and, therefore, fails level 16.

Password quality depends on complexity, which involves combining numbers and letters as well as having an adequate length. 24. B. Free time is stored in the BusyTime.nsf database. 25. B. The minimum access level required is Reader if the additional per-

mission to create personal agents is given to the user. This will allow the users to create personal agents not shared. 26. A. Manager-level access is required to make ACL changes.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

257

Chapter

6

Client Security LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Determine Notes security levels: database level
Determine Notes security levels: document level
Determine Notes security levels: field level
Determine Notes security levels: form level
Determine Notes security levels: network security (firewalls)
Determine Notes security levels: server level
Determine Notes security levels: view level
Determine Notes security levels: workstation level (ECL)
Determine Secure Sockets Layer security
Determine Web security levels: database level
Determine Web security levels: document level
Determine Web security levels: field level
Determine Web security levels: form level
Determine Web security levels: network level (firewalls)
Determine Web security levels: server level (sockets)
Determine Web security levels: view level
Determine Web security levels: workstation level
Web: anonymous groups
Web: challenging
Web: SSL
Workstations (ECL)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

W

ith the release of R5, the Lotus team declared to the world that their goal was to provide a Web and application server that was accessible by many types of clients, including Web and Notes clients. Since security is one of the core services in the product, the scope of the security net needs to be studied from the perspectives of both types of clients. In this chapter, you’ll examine the security features that Notes and Web clients use when communicating with a server or when working offline.

Notes Client From the ground up, the Notes client was designed to offer secure access to the Domino server. Table 6.1 summarizes security protection levels and the mechanism used to provide that protection in the Notes client. TABLE 6.1

Levels of Protection—Notes Client Protection Level

Mechanism Providing Security

Server Level

Authentication

Network Level

Firewalls

Workstation Level

Execution Control List

Database Level

Access Control List and database encryption

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Notes Client

TABLE 6.1

261

Levels of Protection—Notes Client (continued) Protection Level

Mechanism Providing Security

View Level

View access list

Form Level

Form access list

Document Level

Authors fields, Readers fields, and document encryption

Field Level

Field encryption, field signing, and controlled access sections

Let’s examine each of the protection levels in more detail from the perspective of the Notes client and the job it does to provide security.

Authentication If you have a network path to a Domino server and are using a Notes client to access it, you will be challenged to authenticate to actually gain access. The method of authenticating a Notes client user is known as basic password authentication. The server challenges the user to provide a valid name and valid password.

This type of authentication is also known as challenge/response authentication.

The Notes client or, for that matter, another Domino server, is asked to authenticate with a server when the initial access attempt is proffered.

Firewalls In today’s work environment, it has become more and more common for a Web browser to access the company intranet and the applications available on the intranet. This means that a Web browser is often used internally to access a Domino server. If a firewall is in place to control Web traffic, an internal intranet user might be subject to the same open-port dependencies that affect a Web client. Access through a firewall is transparent to the client as long as the system administrator has opened the appropriate ports for communication between servers and clients. These communication ports are better described in Chapter 5, “Server and Database Security.”

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

262

Chapter 6



Client Security

Execution Control List The Notes client can gain additional security protection by applying three levels of control to its operating environment through the Execution Control List, or ECL: 

Workstation security



Java applet security



JavaScript security

The ECL can warn users of attempted security issues, such as writing files to the hard drive outside of Notes, and access to other resources on the computer. To open the ECL, use the Security Options button accessed from the File  Preferences  User Preferences menu sequence dialog window. The workstation security control level is then displayed, as shown in Figure 6.1. FIGURE 6.1

ECL—Workstation security

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Notes Client

263

The ECL is configured on a by-user basis in a similar manner to a database’s Access Control List. To customize the ECL, the radio buttons are used to switch between the three control levels, while the check boxes are used to enable or disable security checking for individual options. Figures 6.2 and 6.3 show the options available for Java applet and JavaScript security, respectively. FIGURE 6.2

ECL—Java applet security

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

264

Chapter 6



Client Security

FIGURE 6.3

ECL—JavaScript security

The ECL can be used to prevent attachments from being stored or executed on the workstation computer. In this way, it offers an additional layer of protection from malicious executable files that might arrive in the Notes client as attachments.

A system administrator can deploy a server-based ECL setting that will override the individual user settings.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Notes Client

265

Access Control and Encryption While a database’s Access Control List does a thorough job of protecting the use of server-based databases, the ACL does not adequately protect local databases. This makes database encryption the best option for securing local databases. The topic of database encryption was introduced in Chapter 5, but let’s look a bit closer at the mechanics of encrypting a database.

Public and Private Keys A user’s public key is stored in two places: the Domino Directory and the user’s ID file. A user’s private key is stored in one place: the user’s ID file.

Encrypting a Database To encrypt a database, you must have a Notes client and a Notes ID. From the database Properties box, the Encryption Settings button shown in Figure 6.4 allows you to initiate the encryption process. FIGURE 6.4

Database properties

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

266

Chapter 6



Client Security

You must have Manager access to a database to encrypt it.

The process of encrypting a database generates a random encryption key that is then encrypted with the user’s public key from the user ID file. This generated, encrypted key is then applied to the database as an unlock code. To unlock the database, the private key from the user’s ID file is used. This means that no user other than the one who encrypted the database can open the database.

View Access List The Notes client fully respects the use of the view access list to control who can see a view. The default, shown in Figure 6.5, is that all users with Reader access or above can see the view. FIGURE 6.5

Default view access list

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Notes Client

267

Form Access List The Notes client also fully supports the use of the form access list to determine who can create documents using a particular form and who can read documents created with the form. The default for these two settings, shown in Figure 6.6, is that all users with Reader access or above can read documents from the form while users with Author access or above can edit documents created from the form. FIGURE 6.6

Default form access list

Document-Level Security The database Access Control List, the form access list, and the view access list control who can access a database, create documents, and see views based on the ACL and roles. Documents or parts of documents can be additionally protected with two special field types: Authors fields and Readers fields.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

268

Chapter 6



Client Security

Authors Fields Authors fields control who can edit documents after they are created. These fields apply only to users who already have Author access to a database. The concept of this type of field is that the field’s value controls who can edit the document after it has been created. For example, if the value of an Author’s field is the user ID name “GMCGUIRE,” only the user ID GMCGUIRE.ID can edit the document after it has been saved. All other users, even if they have author or editor rights to the database, are prevented from editing the document.

Readers Fields In a similar manner to Authors fields, Readers fields control who can see or read existing documents. These fields apply to users with Reader access or above on a database. As an example, if the value of a Readers field is “GMCGUIRE,” only the user ID GMCGUIRE.ID can see the document after it has been saved. All other users, even if they have reader or above rights to the database, are prevented from seeing the document in the database.

Encrypting a Document In a similar manner to encrypting a database, Notes client documents can be encrypted using public and private keys. Encrypted documents, when mailed between Notes users, provide additional security during the network transmission. For documents that are mailed, the public key of the recipient is used to encrypt the document while the recipient’s private key is used to decrypt the document.

Field Encryption and Signing The Notes client can be used to encrypt or sign data items stored in a document. Encrypting scrambles the data using an encryption key algorithm, making it unreadable to anyone who does not have the encryption key. Signing associates the field with a unique code that guarantees that the data has not been tampered with during transmission or since it was last edited by a valid editor.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Notes Client

269

Field Encryption Fields are encrypted using encryption keys created by the designer or manager of the database. In addition to the public and private keys stored in a user’s ID file, additional keys can be created by anyone with a Notes ID to encrypt individual items of data within a document. These types of keys are known as secret encryption keys and are stored in a user’s ID file. Any fields that are enabled for encryption are encrypted when the document is saved. Password type fields are automatically enabled for encryption. Fields enabled for encryption display with a red border around the field in Designer. Creating and Managing Secret Encryption Keys To create a secret encryption key, the Notes client is used. Using the menu options File  Tools User ID, a user can access the Encryption area of the user ID, as shown in Figure 6.7. In this area, keys can be created, deleted, imported, mailed, and exported. FIGURE 6.7

Creating a secret encryption key

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

270

Chapter 6



Client Security

Multiple keys can be created and even applied to the same document; however, any one of the keys applied will decrypt the data.

When a Domino programmer creates an encryption key for use with an application, they must manage and distribute the keys to the users who need access to the encrypted data. Managing the distribution of keys is the responsibility of the database manager, who is often the programmer. Those users can receive the key through an e-mail or on a diskette. Editing Encrypted Documents Data items that have been encrypted with secret encryption keys are not visible to users who do not have the key. While the user may be able to open the document, the field will appear to be empty. In addition, the data item does not display in the database’s list of fields when inspected using the Properties box. If a user has edit rights to an encrypted document but does not have the encryption key to see the encrypted fields, the user cannot edit and save the encrypted document. On the other hand, if the user does have the key and has edit rights to the document, when the document is saved, the encryption algorithm updates the key using the current editing user’s ID.

Signing Fields A digital signature can be added to a document that will be mailed or has a controlled access section by sign-enabling a field on the form or in the section. Attaching a digital signature to a document guarantees that the person who saved the document is authentic and that the data was not tampered with from the time it was saved. Storing a Digital Signature When a document is signed, the following pieces of information are stored in the signed document: 

A generated unique key



Private key of the user saving or mailing the document



Public key of the user saving or mailing the document



List of certificates from the user’s Notes ID

So, from this list, you can correctly assume that you must have a Notes ID to digitally sign a document.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Notes Client

271

Signing a Field To sign a field or a section, the field attribute to Sign If Mailed Or Saved In Section must be enabled in the field’s Properties box as shown in Figure 6.8. FIGURE 6.8

Signing a field

By definition, controlled access sections contain fields that are editable by a specified set of users of the database. While this does not prevent users from seeing the data, it does limit who can edit the data. Signing a field in a section guarantees the identity of the saver and the integrity of the data and does not change who can see the data. When a document is mailed with signable fields, the digital signature is attached to the document during the mailing process using one of the following methods: 

If the Sign option is chosen in the Mail Send dialog



If the form contains a field called “Sign” and the value of the field is 1



If the @MailSend formula is used with the [Sign] flag



If an event associated with the document uses the LotusScript “SignOnSend” property with a value of TRUE

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

272

Chapter 6



Client Security

When a document contains signable fields in a controlled access section, the digital signature is attached to the document when the document is saved.

Web Client

W

eb clients are users who access Domino servers from a Web browser. This includes both Internet and intranet users. Table 6.2 outlines the levels of security protection available to a Web client and the mechanism providing that security. TABLE 6.2

Levels of Protection—Web Client Protection Level

Mechanism Providing Security

Server Level

Authentication

Network Level

Firewalls

Workstation Level

None

Database Level

Access Control List and x.509 certificates

View Level

View access list

Form Level

Form access list

Document Level

Authors and Readers fields

Field Level

None

Authentication If you have a network path to a Domino server from a Web client, your access attempt will be challenged with either basic authentication or with SSL authentication.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Web Client

273

Basic Basic authentication means being challenged to provide a username and password. Web clients are challenged to authenticate when a database on a server is accessed. Contrast this to the Notes client authentication process, which takes place on initial access to the server. Any database can assign specific privileges to Web client users by adding their usernames to the database ACL. Web users will have a username and password, also known as an HTTP or Internet password, if a Person document has been specifically created for the user in the Domino Directory. Web users who don’t have Person documents can only access the server as Anonymous users through the privilege granted to the Anonymous group in a database’s ACL. Maximum Internet Name & Password Access If basic username and password authentication is being used by a Web client, an advanced database property can be set requiring a specific ACL privilege. If the user accessing the database is listed individually or in a group in the ACL, the maximum Internet setting overrides that access level. The Maximum Internet Name & Password Access is located on the Advanced tab of a database’s ACL as shown in Figure 6.9. FIGURE 6.9

Maximum Internet access setting

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

274

Chapter 6



Client Security

Anonymous Access The maximum Internet access setting is also in effect for users who access the Domino server using an anonymous Internet connection on the TCP/IP port or the SSL port. Two Domino Directory configuration settings, which were described in Chapter 5, affect whether anonymous Web client access is allowed to a server: 

Allow Anonymous HTTP Connections



Allow Anonymous Notes Connections

If the user is not anonymous and has an SSL certificate for the browser client being used, the maximum Internet setting is ignored.

Login URLs Server and database authentication from a Web client can be activated through hotspots or events using the following URL command format: http://Host?OpenServer&login http://Host/DatabaseDirectory/ DatabaseFileName?OpenDatabase&login If basic authentication is not used by a client and a server, then the more secure SSL authentication is used. Table 6.3 describes the available protocols and notes which ones use encrypted data transmissions. TABLE 6.3

Protocols That Use Name and Password Authentication Protocol

Behavior Description

TCP/IP

Information transmitted between user and server is not encrypted.

SSL

All information transmitted between user and server is encrypted.

NNTP

Configured in Domino Directory to use either TCP/IP or SSL method.

LDAP

Configured in Domino Directory to use either TCP/IP or SSL method.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Web Client

275

Protocols That Use Name and Password Authentication (continued)

TABLE 6.3

Protocol

Behavior Description

POP3

Configured in Domino Directory to use either TCP/IP or SSL method.

HTTP

Configured in Domino Directory to use either TCP/IP or SSL method.

SMTP

Configured in Domino Directory to use either TCP/IP or SSL method.

IIOP

Configured in Domino Directory to use either TCP/IP or SSL method.

IMAP

Configured in Domino Directory to use either TCP/IP or SSL method.

SSL Secure Socket Layer (SSL) is an encrypted type of data transmission between Web clients and servers. For SSL to work in the Domino environment, both the database itself and the Domino server must be configured to allow it. The programmer’s responsibility for SSL lies naturally on the database side. To enable a database to allow SSL communications, enable the database property requiring an SSL connection as shown in Figure 6.10.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

276

Chapter 6



Client Security

FIGURE 6.10

Enabling database SSL

The administrator’s responsibility for SSL lies in configuring the server to allow one of three types of SSL communication: 

Anonymous SSL access



Name and password authentication using SSL



Authentication using x.509 client certificates over SSL

The system administrator can also enable session-based authentication so that users can log out of a Domino session without needing to close their browser client.

Login URLs Secure server and database authentication from a Web client can be activated through hotspots or events using the following URL command format: https://Host?OpenServer&login https://Host/DatabaseDirectory/ DatabaseFileName?OpenDatabase&login

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Web Client

277

Firewalls To use a Web client to access a Domino server, you may need to pass through a software firewall. This will happen transparently to the client…unless it can’t get through the firewall. A system administrator will open up specific ports for communication between servers and clients. To troubleshoot Web or Notes client access to a Domino server, touch base with the administrator to see if the appropriate communication ports are open. The essential communication ports were described in Chapter 5.

Execution Control List The Web client is not protected by the Execution Control List (ECL) settings. The ECL has no effect in the Web environment.

Access Control and Encryption A database’s ACL is applicable to both Notes and Web clients; however, the one special entry in use for Web clients is the Anonymous entry. Any Web user who does not have a specific username and password can only access the server as an Anonymous user. Standard Domino encryption is not supported in a Web environment. Encryption requires the use of public and private keys. In Notes, these keys are stored in the Domino Directory and a user’s ID file. Web clients do not have a user ID file, making Notes encryption impossible. This makes encrypting anything based on a user ID’s private key impossible. In addition, since the server stores public keys in the Domino Directory, anything that can be decrypted using the public key of a user is transmitted as clear text during an HTTP transmission to a browser since the server automatically decrypts this type of encryption.

An alternate approach to encryption in a Web environment is to use x.509 certificates in place of Notes IDs.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

278

Chapter 6



Client Security

View Access List If a Web user has a username and password and has authenticated to access a Domino server, their username can be used in a view access list just like users who have a Notes ID. In addition, Web users who do not authenticate but instead access applications anonymously can be excluded or included in the view access list. Figure 6.11 shows an example of a view access list that configures the view in question to be used only by Anonymous users. FIGURE 6.11

Anonymous view access

Form Access List In a manner similar to the view access list, Web users can be listed in a form’s access list. Since a Web user may log in with a username or may be accessing the database anonymously, the explicit username or the more generic Anonymous group can be used in the access list. Figure 6.12 shows a form that allows only Anonymous users to read documents created with the form and to create documents using the form.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Web Client

FIGURE 6.12

279

Anonymous form access

Document-Level Security Authors fields and Readers fields behave the same way in a Web client as they do in a Notes client. A Web user’s username or the group name Anonymous can appear as values of either type of field. Keep in mind that for Authors fields to be in effect, the user needs to have exactly Author access to the database in the ACL. For Anonymous users, that would mean setting the Anonymous privilege level to Author for the entire database.

Field Encryption and Signing From the discussion of field encryption in a Notes client, you might recall that secret encryption keys used to encrypt field data are stored in the user ID file of the person creating the key. Since Web users do not have Notes ID files, field encryption is not a supported security feature in a Web client. This holds true for signing fields in documents as well since a Notes user ID is required.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

280

Chapter 6



Client Security

Summary

This chapter has focused on drawing distinctions between the security features available in a Notes client and those available in a Web client. From the network level down to the field level, you should now have a better understanding of how to build a secure Web or Notes application.

Key Terms Before taking the exam, you should be familiar with the following terms: Anonymous Authors field controlled access section database encryption Execution Control List field encryption firewall form access list Readers field Secure Socket Layer (SSL) view access list

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

281

Review Questions 1. Alyson wants to limit which users in the database can create docu-

ments using the Product Profile form. What can she use to do this? A. Authors field B. Readers field C. View access list D. Form access list 2. Bruno is trying to create an agent in a database from the Web. How

can he do this? A. From the main view in the Web navigator, select the Create

Agent link. B. Use the URL http://serverName/

databaseName.nsf?CreateAgent. C. Use the URL http://serverName/

databaseName.nsf?OpenDatabase&CreateAgent. D. This cannot be done. 3. Carlotta will be mailing an encrypted document to Greg. Which key is

used to encrypt the document? A. Public B. Private C. Secret D. Personal

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

282

Chapter 6



Client Security

4. Damon wants to code a URL command that will force the server to

authenticate a Web user. Which of the following URL command formats should be used for this purpose? A. http://Host?OpenServer&login B. http://Host/DatabaseDirectory/

DatabaseFileName?Open&login C. http://Host/DatabaseDirectory?OpenServer&login D. http://Host?OpenDatabase&login 5. Elaine has multiple encryptable fields on her form and has applied sev-

eral secret encryption keys to the form. How many decryption keys must be used to view the data in the encrypted fields? A. One B. Only the first one that was applied C. Only the last one that was applied D. All keys that were applied 6. Freddie wants to stop executable files from being detached to the

workstation. Which of the following will do this? A. Access Control List B. Execution Control List C. Secure sections D. View access list 7. Giselle plans on encrypting the AnnualBonus field on the form she is

currently coding. The data will be edited and saved by users with Web clients. How will this affect the stored data in the AnnualBonus item? A. The AnnualBonus data will be encrypted only for Notes users. B. The AnnualBonus data will be encrypted only for Web users. C. The AnnualBonus data will be encrypted for Notes and Web users. D. The AnnualBonus data will not be encrypted.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

283

8. Harry has enabled a field to be signed in Designer for a form that will

not be mailed to anyone. Which of the following is a true statement about signed fields? A. The field must be in a standard section to be signed. B. The field must be in a controlled access section to be signed. C. The field will be signed only when mailed. D. The field will be signed within 24 hours. 9. Ilona wants to add an additional layer of security to her database by

adding document-level security. Which of the following can she use? A. Form access list B. View access list C. Encryption D. Authors field 10. Jacques has deployed an application to his Notes users that writes

temporary files to the user’s hard drive. Users are complaining that they are getting security warnings when they use his application. What security feature is generating these warnings? A. Access Control List B. Execution Control List C. View access list D. Form access list 11. Kaitlyn has Editor rights to a database that has several encrypted doc-

uments in it. She does not have an encryption key, so she cannot see the data in encrypted fields. Which of the following is a true statement regarding her ability to work with the encrypted documents? A. She can read the documents but not edit them. B. She can edit the documents. C. She cannot read or edit the documents. D. She cannot open the documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

284

Chapter 6



Client Security

12. Lloyd knows that four pieces of information are stored in a document

when it is digitally signed. Which of the following is not one of those four pieces of information? A. A generated unique key B. Private key of the user saving or mailing the document C. Public key of the user saving or mailing the document D. All secret keys from the user’s ID file 13. Maegan is using a controlled access section on her form. Which of the

following is a true statement about this type of section? A. Only certain users can edit information in the section. B. Only certain users can read information in the section. C. Only certain users can collapse the section. D. Only certain users can expand the section. 14. Napoleon added fields containing sensitive data to your Web applica-

tion and would like to encrypt them. When you enable encryption for the field and apply an encryption key, what will happen? A. The sensitive data will be encrypted when viewed by Web users. B. The sensitive data will be encrypted when viewed by Notes users. C. The sensitive data will be encrypted when viewed by Web and

Notes users. D. The sensitive data will not be encrypted. 15. Odelia wants to prevent users from running applets with their Notes

client. What security mechanism can she use to do this? A. Access Control List B. Execution Control List C. Readers fields D. Authors fields

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

285

16. Paul is using SSL on his database and the system administrator has

enabled SSL on the server. What effect will the maximum Internet access setting in the database’s ACL have on SSL-authenticated Web users if these users are listed in the database’s ACL with a specific privilege? A. The maximum Internet access will override the specific privilege. B. The maximum Internet will affect only Notes users. C. The maximum Internet access setting will be ignored. D. The maximum Internet access setting will be reset to the specific

privilege. 17. Quiana wants a digital signature to be attached to a document when

it is mailed. How can she make sure this happens? A. Place a sign-enabled field in a controlled access section. B. Make sure a sign-enabled field is not in a controlled access section. C. Place a sign-enabled field in a standard section. D. Make sure a sign-enabled field is not in a standard access section. 18. Raul has mail-enabled a form that contains signable fields. There are

no sections on the form. When will the fields be signed? A. When the document is saved B. When the document is mailed C. When the document is opened by the recipient D. Never, since signable fields must be in a controlled access section 19. Shania is confused about which key is used to create digital signatures.

Which one is used? A. Public B. Private C. Secret D. Session

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

286

Chapter 6



Client Security

20. Timothy will be using digital signatures in a workflow application for

documents that are routed up an approval chain. Which of the following must be present on the form for this to happen? A. A field named Encrypt B. At least one field that has been sign-enabled C. A controlled access section D. At least one Authors field 21. Usha has added a signable field to a controlled access section in his

form. When will this field actually be signed? A. When the document is mailed B. When the field is edited C. When the document is saved D. When the form is saved 22. Vincenzo’s new form in his Web application contains a field that will

store sensitive data that should only be seen by certain people. He is considering using field encryption. What effect will this have on the data stored in the sensitive field? A. The data in the field will be encrypted only for Notes users. B. The data in the field will be encrypted only for Web users. C. The data in the field will be encrypted for Notes and Web users. D. The data in the field will not be encrypted. 23. Wilhelmina wants to stop Java applets from being run on the work-

station. Which of the following will do this? A. Access Control List B. Execution Control List C. Secure sections D. View access list

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

287

24. Xuan has applied three secret encryption keys to a form. To decrypt

the data, how many keys must be used in order to view the data? A. One B. Two C. Three D. None 25. Yesenia often receives encrypted documents from Schuyler in the Inbox

of the mail database. Which key is used to decrypt the documents? A. Public B. Private C. Secret D. Personal 26. Zane wants only certain users to be able to create Product Profile

documents even though all users have Author access to the database. What can be done to accomplish this? A. View access list B. Form access list C. Authors field D. Readers field

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

288

Chapter 6



Client Security

Answers to Review Questions 1. D. The form access list can be used to limit who can create documents

with the form in question. 2. D. Web users do not have the ability to create agents. 3. A. For documents that are mailed, the public key of the recipient is

used to encrypt the document, while the recipient’s private key is used to decrypt the document. 4. A. The host name is followed by the question mark command prompt,

then the OpenServer command, and finally, the parameter keyword “login” after the & parameter marker. 5. A. At least one of the keys must be available to decrypt the data; how-

ever, it doesn’t matter if it was the first or last or even ones in between that were applied. 6. B. The Execution Control List for a workstation can be configured to

prevent Notes client access to the file system, which would stop executable files from being detached to the workstation. 7. D. Field-level encryption is not supported in a Web environment

because there is no user ID file that stores the encryption keys. 8. B. To attach a signature to a document that will not be mailed, the

field must be contained in a controlled access section. 9. D. An Authors field provides document-level security by preventing

edits by users other than those listed in the Authors field. Since the value of the Authors field can change programmatically from one document to another, each document is uniquely protected. 10. B. The workstation’s ECL in a Notes client can be used to warn users

about activity that an application will do that might be harmful to them. Writing files to a hard drive could be malicious, so the ECL warns the user.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

289

11. A. If a user has edit rights to an encrypted document but does not have

the encryption key to see the encrypted fields, the user cannot edit and save the encrypted document. 12. D. Digital signatures do not use secret encryption keys. The fourth miss-

ing item is a list of the certificates from the sender/saver’s ID. 13. A. Controlled access sections allow all users with Reader access to the

document to see the contents of the section. However, only certain users can edit the data contents of the section. 14. D. Field-level encryption is not supported in the Web environment since

the encryption keys required to encrypt data are stored in the ID file and Web users do not have ID files. 15. B. The ECL can be configured to prevent Java applets from executing

in the Notes client. 16. C. When SSL is in use, the maximum Internet access setting has no

effect. Therefore, the access granted to the group in the database’s ACL is in effect. 17. B. Signing happens when a document is either mailed or saved. Signing

happens at mail time if a sign-enabled field exists anywhere on the form except in a controlled access section. Signing happens at save time if the sign-enabled field is located in a controlled access section. 18. B. Fields that are not contained in controlled access sections are signed

only if the document is mailed and the signing occurs at mail time. 19. B. The private key from the ID of the user saving the document is

stored in the document together with the public key and the list of certificates of the person saving the document. 20. B. To attach a digital signature to a document, at least one field on the

form must be sign-enabled. 21. C. When a document contains signable fields in a controlled access

section, the digital signature is attached to the document when the document is saved.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

290

Chapter 6



Client Security

22. D. Field-level encryption is not supported in a Web environment

because there is no user ID file that stores the encryption keys. 23. B. The Execution Control List for a workstation can be configured to pre-

vent Notes client access to the file system, which would stop Java applets from being written to and executed on a workstation. 24. A. When multiple keys are used, at least one of the keys must be avail-

able to decrypt the data. 25. B. For documents that are mailed, the public key of the recipient is

used to encrypt the document, while the recipient’s private key is used to decrypt the document. 26. B. The form access list can be used to limit which users can create doc-

uments from any given form.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Chapter

7

Design Element Security LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Agent Access
Creating workflow related fields: document encryption
Creating workflow related fields: signing
Field Access: Authors
Field Access: Encryption
Field Access: Groups
Field Access: Readers
Field Access: Signing
Form Access
Form Access: Groups
Section Access
Section Access: Groups
View Access: Encryption

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

W

ith server, database, and client security in place, one additional level of security is offered through the design elements themselves. In fact, the design elements provide some of the tightest data security available. In this chapter, you’ll examine forms, views, and agents to gain an understanding of the design-level security attributes at your disposal.

Forms

Forms serve as the viewing mechanism and the creation mechanism for documents in a database. The level of security that can be applied at the form level protects document access through the form access list and special fields placed on the form.

Document Security through Form Access Lists The form access list is used to isolate user activity within a database with many forms. Not all users should be able to create new documents with a particular form; however, they might need to create documents with a different form. To accomplish this type of isolation in a single database, the form access list is used to specify which users will be able to do two things using the form: 

Create documents with the form.



Read documents created with the form.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Forms

293

By default and in the absence of any other security measures, all users with Reader access or above to a database can read the documents created with the form. When the default is disabled, individual users, groups, roles, and servers can be selected from a list to specify who can read documents with the form. Selecting this option adds a special hidden field to a form called $Reader, which contains users, groups, roles, and servers allowed to read the documents. The form access list setting is shown in Figure 7.1. FIGURE 7.1

Form access list

Also by default, all users with Author access or above can create new documents using the form. This is useful for preventing all but a specified set of users from creating new documents using the form, regardless of their access privilege to the database. If a user does not pass the form access list security, the form will not appear in the Notes client Create menu. Normal behavior is for form names to appear in the Create menu.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

294

Chapter 7



Design Element Security

Document Security through Fields Another layer of document security that can be applied involves using special security fields. This type of security prevents users from seeing or editing certain documents. In addition, you can encrypt fields of data in a document to protect sensitive fields within the document. The techniques of applying document-level security revolve around the use of special fields that you add to the form.

Authors Fields Programmers can add Authors fields to a form by selecting the Authors type for the field type, as shown in Figure 7.2. Authors fields are also known as Author Names fields. The actual field name itself is immaterial and can be any unique name. FIGURE 7.2

Authors field

The behavior of an Authors field refines an Author-level user’s database access by preventing the user from editing documents even if he or she created the document. This type of behavior is desirable when you have multiple users in a database, all of whom require Author access, but at the same time you need to limit edit capabilities.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Forms

295

Here’s an example: imagine that you have an application that allows users to guess lucky numbers over the Internet for the chance to win a free bottle of wine. Ideally, you want the users to be able to create the document, add their lucky numbers, and then not edit the lucky numbers after they submit them yet still be able to see them. To do this, you give the users Author access to the database. However, if you left it at that, with Author access, the user could go back in and edit their own document in the future and, in this case, change their lucky numbers. This is not exactly what you want, since you don’t want users to be able to edit their numbers. By placing an Authors field on the form and leaving its value empty, no one will be able to edit the user’s lucky number document, including the user who authored the document. Using an Authors field affects a user’s ability to edit their own documents later. You should know several important points when using Authors fields: 



If an Authors field value is left empty, no one will be able to edit the document. The values in an Authors field can include usernames, group names, roles, and server names.



An Authors field can contain multiple values.



Authors fields only affect users with Author access to the database.



A document can contain more than one Authors field.

The value for an Authors field can be Editable, Computed, or Computed When Composed.

A special formula that works with Authors field values is @Author. The function returns a text list of all the authors of a document. It does this by first looking for a field of the Authors type and returning the value from the field. If there is no Authors field, Domino looks for a From field and then an $UpdatedBy field and returns the value from that field. The $UpdatedBy internal field is automatically maintained by Domino, and if an Authors field exists, $UpdatedBy automatically adds the names of users who have edited the document to the field.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

296

Chapter 7



Design Element Security

Readers Fields Readers fields are similar in concept to an Authors field in that they refine a user’s access to individual documents in a database. Readers fields are also known as Reader Names fields. In contrast to Authors fields, Readers fields limit who is able to see, or read, documents. Figure 7.3 shows how to create a field of type Readers. FIGURE 7.3

Readers field

As an example, consider the lucky numbers document again. If you add a Readers field to the document and give it a value of [STAFF], then only users who belong to the [STAFF] role will be able to see the documents after they are created. If the user who created the document is not in the [STAFF] role, the user will not be able to see the document. When using Readers fields, keep the following points in mind: 



If a Readers field value is left empty, the field is ignored and has no effect. The values in a Readers field can include usernames, group names, roles, and server names.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Forms

297



A Readers field can contain multiple values.



Readers fields apply to anyone with Reader access or above in a database.



A document can contain more than one Readers field.

The value for a Readers field can be Editable, Computed, or Computed When Composed.

$PublicAccess Another type of field you can place on a form to affect security for a document is $PublicAccess. By adding this field and giving it a value of “1,” as shown in Figure 7.4, the document becomes marked as a public access document. FIGURE 7.4

$PublicAccess

Adding the field to a form is step one of three needed to complete the process of creating a public access document. In addition to adding the field, you need to mark the form and a view to display the document as public access as well. This is done using the form or view’s property box. In fact, all of the following design elements can be designated as public access documents using the object’s Properties box: 

Agents



Folders

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

298

Chapter 7



Design Element Security



Forms



Outlines



Pages



Views

Once a public access document is completely created, users who have the access control privilege to read or write public access documents can work with the public access document you created. Figure 7.5 shows these ACL settings for the Anonymous user who has No Access to the database. Regardless of this No Access setting, Anonymous users can read and write any public access documents. FIGURE 7.5

Public access privilege

Public access documents are primarily used in conjunction with the No Access, Depositor, and Reader access levels to give users an additional path for working with documents without granting them access to the database. A familiar example of public access documents is your calendar in your mail database. You want the ability to allow people to see your calendar, but you don’t want to give them any access privileges to your mail database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Forms

299

SecretEncryptionKeys Field encryption in documents does not use the public and private keys stored in a user’s ID file and the Domino Directory. Instead, secret encryption keys created by the programmer are used and distributed to the users who need the key. A special field, SecretEncryptionKeys, is used by designers to help manage the secret encryption keys applied to a form.

If the value of the SecretEncryptionKeys field is null, the document will not be encrypted.

The field is added to a form by a programmer, and its value is manually set to be the names of the secret encryption keys used to encrypt a document. Before creating this field, three things have to take place to encrypt a document: 

Create one or more fields that can be encrypted.



Create a secret encryption key.



Apply a secret encryption key to a document.

To enable a field for encryption, you have two choices: use the Password type field, which is automatically ready for encryption, or enable field encryption in the field’s Properties box. The property to enable a field for encryption is found on the Advanced tab of a field’s Properties box and is shown in Figure 7.6. Any field can be enabled for encryption. FIGURE 7.6

Enabling a field for encryption

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

300

Chapter 7



Design Element Security

When a field that is enabled for encryption exists on a form, the data values are stored as clear text unless an encryption key is applied to the form. To apply a key, first you need to create a key. This is done in the Encryption area in the user ID of the person creating the key, generally the programmer or designer, as shown in Figure 7.7. The key can be created with any name. While the key itself is actually a hidden combination of ASCII characters, you will only be able to see the key’s name, not its value. FIGURE 7.7

Creating a secret encryption key

With a key created, a form containing fields that have been enabled for encryption can now be encrypted. Once the key is applied when the user saves a document created from the form, the data values in the field are encrypted and visible only to users who have the secret encryption key in their user ID. Figure 7.8 shows the area on a form’s Security tab in the Properties box that is used to apply a secret encryption key to a document.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Forms

FIGURE 7.8

301

Applying a secret encryption key

An encryption key can be changed or removed after the document has been saved. This can only be done by someone who already has the existing encryption key and has edit access to the document. To modify the encryption key, the formula @Command([EditEncryptionKeys]) is used.

Sign Another field that can be added to a form to provide a measure of document security is the Sign field. The Sign field takes a value of “1” to signal that the field should attach the signature of the sender to the field when the document is mailed. When the document is mailed, a hidden field, $Signature, is added to the document, and this field contains the user ID of the sender. When the recipient opens the document, the sender’s name appears in the Notes client status bar. The Sign field only signs fields that have been sign-enabled. To enable a field for signing, use the Security Options property on the Advanced tab of the field’s property box, as shown in Figure 7.9. FIGURE 7.9

Enabling a field for signing

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

302

Chapter 7



Design Element Security

Fields can only be signed if the document is mailed or if the field is placed in a controlled access section.

Field Editor Access Edit access to a field can be limited through a field property. On the Advanced tab of a field’s property box, you can select the security option Must Have At Least Editor Access To Use, as shown in Figure 7.10. FIGURE 7.10

Field edit access

This field setting controls whether the field can be edited in existing documents. New documents can still be created by users with at least Author access.

Document Security through Sections Sections are regions on a form that are encapsulated in collapse and expand areas. While Notes supports two types of sections, standard and controlled access, only the controlled access section offers security to the document contents. This type of section offers security by both controlling access and allowing fields to be signed.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Views

303

Controlled Access Controlled access sections allow specified users to edit the data stored in the fields of the section. All users can see the data, but only certain users can edit it. Figure 7.11 shows the property box setting to enable users to edit data in the section. A formula is used to control which users can edit the data. FIGURE 7.11

Controlled access section formula

In this example, a specific user’s ID name has been hard-coded as the computed value for the section. The value can equate to any user, a list of users, groups, roles, and servers.

Signing Fields Controlled access sections can also contain signed fields. In fact, if a document is not mailed, fields that have been enabled for signing are only signed if they are inside a controlled access section.

Views

V

iews offer little in the way of security to data items stored in documents; however, they do provide a few speed bumps to slow the average user down. Since a user may have been granted the rights to create their own views, the user is in a position to create a view just like the one you’re trying to stop them from seeing. Two mechanisms, however, will slow them down, and often the idea of “out of sight, out of mind” will be enough to meet your application needs. The two mechanisms are view access lists and hiding a view.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

304

Chapter 7



Design Element Security

View Access List View access lists determine which users can see which views in a database. The view access list is set using a view’s Properties box. The default is for all users with Reader access or above to be able to see and use a view. You can disable the default and, instead, select users, groups, roles, and servers from the database ACL or the Domino Directory to grant access to a view. Figure 7.12 shows a view access list that has been configured to allow only users in the WineReviewers group. FIGURE 7.12

View access list

Users who are not in the WineReviewers group will not be able to see the view. This does not prevent them from creating their own view with the identical view selection criteria.

Hiding Views Another view speed bump in a user’s database experience is hidden views. Programmers create hidden views frequently, often using them for database lookups and other behind-the-scenes programming needs.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Views

305

Creating a Hidden View The technique for creating a hidden view is easy…simply surround the view name with parentheses. After naming the view with parentheses, the view displays in the list of all views with a chevron to its left, another indicator that it is a hidden view. Figure 7.13 shows how a hidden view appears in the list of views in Designer. FIGURE 7.13

Hidden view

Displaying a Hidden View Users can display all the hidden views in a database by using a keyboard combination when opening the database. To see hidden views, the keys Ctrl+Shift are held down while the database is opened, for instance, using the File  Database  Open menu sequence.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

306

Chapter 7



Design Element Security

Hidden views are truly hidden from Web users since they do not have a Notes client that allows them to show the views using the Ctrl+Shift and open technique.

Agents

A

gents are code modules that can be called by name within a database. These code modules are used to accomplish database utility tasks, handle scheduled database duties, and act as aids in automating workflow processes. Agents are the indispensable glue that often brings an application together. However, since they are code modules that can touch many areas of a database, including the data, agents are also a security concern. To address the security concern, let’s explore agents from three perspectives: who can create agents, who can run agents, and what access control level an agent has when it runs.

Creating an Agent Users and programmers with a Notes client or the Domino Designer client can create agents in a database. Common sense would tell you, however, that some restrictions apply, starting with the familiar database security checkpoint, access control privileges.

ACL Privileges Required to Create an Agent The ability to create agents is governed by a user’s access control level in the database as well as optional ACL privileges. The optional privileges determine whether the user can create personal or shared agents. A personal agent can only be run by the user who created it and in the database in which it was created. Shared agents, in contrast, are available to all users of the database. By default, agents are created as personal and need to be marked as shared by the creator. In addition to the type of agent, the type of code used to write the agent plays a role in whether a user can create an agent and where it can be created. LotusScript and Java are robust programming languages with more capabilities than Simple Actions and Formula Language, and therefore, the ability to create these types of agents requires a special privilege in the ACL.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Agents

307

Table 7.1 describes the agent types, code types, and access privileges required by Notes client users to create agents in databases. Database Access Levels for Creating Agents

TABLE 7.1 Agent Type

Type of Code

Minimum ACL Level

Additional ACL Privileges Required

Personal

Simple Actions, Formula Language

Reader

Create personal agents

Shared

Simple Actions, Formula Language

Designer

None

Shared

LotusScript, Java

Designer

Create LotusScript/Java agents

Agents cannot be created by Web users, regardless of ACL privileges.

Running an Agent A user’s ability to run an agent depends on the runtime environment and the access control level associated with the agent. The runtime environment will either be a user’s local machine or the Domino server. If an agent is invoked by a user interactively, the runtime environment of the agent is the user’s local machine. Since users generally have Manager access to databases on their local machine, security restrictions are avoided. When an agent runs on a scheduled basis in a server-based database, its runtime environment is the server and it therefore uses server-based resources. For agents that run on the server, there are three settings in the Agent Restrictions area of the server document that control which users, if any, are allowed to run agents on the server as well as what type of agents they can run. Run personal agents This server document field specifies the names of users and groups who can run personal agents on the server. By default, this field is empty, which means that anyone can run personal agents. In addition to this server setting, users must also have the optional ACL privilege in the database to create personal-agents access for that particular database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

308

Chapter 7



Design Element Security

Run restricted LotusScript/Java agents This server document field specifies the names of users and groups who can run LotusScript and/or Java agents that use a subset of the language features. The agents are restricted from doing certain things; namely, this access level does not allow the specified individuals to perform file system operations (file I/O), modify the system time, or run operating system commands. By default, this field is empty, which means that no users can run restricted agents. Run unrestricted LotusScript/Java agents This field specifies the names of users and groups who can run LotusScript and/or Java agents without any restrictions. Unrestricted agents have complete access to the server’s operating system and all Domino features. By default, this field is empty, which means that no users can run unrestricted agents.

Agent Access Control Every user who has access to a database is associated with a specific access control level. What would happen if you logged into a database with Reader access and ran an agent that edited documents? Would the agent run? Or perhaps a better question is, should the agent run? In the same way that a user has an access privilege to a database, an agent has an access privilege in the database too. There are two factors to consider when determining an agent’s access privilege: the ACL of the user running the agent and the ACL of the user who last saved the agent. One of these is used as the effective ACL of the agent at runtime. Table 7.2 describes the three ACLs associated with an agent. TABLE 7.2

Agent ACL Perspective

Description

Signer’s ACL

The access level of the user who last saved the agent

Invoker’s ACL

The access level of the user who is invoking the agent

Effective ACL

The access level of the agent at runtime, which is either the signer’s or the invoker’s ACL

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Agents

309

The following rules determine whether the signer’s or invoker’s ACL will be used as the effective ACL: 





If an agent is running interactively in local memory, the invoker’s ACL is used. If an agent is running in the background on the server, the signer’s ACL is used. If an agent is invoked by the server, the signer’s ACL is used.

When troubleshooting agents, check the agent log to see what security the agent had at runtime. If an agent runs interactively just fine but fails when run scheduled on a server, there is a high likelihood that the agent doesn’t have the proper ACL privileges.

Web ACL and Agents Whenever a Web user invokes an agent, it runs on the server due to the stateless nature of the HTTP communication between a server and a browser. This means that the agent will run with the access privilege of the agent signer. Since Web users will either access a database by logging in with a username and password or by using the Anonymous entry in the Access Control List, you can enable an agent property to run the agent with the Web user’s privilege instead of the signer’s access privilege. This setting is shown in Figure 7.14. FIGURE 7.14

Run Agent As Web User

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

310

Chapter 7



Design Element Security

Script Libraries Security A script library is a repository area for named LotusScript code modules that can be called from multiple points in a database. Script libraries reduce code duplication and provide a place for a single point of maintenance for LotusScript routines. As a security side note, if code in a script library is called by an agent, no security checks or ACL verification are done on the code in the script library module.

Internet Inter-Object Request Broker Domino R5 supports the ability to create applets that perform Domino tasks, just like LotusScript agents. Normally Java applets are restricted from accessing native operating system calls, like the ones used when accessing Domino. A new R5 server task, however, makes this possible. The task is called DIIOP, which stands for the Domino Internet Inter-ORB protocol. This server task allows Java applets to communicate with the Domino Object Request Broker (ORB) server program, which is a server task that serves up Domino objects. Both the DIIOP and ORB server tasks must be running on the Domino server for Java applets to use Domino objects. In a similar manner to the agent restrictions in the server document, two fields in the server document are used to limit a user’s ability to run restricted and unrestricted Java/JavaScript and COM objects. The distinction between restricted and unrestricted is the same as for agents; namely, unrestricted code has access to the external file system and its resources, while restricted code does not. Run restricted Java/JavaScript/COM This field specifies the users and groups that are allowed to execute restricted Java applications and Java applets over IIOP, Java servlets and JavaScript over IIOP, or COM applications (which include Active Server Pages and VBScript) on the server. The default is blank, which means that no users can run this type of code. Run unrestricted Java/JavaScript/COM This field specifies the names of users and groups that can execute unrestricted Java applications and Java applets over IIOP, Java servlets and JavaScript over IIOP, or COM applications (which again include Active Server Pages and VBScript). The default is blank, which means that no user can run this type of code.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Summary

311

Summary

In this chapter, you have examined security from the design element perspective. Design elements such as forms, views, and agents can all be secured in a way that increases the overall protection offered by your application especially when more than one type of security is employed. Combining design element security with server, database, and client security, Domino gives you a way to build secure applications.

Key Terms Before taking the exam, you should be familiar with the following terms: agent Authors field controlled access section encryption hidden view public access document Readers field sign

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

312

Chapter 7



Design Element Security

Review Questions 1. Arthur has created a LotusScript agent in a database on the ORG2741

server. When he tries to save the agent a message dialog is displayed with the message “You are not authorized to perform that operation.” What database access level does he have, and what is the minimum access control level he needs to be able to create this agent? A. Reader and Designer B. Author and Designer C. Editor and Designer D. Designer and Manager 2. Brianna has listed four encryption keys in the SecretEncryptionKeys

field on her document. When the document is mailed to users, how many keys are required to decrypt the document? A. One B. Two C. Three D. Four 3. Christopher would like to run scheduled LotusScript agents on the

ORG2741 server. These agents do not access the file system. What is the minimum access needed in the server document for this action? A. Run Personal Agents B. Run Restricted LotusScript/Java Agents C. Run Unrestricted LotusScript/Java Agents D. None

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

313

4. Darlene wants to track the names of the encryption keys she’s using in

a form by adding a special field to store the names. What field name should she give this field? A. EncryptionKeys B. SecretEncryptionKeys C. Sign D. $Signature 5. Edgar has changed the default form read access list to limit access to users

in the WineMaster group. What field will this action automatically add to documents created with the form? A. $FormAccessList B. $UpdatedBy C. $Signature D. $Readers 6. Fiona wants to prevent Anonymous Web users from working with a set

of views she’s created but wants Notes users to see the views by default. What design element security mechanism can she use to do this? A. Form access list. B. View access list. C. Hidden views. D. Assign No Access to the Anonymous entry in the ACL. 7. What approach can Geoffrey take to limit who can create Product

Profile documents from the Notes client’s Create menu? A. Disable the Create menu. B. Use an underscore (_) character at the beginning of the Product

Profile form name. C. Apply a form access list. D. None; all form names will appear in the Create menu.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

314

Chapter 7



Design Element Security

8. Hyacinth has Author access to a database and is included in the value

of the Readers field that is on the ProductProfile form. An Authors field on the form is blank. Which activities best describe the actions she can take on ProductProfile documents she creates? A. Read and edit B. Read only C. Edit only D. Read, edit, and delete 9. Ike has given Designer access to the programmers on his team. He

does not want them creating LotusScript agents. What can Ike do to prevent them from coding this type of agent? A. Disable the Create LotusScript/Java Agents option in the ACL. B. Disable the Create Shared Views option in the ACL. C. Disable the Create Personal Agents option in the ACL. D. Nothing; all users with Designer privileges can always create

LotusScript agents. 10. Jewel has added an Authors field to a form but not provided a value for

the field. What effect will this have on documents created with the form? A. No users will be able to edit the documents. B. All users will be able to edit the documents. C. Only users with Author access will be able to edit the documents. D. Only users with Manager access will be able to edit the documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

315

11. Karl has never used Authors and Readers fields. What statement

would you use to describe the power of these types of fields? A. Authors fields refine Author access to documents while Readers

fields refine read access to documents. B. Authors fields and Readers fields cancel one another out. C. Authors fields refine edit access to documents while Readers fields

refine read access to documents. D. Authors fields refine edit access to a database while Readers fields

refine read access to a database. 12. Lara wants to limit the view she is creating to be used by only the

WineReviewers group. How can she do this? A. Apply a view access list specifying only the WineReviewers group. B. Give the WineReviewers group Reader access to the database. C. Add the special field $Readers to the documents she wants the

WineReviewers to see, and specify WineReviewers as the value of the field. D. Modify the form properties to encrypt the documents and only

give the key to the users in the WineReviewers group. 13. Marcelo has Author access to the WineMaster database. The Product-

Profile form in the database has an Authors field on it that does not contain Marcelo’s username. Which of the following describes what he can do with these documents? A. Edit. B. Delete. C. Read. D. Nothing; he cannot see these documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

316

Chapter 7



Design Element Security

14. Noreen and Doreen both have Author access to the WineMaster data-

base. The ProductProfile form includes an Authors field that contains only Noreen’s username. Which statement best describes who can create and edit ProductProfile documents in the database? A. Noreen and Doreen can both create and edit. B. Noreen and Doreen can both create, but only Noreen can edit. C. Noreen and Doreen can both create, but only Doreen can edit. D. Neither Noreen nor Doreen can edit. 15. Ozzie and Harriet both have Editor access to the WineMaster data-

base. The ProductProfile form includes an Authors field that contains only Harriet’s username. Which statement best describes who can create and edit ProductProfile documents in the database? A. Ozzie and Harriet can both create and edit. B. Ozzie and Harriet can both create, but only Ozzie can edit. C. Ozzie and Harriet can both create, but only Harriet can edit. D. Neither Ozzie nor Harriet can edit. 16. Priscilla created a form and applied a read access list. Her database

will be used by both Notes and Web users. With which type of user can a form read access list be used to limit read capability? A. Notes B. Web C. Notes and Web D. Neither

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

317

17. Quincy does not see WineReview documents in the WineMaster

database, but he noticed that Rip, his office mate, can see them. Which security mechanism is a likely cause of this behavior? A. Field encryption B. $Readers field C. Form read access list D. View read access list 18. Rhonda wants to take full advantage of the public access document

feature in Notes. Which of the following does she not have to do to effectively use public access documents for a form she is creating? A. Add the field $PublicAccess with a value of “1” to the form. B. Mark the form to allow public access use. C. Mark the database ACL for users to use public access documents. D. Mark the database property to allow public access use. 19. Sanford wants to create a form that allows two different groups to

control the contents of a single document. Neither group is allowed to edit the other group’s information, but all information must be visible at all times. What security mechanism should he use? A. Field encryption B. Roles C. One controlled access section D. Two controlled access sections 20. Teresa is about to use an Authors field for the first time. Which of the

following is not a true statement about Authors fields? A. An Authors field can contain multiple values. B. Authors fields only affect users with Author access to the database. C. Authors fields override the Access Control List setting. D. A document can contain more than one Authors field.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

318

Chapter 7



Design Element Security

21. Ulysses has granted a default of Author access to his database. How-

ever, he wants to prevent OpinionSurvey documents from being edited after they are created. How can he do this? A. Add an Authors field to the form and exclude the names of the

users from the field who should not be allowed to edit. B. Use a form read access list. C. Use a form create access list. D. Use the property Must Have At Least Editor Access To Use. 22. Vonda’s username is listed in an Authors field in the ProductProfile

form in the WineMaster database. What access privilege does she need to edit ProductProfile documents she creates? A. Manager B. Editor C. Author D. Depositor 23. Wayne is using the default view access list on all the views in his database.

How will this affect the users of his database? A. Users with Reader access to the database will be able to edit

documents in the database. B. Users with Reader access to the database will be able to edit

documents using the view. C. Users with Reader access to the database will be able to see the

views. D. Users with Reader access to the database will be able to read the

documents in the database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

319

24. Xenia noticed that the documents created with the ProductProfile

form seem to have a $Readers field on them. She does not see this field in the form’s design. What accounts for the presence of this field? A. The form has a Readers field on it. B. The form has a form read access list applied to it. C. The form contains an Authors field. D. The $UpdatedBy field does not exist so $Readers is used. 25. Yang has created a multivalued field called SecretEncryptionKeys.

What will happen if he does not provide a value for the field? A. The documents created from the form will not be able to be edited. B. The documents created from the form will not be able to be

opened. C. The documents created from the form will not be able to be

mailed. D. The documents created from the form will not be encrypted. 26. Zoraida wants to assign the users of her database the minimum access

level that will allow them to create their own agents in a database. What level should she assign? A. Depositor B. Reader C. Editor D. Designer

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

320

Chapter 7



Design Element Security

Answers to Review Questions 1. A. If you have Reader access to a database on a server, you have

the ability to create agents. Only personal agents can be created with Reader access, and the type of code allowed is simple actions or formulas. The user additionally needs the ACL privilege to Create Personal Agents. The minimum access level needed to create LotusScript agents is Designer. 2. A. Even though four encryption keys have been specified for a document,

only one is required to decrypt the document. 3. B. Since no file system manipulation will be occurring in the LotusScript

agents, the minimum access required would be Run Restricted LotusScript/Java Agents. 4. B. The special field SecretEncryptionKeys can be created as a multi-

valued field to store a list of the encryption keys for the form. If this field has no value, the document will not be encrypted. 5. D. The field $Readers contains the names of the users, groups, servers,

and roles that have been granted read access through the form access list. 6. B. Using the view access list in the view’s properties to specify that all

users except Anonymous should be able to use the view will prevent Anonymous users while allowing other users. 7. C. A form access list limits who can read or create documents with the

form. If a create access list is applied, only users allowed to create new documents with the form will see the form type on the Notes client’s Create menu. 8. B. Since she is not listed in the Authors field, Hyacinth cannot edit

documents she creates. She can, however, read them. She may even be allowed to delete them.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

321

9. A. A designer must have the Create LotusScript/Java Agent option

enabled in the ACL to create LotusScript agents. This option is enabled by default but can be disabled. 10. A. Leaving an Authors field blank prevents anyone from editing the

documents in the future. Not a bad security measure if it’s what you intended but a pretty bad one if it’s not what you intended! 11. C. As a document-level security mechanism, Authors fields refine edit

access to documents while Readers fields refine read access to documents. 12. A. A view access list defines who will be able to read, and therefore see,

a view. By specifying the WineReviewers as the users who can see the view, no other users will be able to see that particular view. 13. C. Since he has Author access, Marcelo can create documents with the

ProductProfile form but he cannot edit them. He can, however, see them, so C, read, is the correct answer. 14. B. Since Doreen’s username is not listed in the Authors field, she can

create but not edit documents from the ProductProfile form. 15. A. Since Ozzie and Harriet have Editor access and not Author access,

they are unaffected by the Authors field. 16. C. A form’s read access list can include both Web and Notes users and

applies to both. The Anonymous user can be listed as a form read access entry to either prevent or allow Anonymous access. 17. C. The form read access list is the best candidate; however, the view

read access list is a good second choice. The difference between the two is that the view read access list is a speed bump or barrier while the form read access list definitely can be used to prevent certain users from seeing documents created from a form. 18. D. A database cannot be marked to allow public access use. This is a

setting that takes place at the design element level in conjunction with the ACL.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

322

Chapter 7



Design Element Security

19. D. While roles might be useful, using two controlled access sections

is the best way to allow both groups to see the data while limiting edit access for areas to a specific group. 20. C. Authors and Readers fields refine, not override, a database’s Access

Control List. The ACL is always in effect. 21. A. By adding an Authors field to the form, Ulysses can specify users who

should not be allowed to edit the documents after they are created. 22. C. Authors fields only apply to users with Author access in a database. 23. C. View access lists determine who can see the view, not who can read

or edit documents. The default view access list is that all users with Reader access or above can see the view. 24. B. Creating a read access list for a form using the form’s properties auto-

matically adds the reserved and hidden field $Readers to all documents created from the form. The field contains the names of users, groups, servers, and roles allowed to read documents created with the form. 25. D. The SecretEncryptionKeys field helps manage and track the secret

encryption keys used to encrypt fields on a document. A side effect of using this field is that if the value evaluates to null, meaning no keys are listed in the field, the document will not be encrypted. 26. B. The minimum access level required to create personal agents is Reader.

This means that the additional ACL privilege to create personal agents must also be assigned to the user.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Chapter

Workflow Applications

8

LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Creating mail enabled forms
Creating Mail-in Databases
Creating workflow related fields: conditional/unconditional fields
Creating workflow related fields: hide when fields
Creating workflow related fields: keyword fields
Creating workflow related fields: reserved word fields
Creating workflow related fields: workflow related field attributes
Creating workflow related forms: mail enabled forms
Creating workflow related forms: setting workflow related form attributes
Creating workflow related sections
Creating/distributing workflow tracking databases
Creating/setting up workflow roles: external to Notes
Creating/setting up workflow roles: within Notes
Creating/setting up workflow routing rules (addressing) using formulas: Booleans
Creating/setting up workflow routing rules (addressing) using formulas: conditional/unconditional
Creating/setting up workflow routing rules (addressing) using formulas: constants

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com


Creating/setting up workflow routing rules (addressing) using formulas: variables
Creating/setting up workflow routing rules (addressing) using formulas: @Commands
Creating/setting up workflow routing rules (addressing) using formulas: @Functions
Creating/setting up workflow routing rules (addressing) using multiple mail systems
Determine Workflow control
Distribution through routing
Mail enabled field problems: field attributes
Mail enabled form problems: workflow related
Mail encryption
Mail-in database problems
Parallel/Serial distribution
Planning for multiple mail systems
Setting up events
Setting workflow related form attributes
Tracking through mail-in databases
Tracking through replication
Workflow distribution problems: replication
Workflow distribution problems: routing
Workflow distribution problems: roles
Workflow distribution problems: rules

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

I

t’s no secret that workflow and collaboration are two of the prime reasons Lotus Notes Domino is the top groupware product on the market. The strength of the product comes from the combination of messaging, security, and programmability. It’s in the programmability area that workflow is implemented in a Domino database by you, the programmer. In this chapter, you’ll learn what workflow is, how to implement it using the Domino toolkit, and how to troubleshoot problems that might crop up.

Workflow Defined

W

orkflow describes the state-transition changes of ownership or information in a document over a period of time. The changes represent a defined business process. For instance, getting reimbursement for travel expenses incurred on a business trip represents a business process. A defined procedure is in place to ensure that you are reimbursed. The concept behind workflow is that the reimbursement form you fill out flows from one step, or state, in the process to the next until you eventually receive the money due you. Did you notice that neither the word workflow nor the phrase “business process” implies automation? That’s where Domino comes in. With Domino, you can automate a business process. So the answer to the unasked question of how workflow happens in Domino is that you, the programmer, code it to happen.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

326

Chapter 8



Workflow Applications

Benefits of Workflow Applications Workflow applications encapsulate and automate business processes that are often human-interaction intensive. Creating a workflow application can offer the following benefits to the business process itself: 

Decreased process-completion time



Streamlining of the process



Potential enhancements of the process



Improved tracking and control of the process



Reduction in total process cost



Increased profitability of the process

Tasks and Activities All businesses consist of numerous business processes. Each business process is composed of a set of steps or activities. Examples of business processes include purchasing, order management, invoicing, resource management, time tracking, expense reports, approval processes, inventory control, and vacation request procedures. All of these can be done as manual tasks, and all of them are candidates for workflow automation. Let’s examine the business process of applying for vacation leave. The process varies from company to company but might contain the following discrete steps: 1. Create an initial vacation request using a vacation request form. 2. Submit the completed vacation request form. 3. Approve or deny the vacation request. 4. Report approved vacation to shift manager.

To create workflow in Notes to model this process, you need to automate the tasks. Here’s a thought on how to make it happen in Notes: Create Create and save a Notes document. Submit Route the document to an approver. Approve/Deny Route an approval/rejection back to the submitter. Report E-mail the shift manager.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow Distribution Models

327

As you can see from this example, the idea of automating a workflow is to break the business process down into small tasks and automate each one. Completing a business process generally requires the collaboration of multiple people. Domino is known as a collaboration tool since it facilitates the exchange of information between multiple users even if they are geographically located in different places.

Workflow Distribution Models

W

orkflow applications distribute information and tasks to the people participating in the business process. A good model helps to ensure that a person who is responsible for a task actually carries out the task. The programmer designing and automating the workflow can smooth the interactions between tasks using code. Once one task is complete, the application provides the information for the next task and distributes it to the appropriate people. Workflow information distribution models can be classified into three types: Send model Sends the information directly to users. The form is stored in the document and documents are routed automatically to users involved in the workflow process. Users act on information in the documents as they are delivered into the users’ mail databases. Share model Users participating in the workflow process go to a central database located on a server to interact with documents. Users are responsible for regularly checking the database for document status. Hybrid model Uses the best of both models. Brief notification or reminder e-mails are sent to users when their attention is required to a task in the central database on a server. The e-mail contains either a link to the workflow database or a directive telling the user where to go in the workflow database. Which model should you choose? Your choice will be driven by the complexity of the business process you are modeling, the network accessibility of your

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

328

Chapter 8



Workflow Applications

users, and the database size restrictions on your servers. Table 8.1 compares the advantages and disadvantages of the three models. TABLE 8.1

Workflow-Distribution Model Comparison Model

Advantages

Disadvantages

Send

–Remote users only need to replicate their mail file to contribute to the workflow application.

–The disk space increases for workflow-application users because the logic created in the form must be stored in the document so it can be routed to the users. –The mail database needs to be replicated frequently for effective information flow.

Share

–People on the LAN can create and edit data directly in the database. –Users get to see all revisions to the document.

–Remote users must connect to the network to contribute to the workflow application.

Hybrid

–This method will have the same advantages as the send and share methods. –A user receives a short e-mail indicating that a workflow task needs processing attention. –This model conserves disk space.

–This model is usually more complex to design, making it harder and more time-consuming to implement.

To distribute information in any of the models, the timing for when an action on an activity is needed is decided either in parallel or serially. Let’s examine the implications of the two different distribution mechanisms.

Parallel Distribution Activities that do not have to be completed in a specific order can be distributed in parallel. If this is a send model database or a hybrid model, then notification or an encapsulated version of the form will be sent to every person who is interested in

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow Distribution Models

329

the data. For instance, if the vacation request needs to be approved by a manager and by the human-resources director but it doesn’t matter who approves it first, the request can be sent to both parties in parallel. There is a caveat to using parallel distribution. Since separate copies of the document are sent to all the involved parties simultaneously and independently, the users could make changes to the document that need to be managed or merged. If this back-end process for parallel distribution is not implemented, different versions of the document will exist, which may cause data conflicts. Two kinds of conflicts are possible: save conflicts and replication conflicts. A save conflict is created when two or more people modify the same fields in a document that is stored on a single shared server. A replication conflict occurs when two or more people modify the same fields in a document that is stored on multiple servers that replicate with one another. Both types are commonly referred to as replication save conflicts. Replication save conflicts can be reduced using the database property to merge replication conflicts. However, they can be eliminated if serial distribution is used in a workflow instead of parallel distribution.

Serial Distribution If you have an activity that must be completed in a specific order by specific individuals with specific privileges, then you are interested in serial distribution. Serial distribution means that tasks are carried out sequentially. The activities in the vacation request process happen sequentially. The state of the information and who owns it changes when the prior activity is completed. At the beginning of the process, the employee owns the information and its state is “new.” In the middle of the process, the state of the information is “pending” and the owner is the vacation approver. At the end of the process, the status is either “approved” or “denied” and its owner is the system itself since no further action is required. From the point at which you request a vacation until the time your request is acted upon, your request is flowing sequentially through a set of processing states or phases. With serial distribution, only specific individuals that meet a predefined criterion are allowed to edit the documents at a particular stage in the process. When the user has made the appropriate modifications to the information in the document, a predetermined user is then allowed to edit it. This process continues until the document is complete, which is generally flagged by a status field of some kind. If this is a send model database or a hybrid model, either the document itself or an e-mail containing a document link will be sent to the appropriate individuals.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

330

Chapter 8



Workflow Applications

Using serial distribution, the workflow may take longer than it would with parallel distribution, since it is done sequentially.

Implementing a Domino Workflow

D

omino provides services and methodologies to support parallel and serial workflow distribution and flexible support for the different types of workflow models. The most often used workflow capabilities and their descriptions are shown in Table 8.2. TABLE 8.2

Domino Workflow Capabilities Capability

Description

Flexible client access

Domino applications can be accessed using either Notes clients or Web clients.

Integrated mail capabilities

Workflow applications can route information to users through the built-in Domino mail infrastructure.

Modification tracking

Changes to documents can be tracked over time using document versioning with Response documents.

Replication

Flexible geographic mobility is possible through synchronizing the contents of two replica databases.

Robust security model

User identity and access rights are investigated when a user opens a database and randomly when carrying out tasks within a database.

Domino allows a programmer to combine these techniques to automate business processes into workflow processes. Depending on the type of database implemented, one or more of the techniques will solve the workflow problem.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Implementing a Domino Workflow

331

Workflow and Databases Workflow applications are comprised of a single database or a combination of databases. There are five major types of databases. The type of database used determines how information is shared with or distributed to users. The five types of Lotus Domino databases are listed as follows: Broadcast Used to relay information to multiple users; users receive information that is pushed out from a broadcast database into each user’s individual mail file. Discussion Used to coordinate discussions with multiple users, including responses and responses to responses; users add new comments to a database and read the comments of other users. Reference Used to store relatively static information; users access the database to read information. Tracking Used to track information about data; users access the database to modify fields of information and to view the status of information. Workflow Used to model business processes; users interact with a workflow database for the purpose of document approval or denial as well as reviewing its current status. The vacation request workflow application you’ve been considering can be implemented as a combination of the five database types. Table 8.3 describes the activity and relates it to the type of database that supports the activity. TABLE 8.3

Vacation Workflow Process: Database Analysis

Activity

Type of Workflow

Database Type

Create Request, Submit Request

The request will be saved in the database for future reference. An alert may be sent to the appropriate supervisors, letting them know that an approval is to be made. Changes may be tracked.

Reference, Workflow, Broadcast, Tracking

Approve Request, Deny Request

Approvals and denials will be stored for future reference. The approval or denial could be broadcast to the requesting user. The data may be tracked for future reference.

Reference, Workflow, Broadcast, Tracking

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

332

Chapter 8



Workflow Applications

Database Replication Replication is the process in which two databases exchange incremental content and design updates. Replication occurs only between two databases that have identical Replica IDs. Each time a database replicates, a log of the replication events is recorded and stored in the database. This is a feature in Domino that is useful in troubleshooting problems that may occur during replication. This event log history is actually used as part of the replication process to determine the date time stamp of when data was last synchronized between different replica copies of a database. You may find it helpful to examine a database’s replication history when trying to troubleshoot replication problems. The log, shown in Figure 8.1, can highlight transmission and delivery failures. FIGURE 8.1

Replication history

The history can be opened in Domino Designer or the Lotus Notes client using the Replication History button on the first tab of the database Properties box or using the menu sequence File  Replication  History.

Tracking Databases Tracking databases are designed to monitor the state of a document and maintain status information for each state. There is no option to mark a database as a tracking database; instead, it’s how the information in the database is used that makes it a tracking database. In addition, several features in Domino facilitate the tracking of a document in a database over time.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Implementing a Domino Workflow

333

Document Versioning One of the features that allow every state of the document to be preserved over time is document versioning. The concept behind document versioning is that each time a document is re-saved, a new copy or version of the document is generated and stored. The $VersionOpt special field can be added to a form by a programmer to allow users to create new versions of existing documents by specifying a value for the field that determines the versioning behavior. Table 8.4 details the behavior associated with the seven possible values of $VersionOpt. TABLE 8.4

Document Versioning Options Field Value

Behavior Description

0

Document versioning is disabled.

1

New saves to a document become Response documents with the menu sequence File  Save As New Version.

2

New saves to a document become Response documents automatically when the document is saved.

3

Prior existing versions of a document become Response documents with the menu sequence File  Save As New Version.

4

Prior existing versions of a document become Response documents when the document is saved.

5

New saves to a document become sibling documents with the menu sequence File  Save As New Version.

6

New saves to a document become sibling documents automatically when the document is saved.

Tracking Edits In addition to tracking versions of a document, Domino can track the history of who has edited a document over time. The internal reserved field $UpdatedBy is maintained by Notes automatically. This read-only field contains the user IDs of all users who have modified the document.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

334

Chapter 8



Workflow Applications

The only time the $UpdatedBy field does not exist and is not updated is if the form was marked to be an Anonymous form using the form properties. In this case, the $Anonymous field exists with a value of “1” and no $UpdatedBy field exists.

Servers that interact with the documents for replication purposes are not added to the $UpdatedBy field.

The @Accessed formula is useful to inspect who has edited documents, and in addition, it identifies users who have simply read the document and not edited it.

Mail-In Databases Any Domino database can receive mail if there is a routing document in the Domino Directory that tells the router where to deliver the mail. Databases that have these routing documents are called Mail-In databases. Mail-In databases can also be used as tracking databases since information is being mailed to and stored in the database and can be tracked and reported on over time. The routing documents themselves are referred to as Mail-In database documents. Workflow databases are often implemented as Mail-In databases to facilitate the movement of information in a business process. How does Domino know where to deliver the mail? A Mail-In database is assigned a Mail-In name that acts like a username for routing purposes. When the mail is being routed, the router looks up the recipients’ addresses in the Domino Directory to figure out where to deliver the mail. Among the documents the router considers in its look-up process are Mail-In database documents as well as Person and Group documents. Once the router knows where the database is located and how to deliver mail to it, the router adds the message document to the database. When a document is received by a Mail-In database, it is treated like the creation of a new document. The router then deposits the mail as a new document in the Mail-In database, similar to depositing a new mail message document in an individual user’s mail database. Creating a Mail-In Database Since Mail-In database documents are created and reside in the Domino Directory on the Domino server, you need appropriate security privileges to

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Implementing a Domino Workflow

335

the Domino Directory database (names.nsf) to create this special type of routing document. Two security privileges are required as listed below and shown in Figure 8.2: 



FIGURE 8.2

Author access to the Domino Directory with the ability to create documents The NetCreator role in the ACL

ACL for creating a Mail-In database

Domino system administrators have these privileges by default, and the administrators may also have given certain developers the same privileges. The following steps describe the process of creating a Mail-In database document: 1. Open the Domino Directory and verify that you have Author access

with the Create Document privilege enabled. 2. Use the menu sequence Create  Server  Mail-In Database to create

a new Mail-In database document. 3. Fill in the Mail-In name, description, domain, server, and filename for

the Mail-In database. 4. Save and close the document. 5. Provide the name of the Mail-In database to users and programmers

for use in the To: field of messages to be sent to the database.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

336

Chapter 8



Workflow Applications

To help you understand the information required in a Mail-In database document, the fields and their descriptions are outlined in Table 8.5. TABLE 8.5

Mail-In Database Document Fields

Tab

Field Label

Description

Basics

Mail-In name

Enter the name used to mail documents to the database, e.g., Vacation Request, making sure the name is unique for the server.

Basics

Internet message storage

Choose from three drop-down options for the preferred data format for the mail message: –No Preference (default) –Prefers MIME –Prefers Notes Rich Text

Basics

Internet address

The Internet address for this database.

Basics

Description

Place a description for the use of this document for documentation.

Database Info

Domain

Enter the domain name that the database resides on.

Database Info

Server

Enter the fully distinguished name that the database resides on.

Database Info

Filename

Enter the database path name, including subdirectories, e.g., Apps\ winemaster.nsf.

Administration

Owners

Enter the fully distinguished name of users, groups, and/or servers allowed to modify this document.

Administration

Administrators

Enter the fully distinguished name of users, groups, and/or servers allowed to edit this document.

Administration

Foreign directory sync allowed

Specify if the database mail address can be sent to foreign directories like cc:Mail.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Implementing a Domino Workflow

337

Agents and Mail-In Databases The arrival of new mail into any database, including a Mail-In database, can trigger an agent. An agent can detect changes in the state of the database, and inbound messages and documents definitely change the state of the database. Two of the changes that come into play in a Mail-In database occur before and after new mail is delivered. An agent can be set to react to either of these two state changes. The agent triggers are the Before New Mail Arrives and After New Mail Arrives state changes, as shown in Figure 8.3. FIGURE 8.3

Agent mail triggers

An example of how to put the agent trigger facility to use would be to automatically generate a “Thank You for Your Input” message to be returned to the sender of the inbound document. Troubleshooting Mail-In Database Problems Since a Mail-In database is treated like a user receiving mail, it can experience the same kinds of mail-routing problems that the average user experiences. To troubleshoot mail routing problems, try the following: 1. Use the Notes client to trace mail manually. 2. Inspect the Notes log for any problems that may have been logged. 3. Check with your system administrator.

An administrator can treat custom-developed applications as if they were user mail files, using the normal mail-tracing tools to troubleshoot problems. In addition to mail-routing problems, a Mail-In database may not allow documents to be created in it. If so, the likely cause is that security settings have not been appropriately set on the database by the administrator.

Mail Addressing and Routing Workflow applications model a business process by anticipating the expected route a process will follow. All workflow applications follow predefined rules and routes for input, approval, modifications, and comments.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

338

Chapter 8



Workflow Applications

Types of Routing There are three types of routing: 

Client-based



Role-based



Dynamic rerouting

Client-Based Routing Organizations sometimes use more than one mail system or operating system. This causes problems when creating workflow applications, because by the time the mail reaches its intended recipient, the routing information that is required to determine the next recipient may have been stripped off the message. Without the routing information, the document cannot complete its workflow lifecycle. Client-based routing gets around this problem by having the routing information and the form travel together through a message’s workflow journey. Domino achieves this by storing the form structure in the document so that it becomes part of the mail message. Role-Based Routing Roles are collections of users that are referred to using a single name in a database. Role-based routing allows the recipients of mail messages to be programmed in a general way to de-couple specific usernames from the business process and instead associate a set of users with a task in an application. This means that when the particular item has finished, the new document is sent to the new recipient or recipients based on a generic role. The advantage of this is that if individuals leave the organization, the logic of the application need not be rewritten. The database maintainer, someone with Manager access to the database, adds and removes users from database roles. Dynamic Rerouting Routing a form is often based on the value of the data entered in the form. For example, in an expense-reporting workflow application, expenses under $300 could be automatically approved by the system, expenses over $300 and under $1000 could be approved by the CTO (Chief Technical Officer), and any expenses over $1000 could be required to be approved by the CEO (Chief Executive Officer). Dynamic routing relies on a process governed by rules programmed by the database designer using conditional statements and field combinations.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Implementing a Domino Workflow

339

Mail Addressing The single most important task in successful mail routing, and therefore workflow routing, is correctly addressing the document being mailed. A document can be assigned a destination programmatically using special fields combined with formulas or LotusScript. Using a programming language like Formula Language or LotusScript, routing rules can be coded to automate the sequence involved in a business process. The issues involved with mail addressing include working with Booleans, conditional statements, constants, variables, @Commands, @ functions, and multiple mail systems. Booleans Booleans are true or false values. True is represented in the digital world as a 1. False is represented digitally as a 0. Booleans are used in conjunction with conditional statements. A typical Boolean function used in workflow applications is @IsNewDoc, which tests whether a document has been previously saved. Conditional/Unconditional Conditional statements evaluate to true or false, triggering some action in either case. Conditional statements generally test the value of a field, the state of the document, or the state of the database and take an action based on a true or false condition. As an example of an action, the following formula mails a document if it has never been saved before: @If(@IsNewDoc;@MailSend;NULL). Constants Constants are values in code that do not change over time. One famous constant is pi, the mathematical value used to calculate the radius of a circle. In LotusScript, you can define your own constants for workflow to test thresholds, for instance, checking to see if two approvers signed off on a document by testing against a constant you created and set to 2 called NumberOfSignOffsNeeded. Variables Variables are named identifiers that reference a value that either is stored in the NSF or exists in memory. Fields on forms are referred to as form variables. In workflow, variables are used to store state information. For instance, you may have a field on a form called OrderStatus that changes state from “NEW” to “PENDING” to “COMPLETE.” The variable changes programmatically and is often used for testing purposes in a conditional statement. @Commands @Commands represent the step-by-step tasks that are carried out interactively, oftentimes through the Notes client menu. Workflow automation often involves providing users with buttons and hotspots that contain @Commands to ease some of the manual interactions required to process information.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

340

Chapter 8



Workflow Applications

@ functions @ functions are the programmatic heart of workflow. Functions provide conditional statements and access to variables that are testable for the state changes that are characteristics of workflow applications. Multiple mail systems Domino workflow can be routed to Notes mail addresses as well as Internet addresses. This allows a database to be designed to support Notes workflow and Web workflow. Additionally, some formulas provide for automatic conversion to cc:Mail messaging format.

Workflow and Forms

F

orms are one of the basic design elements in a Domino database. To create a workflow application, you design forms that collect the data required by the business process. A basic form consists of fields that gather information from the users, and static text labels that describe the fields or offer the user direction on how to fill out the form. When a user adds data to a form and then saves it, a document is created. A document consists of the data items that were entered by the user, and a Domino database consists of many documents. The power of a workflow application lies in the ability of multiple individuals to contribute information to the same document. In a workflow application, the initial creator of a document uses the form supplied by a programmer to create a new document. Depending on the underlying logic of the application, another individual or a set of individuals in the company will then contribute to the document by adding or modifying content. The contributions by users often occur in a predefined order representing the sequential flow of information in the business process. This process is known as user interaction, and it connects the activities in the business process to one another.

Form Attributes Two form attributes can be set to modify the behavior of documents created with the form and allow the documents to be mailed in a workflow process. Store Form In Document This option is found on the Form Info tab of a form’s Properties box as shown in Figure 8.4. Enabling this option allows the structure of the form to be stored with each data document created using the form. This encapsulates the information used to view the document with the document itself. When the document is routed, the stored Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow and Forms

341

form seamlessly allows recipients to view the data stored in the document. Without a stored form in the document, a user’s mail file would need to include a copy of the form to display the document’s data. FIGURE 8.4

Store Form In Document

Storing the form in the document increases the size of mailed messages, but it also ensures that the recipient will be able to see all items in the document.

On Close: Present Mail Send Dialog This check-box option is found on the Defaults tab of a form’s Properties box as shown in Figure 8.5. When this option is enabled, a dialog window pops up when the document is saved to allow the user to decide whether the document should be mailed. The dialog window is shown in Figure 8.6.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

342

Chapter 8



Workflow Applications

FIGURE 8.5

Mail Send dialog

FIGURE 8.6

Save Options dialog

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow and Forms

343

Web users can participate in workflow distribution through form and view action buttons to process and route information.

Troubleshooting Form Attributes If the form is not stored in a document that is mailed to users’ inboxes, the user must have a copy of the form in their mail database to be able to view the data. A special field in the document called Form contains the name of the form used to create the document. If the user does not have the form named in the Form variable, an error message similar to that shown in Figure 8.7 is displayed. At that point, Domino attempts to display the document using the default form for their mail database, which is the Memo form. FIGURE 8.7

Cannot Locate Form dialog

It is not always practical to store a copy of the form used to create the document in every user’s mail database. In this case, it may be best to encapsulate the form into the document that will be routed to the users. This can be done by using one of the options in the send command for Java or LotusScript or by selecting the Store Form In Document check box from the form’s Properties box as shown previously in Figure 8.4.

Sections on a Form A section is a special area that you can place on a form to simplify a busy form and assist in workflow. Sections can be collapsed and expanded. The type of section used with workflow is called a controlled access section. Controlled access sections are editable by a subset of the users who are allowed to access the entire database. The information in the section is visible to all users but can only be edited by the subset of users. The Properties box of a controlled access section is used to designate which users can edit the section, as shown in Figure 8.8. By coding a formula, the programmer determines who will be able to edit the section. The formula type can be Editable, Computed,

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

344

Chapter 8



Workflow Applications

Computed For Display, or Computed When Composed. The value of the formula must evaluate to a name, a set of names, a group, or a role. FIGURE 8.8

Access formula

In addition to controlling who can edit the section, the Properties box contains settings to control the expand/collapse behavior for the document as shown in Figure 8.9. The programmer determines whether the section is expanded or collapsed automatically when the document is Previewed, Opened For Reading, Opened For Editing, or Printed. It also allows you to choose different selections based on whether the person can edit the document. By default, all selections are set to Don’t Auto Expand Or Collapse. You can also choose to Auto Expand or Auto Collapse the section. FIGURE 8.9

Expand or collapse a section

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow and Forms

345

Mail-Enabled Forms Workflow requires a good mail-messaging infrastructure, and Domino provides the following features that facilitate the automatic mailing of documents: 

Sending a link to a document



Sending documents directly



Sending documents as part of a mail memo



Sending replies to a mail memo

To use any of these features, the programmer mail-enables a form by using special reserved fields, form actions, and view actions to move information through a workflow process. Table 8.6 describes these special fields and actions. Automation Features

TABLE 8.6

Automation Feature

Implementation

Value

SendTo

Text field

E-mail addresses of recipients.

MailOptions

Text field

1 to mail automatically on save.

CopyTo

Text field

E-mail addresses of recipients on copy.

BlindCopyTo

Text field

E-mail addresses of recipients on blind copy.

Send Mail Message

Simple action

E-mail with doclink or copy of document.

Send Newsletter Summary

Simple action

E-mail with summary of document Date, Author, and Title with links back to individual documents.

@MailSend

Formula Language

E-mail document to SendTo recipients.

Send method

LotusScript

E-mail document to SendTo recipients.

FormatMsgWithDoclinks method

LotusScript

E-mail with doclink to SendTo recipients.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

346

Chapter 8



Workflow Applications

Forms that include a SendTo field with no value and, at the same time, a CopyTo or BlindCopyTo field with a value can still route mail automatically. This feature allows you to send mail to any number of users, and they will not know the other recipients of the document.

Troubleshooting Automation Features The automation features described in Table 8.6 rely on the ability of information to be routed using the Domino mail infrastructure. When a routing fails, the problem is often related to addressing problems. Let’s review some of the issues with these special fields. The SendTo Field If the SendTo field exists but its value does not contain a valid destination address, the server will still try to route the document but will fail. The failed send generates something fondly referred to as dead mail. Dead mail is stored in the server’s MAIL.BOX database, the routing database. If the On Close: Present Mail Send Dialog form property is set and no SendTo field exists on the document, an error will occur. To troubleshoot this problem, add a SendTo field to the form. The MailOptions Field The MailOptions field tells Domino to automatically route a document to the recipients in the SendTo field directly after the document is saved. If the SendTo field contains invalid values, the document becomes dead mail. Only a value of 1 is recognized in the MailOptions field. Any other value is ignored and no mailing takes place. If no SendTo field exists for the MailOptions field to use, the error dialog shown in Figure 8.10 is displayed. FIGURE 8.10

No ‘SendTo’ Field dialog

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow and Forms

347

On documents that were created with the Store Form In Document attribute, a MailOptions field should not be included on the form. If this field is present, the document will be routed whenever the recipient opens the document in Edit mode. The Send Mail Message Simple Action For the Send Mail simple action to work, a SendTo field must exist. To create the Send Mail simple action, do the following: 1. Create a button on a form or an agent. 2. Select Simple Action(s) from the drop-down menu. 3. Click the Add Action button. 4. Select the Send Document action, as shown in Figure 8.11. FIGURE 8.11

Add simple action dialog

Simple actions are only valid in agents or buttons.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

348

Chapter 8



Workflow Applications

The Send Newsletter Summary Simple Action The Send Newsletter Summary simple action specifies parameters using the dialog window shown in Figure 8.12. FIGURE 8.12

Send Newsletter Summary

If the To: field is not correctly filled in, the routing will fail. To help ensure that valid e-mail addresses are used, the button to the right of the To: field can be used to pick e-mail addresses from the Domino Directory. The @MailSend Formula The @MailSend function can be used with or without parameters. When no parameters are specified, a valid SendTo field must exist. If the SendTo field is not present or the value of the SendTo field is invalid, an error will occur. When used with parameters, the first one is required and is the recipient of the document. The syntax of the @MailSend formula is @MailSend(sendTo;copyTo;blindCopyTo;subject;remark; bodyFields;[flags])

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow and Forms

349

If any of the parameters have invalid values, the document will not be mailed. Table 8.7 details the parameters and Table 8.8 lists the optional flags that can be used with @MailSend. TABLE 8.7

@MailSend Parameter Options Option

Description

SendTo

Text or text list containing the recipient(s) of the message.

CopyTo

Optional text or text list containing the copy recipient(s) of the message.

BlindCopyTo

Optional text or text list containing blind copy recipient(s) of the message.

Subject

Optional text to be displayed in the subject field of the message.

Remark

Optional text that can be placed at the beginning of the message’s body field.

BodyFields

Optional text or text list containing the names of fields from the current document that you would like included in the mail memo. The fields will appear below the body field in the order listed.

[flags]

One or more optional flags separated with colons indicating the message’s security level and priority. All of the flags are listed in Table 8.8 and must be enclosed in square brackets as shown.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

350

Chapter 8



Workflow Applications

TABLE 8.8

@MailSend Flag Options

Option

Description

[Sign]

Add an electronic signature to the message from the user’s ID file.

[Encrypt]

Encrypt the document with the recipient’s public key from the Domino Directory. This will ensure that only the recipient with the correct private key will be able to unlock the document for reading.

[PriorityHigh] or [PriorityNormal] or [PriorityLow]

Set the priority for the message. If no priority is specified, PriorityNormal is used.

[ReturnReceipt]

Notify the sender when each recipient reads the message.

[DeliveryReportConfirmed]

Notify the sender as to whether the message was delivered successfully.

[IncludeDocLink]

Add a link pointing to the opened or selected document that this command was launched from.

LotusScript Send Method LotusScript agents are often used to trigger the routing of a document from one place to another. When LotusScript code is used to route documents, the recipient e-mail addresses are parameters to the send method. The syntax is shown below: Call notesDocument.Send( attachForm [, recipients ] ) Using this method, Domino will either create a field on the form called SendTo or override the value in an existing SendTo field. If the parameters to the send method are incorrect and the recipient addresses invalid, the router attempts to route the document and fails, again creating dead mail.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow and Forms

351

If any of the parameters have invalid values, the document will not be mailed. Table 8.9 details the parameters and the flags that can be used with the LotusScript send method. TABLE 8.9

LotusScript Send Method Parameters Option

Description

AttachForm

Value is either TRUE or FALSE. When TRUE, the form will be stored with the document when it is sent. When FALSE, the form is not stored and the default form in the recipient’s database will be used to display the data.

Recipients

This is an optional text list to specify the recipients for the document. If the SendTo field appears on the form, this document will be sent to recipients also.

For a LotusScript program to mail the document, the document must be associated with a form and it must have been saved already. If the form has not yet been saved, an error similar to the one in Figure 8.13 will display. FIGURE 8.13

No Form Associated With Document dialog

You can fix this problem by associating the document with a form using one of the following four techniques: 







Hide the button or hotspot containing the LotusScript send method until the user saves the form. Programmatically save the form using the NotesDocument save method before calling the send method. Associate the document with a form before you send it by using doc.form = “YourFormName”. Do not store the form in the document; setting the first parameter in the doc.send method to FALSE does this.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

352

Chapter 8



Workflow Applications

Workflow through Fields and Events

You’ve seen that much of the workflow automation that can be programmed for forms and databases involves mail routing and the correct use of special fields. In addition, workflow-related fields and events help move information through a process in a predetermined way.

Workflow-Related Fields Earlier in this chapter, we described ways to enable a form to be mailed. In workflow applications, sending mail is one of the keys to the success of an application. To create a mail-enabled form, fields such as SendTo and MailOptions are used. Table 8.10 lists additional fields that provide additional mail functionality to Domino forms. TABLE 8.10

Reserved Text Fields for Mailing Documents Field Name

Value and Behavior Description

Delivery Priority

H—High priority. N—Normal priority (default). L—Low priority.

Delivery Report

B—Generate a delivery report if delivery fails. C—Generate a delivery report if delivery succeeds. T—Generate a delivery report tracing the entire delivery path. N—No delivery report is generated (default).

Encrypt

1—Encrypt the document. 0—Do not encrypt the document.

MailFormat

B—Mail both data and encapsulated form structure as a cc:Mail. E—Encapsulated data and Notes form structure to attach to a cc:Mail. M—Body field of document is text and pasted into cc:Mail. T—Contents of the document are rendered as text and pasted into the body of the cc:Mail.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow through Fields and Events

TABLE 8.10

353

Reserved Text Fields for Mailing Documents (continued) Field Name

Value and Behavior Description

Return Receipt

1—Return a receipt to sender when recipient reads the mail. 0—Do not return a receipt to sender.

Save Options

1—Suppress the on save dialog prompt. 0—Do not suppress the on save dialog prompt.

Sign

1—Digitally sign the document. 0—Do not digitally sign the document.

When you make any change in a document and attempt to close it, Domino will present the options to save as shown in Figure 8.14. FIGURE 8.14

Save dialog

This behavior is perfect for most situations, but if you require the window dialog prompt to not be displayed, the special text-editable field SaveOptions will provide added functionality. When the value of SaveOptions is set to “1,” the document is automatically saved and the window-dialog prompt will be suppressed. If the SaveOptions field is set to any value other than “1,” the window dialog will still prompt to save any modifications. Using the SaveOptions field will only stop Domino from prompting the user to save any modifications made in the document since it was created or last saved. This will not stop the user from saving a document. To stop documents from being saved, you can use the Querysave form event.

Form Events Form events can trigger workflow behavior because they represent changes in the state of the document. Any event can invoke code. The code could be programmed to do tasks like route a document, pop a question box up on the user’s screen, or put the user into Edit mode of a particular document. The set of form events available in the Object Viewer is shown in Figure 8.15.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

354

Chapter 8



Workflow Applications

FIGURE 8.15

Form events

Querysave The Querysave form event, for instance, is triggered when a user saves a document executing any code contained in the event. To stop documents from being saved in a database, you can write conditional code to set a stop flag in LotusScript. The stop flag is known as the Continue variable. Continue takes on the value of True or False; when Continue equals True, the document saves; when Continue equals False, the document cannot be saved. The following code gives you an idea of how this should be coded if you want to exclude documents of a certain form type from saving: Sub Querysave(Source As NotesUIDocument, Continue As Variant) If Form = “WineMaster News” then Continue = False End Sub

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Workflow through Fields and Events

355

Queryclose If you want to force a document to be saved when a user presses the Escape key and prevent the window dialog from prompting to save the document, you have an interesting dilemma. The Save dialog can be suppressed by setting the SaveOptions field to “1” as described earlier; however, the document will not be saved if the user presses the Escape key after editing the document. To accomplish this feat you need to programmatically set the SaveOptions field to “1,” then programmatically save the document in the Queryclose event and reset the SaveOptions field back to “0.” The following LotusScript code gives you an idea of how to do this: Sub Queryclose(Source As NotesUIDocument, Continue As Variant) Dim ws As New NotesUIWorkspace Dim uid As NotesUIDocument Dim doc As NotesDocument Set uid = ws.CurrentDocument Set doc = uid.Document If uid.editMode Then doc.SaveOptions = "1" Call uid.Save doc.SaveOptions = "0" End If End Sub

Troubleshooting Form Events If the Continue variable in the Querysave event is set to False, and the SaveOptions field is set to “1,” your form could get stuck in an infinite programming loop prompting the user continuously to ask if they want to save the document—and never letting them do it! Let’s examine this below: 1. When a modification is made to the form and you close the document,

you will be prompted to save the document. 2. If you select Yes, the Querysave event will be called. The Continue

Variant is set to False in the Querysave event, which stops the save. Since the SaveOptions field is set to “1,” you will be prompted to save the document again, as in step 1. 3. This will continue until you select No or Cancel from the given

options.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

356

Chapter 8



Workflow Applications

Hiding Design Components Design components have the ability to be hidden based on a formula or document event. Hiding components is a quick way to change the look and feel of a form based on formula-related information, such as if the user is using the Notes client or is accessing the page from the Web. Hide When formulas are specified for each design element using the Paragraph Hide When tab of the Properties box as shown in Figure 8.16. FIGURE 8.16

Paragraph Hide When settings

Table 8.11 describes the different situations that can be used to hide data. TABLE 8.11

Hide When Options for Field Design Elements Field

Description

Notes R4.6 or later

Hides the element from users of Notes R4.6 or later.

Web browsers

Hides the element from Web browsers.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Summary

357

Hide When Options for Field Design Elements (continued)

TABLE 8.11

Field

Description

Previewed for reading

Hides the element when users are reading the document in the preview pane.

Opened for reading

Hides the element when users have the document opened for reading.

Printed

Hides the element when the document is printed.

Previewed for editing

Hides the element when the document is opened for editing in the preview pane.

Opened for editing

Hides the element when the document is opened for editing.

Copied to the clipboard

Prevents the element from being copied to the clipboard to be pasted elsewhere.

Hide paragraph if formula is true

A true formula condition determines the circumstances in which the information is hidden.

Summary

W

orkflow support is one of the primary strengths of the Domino product, and in this chapter, you have examined the programming capabilities that implement Domino workflow. Workflow is the movement of control and information and the automation of a defined business process. Business processes are composed of activities and interactions. Domino workflow applications encapsulate business processes and are coded to distribute information using the send model, the share model, or the hybrid model, taking advantage of either parallel or serial information distribution.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

358

Chapter 8



Workflow Applications

Key Terms Before taking the exam, you should be familiar with the following terms: @ functions @Commands activities Agent log BlindCopyTo Boolean business process collaboration constants CopyTo dead mail distinguished name Domino Directory events fields forms Hide When formulas Mail Options field MAIL.BOX Mail-In database MailOptions replication Response document Response to Response document

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Key Terms

route mail SaveOptions SendTo variables workflow

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

359

360

Chapter 8



Workflow Applications

Review Questions 1. Amanda is trying to formulate a good definition of workflow. Which

of the following describes workflow best? A. The movement of control in a defined business process B. The movement of information in a defined business process C. Both A and B D. None of the above 2. Billy is trying to understand what a business process is. Which of the

following describes a business process? A. A set of steps that describes how to perform a specific task B. A program used to accomplish a business task C. The flow of information and control D. None of the above 3. Carmen would like to understand what to use workflow applications

to do. Which of the following is a good definition of this? A. Encapsulating workflow B. Encapsulating business processes C. Both A and B D. None of the above 4. Dirk has mail-enabled a form so that an e-mail alert is sent to users

when a task needs attention in a central database. The users of the system are both in-house on the local area network and remote users. What can Dirk do to make it convenient for both types of users to easily process the information? A. Include a copy of the document in the e-mail alert. B. Store the form in the document. C. Include a doclink to the remote server. D. Make the form usable from a Web client.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

361

5. Elise’s form contains fields for mailing-address and billing-address

information. She wants the mailing address to be visible to certain users and the billing address to be visible to a different set of users. What can she do to accomplish this? A. Put the fields in a controlled access section. B. Put the fields in a standard section. C. Apply Hide When attributes using a formula. D. Apply Hide When attributes to hide when reading and editing. 6. Felipe wants a document to be mailed as soon as it is saved. Which of

the following can he use for this purpose? A. @MailSend B. SaveOptions C. MailOptions D. LotusScript send method 7. Grant wants to use the @MailSend formula without any arguments to

route a document. Which of the following fields needs to exist on the document first? A. SaveOptions B. MailOptions C. SendTo D. DeliveryReport 8. Harmony wants the radio buttons for color choices to be visible only

when a user is editing a document. What can she do to suppress the radio-button field visibility? A. Use Hide When field attributes to hide while in Read mode. B. Use Hide When field attributes to hide while in Edit mode. C. Place the field in a controlled access section. D. Place the field in a standard section.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

362

Chapter 8



Workflow Applications

9. Issac wants to place some LotusScript code in a form event to prevent

certain users from saving a document. Which of the following events can he use? A. Querysave B. Queryclose C. PostOpen D. Terminated 10. Jana is trying to decide whether to use a controlled access section or a

standard section. Which of the following is a true statement about controlled access sections? A. Users cannot collapse controlled access sections. B. Multiple users are needed to use controlled access sections. C. Users may be able to see but not edit the section. D. None of the above. 11. Kassandra is concerned about her development time line and would

like to choose a workflow model that does not take a long time to implement. Which of the following workflow models should she therefore avoid? A. The share model B. The send model C. The relational model D. The hybrid model 12. Luther wants to trigger an action when a document is closed regardless of

whether it has been edited. Which of the following events can he use to do this? A. Queryopen B. Queryclose C. Terminate D. Initialize

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

363

13. Marcia created an application that implements serial distribution to

the marketing, sales, and accounting groups. In what order will the information be distributed to the groups? A. Marketing, sales, and accounting B. Accounting, marketing, and sales C. Sales, marketing, and accounting D. None of the above 14. Nathan needs to get a return receipt sent back to the originators of a

workflow document. Which of the following fields can he place on the form to accomplish this task? A. $$Return B. $ReturnReceipt C. MailOptions D. $Signature 15. Oretha is creating an application for the sales force of her company.

The sales team is out of the office most of the time, connecting remotely. What would be the best model for developing applications for this team? A. The send model B. The share model C. The hybrid model D. None of the above 16. Phil wants to create a discussion database application. He would like to

send a message to interested individuals when information is entered into the database. What design model does this most resemble? A. The send model B. The share model C. The hybrid model D. None of the above

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

364

Chapter 8



Workflow Applications

17. Queenie needs to create an invoicing application that must go to two

department heads for approval before the document can be considered closed. What method of distribution should she implement? A. Parallel distribution B. Serial distribution C. A and B D. None of the above 18. Ricardo wants to create an application that incorporates an approval

process. The application contains a set of users who can approve tasks as they become available. What method of distribution should he try to implement? A. Parallel distribution B. Serial distribution C. A and B D. None of the above 19. Sandy knows that all replication events are recorded. Where are these

events recorded? A. The replication log for the server B. The design synopsis for the database C. The shared actions in the database D. The replication history for the database 20. Theo noticed that certain documents were not replicating between

two servers. Where should he look to see the replication events? A. In the replication log B. In the replication section in the Domino Directory C. In the replication history dialog D. In the replication design element

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

365

21. Ursula created a controlled access section that she wants to be visible

to editors of the section only when the document is in Edit mode. How can she accomplish this? A. Use expand/collapse rules for the section. B. Use the Hide When attributes for the section. C. Limit the section to being edited by users with Editor access. D. This functionality is not possible with controlled access sections. 22. Van’s workflow application mails documents to user mail files. The

users are complaining that they can’t see any data when they open the e-mail. What is a likely cause of the problem? A. The form is not stored in the document but is present in the user’s

mail file. B. The SendTo field was not created correctly. C. The document contains truncated data. D. Form is not stored in the document and is not present in the user’s

mail file. 23. Wanda wants to send users an e-mail that summarizes a workflow

document that needs processing with a link back to the document to process. Which of the following easily accomplishes this? A. Send Mail Message simple action B. Send Newsletter Summary simple action C. @MailSend function D. LotusScript send method 24. Xavier wants to mail documents directly to user mailboxes. Which of

the following should he do to ensure that the data in the document is visible? A. Do not use Hide When attributes. B. Store the form in the document. C. Use standard access sections. D. Set the database property to allow merging of conflicts.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

366

Chapter 8



Workflow Applications

25. Which formula should Yelena use to send a doclink to specified users

as part of a workflow application? A. @MailSend(“Mary Jones/”;”Action

Needed!”;(IncludeDocLink)) B. @MailSend(“Mary Jones/”;””;””;”Action

Needed!”;””;””;[IncludeDocLink]) C. @MailSend(“Mary Jones/”;”Action

Needed!”;[IncludeDocLink]) D. @MailSend(“Mary Jones/”;””;””;”Action

Needed!”;””;””;”IncludeDocLink”) 26. Zack wants to combine the @MailSend with a formula to condition-

ally send a document only if the document has never been saved. Which function will help with this task? A. @IsNewDoc B. @Accessed C. @True D. @Created

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

367

Answers to Review Questions 1. C. Workflow can be defined as the movement of information and

control through a defined business process. 2. A. A business process is a set of steps that describes how to perform a

specific task. 3. B. Workflow applications are used to encapsulate business processes. 4. A. Both internal Notes users and users who connect remotely are best

served by including a copy of the document in the original e-mail alert, which offers the fastest and most convenient access to the document. 5. C. Hide When formulas can hide fields from users based on a formula,

including being able to test to see if a user is a member of a group that should see the field. 6. C. The MailOptions field with a value of 1 automatically mails a docu-

ment when it is saved, using the SendTo field to obtain the recipient list. 7. C. The SendTo field contains the recipient list for a mail-enabled

form, and it must contain a valid value for the @MailSend to be used without any arguments. 8. A. The basic Hide When field attributes should do the trick here, sup-

pressing the radio buttons while in Read mode but displaying them in Edit mode. 9. A. The Querysave event can set the Continue variable to False to prevent

specified users from saving a document. 10. C. Controlled access sections are editable by a subset of the users who

are allowed to access the entire database. The information in the section is visible to all users but can only be edited by the subset of users. 11. D. The hybrid usually takes the longest to implement because it requires

a great amount of understanding from the user and programmer with respect to the overall business process.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

368

Chapter 8



Workflow Applications

12. B. The Queryclose event fires when a document is closed regardless of

whether it was edited. 13. A. Serial distribution will send the information from group to group,

sequentially one at a time. 14. B. The $ReturnReceipt is used to return a message back to the sender

after the recipient has read the mailed document. 15. A. Since the sales force will be connecting remotely and will not have

consistent connections to their network, developing applications that store all the needed information in an e-mail would make the sales team’s job much easier. All they would have to do when connecting to the network would be to replicate their mail file. 16. C. Since a notice, not the actual document, is going to be sent to individ-

uals, but they will be accessing the information in the discussion database, this application uses a combination of send and share, making it a hybrid. 17. B. In this case the document, or a link to the document, needs to be sent

to the correct people in a specific order and the state of the document needs to change sequentially. Therefore, serial distribution is the best distribution option. 18. A. Since a set of users can approve the items in the database, Ricardo

should send an approval notice to the set of individuals in the group, indicating work needs to be done. 19. D. All replication events are stored in the replication history dialog. 20. C. To help troubleshoot replication problems, the replication history

dialog is a great tool. This is accessed from the Properties dialog of the database. There is no such thing as a replication design element, the Domino Directory doesn’t have a replication section, and there isn’t a replication log. 21. A. A section’s Properties box contains settings to control the expand/

collapse behavior when the document is previewed, opened for reading, opened for editing, or printed and allow it to be set specifically for section editors.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

369

22. D. If the form is not stored in a document that is mailed to users’

inboxes, the user must have a copy of the form in their mail database to view the data. 23. B. The Send Newsletter Summary e-mails a summary of the document’s

Date, Author, and Title with links back to individual documents. 24. B. Storing the form in the document delivers the form structure and

the document data to the user mail files so that the data can be viewed directly. 25. B. There are six required parameters plus optional flags for the

@MailSend function unless the option of using no arguments is chosen. The flag needs to be enclosed in square brackets. 26. A. The @IsNewDoc function is a Boolean function that returns a 1 if

the document has never been saved. When used with @MailSend, it can guarantee that a document will be sent only once, at create time.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Exam 512: Domino R5 Application Architecture

Copyright ©2001 SYBEX, Inc., Alameda, CA

PART

IIl

www.sybex.com

Chapter

9

Application Planning LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Design a secure application
Design an update distribution mechanism
Design an update distribution mechanism using replication
Design applications based on the object store
Design applications for consistent ACL enforcement
Plan applications based on how attachments are handled
Design applications for replication
Plan applications based upon impact of replication on server involvement
Plan for Design distribution based on replication
Plan for Design distribution based on templates
Plan applications based on backwards compatibility
Plan application security based on Password encryption
Plan application security based on the Domino directory
Plan applications based on authentication characteristics
Plan application security based on User Ids
Plan application security based on Notes authentication
Plan application security based on Web authentication
Plan applications based on Database architecture
Plan Capacity based on bandwidth
Plan for access mode
Plan for different license types

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com


Plan for North American vs. International license types
Plan for usage
Plan for connected usage
Plan for constantly connected usage
Plan for remote access mode
Plan for disconnected usage
Design Archiving techniques based on Document characteristics

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Y

ou’re in your car driving through the countryside humming to the radio. Do you know where you’re going? Do you know the route? Do you have a map? Do you have fuel? You could wander about aimlessly for a while, but with the price of fuel and the scarcity of clean bathrooms, you might want to rethink that plan. Plan? Did we say plan? Yes, everything starts with a plan. Planning your Domino application before you begin building it is similar to preparing for a drive in the country. As an application architect, your job is to understand the business problem to be solved and code an appropriate solution to it. Your coding environment is Lotus Notes Domino, so planning will be done with the functionality of the coding tool in mind. Let’s start by understanding Domino’s infrastructure and how Domino stores, retrieves, presents, and processes information.

Laying the Groundwork

For companies that went looking for a distributed, multiplatform, client/ server database system to use as a messaging platform, application platform, Intranet platform, and Internet platform, Domino and Lotus Notes was the answer. Domino is the server component, and it’s been designed to work on a wide variety of operating systems, including Windows NT, Windows 2000, AIX, HP-UX, Linux, Solaris, OS-400, and OS-390. Lotus Notes, Domino Designer, and Domino Administrator are the Windows 32-bit clients from Lotus that interact with the server storing, retrieving, processing, and presenting data.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

376

Chapter 9



Application Planning

Distributed Database A distributed database means that there is no central server that everyone interacts with for services. Instead, servers can be located around the world or around the hall. Interactions from client to server travel through a network and are not dependent on where the server is physically located. Servers interact with one another, treating each other as clients requesting data. The distributed nature of Domino makes it ideal for working in your office, offline sitting by the pool (well, maybe not), or connected via a modem in a hotel room. Data in Notes is stored as documents in databases. These documents are called notes (you’ll be able to sleep better knowing where the product name came from!). There are four types of notes used in the system: data, design, Access Control, and database headers. Figure 9.1 depicts the four types of notes stored in a typical database. FIGURE 9.1

Notes in a database

Database header notes Access Control notes Data notes Design notes

Database header notes Store the database’s name and server location. All databases sit on a server or on the local machine. Local in Notes means the hard drive of your personal, private machine, as opposed to a network server resource. Access Control List notes Store security information about a database, making the database itself a kind of self-governing body. Data notes Store the data that is entered by end users. Design notes Allow end users to create data notes. They store the structure that gives the data shape and meaning. Design notes are also referred to as design objects and design elements.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Laying the Groundwork

377

Data Storage Model At its simplest, the Notes storage model is a container hierarchy. The operating system contains databases, databases contain documents, and documents contain items of data. Figure 9.2 gives you a graphical look at the container hierarchy. FIGURE 9.2

Notes container hierarchy

Operating system

Database

Items Company Name Address City State/Province Postal Code Telephone

Documents

If you’re a relational database person, the equivalent is an operating system, which contains tables, which contain records, which contain fields. The NotesPeek tool, which is a free software utility from Lotus, helps you examine the contents of a database from a hierarchical container perspective.

Documents Documents are the container that holds user data and presentation content. They can store a wide variety of objects including 

Rich text



Plain text



Numerical data



Images



Videos



Audio clips

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

378

Chapter 9



Application Planning



File attachments



Java applets



ActiveX components



Any other kind of object that can be embedded in a document

The database format for data is referred to as the Notes object store. This object storage model is flexible and unstructured as compared with a relational data storage model in which data characteristics are predefined and more structured. The relational model revolves around the concept of primary keys. In Notes, there is no primary key for documents, but there are several unique values that identify information in a Domino database and assist the server in its distributed database tasks. These unique identifiers are generated automatically by Notes whenever a new database or document is created, as shown in Table 9.1. TABLE 9.1

Unique Identifiers in Domino Unique Identifier

Purpose

Replica ID

Each database has a Replica ID that is unique across servers.

Document Unique ID

Each data note has a Document ID that is unique across servers.

Note ID

Each data note has a Note ID that is unique within a database.

Domino has a concept of a parent/child relationship between documents. A document created in relation to another document becomes a child document. This is known as a Response document in Notes.

Response Documents A Response document in Notes represents a relationship or a link between a Response document and another document. As an example of this relationship between documents, consider a customer management application that tracks individual human contacts within a company. Your application would model this as a Company document representing global information about the company, and Contact documents representing specific information about each of the people who are your contacts. The relationship

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Laying the Groundwork

379

between the documents would be coded such that the Contact document is a Response document to the Company document. This relationship is created with a special variable called $Ref that the Notes system adds to Response documents. $Ref stores the Document Unique ID of the parent document, similar to creating a pointer back to the parent’s address. Using this parent/child relationship, Notes can model the traditional one-to-many relationship found in relational databases. Notes does not, however, enforce referential integrity between parents and children, so it is quite possible to have orphan documents in an application that is not planned, designed, and programmed properly. So who is responsible for the referential integrity? You guessed it—you! If you allow users to delete a parent document, you need to write code to automatically process the child documents in some way. How you process them will depend on your application needs.

A Domino Application When you use the term application in Domino, it is often synonymous with the term database. A Notes database contains data in the form of parent and Response documents, the code, the graphical user interface, and security settings. a Notes database = Data + Code + GUI + Security There are essentially two kinds of Notes databases: application databases and application templates. Application database Typically has an NSF file extension, which stands for Notes Storage Facility. An application database contains data notes, design notes, Access Control notes, and database header notes. Application template Typically has an NTF file extension, which stands for Notes Template Facility. A template has the same structure as an application database but it generally does not store data notes. Figure 9.3 compares NSF note storage to NTF note storage.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

380

Chapter 9



Application Planning

FIGURE 9.3

Storage of notes in an NSF versus NTF

NTF

NSF

Database header notes

Database header notes

Access Control notes

Access Control notes Data notes

Design notes

Design notes

Application databases and application templates are used together. You can create your own templates or use ones from Lotus or third-party developers. Prebuilt templates can let you quickly create applications like discussion forums, address books, and approval cycle workflow, to name a few based on templates from Lotus. Most important, however, is your ability to make a template yourself. Templates are typically the focus of programming activity, and store code and not user data. Application databases store user data and code, and they can inherit the code (or design notes) from a template. This inheritance means that on a scheduled basis on a server, or on demand between servers and local machines, an application receives incremental changes to the design notes. The separation of where the coding activity is performed and where the user activity is performed keeps production data out of harm’s way. To test, it is common to copy production data notes from an application database into the template on the server to use as test cases, and at no point is live data at risk.

Client/Server Data in a Notes database on a Domino server is available to users with Lotus Notes clients and to non-Notes clients. Domino is the server component of the Lotus Notes Domino client/server software. Imagine a very proper butler, one hand tucked behind his back, bending toward you and presenting a silver tray full of newspapers from around the world. The butler is serving up information to a client… you! The Domino server can serve up information to a variety of client types.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Client Types

381

The first type of client to come to mind, naturally, is the Lotus Notes client. Clients make use of server information. Some not-so-obvious Domino clients include 

Web browsers



Internet mail programs and newsreaders



x.500-capable directories



Non-Notes applications

Client Types

W

hile Domino is a proprietary software product from Lotus and IBM, it is at the same time an open system serving data to many clients or acting as a client itself.

Client Access Methods Client access methods include technologies like 

Object Linking and Embedding (OLE)



Component Object Model (COM)



ActiveX



Open Database Connectivity (ODBC)



Common Object Request Broker Architecture (CORBA)

The technologies used to access Domino grow in number and capabilities as industry standards evolve. For example, older access technologies like Dynamic Data Exchange (DDE) allow Notes to behave as a client of information only, not a server. Today, in contrast, with OLE and COM, Domino can now act as either a server or a client of Microsoft application information and allow field-level data exchange. OLE, COM, ODBC, and ActiveX all provide programmatic access in a Windows 32-bit environment to data stored in Domino databases. CORBA is an additional programmatic method for accessing data. It is different from OLE, COM, and ActiveX in that its strength is accessing remote data on distributed servers; for instance, retrieving information from an Oracle database that sits on one server in an organization while Domino sits on a different one. Domino can retrieve the Oracle information using CORBA as a middleware to access the remote data. CORBA is an industry Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

382

Chapter 9



Application Planning

standard that uses Java applets to interact with network resources like databases. Domino supports CORBA as both a data source and as a client that retrieves data.

Communication Ports When clients of any type communicate with Domino, they use dedicated ports and client-specific protocols. The ports and protocol arrangement lets servers and clients agree to send and receive network messages over a prearranged channel. Table 9.2 lists popular network client types, the protocols they use to communicate, and the port or channel used to transfer messages over a network. TABLE 9.2

Clients, Protocols, and Ports Client

Protocol

Port

Lotus Notes

Notes Remote Procedure Call (NRPC)

1352

Web browsers

Hypertext Transfer Protocol (HTTP)

80

x.500 clients

Lightweight Directory Access Protocol (LDAP)

389

Secure Sockets

Secure Socket Layer (SSL)

443

Internet Mail

Post Office Protocol v3 (POP3)

110

Internet Mail

Simple Mail Transfer Protocol (SMTP)

25

Internet Mail

Internet Mail Access Protocol (IMAP)

143

News Reader

Network News Transfer Protocol (NNTP)

119

While not critical to the application development process directly, knowing the ports will help if you need to debug communication problems for a Notes application; for example, if you design an application that needs to work on the Internet and exchange data with a server behind your company’s firewall. Typically, a network administrator locks down ports with firewall software to prevent malicious tampering from the outside. Consider the case of having an NT server running Domino inside your firewall for your company’s Intranet and a Linux server running Domino as a Web server outside the firewall. The two servers will need to talk to one another, and to do that, port 1352 needs to be open. Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

383

Domino System and Application Services

When clients interact with a Domino server, they are requesting a service. In response to the service request, the Domino server then interacts with the operating system software. These interactions are shown in Figure 9.4. FIGURE 9.4

Domino service interactions Domino applications

Domino services

Operating system

To manage these communication tasks, Domino has two types of services: system services and application services. System services allow Domino to communicate with clients, other servers, and low-level computer resources, while application services allow databases to interact with one another and with network services.

System Services System services provide the communication backbone essential for authentication, directory services, database replication, and message routing. System services focus on tasks that take place at the server level.

Directory Services The Domino Directory is a Notes database that stores all the configuration information for a Domino server. The operating system filename is names.nsf. Configuration settings determine what the server is capable of and how secure it is.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

384

Chapter 9



Application Planning

Domino Directory All Lotus Notes clients as well as Web users are registered in the Domino Directory. Users can also be grouped within the Domino Directory to help in granting privileges and checking security. When individual users become members of groups, security for a database can be controlled at the group level rather than for individual users. The concept of a system directory is one that has become standard in the Internet world. Simply put, a directory is like a phone book. It provides a way to look up information you need based on information you know. When you use the phone book or a PalmPilot to find phone numbers, you start out with someone’s last name and retrieve the person’s phone number through a lookup into a directory. LDAP While the Domino directory lets Notes users look up information on the server, external clients, like Web browsers, also need a way to look up key information like e-mail addresses. To allow lookups into the Domino server from non-Notes clients, Domino supports the industry standard Lightweight Directory Access Protocol (LDAP). LDAP is an Internet directory standard that allows information lookup between directories based on the x.500 standard. The Domino Directory supports the x.500 standard through an LDAP service. With this service running, software like Outlook communicating as an LDAP client can look up information in the Domino Directory as depicted in Figure 9.5. FIGURE 9.5

LDAP interactions LDAP

Microsoft Outlook

Domino Directory

Security Security in Domino is also a system service. Domino takes a layered, topdown approach to security, and as an application programmer, you can apply as many or as few of the layers as you need. The more layers you apply, the more secure your application. Figure 9.6 presents the security options from general to most specific in top-to-bottom format. Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

FIGURE 9.6

385

Steps to good security Network O.S. Domino server Database View & Form Document Section Paragraph Field

Authentication At the top layer are the rights to access a server from the operating system and network level. Once you have access to the operating system, the Domino server authenticates a user by checking the user’s identity to verify that the user has a valid certificate to access the server. Like a traffic cop stopping a driver and checking to see that they have a valid driver’s license, the Domino server checks the certificate of the user attempting to access the server. Certificates are permissions to access a server in general, and they are stored in a user’s ID file. An ID file is created when a new Lotus Notes client user is registered on the server. The ID file contains critical information that identifies the user, including the username, the Domino certifier of the server issuing the ID, and encryption keys used to create encrypted data using digital signatures. The process of validating a user is called authentication, and it’s a major security service provided by Domino. Authentication is performed every time a user accesses a Domino server resource. Database Security Database security is comparable to the front door of your house. Once you get into the house, there are many rooms you might want to visit, but first you need to get in. The security you apply to a database as a whole guards the contents as a whole.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

386

Chapter 9



Application Planning

SERVER-BASED DATABASES

If a user passes the server’s authentication challenge, individual database security is checked for the user’s privilege authorization to access the database. Once inside a database, a variety of security measures can be put in place to protect the database contents. Stay tuned for an in-depth look at securing a database application in Chapter 12, “Application Security.” LOCAL DATABASES

When working with local databases, the server’s Domino Directory is not available, so local databases like your Address Book are not protected by the same tight security that exists on server resources. In fact, no security is enforced on a local database at all unless you enforce a consistent ACL by enabling an advanced property in the ACL. Figure 9.7 shows this ACL setting. FIGURE 9.7

Enforcing consistent ACLs

The Domino server is the bastion of security, so this lack of security enforcement on the local level is explainable because none of the server’s services are available.

Replication Also a system service, replication is an incremental field-level data synchronization process between two or more replica copies of a database. At the end of a replication, all data notes and design notes are identical in the replicated databases, unless otherwise specified in replication settings. Server and Client Replication Replication can be configured to be bidirectional and can take place 

Between two Domino servers

or 

Between a Notes client and a Domino server

On the server, replication can be automated through scheduling. For instance, two servers can be timed to replicate every 8, 16, or 24 hours.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

387

In addition to servers replicating with one another, individual users can replicate databases with a server. Mobile users often work remotely and work in disconnected mode. Notes provides an environment where users can make a local replica copy of any database, work with the data offline on a local machine, and then replicate changes back to the server when they’re back online. Replication Settings With these mobile users in mind, it’s useful to examine some of the replication options that can affect the amount and selection of data that is sent between two replica databases. Replication options are set on a database-bydatabase basis and can be set either when a new replica is first created or at any time after that. Replication settings are viewable through the database Properties box. Table 9.3 outlines the replication options. TABLE 9.3

Replication Options Option

Purpose

Remove documents not modified in x days

X is the purge interval in days; deletion stubs are purged.

Only Replicate Incoming Documents Saved or Modified After: date

Use a date to determine document replication candidates.

Receive summary and 40K of rich text only

Truncate documents before replicating.

Replicate a subset of documents

Write code to choose which documents should be replicated.

Replication settings are accessed from the database Properties box using the Replication Settings button. The settings can then be configured using the dialog box shown in Figure 9.8.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

388

Chapter 9



Application Planning

FIGURE 9.8

Replication settings

Replication History Domino tracks the replication activity that takes place on a database, associating a time stamp with each replication and recording the direction, as shown in Figure 9.9. FIGURE 9.9

Replication history

When a replication sequence is initiated, the time stamp of the last replication is used to start the process of identifying which documents and which Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

389

data items have been modified. Incremental changes are exchanged based on the time stamp of the last replication. You can access the replication history using the Replication History button on the database’s Properties box. Replication Process How does the server know which databases to replicate and which items within a database have changed? Two databases that are allowed to replicate and exchange data are called replica copies of one another, and they share an identical Replica ID, as shown in Figure 9.10. You may recall from Table 9.1 in this chapter that the Replica ID is a unique number that identifies a database on a Domino server. Two databases that share this unique number are actually multiple instances of one another and therefore can share the data. FIGURE 9.10

Identical Replica IDs Security check Authentication & authorization Replication request

Domino server

Server NSF Replica ID 8025678B:00609200

Local NSF Replica ID 8025678B:00609200

Within a replica copy of a database, Domino keeps track of when the last replication was, which fields were replicated, and who performed the replication. Every document in Notes has a unique document ID, so the server makes a list of the documents that have changed and then incrementally updates them until they are identical. MECHANICS OF REPLICATION

Replication keys off a document’s Document Unique ID, the time stamp when it was saved, the number of times it’s been saved, and the individual fields, or items, stored in the document. When the Replication task sees two documents with the same Document Unique ID, it examines the items on the documents

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

390

Chapter 9



Application Planning

to see if any incremental modifications need to be shared between the two replicas. Each time a field is modified by a user, a special flag associated with the field is incremented. This flag is called SeqNum and tracks the number of times that field has been changed. So to summarize, replication relies on five things: 

A database’s Replica ID



A document’s Document Unique ID



Date time stamp when the document was last saved



The number of times a document has been saved



A field’s SeqNum flag

By using these five tracking values, no updates to a document fall through the cracks. There is, however, the chance for multiple changes to a single document wreaking havoc in your database. Consider the case where Alex modifies the FirstName field on a document on the New York server and Norma modifies the FirstName field on the same document on the Florida server. The two servers don’t know about the change until they replicate. At that point, the database’s Replica ID is checked (and matches), the document’s Document Unique ID is checked (and matches), and the field’s SeqNum flag is checked (and matches). Domino proceeds with the replication and the result is that two documents are created where originally there was one. One of the documents becomes the main document, while the other becomes a response to that main document. The Response document is marked as a conflict document through the addition of the special flag field $Conflict. REPLICATION SAVE CONFLICTS

The presence of the $Conflict flag field indicates that a Replication Save Conflict has taken place. These conflicts require manual user intervention to compare the changes and delete one of the documents. So which document gets marked as the conflict document? Well, the good college professor answer is that it depends. Here are the rules: 



The document saved the most times is promoted to main document and the remaining document is demoted to a Response document with $Conflict present. If the two documents were saved an equal number of times, the save time stamp is examined, and the most recently saved document becomes the main document and the other document becomes the $Conflict response.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services



391

If the change that took place on a document was a deletion of the document, then additional rules apply: 





All replicas of the document are deleted if no changes were made on replica copies of the document, meaning the deletion was the only change. The document is not deleted if a change was made to the replica copy after the deletion was done, thus pulling in the date time stamp of the document change. The document is not deleted if the replica copy of the document has been saved more times than the deleted document.

Confused yet? Fortunately, the Lotus folks have this replication stuff all figured out, but without a good understanding of it yourself, you might think strange things are happening to your data.

The error condition is known as a Replication Save Conflict in Notes because it can happen when documents replicate between servers or when they are saved on the same server. The trigger is the same (users modifying the same data in the document) but the moment at which Domino notices it is different.

REDUCING REPLICATION CONFLICTS

Lotus provides two mechanisms to reduce the number of Replication Save Conflicts that occur. They are 

Document versioning



Merging replication conflicts

Document versioning allows you to save a complete audit trail of every change to a document by creating a new document each time a change is made. The new document can be associated with the original document as either a response or as the parent. Using this method gives you a good data trail, but it chews up disk space like kids eating french fries. The second mechanism, merging conflicts, gives Domino the ability to merge two replica documents where different fields were changed. So, if Sally in Kansas City changes the Address1 field and Walter in Newfoundland changes the Address2 field, then when the servers replicate, Domino will automatically merge the changes and not raise a conflict condition.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

392

Chapter 9



Application Planning

Both of these options are enabled as form settings using the form Properties box. PULL-PUSH REPLICATION

The default direction for a server’s replication is to first pull all changes from the target database back to itself, and then push out any changes to the target database. In the case where documents were deleted from the target database, the server initiating the replication would pull in the deletion stubs from the target database, apply them to itself, and then push any new changes out to the target database. So in no way should replication be considered a backup methodology for data in a database! When a database replicates, new notes and incremental changes to notes are updated in the two databases replicating. The notes replicate in the following order: 1. Access Control List notes 2. Design notes 3. Data notes

Replication and the ACL Since Access Control List notes replicate before other notes, replication obeys the Access Control settings in place on the replica databases. Users and servers must have an ACL entry that allows them to access the data in the database. As an example, if a user is not allowed to delete documents, deletion stubs will not replicate. If deletions are allowed for the user doing the replication, deletion stubs replicate just the same as an addition to a database would replicate. Elements That Do Not Replicate The Replication task updates both data notes and design notes, making it useful as a built-in distribution mechanism for updating applications. Information not stored in data or design notes, however, will not replicate, including 

View indexes



Full-text indexes

View indexes will be recreated on an as-needed basis when the replica database is opened. Full-text indexes, however, need to be manually created for each replica. Index structures don’t replicate because these structures aren’t stored as documents, and replication is document-based.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

393

Planning a replication methodology for an application should be done with the system administrator to fully understand the replication topology, schedule, and constraints in place for an organization.

Routing If replication is the system service used to exchange data between two replica databases, routing is the system service used to transfer mail-related information between non-replica databases. Router Task Message routing moves message documents to and from clients and between servers. All messages between clients travel through the Domino server. When one user sends mail to another user, the message is routed through the Domino server and then forwarded to the other user, as shown in Figure 9.11. FIGURE 9.11

Mail routing Domino server

Router Domino Directory

MAIL .BOX

User A

User B

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

394

Chapter 9



Application Planning

This server task is commonly referred to as the Router task. The routing path that the data takes between servers is dependent on the configuration established by the system administrator. While e-mail between individual users is the most popular form of routing, programmer-created Domino applications can also route documents. That means the database itself is sending mail! This is very powerful when you’re automating a workflow application. MAIL.BOX When a message is routed, the e-mail address is retrieved from a lookup into the Domino Directory and then the message is deposited in the MAIL.BOX database. This is a special database that the Router task monitors to see if anything needs routing. The Router can deliver mail to users and to mailenabled databases. Mail-In Databases Mail-enabled databases in Notes are known as Mail-In databases. This kind of database can receive mail just like a normal Notes user. The database has a username associated with it, and Domino can route mail to the database just as if it were routing mail to a user’s mail database. Mail for normal Notes users routes correctly because a Person document exists for the user in the Domino Directory. Similarly, a Systems Administrator adds a special Mail-In document for the database to the Domino Directory to mail-enable a database. The Router uses these documents to determine how and where to deliver messages for the person or database.

Application Services While system services are server-level Domino features, application services, by comparison, apply or are configured at the database level. Application services focus on the elements required to build, maintain, and run database applications, including essential services like 

User authorization



Database management services



Indexing services



Data archiving



Integrated development environment

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

395

User Authorization Access to a Domino database is controlled by the Access Control List (ACL). The ACL specifies users and their privileges within the database. Any user not explicitly listed in the ACL as an individual or by membership in a group is governed by the Default setting, which must exist for every database. Figure 9.12 shows that the Default setting for this database has been set to No Access, a very safe access level. FIGURE 9.12

Default ACL setting

Each time a user accesses a database, their user ID is first authenticated by the server and then checked for privilege authorization granted to the ID in the database being accessed.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

396

Chapter 9



Application Planning

Access Levels There are seven privilege levels ranging from Manager, which has complete access, to No Access, which prevents users from interacting with the database. The Access Levels and their privilege settings are shown in Table 9.4. TABLE 9.4

Access Control Levels

Manager

Designer

Editor

Author

Reader

Read Docs
















Edit Docs













Create Docs













Delete Docs













Modify Design







Delete database




Modify Replication




Modify ACL




Depositor

No Access







Every database ACL must have a Default setting. It also must have at least one entry that has Manager access, since Manager is the only level allowed to modify the ACL. Web Users and ACL Web users are also governed by the ACL. They can be listed explicitly in the ACL and granted a privilege level if they have an entry in the Domino Directory. Alternately, a special group name called Anonymous can be used to apply security to all Web browser users who are not explicitly listed in the ACL. When a Web browser requests information, if users are not forced to log into Domino, they are tagged as Anonymous users. All applications intended for Web deployment should have an Anonymous ACL entry with

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

397

an appropriate privilege level. If Anonymous does not exist, the Default setting will be used. There is one additional setting in the ACL that will affect a Web user’s ability to access a Domino application. On the Advanced tab of the ACL, you can enable an option that will set the maximum Internet privilege allowed for any user. This includes people who obtain access through the Anonymous group and Web users who logged in with names and passwords through the Domino Directory. Figure 9.13 demonstrates this setting. FIGURE 9.13

Maximum Internet access

If the maximum Internet privilege allowed is Reader, and Anonymous or individual Web users have privileges set to Editor, the highest access they will receive is Reader.

Database Management The Database service manages interactions within and between databases. Table 9.5 lists the tasks that maintain the health of Notes databases. TABLE 9.5

Database Tasks Service Name

Also Known As

Job Performed by the Service

Design Task

Design Refresh, Designer Task

Incrementally refresh the design of a database from a template.

Compact Task

Compaction

Remove white space from physical database storage to optimize read/write performance. Popular flags: –D Discard indexes –R Do not convert the ODS –B In place compaction with no copy –C Copy style compact to new space –L Enable users to use during compact

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

398

Chapter 9



Application Planning

TABLE 9.5

Database Tasks (continued) Service Name

Also Known As

Job Performed by the Service

Fixup Task

Fixup

Examine a database for corrupt notes (design or document) and attempt a repair or delete the corrupt note

Design Task The Design task on a server is responsible for managing the update of serverbased databases that inherit their design from a template. Once a night, the Design task looks for databases that are marked to inherit from a template. For marked databases, the Design task brings incremental changes into the database that were programmed in the template since the last time the Design task was executed.

The Design task runs on the server at 1:00 A.M. by default, updating any server-based databases that use templates. The task can also be run on demand interactively. Design Refresh on individual design elements can be stopped from rolling out automatically by marking a design element property to prohibit design replace. Compact Task The Compact task does the equivalent of a defragmentation sequence. Compact will rewrite a database’s physical storage to compress out any holes that exist in the physical contiguous space. These holes would have been created through the process of deleting documents. FREEING UP SPACE

When a document is deleted, a deletion stub is put into the space originally occupied by the document. Ready for a corny analogy? Think of compacting

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

399

as the process of turning Swiss cheese into American cheese! Your data starts out with all kinds of holes in it due to deletion stubs, and after compacting, the holes are removed and a smaller slice of cheese, um, physical space is left in its place.

CHANGING ON DISK STRUCTURE

In addition to its space optimization duties, the Compact task is also used to preserve or upgrade the On Disk Structure (ODS) format of a database. With each major upgrade of Notes, the underlying database format, or ODS, has been modified to accommodate the new features of the product. While existing R4 Notes applications will run on a Domino R5, you may choose to upgrade your applications to take advantage of new R5 features. To do this, the ODS format needs to be converted from R4 format to R5 format. When Compact is run against a Release 4 database, it is automatically upgraded to the Release 5 file ODS format. You’re probably thinking, “But what if I want to free up space in my R4 database and not convert it to R5 format?” To do this, give the database the file extension NS4 instead of NSF. Then, when Compact is run, it will still reduce the storage space fragmentation but will not upgrade the ODS.

Each ODS version is assigned a number. In R5, the ODS version is 41. ODS version information can be found on the Info tab of the database Properties box.

Fixup and Transaction Recovery There are times when a database becomes corrupt and needs to be repaired. One example is when a user has a database open, then shuts the computer off without closing Notes and doing a proper shutdown. To fix a corrupt database, either the Fixup or Transaction Recovery tasks will be used. These two tasks are mutually exclusive of one another.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

400

Chapter 9



Application Planning

When a Domino server is started, Fixup automatically scans all databases that do not have transaction logging enabled. Fixup attempts to repair inconsistencies or corruption in views and documents. You can also run Fixup on individual databases if you suspect a database of being corrupt. Transaction Recovery is a new feature in R5 that can restore a database to a noncorrupt state. Transaction recovery relies on transaction logging. It is a method of tracking changes to a database while it is being modified by writing to a set of before, during, and after image logs, as depicted in Figure 9.14. Using these logs, a corrupt database could be recovered to the exact point of failure by applying incremental logged transactions. Ideally, the transaction log is written to a different physical hard drive to provide the best recovery opportunity in case of a disk failure. FIGURE 9.14

Transaction logging Data update

NSF

Log file

Transaction logging must be enabled for the entire server by the system administrator. Once turned on, all databases on the server will use transaction logging. Transaction logging can be disabled on a database-by-database level, and in that case, the Fixup task would once again be the way to recover for a corrupt situation.

Indexing Services The Indexing application service builds, maintains, and optimizes index pointer structures in Notes databases to efficiently retrieve notes (design and data). This server task is commonly referred to as the Indexer task or the Notes Index Facility (NIF).

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

401

Types of Indexes There are two kinds of indexing that take place on the data in a Notes database: View index Keeps track of documents in databases. This index is stored within the NSF and, therefore, contributes directly to the size of the database. Indexes, like databases, can become corrupt, so Domino has two specialized maintenance tasks that look after the health of view indexes. Full-text index Keeps track of individual fields of data, or items, within documents. A full-text index is stored separately from the database and can grow to be quite large depending on the options chosen when creating the index. Indexing options include choices to index. Among the options available, you can choose to index file attachments, OLE objects, encrypted fields, and case-sensitive words. The more options you enable, the larger the size of the full-text index. The rule of thumb is that the full-text index can grow to be three-fourths the size of the database itself. Since the full-text index is not part of the NSF file, it does not replicate with the database. Index Maintenance Tasks Index structures are dynamic pointers to data and documents. The index structures are constantly growing and shrinking as documents are added and deleted from a database. To keep indexes optimized and performing well, the Updall and Update index maintenance tasks are available. UPDALL

Updall is a scheduled task that runs at 2:00 A.M. on a server and can also be run interactively. If you suspect a corrupt view index or full-text index, running Updall will update all the views and indexes for the database. Updall discards deletion stubs and rebuilds view indexes that are corrupt. UPDATE

The Update task runs continually on a Domino server. It is responsible for adding and deleting entries to both view and full-text indexes.

Data Archiving Keeping a database manageable involves healthy indexes and a manageable amount of data. When the content in an application grows too large, it can be slow to open and slow to work with for the users. The built-in archiving tool allows you to set up a secondary database that documents can be moved to from the primary database on a scheduled basis or on demand.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

402

Chapter 9



Application Planning

End users often make use of the archive facility to make local archives of their mail database.

Archiving in R5 is straightforward. If an archive database doesn’t already exist for a database you want to archive, Notes will create one to get you started. The archive database is given a name prefixed with an underscore (_) and the database name. By default, the archive database is created in the Archive folder under the Data directory on your local machine, but this is configurable. The data to be archived can be selected by criteria based on document characteristics; for example, the creation time stamp of the document, its author, and the time stamp it was last modified.

Integrated Development Environment The Domino Designer provides a complete integrated development environment (IDE) that is used to build and maintain Notes databases. Coding functionality in a Notes database can be done with several coding techniques. Table 9.6 lists the coding languages that work with Domino. TABLE 9.6

Coding Options Code Method

Description

Simple and System Actions

Built-in utility tasks that can be combined

Formula Language

Task-oriented, optimized internal language

LotusScript

BASIC-like procedural programming language

JavaScript

Document-oriented programming language

Java

Object-oriented programming language

Understanding the coding options available to you is the topic of Chapter 11, “Application Coding,” where it is covered in detail.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Domino System and Application Services

403

Optional Services In addition to application and system services, Domino also provides optional services that tailor a server to the needs of an organization. When a newly installed Domino server is first started, a set of default services is invoked automatically, including several of the ones discussed previously. A Domino system administrator often tunes server performance by turning off unneeded services or adding optional services required by the organization. Many of the optional tasks available are shown in Table 9.7. TABLE 9.7

Optional Domino Services Service Name

Job Performed by the Service

HTTP Server

Web server functionality for Web clients

LDAP Server

x.500 directory publishing and interactions for LDAP clients

SSL

Secure Socket Layer (SSL)

POP3

Post Office Protocol v3 (POP3) for POP3 clients

SMTP

Simple Mail Transfer Protocol (SMTP) for SMTP clients

IMAP Server

Internet Mail Access Protocol (IMAP) for IMAP clients

NNTP Server

Network News Transfer Protocol (NNTP) for NNTP clients

DECS

Domino Enterprise Connection Services

It’s no mistake that most of the protocols listed in Table 9.2 map very closely to the optional Domino services listed previously. For each of the different ports and protocols to be available in Domino, the appropriate service must be running on the Domino server. With this design, the server can be tuned to provide exactly the services needed without extra baggage in situations that don’t require the full complement of services available.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

404

Chapter 9



Application Planning

Connecting to a Domino Server

Think, for a moment, about your favorite local restaurant and where it is physically located. Can you think of the street name? Do you know what roads you would travel on to get to the restaurant by car? Would you take the same roads to get to your destination regardless of where you started your trip? Would you take a different path to the restaurant at different times of the day, perhaps trying to bypass rush-hour traffic? As you can see from the line of questioning, the path you take to your favorite restaurant depends on several factors, such as where you’re starting from, the time of day, and traffic. Likewise, the users of a Domino server might take different paths depending on several factors. Let’s explore the factors that can influence the path.

Lotus Notes Clients A Lotus Notes client can connect to a Domino server in different ways depending on where the client is located or which network path is best. So that’s two different variables: 

Location of the client



How the client connects to the server

Configuration documents providing this information are stored in a user’s local Address Book, which is also called your personal Address Book. The local Address Book has the operating system filename names.nsf. Sound familiar? It should! That’s also the filename of the Domino Directory on the server. What’s the difference? The server’s names.nsf stores server configuration information and is available to all users of the server. Your personal names.nsf stores user configuration information and is only available to users of the computer where it’s installed. Figure 9.15 shows a personal names.nsf for a Notes client with several connection settings. FIGURE 9.15

Notes client connection settings

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Connecting to a Domino Server

405

The configuration information that determines how a Lotus Notes client connects to a Domino server is stored in two special types of documents in the local Address Book: 

Connection documents



Location documents

Connection Documents Notes clients store connection information about how to get to a server in a special document called a connection document. The document specifies the communication protocol to use to connect to a server, as well as the name and network address of the server. Protocols include Transmission Control Protocol/Internet Protocol (TCP/IP) connections over a Local Area Network (LAN), Notes direct dial-up connections through a modem and phone line, and network dialup. Figure 9.16 shows a connection document to a server. FIGURE 9.16

A connection document

The kind of connection you make to a server can affect the performance of an application. Bandwidth is a measure of the speed and capacity of information that can pass between two points on a network. If you have limited bandwidth available, using your application over a network will be slow. Another factor in application performance is whether you’re working with a dedicated connection or one that exists only when you invoke it. Dedicated connections Dedicated connections maintain a persistent end-to-end connection between a client and a server. That means they’re always available and generally offer good connection speeds. Dial-up connections Dial-up connections connect to a server on demand by modem connection to a server. The connection exists only when you dial in and the speeds reach a maximum of 56KB of information per minute.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

406

Chapter 9



Application Planning

Internet connections As a public network, the Internet provides communication pathways to millions of destinations. If the Domino server you need to connect to is accessible through the Internet, the Internet becomes a pass-through to the Domino server. Hybrid connections There are times when a combination of connection types works best. A hybrid of dial-up and dedicated connections can create an Internet connection. The scenario is that you make a local phone call to your Internet Service Provider (ISP), which gets you to the Internet. Since the communications protocol used on the Internet is TCP/IP and Notes can communicate on TCP/IP, you can use the Internet to simulate an office connection to the dedicated IP address of a Domino server on the Internet. This scenario is depicted in Figure 9.17. While the maximum speed is still governed by your modem connection to your ISP, your connection to the server goes through as network traffic instead of modem traffic. FIGURE 9.17

A connection document

Location Documents Connection documents work in conjunction with location documents. Location documents identify the mail file to be accessed, the TCP/IP address of the server or a phone number to dial it directly, which server the mail database sits on, ports to use to send messages, and which user IDs are allowed to use the location documents. Figure 9.18 displays a location document. FIGURE 9.18

A location document

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Connecting to a Domino Server

407

Ports For connection documents and location documents to work in the Lotus Notes client, ports must be active to send and receive network data. Earlier, the topic of ports was introduced in reference to how a server communicates with services. Lotus Notes clients also must store information about ports so they know where to look for network traffic. Port information for clients is stored in the User Preferences area of the Notes client. You can access the settings using the menu sequence File  Preferences  User Preferences  Ports, as shown in Figure 9.19. FIGURE 9.19

Port options

The ports enabled by the client will be the ones available for network traffic. COM ports are used by modems to make dial-up connections to a server. The TCP/IP port is very popular since it can be used to talk to LANs and to the Internet since traffic on the Internet communicates between points using TCP/IP.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

408

Chapter 9



Application Planning

Web Clients Internet traffic includes requests traveling from Web browser clients connecting to a Domino server. While the request travels from a Web client to the server over TCP/IP just like Notes clients talking to a server, Web clients are treated in a different way from Notes clients. A Web client has no user ID file issued by a server, so the rules have to change a bit. If the system administrator has turned on the HTTP service on the Domino server, the server becomes a Web server as well as a Domino application server. When Domino acts as a Web server, data is communicated using the Hypertext Transfer Protocol (HTTP), which is the communications protocol of the Internet. When Domino’s HTTP service is started, Domino becomes a server capable of fulfilling Web requests. Domino listens for requests from a Web browser on port 80 and responds to requests by authenticating a user, checking authorization at the database level, pulling the appropriate data from a Notes database, converting it on the fly to HTML, and sending it back to the requesting Web browser. This process is depicted in Figure 9.20. FIGURE 9.20

HTML conversion process

Security check Authentication & authorization

On-the-fly conversion to HTML

HTTP Web request

Domino server

NSF

Display HTML page

Like other Web servers, Domino can also serve up information from an NSF using Java programs, Java applets, and JavaScripts. Domino can serve raw HTML files and image files and can execute CGI scripts and Perl programs if they are stored in the subdirectories provided in the Domino path. These subdirectories are shown in Figure 9.21.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

License Types

FIGURE 9.21

409

Additional Web server directories

License Types

Two types of licensing come into play for the Lotus Notes and Domino products: client license types and security license types.

Client License Types When you install a Lotus Notes client, you are asked what kind of client is being installed. Depending on your choice, different executable files run and install each of the clients you chose. When you purchase the software, the type of client license you buy determines your purchase price. Table 9.8 describes the purpose of the current client license types, but beware, the

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

410

Chapter 9



Application Planning

licensing strategy changes complexion whenever it takes a good hard look at itself in the mirror! TABLE 9.8

Lotus 5.0.3 Client Types Client

Purpose

Lotus Notes for Messaging

Interact with Domino mail and discussions

Lotus Notes for Collaboration

Interact with Domino applications of any kind, including mail

Domino per-user Client Access License (CAL)

Interact with Domino applications by logging on using a Web browser; fee is charged on a peruser basis

Domino per-server Client Access License (CAL)

Interact with Domino applications by logging on using a Web browser; fee is charged on a per-server basis

Domino Designer

Create and modify Domino applications

Domino Administrator

Administer the Domino server and register new users

In the spring of 2000, Lotus introduced a new client license, iNotes. This license provides for secure access to a Domino server from a browser; Web mail using POP, IMAP, HTTP, or MAPI, offline capabilities; and Microsoft Outlook client access to Domino.

Security License Types Domino R5 was introduced to the marketplace on April 1, 1999, with two different kinds of security licenses: North American and International. The citizenship of the user or the geographic location of the server determined the license issued. This same scheme was used in Release 4 of the product. The server and a user ID each have a security license.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

License Types

411

When you install a Domino server or a Lotus Notes client for version 5.0.3 and earlier, you choose the licensing type from one of six available: North American, North American Canadian French, International English, International English for France, French for France, and French. User IDs for Lotus Notes clients are generated by the Domino server and specify either a North American or International license type. The administrator issuing the ID chooses the license type at registration time based on the user’s citizenship.

Starting with release 5.0.4, Lotus adopted a global licensing scheme in recognition of the U.S. government’s relaxation of laws that previously banned the export of high (strong) encryption software products outside North America. North American releases 5.0.4 and higher with strong encryption can be exported to most countries.

The difference between the North American and International license types is cryptographic strength. Lotus Notes and Domino use two kinds of cryptography: symmetric key and public key encryption. R5.0.3 and earlier International flavors of Lotus Notes and Domino use a 40-bit symmetric key, while North American versions use a 56-bit symmetric key. Figure 9.22 shows an International User ID. FIGURE 9.22

Inspecting the User ID

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

412

Chapter 9



Application Planning

Symmetric Key Encryption A symmetric key is one in which a single key exists but many copies of it are available; any of the copies will encrypt or decrypt information. In a sense, this is single key encryption. When you create an encryption key in a Lotus Notes user ID and use it to encrypt a field of data, you are using a symmetric key. To decrypt the data, your intended users will need a copy of the key. This is often referred to as secret key encryption in Notes.

Public Key Encryption Public key encryption takes a dual key approach to protecting data using a public key and a private key. Public keys are used to encrypt mail messages. The public key is available to everyone, while the private key is available only in the user’s ID file. With public key encryption, one key is used to encrypt information and the other key is used to decrypt it. For instance, if Sara encrypts a mail message for Lee, she’ll use his public key because it is published in the Domino Directory. When Lee receives the encrypted mail message, he’ll use his private key to decrypt the message.

With 5.0.4, a Notes client can use a 64-bit symmetric key to protect data on a Domino server. Domino servers can use even higher keys for communications between servers, supporting 1024-bit dual keys and 128-bit symmetric keys.

The logical question to ask at this point is whether North American Domino servers can talk to International Domino servers. The answer is yes, with one exception: data that will be used worldwide should only be encrypted with keys created on an International client. North American servers will negotiate down to the lower key to correctly decrypt information. The opposite, however, is not true. International servers cannot trade up to a higher key, so data encrypted with a North American key will not be visible to users with International licenses.

Summary

Many of the decisions you make during the application planning stage are determined by the capabilities of the Domino server and the available clients. You should now be comfortable with Domino’s infrastructure, the data storage model, the Domino services provided, the types of clients that interact with Domino, and high-level security and licensing strategies. Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Summary

413

Key Terms Before taking the exam, you should be familiar with the following terms: Access Control List (ACL) Client Access License (CAL) Component Object Model (COM) Compact connection document Design Refresh dial-up connection Domino Directory Fixup Hypertext Markup Language (HTML) Hypertext Transfer Protocol (HTTP) Internet Message Access Protocol (IMAP) indexing International license type Lightweight Directory Access Protocol (LDAP) location document Network News Transfer Protocol (NNTP) North American license type Notes Storage Facility (NSF) Notes Template Facility (NTF) object store Object Linking and Embedding (OLE) Post Office Protocol v3 (POP3) private key

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

414

Chapter 9



Application Planning

public key remote access replication routing secret key/single key Simple Mail Transfer Protocol (SMTP) template transaction logging

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

415

Review Questions 1. Anne is trying to explain to the NT systems and security administrator

how a Lotus Notes application communicates with a Domino server. What is the best description of how this communication takes place? A. Remote Procedure Call B. Notes Remote Procedure Call C. Application Programming Interface D. Lightweight Directory Access Protocol 2. Bob has encrypted several fields of data within a database, a large

number of image files that are read-only, and several long attachments. The database is searched frequently, so Bob has decided to add a full-text index. What security concern will Bob face if he turns on all available options when he creates the full-text index? A. Image files cannot be protected after they are indexed. B. Text within the images will be indexed. C. The attachments will no longer be protected by the ACL. D. Encrypted fields are stored in a full-text index as clear text. 3. After struggling for an hour and being unable to modify information in

a database on the server, Cassandra made a local copy of the database. Her purpose is to get mailing labels out for a last-minute marketing campaign request. She doesn’t care if her changes are saved long term since this is a personal project that doesn’t affect anyone else in the department. What aspect of Notes is allowing Cassandra to do this? A. Local databases allow the changing of data, while server databases

do not. B. Server databases can become corrupt. C. Notes does not enforce security on local databases. D. Databases on a local machine do not save changes.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

416

Chapter 9



Application Planning

4. Dana has just completed a major programming change to an existing

application. She’s ready to roll the change out to users on the seven company servers located around the world. Which of the following Domino services will she utilize to accomplish the rollout? A. Indexing B. Directory C. Replication D. Routing 5. Which of the following Domino services will protect Eva’s new data-

base application from a user trying to perform a task outside his or her assigned privileges? A. Security authentication B. Security authorization C. Directory D. Indexing 6. Frank is in the final stages of planning a new database application and

the customer has put forward the new requirement of including key information currently stored in Microsoft Word documents. Users will continue to maintain this special data in Word but the information needs to be available in Notes as well. Frank has decided to include the Microsoft Word documents as attachments embedded in documents that will open when clicked by a user. By doing this, he is taking advantage of which of the following Domino features or services? A. Directory B. Database C. Indexing D. Object store

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

417

7. George wants to use Microsoft Excel to pull field-level data out of a

Notes application stored on a Domino server. Which of the following data access technologies would not be a good choice for this data exchange? A. DDE B. OLE C. COM D. ActiveX 8. Hillary is dialed in from her home over a modem connection to her com-

pany’s Domino server. She notices that it’s taking a longer time to open documents in the application she is using than when she used it yesterday in her office. What would explain this performance slowdown? A. Her phone line isn’t capable of fast data transfer. B. Performance in her office is faster because she is physically closer

to the server. C. The data transfer speed is being affected by other users dialed into

the server. D. The data transfer speed is limited by the capabilities of the modem. 9. Ivy promised one-hour turnaround on a design change. She’s made the

change to the design template and is ready to distribute the change to the users on the three servers. The servers are located in Austria, New York, and Germany. Which of the following server tasks should she do immediately to distribute the changes to the servers? A. Design B. Replicate C. Routing D. Update

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

418

Chapter 9



Application Planning

10. Joyce promised 24-hour turnaround on a design change. She’s made

the change to the design template and has tested it successfully. The servers are located in London, San Francisco, and Italy, and they replicate all templates and databases with one another every eight hours. Which of the following server tasks will distribute her changes for her automatically at 1:00 A.M.? A. Designer B. Replicate C. Routing D. Update 11. K.J. has been working in Release 5 for a while now, but many of his

database applications are still in Release 4 format. The databases have been stable for years and are working just fine on the Domino R5 server since they were moved over. K.J. knows that the Compact database utility that the system administrator runs has the capability of upgrading his Release 4 databases to Release 5 format. Which of the following should he do to ensure that his R4 database is not automatically upgraded by Compact? A. Ask the administrator to use the -B option when running Compact. B. Disable Design Refresh on his R4 databases. C. Give his R4 databases a file extension of NS4. D. At the operating system level, apply the -R read-only flag to R4

databases.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

419

12. Lily is attempting to use a Domino application that her friend told her

about on the Federal Aviation Administration’s (FAA) Domino server. Lily has not previously visited the FAA server. She has set up connection documents and location documents using the same settings her friend used. When she attempts to get to the server, she types in her Notes user ID and password and receives an error message. What is the most likely problem? A. She failed the authorization process because she was not granted a

license to use the FAA server. B. She failed the authentication process because she was not granted

a certificate to use the FAA server. C. She failed the database security check because she was not listed in

the Access Control List. D. She failed the authentication process because her connection doc-

ument was incorrect. 13. Mike is grinning from ear to ear. He’s just written an application that

will present a Web-based calendar application for scheduling hotel meeting rooms for convention groups. Users will authenticate with the Domino server, log into the application, and then make new convention reservations on line. Mike is piloting the application with 10 users. He’s had the system administrator issue him 10 Notes user IDs that he can use during the pilot. After sending the users the temporary Notes ID files and a separate e-mail with the temporary password, he sits back and breathes a sigh of relief that the application is complete. What has Mike forgotten? A. Notes IDs cannot be sent via e-mail. B. Web users do not use Notes IDs to log into an application. C. Web browsers do not allow users to log into a Domino application. D. The Domino Directory cannot store individual Web usernames.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

420

Chapter 9



Application Planning

14. Norma has been assigned to create a Web site in Domino. The home

page will be read-only for all users, but from that point forward, a click on a link will pop up a login screen before allowing a user to proceed. Which type of system design should she plan for easy Domino authentication? A. Use Domino as the home page and then link to HTML pages. B. Use HTML as the home page and then link to a Domino database. C. Use Domino and put all content in one database. D. Use Domino as the home page in one database, making it read-

only, and then build separate databases for the content with individual security. 15. Orson is designing a database for the call center. This database will be

sure to grow because documents are created for each incoming call. These documents can never be deleted, but call documents modified during the last 90 days are the call-center team’s focus. What can Orson do to limit the size of the database? A. Delete data every 90 days. B. Archive data every 90 days. C. Copy and paste data to a different database every 90 days. D. Make an operating-system copy of the NSF file every 90 days and

then delete data older than 90 days. 16. Petra has successfully tested her new Web site project in her New York

office on the company network. The site will be used as the official Austria visitor site. Since its draw is tourism, the site includes a great many graphics of the Austrian countryside in the fall, winter, spring, and summer. Which of the following is going to affect the performance of her application on the Internet? A. Monitor resolution B. Bandwidth C. Monitor size D. Web browser palette settings

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

421

17. Q is planning a database that will keep track of James’s gadgets. This

Web application will retrieve information from an Oracle database on a remote Linux server. Which data access method could be used to accomplish this task? A. DDE B. COM C. ActiveX D. CORBA 18. Richard is stumped. He’s been trying to figure out why Web users who

log into his Domino application with names and passwords aren’t able to edit information even though they are explicitly listed in the database’s ACL with Editor access. Which of the following might explain the problem? A. The Default ACL entry is set to Reader. B. The Anonymous ACL entry is set to No Access. C. The ACL option to enforce a consistent ACL is turned on. D. The Maximum Internet Name & Password Access option is set to

Reader. 19. Susan has built a contact management application that contains docu-

ments with a parent/child relationship. Company information is stored as a parent document, while the names and phone numbers of company representatives are stored as child Response documents. Which of the following is a false statement about Response documents? A. Response documents contain the variable $Ref. B. Deleting the parent document will automatically delete the child

Response document. C. Response documents store the Document Unique ID of the parent

document. D. Databases may contain orphan Response documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

422

Chapter 9



Application Planning

20. Thomas has modified the human resources application. He’s made

changes to the user’s data, the code, the graphical user interface, and the application security settings. How many NSF files will Thomas need to distribute in order to roll out all of the changes? A. One B. Two C. Three D. Four 21. Ulysses has led a mysterious life and has many secrets. He keeps his

secrets safe by utilizing a symmetric or secret key encryption scheme on his data. If Ulysses encrypts his data with a secret key, which key will decrypt his data? A. The same key that was used to encrypt the data. B. The public key stored in the Domino Directory. C. The private key stored in his ID file. D. A combination of public and private keys is required to decrypt

the data. 22. Victoria has written an e-mail to Tommy. Both are using Lotus Notes

clients. She has encrypted the e-mail and Tommy will be decrypting it. Which key is used when? A. Victoria’s public key is used to encrypt the e-mail, and her private

key is used to decrypt the e-mail. B. Victoria’s private key is used to encrypt the e-mail, and her public

key is used to decrypt the e-mail. C. Tommy’s public key is used to encrypt the e-mail, and his private

key is used to decrypt the mail. D. Tommy’s private key is used to encrypt the e-mail, and his public

key is used to decrypt the mail.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

423

23. Wills wants to make sure the Salary field and Ethnicity field on the

company’s personnel profile documents are very secure. He’s designed an application that makes use of secret encryption keys, so he has created two secret encryption keys and would like to associate each field with a different encryption key. Will his strategy work? A. No, because when multiple encryption keys exist, all are used to

encrypt all encryptable fields. B. No, because more than one key is not allowed. C. Yes, because each field can be associated with a named encryption key. D. Yes, because multiple encryption keys automatically apply one at

a time to any encryptable fields. 24. Xavier knows that users will be replicating his application to their lap-

tops so that they can use it with their local copy of Notes when they travel. The users are granted access to the database through a group name in the ACL. What option should he enable so that the users do not compromise the security of his system? A. Set the Default ACL entry to Reader. B. Set the Anonymous ACL entry to No Access. C. Set the ACL option to enforce a consistent ACL. D. Set the Maximum Internet Name & Password Access to Reader. 25. Yomar is planning an application that will be used by Web browser

clients to log in, then retrieve and store data. He anticipates only a handful of users for the application; however, they are new to using Domino. Which of the following client license types should he pursue? A. Lotus Notes for Collaboration. B. Lotus Notes for Messaging. C. Domino per-user Client Access License (CAL). D. No license is needed for Web browsers.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

424

Chapter 9



Application Planning

26. Zoe is preparing to encrypt documents in a database that will be rep-

licated between the New York server and the London server. Users in both cities need to work with the data. The New York server is running Domino’s North American version 5.0.3, while the London server is running the International 5.0.3 version. Which of the following is a true statement? A. A North American encryption key should be used to encrypt the data. B. An International encryption key should be used to encrypt the data. C. Both an International key and a North American key should be

used as dual keys, where one key encrypts and the other decrypts. D. Encrypted data cannot be replicated between servers using differ-

ent license types.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

425

Answers to Review Questions 1. B. NRPC is a proprietary remote-procedure call implementation used

to pass messages between Lotus Notes applications and Domino servers. That means that answer A is tempting but B is more correct since it is the specific type of RPC that allows the communications to take place. An application programming interface is what programmers can use to manipulate the object store and has nothing to do with how the information is passed across a network. LDAP is a protocol that allows x.500-directory-compatible applications to interact with the Domino Directory, so it does not control how a Lotus Notes client talks to a Domino server. 2. D. To index encrypted fields, the encrypted data is stored in the exter-

nal index file as clear text, which may be a security concern. Answers A, B, and C are all false statements. 3. C. Cassandra was most likely unable to modify data on the server

because security prevented it. She was able to bypass the security by making a local copy of the database. However, her changes will never be sent back to the server, so the security on the server-based copy is intact. All the other answers are completely untrue. 4. C. The replication service synchronizes multiple copies of the same

database, making the design elements and data contents identical. The Indexing task keeps view and full-text indexes healthy, but neither is involved in replication. The Routing task moves messages between clients and servers as well as between servers. To roll out changes, communication is taking place between servers, but the Router task does not get involved because the application is not being sent to a particular user. Rather, the updated application needs to be put on the server and will be invoked on demand by authorized users. The Directory service manages user information and will be consulted when Dana replicates the database to ensure that she has the right privileges to do the replication; however, the Directory service itself does not perform the rollout.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

426

Chapter 9



Application Planning

5. B. Authorization is the service used to control which users have access

to an application and what privileges and rights they have within a database. While authentication was a reasonable choice, the Authentication task is actually responsible for validating the identity of the user and the server and does not check the privileges of the user. The Directory service manages user information, but the security authorization is invoked to check privileges on a database. The Indexing service creates pointer structures to documents, and data is not involved in security. 6. D. The object store allows flexible, unstructured data and therefore

allows a Notes document to contain attachments that get stored as part of the NSF. The Domino Directory controls server configuration and security, so it really doesn’t come into play in terms of storage. The Database service controls interactions within and between a database but not how data is stored. The Indexing service maintains pointers to documents, which is important for fast retrieval, as opposed to how the database stores the data. 7. A. DDE is an older technology that only allows a Notes server to act

as a client of data, not as a server of data. OLE, COM, and ActiveX all provide programmatic access to Domino data. 8. D. Data transfer speeds negotiate down to the common denominator.

Since the modem cannot send or receive as fast as her office network, data slows down to the fastest available speed from her modem. While answer A is reasonable, the real gating factor is the speed of her modem. Answer B is incorrect because physical closeness to a server doesn’t determine data transfer rates; the communications connection does. Answer C is not correct because a modem connection, once made, is dedicated to the user dialed in; no other traffic flows through that connection.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

427

9. B. Replication is the task that synchronizes databases across servers.

While Design is a tempting choice, the Design task incrementally refreshes a database that inherits its design from a template. Until the template with the change exists on the three servers, the Design task will have no effect. So, in fact, the Replicate task must run first and then the Design task will take over. Routing is also a reasonable choice; however, routing focuses on distributing messages between databases rather than changes within a database. The Update task is responsible for updating view and full-text indexes, so it does not apply to distributing design changes. 10. A. The Design task runs at 1:00 A.M. every night to refresh the design

of server-based databases that inherit their design from a template. Since the change was made in a template that replicates every eight hours, the design change will occur automatically on each server at 1:00 A.M. local time to the server. The Replicate task is involved in the change rollout since it distributes the template, but the Design task updates the production application. Routing is also a reasonable choice; however, routing focuses on distributing messages between databases rather than changes within a database. The Update task is responsible for updating view and full-text indexes, so it does not apply to distributing design changes. 11. C. Compact will defragment the space in an R4 database and leave it

in R4 format if the file extension is NS4. Running Compact with the -B option simply tells Domino to compact the database in place and reduce the file size if possible, so this will not prevent the automatic conversion to R5 format. Disabling Design Refresh will prevent a template from updating the design, but it has no effect on the R4-to-R5 automatic conversion. Finally, going to the operating system and setting a read-only flag might actually work, but no one would be able to interact with the database back in the Notes world, so this is not a reasonable solution.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

428

Chapter 9



Application Planning

12. B. When Lily attempted to log into the server, her ID file was checked

for a certificate that allowed her to access the server. None existed. Although she was able to create connection documents to the server, connection documents do not grant server access. The authorization process is not the same as the authentication process; authorization is the privilege level at the database level granted to an ID. Lily did not get that far since she failed authentication at the server level. Similarly, the database’s Access Control List was never checked since she failed to authenticate with the server. 13. B. Web users are registered in Domino and are given an Internet pass-

word, which the server checks for authentication. A Web browser does not make use of the Notes ID file in any way. Instead of registering new users, Mike should have requested that the system administrator add 10 new people to the Domino Directory and assign them an Internet password. Notes IDs can be sent via e-mail, so that is not an issue. Web browser users can log into a Domino application if they have an Internet password, and each user can be stored in the Domino Directory individually, so the issue is that Web users do not use a Notes ID file to access applications. 14. D. Using separate Domino databases will let users authenticate closer

to the content that they actually access, and each of the content databases can use different security settings. Answer A is not an option since HTML does not natively provide security control. Answer B will also work, but since Norma was asked to use Domino, there’s not much motivation to use HTML at the top if Domino can do the same job. Putting all the content in one database will also work; however, security becomes a bit trickier since it would need to be applied within the database at a lower level than at the gateway into the database. 15. B. Using the Notes archive facility, data can be archived automatically

based on document characteristics, such as when they were last modified. Deleting data would get Orson in a bit of trouble, and copying and pasting the documents would take up an unnecessary amount of time. While an operating system copy of the NSF file would work, it also would take up an unnecessary amount of time as compared with the built-in archiving facility.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

429

16. B. Petra cannot control whether users access her site with a 28.8

modem or a T1 line. Since graphics take time to download and display, the slower the bandwidth, the worse the application will perform. Monitor resolution, monitor size, and palette settings will all affect how accurately the images render, but not how fast they display. 17. D. You can code Java applets using the CORBA as middleware to

access Oracle in a distributed network environment and pull data into Domino. Both COM and ActiveX require a Windows 32-bit operating system to be used, so these are not options for the Linux server. DDE is not supported in R5. 18. D. When the Maximum Internet Name & Password Access option is

set, the access level associated with it will be in effect for all Web users, both Anonymous and those that log in with a name and password. Since there is an Anonymous entry, the Default entry is never accessed for Web users. Having the Anonymous entry set to No Access does not come into play because the Maximum Internet Name & Password Access takes priority. The ACL option to enforce a consistent ACL only affects replica copies. 19. B. Notes does not have a mechanism for enforcing referential integrity

between parent/child documents, so it will not automatically delete Response documents when the parent is deleted. This creates the possibility of having orphan Response documents, so answer D is a true statement. Answers A and C are also true since the $Ref variable on a Response document contains the Document Unique ID of the parent document. 20. A. The design of the NSF is such that it contains the user’s data, the

code, the graphical user interface, and the application security settings all in a single NSF file, so only one file will need to be rolled out to the users. Answer D, four, may have been tempting since it matched the number of changes he made, but it is incorrect since everything is stored in a single NSF. 21. A. A symmetric key or single key is used to both encrypt and decrypt

information, making it very important for the key to be kept absolutely secret. Since the data was encrypted with a symmetric key, neither the public or private key will be used in conjunction with this data.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

430

Chapter 9



Application Planning

22. C. Public keys are used for encrypting mail documents, and since

Tommy does not have access to Victoria’s private key, the correct answer is C. Tommy’s public key was available to Victoria through the Domino Directory. 23. A. Using multiple encryption keys on a single document automatically

encrypts all encryptable fields with a combination of all available keys. There is no way to associate a named encryption key with a particular field. 24. C. Setting the option to enforce a consistent ACL will apply the ACL

of the server’s database to the local copy even though local databases normally do not enforce security. The Default and Anonymous ACL entries will have no effect on the users since the group name determines their access level. The maximum Internet password applies only when a Web browser is used, and in this case, the users will be using their Notes clients. 25. C. Since the users will be logging into the application, thus making use

of the authentication services on the Domino server, and there are only a few users, the Domino per-user Client Access License (CAL) makes sense. A Web browser license is not needed if users are interacting with Domino in read-only mode. Neither the Lotus Notes for Collaboration or Lotus Notes for Messaging licenses are appropriate because they don’t provide Web browser access. 26. B. For replication on version 5.0.3 and earlier to be successful and for

documents to be viewable on both servers, a key created with an International ID would need to be used since Domino will negotiate the North American key down to the weaker encryption. Answer A is incorrect because a Domino International server cannot negotiate up to a North American key. Answer C is not right because dual-key encryption requires a user’s public key and private key, which are created when the user is registered; the keys in this question are created specifically to encrypt data and are not user encryption keys. Answer D is incorrect because servers with two different types of licenses will replicate successfully; the issue is who can view the data after they replicate.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Chapter

Application Design

10

LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Design applications based on the basic “Note” unit
Design applications based on the NSF structure
Design applications based on design elements
Design applications based on Document characteristics
Design applications based on forms
Design applications based on the appropriate elements (Forms vs. Subforms vs. Actions)
Design applications based on sections
Design applications based on OLE on a form
Design applications based on field elements
Design applications using item default values
Design applications which use the Rich text structure
Design applications to use the file attachment structure
Design applications based on adding items to a DB: data integrity issues
Design applications based on document items
Design applications based on getting rid of items from a DB: data integrity issues
Design applications based on item data type characteristics
Design applications based on Summary/Non-Summary data storage
Design View Hierarchies based on Document characteristics
Design View Hierarchies using response documents

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com


Design View Hierarchies using view categories
Design applications based on view elements
Design applications based on pages
Design applications based on graphics elements
Design applications based on outlines
Design applications based on framesets
Design applications based on the appropriate elements (actions vs. shared actions)
Design applications for data percolation
Design applications for Field Exchange
Design applications to limit document size
Design applications which use the NoteID
Design applications which use the UNID
Design applications based on Data Integrity issues
Design applications based on document copy integrity issues
Design applications based on conflict integrity issues
Design applications based on document replica copy integrity issues
Plan for Design distribution based on templates
Design applications to integrate data from heterogeneous sources
Design applications to integrate with host data in batches
Design applications to integrate with host data in both directions
Design applications to integrate with host data using ODBC
Design applications to integrate with host data using SQL
Design applications to integrate with host data via live connections

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

D

esigning a good Domino application is not easy. In fact, it is much easier to design a bad Domino application. While this is true of every programming language, because Domino combines an application platform, messaging infrastructure, and security model in one package, your skills must be sharp in many areas to be a good programmer. In this chapter, you’ll learn design techniques that will help you build a good Domino application. How is a good application measured? Many yardsticks are used to measure software project success, and three good ones are whether 

The application is implemented in an appropriate software tool.



The application produces accurate and complete results.



The application is gladly used by the customer.

You might find the last one a bit curious, but there’s a good chance you can recall struggling to use a difficult software product and being motivated to direct a few colorful words at your helpless computer monitor during the process. The reality of the software business is that if users are always complaining about having to use your program, the project is shy of success. This chapter focuses on designing good, solid, usable applications by the appropriate use of Domino’s design features.

From Planning to Designing

T

he design phase follows a successful planning stage. If you were having a house built, an architect’s plan based on your needs, project scope, and available tools would be the output of the planning phase and the input for the design phase. The input for the design phase of a Domino application is the infrastructure knowledge gained in the planning phase. A plan is a global understanding of a software project that applies general knowledge, while a design is a more granular look at the application to be built.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

434

Chapter 10



Application Design

At the design level, you clarify and refine your plan by applying specific knowledge of Domino language features. Design decisions are made at two levels: 

Application design level



Database design level

Decisions made at the application level will affect the design of a database, and database design decisions affect how you build the internal structure of your database.

Application Design

T

he term application is often synonymous with database in the Notes world. An application, however, can consist of multiple databases, making application design a bit more high level than the design of a single database. Designing an application takes into account the entire scope of the business problem being solved and how it should be implemented in Notes. Questions to ask at this point include the following: 



Will multiple databases or a single database be used? What client access mode, meaning Web browser or Notes client, will be used?



Will the application implement a workflow?



Will there be interaction with external data sources?

Application Databases: Multiple versus Single Notes applications are designed to solve business problems. Take the problem, for example, of tracking the sales of products to customers. To model this kind of application, you have to decide whether to store both types of entities in a single database or separate each entity into its own database. Since Notes is not a relational database, the formal process of entityrelationship diagrams (shown in Figure 10.1) and normalization to segment data into independent logical entities is optional. These conceptual

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design

435

techniques, however, have value in Notes to help identify the dependencies that exist in the data being modeled. FIGURE 10.1

Entity relationship diagrams

Customer

1

Places

M

Order

1

Contains

M

Products

In a relational world, you would certainly put customers in one database table and products in another database table. The relationship between the customer and product data is the order that results when a customer buys a product. In Notes, you could choose to store customer data in a single Notes Storage Facility (NSF) file, product data in another NSF, and orders in yet another NSF. Or you could choose to store customers, products, and orders in a single NSF. Figure 10.2 depicts both options. FIGURE 10.2

Multiple databases versus single database

Customers

Products

Orders

Or Company sales Products Customers Orders

How do you decide whether to use one database or more than one? The rule of thumb is to store distinct logical entities in separate databases wherever possible. This has a few advantages: 

Creates smaller, reusable NSF data components



Minimizes the size of the database given a single type of entity data



Makes data available to other application programs with minimum overhead

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

436

Chapter 10



Application Design

It may, on the other hand, be beneficial to your users to store interdependent entity data in a single NSF file. Possible reasons to go this route include 

Replication of only one database instead of multiple databases



Single point of security control at the database level



Ease of use for users who get conceptually bogged down with multiple databases

The modeling approach you choose will be determined by your application needs, your users, and your deployment environment. For instance, if you have Customer information storing name, address, and customer ID, this information can be reused by many applications, so storing it in its own NSF is a good idea. If, on the other hand, customer data is only ever used in conjunction with market research information, you may want to store these two types of information together in a single NSF.

Templates Another kind of interaction that involves multiple databases is template inheritance. The multiple databases in this case are a development template and a production database. The template approach to application development connects a production database to a template from which it inherits its design structure but no data notes, as shown a single Figure 10.3. FIGURE 10.3

Template notes

Template Database header notes Access Control notes

Design notes Why are templates so popular in Notes? Consider the case of sitting at your home computer dialed into a Domino server over a 56K connection. You want to push a change out to a database on the server and also pull back some changes made by other programmers earlier today. To do this, you initiate a replication. When you replicate, both design notes and data notes are sent back and forth over your 56K connection.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design

437

No big deal if there’s very little data, but what if 600 new documents were added on the server during the course of the day? Your replication will pick up not only the design changes you wanted to retrieve but also the 600 new data notes. Not quite what you want over a 56K line! Design Tasks and Replication Templates make use of the server’s Design task, discussed in Chapter 9, “Application Planning,” to merge design notes into a database from a template. A server-based database that is marked to inherit from a server-based template receives incremental design changes each night at 1:00 A.M. The Design task is not equivalent to the Replication process, although both are associated with incrementally updating database contents. Table 10.1 compares the two. TABLE 10.1

Design Task versus Replication Server Task

What Gets Updated

Changes Based On

Replication

Design notes, data notes

Document unique ID and timestamp

Design

Design notes

Design note name and timestamp

The Design task and the Replication task do have occasion to work together. Since the Design task runs on all servers by default, application templates are generally not deployed to remote servers but instead are stored on a single server. This allows the template refresh to take place on one server, updating the application database. Then, following the replication schedule in place for the database, design changes are replicated out to remote servers. The Design task examines the databases on the server each night and identifies those that are marked to inherit from a template. When it finds a database candidate, it then examines the date timestamps of the data notes in the template and the database and makes any incremental changes nesessary. Alias Names A database inherits from a template based on the template’s alias name. The alias name is stored on the Design tab of the database Properties box for the template. Only one template alias is allowed, meaning that a database as a whole can inherit from only one template. However, individual design elements can be inherited from different templates; this will be explored in greater detail later in this chapter. Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

438

Chapter 10



Application Design

A template alias name can be any text, but it must be an exact match on the Design tabs for the database doing the inheriting and the template doing the refreshing. To create a template relationship, the following four things must be done: 

Database must be marked to inherit from a template.



Database must specify the template’s alias name.



Template must be marked to be a template.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design



439

Template must specify the template’s alias name.

Designing an application using templates is a powerful way to separate code from data during the development stage of an application. It also provides an excellent way to create development and test environments through the use of multiple databases. Finally, it is an efficient method of automatically promoting changes into production.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

440

Chapter 10



Application Design

Application Access Mode Whether you decide to use multiple databases or one database to create your application, the next question you need to ask is what kind of client the users will use to access your application. You thought about access modes a bit in the planning stage, specifically physical access modes like modem dialups. Here, the clarifying piece of information needed is whether the users will access your application through a browser, a Notes client, or perhaps both. Some database settings can be tweaked for either environment using the database Properties box.

Browser Client Database Settings Several settings in the database Properties box pertain specifically to browser clients. The Properties box is shown in Figure 10.4 and the property settings are described in Table 10.2. FIGURE 10.4

Database settings

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design

TABLE 10.2

441

Browser-Specific Database Settings Tab

Setting

Info tab

Web access: Use JavaScript when generating pages

Info tab

Web access: Require SSL connection

Launch tab

When opened in a browser

Info Tab The first tab of the Properties box generally contains the most important settings, and that is certainly the case here. Allowing Domino to use JavaScript and SSL when sending information to a browser controls display and security options. JAVASCRIPT

Let’s take a closer look at the option to enable JavaScript. The JavaScript database setting has several implications when it’s enabled, with radically different behavior from when it’s not enabled. Here’s a summary of what this setting does when enabled: 

Formulas for hotspots are evaluated when the hotspot is clicked.



Multiple buttons can be displayed on a form.



No Submit button is automatically generated for input forms.



The following @Commands work on the Web: 

@Command([FileCloseWindow])



@Command([FileSave])



@Command([ViewRefreshFields])

Here’s a summary of what this setting does when disabled: 



Formulas for hotspots are evaluated when the form is opened. Only one button can be displayed on a form, and that one button will always be a submit button (don’t worry if you didn’t code it that way; whatever you did code will be interpreted as a submit button anyway!).

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

442

Chapter 10



Application Design



The following @Commands will not work on the Web: 

@Command([FileCloseWindow])



@Command([FileSave])



@Command([ViewRefreshFields])

The JavaScript database setting was present in Release 4.6 of the product and was disabled by default. In Release 5, the option is enabled by default. This is a point to consider when migrating 4.6 applications to Release 5.

SSL

The second setting listed in Table 10.2 enables Secure Socket Layer (SSL) connections to the database from a Web browser. This setting is useful for databases that need secure transactions between a Web browser and a Web server like e-commerce applications. Any Web browser accessing a database with this option enabled will be challenged to authenticate using its browserspecific SSL certificate. Launch Tab The last setting in Table 10.2 determines what part of the database will be shown, or launched, when the application is opened from a browser. Notes allows you to have separate launch options for the browser and the Notes client.

Notes Client Database Settings Several settings in the database Properties box apply only to users who access a database using a Notes client; these settings are shown in Table 10.3. Figure 10.5 demonstrates how to enable the database-wide image loading setting. TABLE 10.3

Notes Client–Specific Database Settings Tab

Setting

Info tab

Display images after loading

Launch tab

When opened in the Notes client

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design

FIGURE 10.5

443

Database image setting

The first setting in Table 10.3 tells Notes to load graphics completely into Notes client memory before showing them on the screen. This allows the rest of the information on the screen to display as the images are loading, therefore speeding up the delivery to the user. If this option is not enabled, each graphic is displayed in the order it is placed on the form, which slows down the presentation of any data located below the graphic.

This is consistent with the order of evaluation of all design elements (fields, subforms, sections, etc.) on a form in that they are evaluated based on physical placement from left to right, top to bottom.

The second setting in Table 10.3 determines what design element will be displayed when the database is launched from a Notes client. The Notes launch option and the Web client launch option are independent of one another, allowing you to set different options on a single database depending on the user’s client access mode.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

444

Chapter 10



Application Design

The Domino Designer environment provides you with tools and settings that will allow your application to be used in both a Web client and Notes client environment. In Chapter 11, “Application Coding,” you’ll discover techniques to add to the database settings discussed here.

Workflow Applications Like the decisions for how many databases to use in your application and what kind of client access mode to use, the decision to implement workflow in an application will affect how you design your application. In Notes, workflow is the automation of state transition and approval processes in an electronic format. It results in electronically flowing information into the hands of users who process it. Since Domino is both an application platform and a messaging platform, workflow is a natural type of application to implement in Notes. The Approval Cycle Template provided by Lotus is an example of a workflow application. There are two basic information models for workflow, as shown in Figure 10.6, and the models are often referred to by multiple names, including some that might not have made the following list. Let’s see if you recognize any of these popular phrases for the same two models:

FIGURE 10.6



On-demand versus subscription



Pull versus push



Share versus send

Push versus pull

Push using messaging

Pull by user access

The difference between the two models is easily illustrated with a nonprogramming example: magazines. When you stop by a newsstand and purchase a copy of Newsweek magazine, you are using the pull type of information flow. You go and get it when you want it. If, on the other hand, U.S. News and World Report is delivered automatically to your Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design

445

home every week, the push type of information flow is being used. The information is being pushed out to you without any weekly effort on your part.

Pushing Data to Users The subscription, push, or send model puts the responsibility for flowing information on the database to deliver it to the user. When the push model is implemented in Notes, the messaging infrastructure is used to deliver information to users. The main issue for this type of workflow is to identify and test the mail systems being used by the clients. You may find yourself in an organization that uses Notes as an application environment yet uses a non-Notes system as a mail infrastructure. Typically, when information is pushed to users, it is triggered by a state transition of a field on a document or a change in the environment. Imagine a status field that changes from a value of Pending to Complete. As a programmer, you can use the point in time that a field changes value as a trigger to push information to users. Likewise, when a document is first opened, which is a change in the environment, information can be pushed out to users.

Pulling Data from NSFs The on-demand, pull, or share scenario, on the other hand, dictates that the user is responsible for retrieving information from its source. This is an easy architecture to implement in Notes because of the shared nature of NSFs as data repositories on a server. By applying appropriate levels of access control to a database, you can make the information available to users for retrieval. The key to this type of model is that users must check the NSF to see if some action is required on their behalf, thus pulling the information when they desire it. The pull scenario is often used in combination with the push model. This provides central storage of information accompanied by an e-mail to the appropriate user to notify them that data has changed. One of the most popular ways to do this in Notes is to send a document link embedded in an e-mail to the person who needs to take an action on the data.

External Data Interactions While workflow revolves around processing data stored in NSFs and people interacting with that data, often an NSF interacts with data outside the Notes world. Notes can interact with external data in a variety of ways, including 

Import/Export

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

446

Chapter 10



Application Design



Copy/Paste



Embed/Attach



OLE/ActiveX/COM/DCOM



C/C++ Application Programming Interface (API)



Formula language code using Open Database Connectivity (ODBC)



LotusScript Data Object (LS:DO) ODBC class library



Domino Enterprise Connection Services (DECS)

Import/Export Data can be imported into Notes using a form as a structure to store data in documents and using a view to present the data. Importing and exporting document data is done in the Notes client and is not supported in the Domino Designer client.

Copy/Paste Copying and pasting data into Notes uses the Windows clipboard facility. The clipboard is used as a temporary storage location that holds only the most recent information placed in it. You can copy and paste data as well as design elements.

Embedding, OLE, COM, ActiveX Embedding attachments or using OLE, COM, and ActiveX components is accomplished in Notes through the use of rich text fields on a form. Rich text fields can contain any kind of data and therefore behave like a variant or Binary Large Object (BLOB) data. To embed attachments using a Web browser, a special File Upload control is available in Notes and can be embedded in forms and pages using the following menu sequence: Create  Embedded Element  File Upload Control Embedding objects creates a static set of information in Notes. Using OLE for linking, on the other hand, enables field-level exchange of data to named cells in external applications like Excel. Linking to a source is a good choice if the external data changes frequently and the Notes database wants to display the current source data at all times.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Application Design

447

C API The C API provides programmatic access to external data using C and C++. The entire Domino Object Model can be accessed using class libraries written in C that can be manipulated to interact with Notes data without benefit of the Notes user interface.

LotusScript The LotusScript language provides programmatic access to Domino using the built-in, Visual Basic–like language LotusScript. LotusScript has three class libraries that work with different types of information in Notes: 

Front-end classes



Back-end classes



ODBC classes (LS:DO)

The front-end and back-end classes allow interactions with Notes data that is on-screen (front end) and data that is stored to disk (back end). These will be examined in some detail in Chapter 11, “Application Coding.” ODBC Interactions In addition to interacting with front-end and back-end data, the LotusScript programming language can interact with relational data using ODBC. The LotusScript Open Database Connectivity (ODBC) library is known as the LotusScript Data Object, or LS:DO for our acronym collection. ODBC is used to create two different kinds of data interactions between Notes and the external world: 



Make Notes data available to external programs (like Crystal Reports). Make external data (like Microsoft Access data) available within Notes.

To use the LotusScript ODBC classes, appropriate ODBC drivers must be correctly installed on the machine executing the code. For instance, to retrieve data from Notes (thus using it as a data source), the NotesSQL driver must be installed on the machine retrieving the data. Once ODBC drivers are correctly installed for the data source, you can code one- or two-way transactions in Notes to do the following kinds of tasks: 

Perform data lookups into external databases.



Retrieve data back into an NSF from an external database.



Use external databases as a way to validate data entry in an NSF.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

448

Chapter 10



Application Design



Display data in Notes that was retrieved from an external database.



Modify raw data in external databases.



Update data in external databases on-demand or scheduled.

If you only need to perform a one-way read transaction of ODBC data, Notes formula language can be used. Using ODBC formulas does not require traditional programming knowledge. Four specialized ODBC formulas carry out the read and retrieve transactions, and they are noted in Table 10.4. TABLE 10.4

Formula Language ODBC Statements Formula

Purpose

@DbLookup

Execute the equivalent of a simple SQL Select statement to look up values.

@DbColumn

Retrieve a column of data from an external data source.

@DbCommand

Execute a complex SQL Select statement.

@DbExists

Determine if the ODBC data source exists.

DECS Domino Enterprise Connection Services (DECS) is a Notes form-based method to exchange data with external ODBC data sources like relational databases. As an optional service on a Domino server, the system administrator must enable the DECS task. Configuring a DECS environment consists of customizing components in the server-based DECS Administrator database. The two form-based components of DECS are described in Table 10.5. TABLE 10.5

DECS Components Component

Purpose

Connections

A document that specifies the external data being accessed

Activities

A document that specifies when and what data should be exchanged, namely, on document create, open, delete, or update

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

449

For example, to update information in a server-based Microsoft Access database, you would create a DECS Connection document in the DECS Administrator database on the server to connect to Microsoft Access using ODBC. Next, you would create a DECS Activity document to monitor a Notes form so that when the user changed a key data value in Notes, the mapped data value in Microsoft Access would automatically update itself. To map the fields between Notes and an external data source, DECS provides a form-based wizard to associate the monitored field in Notes to its corresponding field in the data source, Microsoft Access in this example. DECS also lets you filter or strain the data, massaging it on its way to or from Notes. In some circles, this is referred to as data percolation, percolation referring to an analogy of water passing through coffee grinds, transforming it to coffee along the way. Transforming data is done with formula language programming.

To integrate with relational data, it’s a good idea to design your forms to include a unique identifier on the Notes side to match against the primary key in a relational database. For instance, build in a unique ProductCode field in Notes to map to the ProductCode primary key in a relational system.

Database Design

D

atabase design is one level down from application design since an application can be made up of multiple databases. At the database level, you do two things: 

Configure database-wide settings.



Create design notes to solve the business problem at hand.

Domino provides a variety of database design elements to help you build a good application. A fairly comprehensive list of design elements is shown in Table 10.6, together with a brief description. TABLE 10.6

Design Elements Design Element

Purpose

About Document

Help menu–accessible document describing database’s purpose

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

450

Chapter 10



Application Design

TABLE 10.6

Design Elements (continued) Design Element

Purpose

Using Document

Help menu–accessible document describing how to use database

Actions

Utility tasks that execute code and are activated by a button click

Agents

Code modules that perform utility functions and scheduled tasks

Applets

Shared applet resources that can be embedded in a rich text field

Buttons

Clickable design elements that execute code

Database Script

LotusScript code that executes for database-wide events

Fields

Atomic data storage unit

Folders

User-determined index collections of documents

Forms

Structures containing fields to gather and present user data

Frameset

Resizable windows to organize scrollable information

Hotspots

Clickable areas on pages and forms that execute code

Icon

Graphic to visually identify a database

Images

Shared graphics stored once and reused many times

Internal fields

Special fields that provide internal document information

Links

Clickable areas that jump to other places in an NSF

Navigators

Graphic-based interface to aid database navigation

Outline

Hierarchical listing of forms and views

Page

Rich text container for displaying text and graphics

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

TABLE 10.6

451

Design Elements (continued) Design Element

Purpose

Reserved fields

Predetermined fields that have associated side-effect behavior

Script Libraries

Globally reusable LotusScript routines for a database

Sections

Collapsible areas on pages and forms

Shared Actions

Actions intended for use on more than one form or view

Shared Fields

Fields intended for use on more than one form

Subforms

Reusable components that can be embedded in a form

Synopsis

Snapshot documentation of an application

URL links

Clickable areas that jump to an Internet address

Views

Formula-determined index collection of documents

Design Notes Design elements are stored in design notes in an NSF. Not all design elements have their own design notes but, instead, are combined with other elements. Buttons, for example, are stored inside the design note of the large object that contains the button, perhaps a page or a form. The Design Panel for a database in Domino Designer displays the design notes for a database and provides a way to modify design notes and add new ones. Figure 10.7 shows the Other design category selected and the Icon design note highlighted.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

452

Chapter 10



Application Design

FIGURE 10.7

Other resources Design Panel

Design Document Properties Each design note has a set of properties associated with it that can display or control aspects of the design object’s behavior. True to form in the Lotus product line, there is always more than one way to perform a task, and you can access design document properties in at least the following three ways: 





Click the Display Infobox button at the top right corner of Designer. Right-click the design note and select Design Properties in the context menu. Use the menu options File  Document Properties with design note selected.

Design properties are displayed in a tabbed Properties box, as shown in Figure 10.8, and describe the attributes that apply to the selected design object. The tabs of the Properties box show an icon describing the purpose of the tab, and moving your mouse slowly over the tab will display a text description.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

FIGURE 10.8

453

Design document properties

All design notes have four tabs that provide information about the design object. The tabs and their descriptions are shown in Table 10.7. TABLE 10.7

Design Note Tabs Tab

Information Contained on the Tab

Info

Dates and times of when the design note was created, accessed, and modified, by whom, and its size

Fields

A scrollable list of all the fields in the design note and the value of each field

Design

Whether this design note can be overwritten by an associated template, what template to inherit from, and other information about the database design

Document IDs

The unique document ID for the design note

Design Document Inheritance You learned earlier that databases can inherit their design structure from a template and that the server’s Design task updates server-based databases from server-based templates on a nightly basis. The Design tab on a Design document

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

454

Chapter 10



Application Design

Properties box shows that inheritance can also be enabled or disabled at the design element level, not just at that database level, as shown in Figure 10.9. FIGURE 10.9

Document-level inheritance

This means that even if a database inherits its design from a template, an individual design element, like the one used in Figure 10.10, can prohibit inheritance on itself. FIGURE 10.10

Prohibiting design refresh

Template A

Template B

Database

Other design notes

Design note

Several design notes, by default, do not allow design refresh, including the ones listed below: 

About document



Using document



Database icon



Database title

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design



Access Control List (ACL)



Replication settings

455

For settings that are stored in a design note, like the About and Using documents, you can change the default setting in the design note’s Properties box to remove the prohibit refresh restriction. An individual design element can also inherit its design from a completely different template than the one being used for the database as a whole. This technique is useful when you want to use many of the features in an existing template but perhaps not all the design features. If you inherit from a template and don’t protect an individual design note, each night when the template refreshes the database, any changes you made to the design note are overwritten. To summarize inheritance, Domino allows a database to inherit from exactly one template while at the same time allowing individual design elements to prohibit the inheritance or to inherit from separate templates. Inheritance applies to all named elements that are stored in their own design note.

Document Design The purpose of the design notes we’ve been discussing is to store structures created by the programmer and used by users of the database. Data entered by users in an application is stored in documents that are based on form design notes. Documents represent the user content stored in a database. To create a document, a user works with a form created by a programmer. The user enters data into fields placed on the form and then saves the information. The process of saving the information creates a new document or updates an existing document. Document = Save(Form + Fields + User Data)

Form Design Forms are the most important design element in a Notes database. Only through the use of a form design note can a user store and view information

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

456

Chapter 10



Application Design

in documents. A form can be made up of a combination of any of the components in Table 10.8. TABLE 10.8

Form Components Component

Function

Fields

Store user data

Text

Label user data and present static information

Graphics

Used as hotspots and to improve aesthetics

Subforms

Reusable, embeddable units that are exactly like forms except these need to be embedded in a form to be used

Sections

Collapsible areas on a form used to organize and streamline the presentation of information

Embedded Elements

Using the Create menu, the following elements can be embedded in forms and pages: –Outline –View –Date Picker –Group Scheduler (not allowed in Pages) –Folder Pane –File Upload Control (for Web clients only and not allowed in Pages)

Special formatting elements

Used to make an application more user friendly, e.g., horizontal rules, tables

From the form structure created by a programmer, users interact with the system to create, edit, and retrieve documents. Forms and Documents A document in Notes exists in three distinct states, each of which is depicted in Figure 10.11: On-screen front-end What the user sees In memory What is interacted with when the document is open On-disk back-end What is stored to disk in the NSF

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

FIGURE 10.11

457

Front-end and back-end documents Store

NSF

Keyword Red Merlot

Key = Red Value = Merlot

Keyword Key Value

Retrieve

Form

Red Merlot

Document

In-memory document On-screen document a.k.a. Front-end document

On-disk document a.k.a. Back-end document

The distinction between the front-end document and the back-end document is important in Notes. The Domino Object Model is actually split into front-end class libraries and back-end class libraries to provide programmatic access to the document in these two states. In the on-disk representation of the document, the separation of the form from the data in the document allows Notes to keep overhead storage low while providing a flexible presentation structure to the data. Consider an NSF that contains 100,000 documents, all based on the same form. The form itself is stored once and the data is stored in the 100,000 documents. Notes keeps track of the name of the form that was used to store the document data in a special internal variable called Form. Figure 10.12 demonstrates that the document Properties box can be used to inspect the value of this special internal variable. FIGURE 10.12

Internal Form variable

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

458

Chapter 10



Application Design

When one of the documents is opened, Notes locates the form, presents the form structure, and populates it with the document data from disk. In a sense, a dynamic merge of the two takes place at runtime. This dynamic merge at runtime has the benefit of allowing changes to a form structure over time to be reflected in previously saved data. For example, if you add a new field to a form and give it a default value, the next time you edit a previously saved document, the new field and its default value will be saved with the document data. Stored Forms While the default in Notes is to store the form separately from the document data, a form attribute allows you to override this default and store the form structure with the document data. This is called creating a stored form. This form attribute can be set using the form’s Properties box as shown in Figure 10.13. FIGURE 10.13

Creating a stored form

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

459

ADVANTAGES OF STORED FORMS

With the form stored in the document, the amount of disk space will go up. Why use it, then, you ask? Well, what if you decide to implement a push workflow design that involves mailing a document to users? When a document is mailed to a user’s mail database, the form needed to view the data is now stored in a different database. Without the form, Notes will not be able to render the document data since the form acts as a viewing mechanism. If the form is stored in the document, when it gets mailed to a user and received in their mail database, the viewing mechanism is a part of the document, solving the presentation problem. DISADVANTAGES OF STORED FORMS

Storing a form in a document is beneficial for workflow, but there is a downside. If you modify a form over time, documents previously saved using the stored form will not have their form structure updated to reflect any changes. Basically, when a form is stored in a document, that document contains a snapshot of the form as it existed at save time. Notes will not automatically update the form structure in previously saved documents. $TITLE AND FORM

When a form is stored in a document, the special internal variable called Form is not used. Instead, a different special internal variable called $Title identifies the name of the stored form, as shown in Figure 10.14. FIGURE 10.14

$Title for stored form documents

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

460

Chapter 10



Application Design

To determine if a document is storing a form, you can inspect the fields of the document, and if $Title exists and Form does not, the document is being stored in the form. Forms to Display Data Since the default in Notes is to store the form separately from the document, a natural next step is to allow a different form to display the document data than the form that was used to save the data. At runtime when a document is opened, Notes goes through a series of steps to determine what form to use to display the data. The following sequence is used to find a form to display the data: 1. If the form is stored in the document, use the stored form. 2. If the document is being displayed in a view and the view has a form

formula, use the form specified in the form formula. 3. If the form is not stored in the document and no form formula is in effect,

use the form that created the data as denoted by the Form variable. 4. If there is no stored form, no form formula, and the Form variable

doesn’t exist or the form identified by the Form variable doesn’t exist, use the default database form. FORM FORMULA

When a document is opened through a view, the view can specify a particular form to use to present the data on the screen. This is called a view form formula, which you’ll often see referred to simply as form formula. The form formula event is coded in the programmer’s pane as shown in Figure 10.15. FIGURE 10.15

Form formula

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

461

DEFAULT FORM

One form in a database can be marked as the default form. This form will be used to present data on the screen if at least one of three conditions is met: 





The document doesn’t have a stored form. The view displaying the data doesn’t have a form formula. The original form used to store the data isn’t found.

A form can be marked as the default form on the form’s Properties box as shown in Figure 10.16. FIGURE 10.16

Default database form

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

462

Chapter 10



Application Design

If Notes is unable to open the document using the preceding four rules, then an error message is displayed. At this point, you cannot open the document. The error message will let you know that a default form couldn’t be found or the form used to create the data wasn’t found. To fix this problem, you would need to create a form that contains the appropriate fields necessary to display the data in the document. Form Events and Relationships While Notes is not an object-oriented language, an NSF can be thought of as an object-based event-oriented environment. Design elements, like Forms, are treated as objects.

To be object-oriented, a language must programmatically support polymorphism, inheritance, and encapsulation. Notes is written in the spirit of these but does support them completely.

As a document moves from state to state (on-screen to memory to stored), a set of events for the form provides a way for programmers to customize the behavior of the document. The events are shown in Figure 10.17 and will be more fully examined in Chapter 11, “Application Coding.” FIGURE 10.17

Form events

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

463

In addition to the event-oriented nature of Notes, inheritance can take place at the document level. Forms, and therefore documents, can be related to one another through inheritance. Inheritance in Notes’s documents takes the form of parent-child documents and values that can be passed from one document to new documents. PARENT-CHILD

A document is created as one of three types, as shown in Table 10.9, and the type is set using a form property. TABLE 10.9

Form and Document Types Type

Description

Document

Main or parent document, the default type

Response

Child document linked to a parent document via $Ref

Response to Response

Child document to either a Document or a Response document

Response documents and Response to Response documents are usually referred to simply as Response documents. To create the parent-child document relationship, Notes adds a special internal variable called $Ref to all child documents. $Ref contains the document unique ID of the parent document. A document unique ID contains the server’s ID, so it is unique across all Notes servers. A document also has a Note ID, which is unique within a database. As a programmer, you do not have to do anything to maintain $Ref other than setting the form type in the form’s property box to allow the relationship to take place. The value of $Ref can be inspected using the document Properties box as shown in Figure 10.18.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

464

Chapter 10



Application Design

FIGURE 10.18

$Ref

INHERITED VALUES

Another type of relationship between documents is one where a document inherits values from another document. The inheritance takes place when a new document is created while another document is open or selected. If the form property that allows inheritance is enabled, field values on an open document can be inherited into the document being created. Below, you see the two Properties box options that enable fields to inherit values from other documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

465

The entire contents of one document can be inherited into a single rich text field on a new document. In this case, Notes will render the data in one of the following three ways depending on how you set the property: 

Link



Collapsible rich text



Rich text

Alternately, individual field values can be inherited into fields on the new document. If the fields are Editable, they’ll inherit a starting value that can be modified by the user. Let’s take a closer look at fields and how to design them.

Field Design Fields are a part of the structure of a form and are the mechanism by which user data is stored in a document. When you think about the form created by the programmer, the term field is used to describe the data entry areas for users. When you think about a document that has been saved by a user, the term item refers to the data that has been stored in a field. Fields are in a form; items are in a document. Field Types Domino Designer provides a variety of field types to design your fields. A list of field types appears in Table 10.10. TABLE 10.10

Field Types Field Type

Display Behavior

Type of Data

Text

Editable or Computed alphanumerics

Character data

Date/Time

Date, time, month, year, day

Numeric data

Number

General, fixed, currency, scientific

Numeric data

Dialog list

Drop-down list

Text list of character data

Checkbox

Multiple-selection check boxes

Text list of character data

Radio button

Mutually exclusive radio buttons

Text list of character data

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

466

Chapter 10



Application Design

TABLE 10.10

Field Types (continued) Field Type

Display Behavior

Type of Data

Listbox

Drop-down list

Text list of character data

Combobox

Drop-down list

Text list of character data

Rich Text

Graphics, embedded items, etc.

Binary large object (variant)

Authors

List of valid Authors of a document

Text list of character data

Names

Usernames from the database’s ACL or the Domino Directory

Text list of character data

Readers

List of valid Readers of a document

Text list of character data

Password

Asterisks in place of typed values

Encryptable character data

Formula

Used to select documents

Character data

Of the above field types, the only one that cannot be displayed in a view is rich text data. Rich text fields can contain any kind of data including graphics, video, audio, and spreadsheets. In R5, the following graphic formats are stored and rendered in their native format while other types of formats are stored and rendered as 256-bit BMP images: 

Bitmaps (BMP)



Graphics Interchange Format (GIF)



Joint Photographic Experts Group format (JPG)

Each field of data is tagged as summary or non-summary data. Only summary data can be displayed in a view. Rich text fields are non-summary data. You can examine whether a particular field is summary by examining its information in the host document’s Properties box. If the Field Flags option is not tagged with the word SUMMARY, the field cannot be displayed in a view or used in calculations.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

467

Field Value Types Fields have an associated value type that determines how the field will behave on the form and whether the value for the field will be stored back in the NSF. Field values are evaluated at different times depending on the value type. Field value types and their behavior are described in Table 10.11.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

468

Chapter 10



Application Design

TABLE 10.11

Field Value Types Saved in the NSF?

Value Type

Behavior

Evaluates When?

Editable

User-modifiable data

Default Value event executes when document is created and field does not already have a value

Yes

Computed

Formula evaluation or hard-coded value is stored in field variable

When document is –Created –Saved –Refreshed

Yes

Computed For Display

Formula evaluation or hardcoded value is calculated for on-screen display only

When document is –Created –Loaded into memory –Opened in Edit mode –Refreshed

No

Computed When Composed

Formula evaluation or hard-coded value is calculated and stored in field variable

When document is created

Yes

In addition to the Default Value event associated with an Editable field, two other events trigger on an edit field when a document is saved or refreshed: 

Input translation event



Input validation event

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

469

INPUT TRANSLATION EVENT

The input translation event gives you a place to write code that will massage the data before it is stored in final form on disk. An example of when to use this event is if you want the value in a field to always be translated to uppercase regardless of how the user typed the data. INPUT VALIDATION EVENT

The input validation event also fires when a document is saved or refreshed. It executes after the input translation event. The input validation event is used to make sure that the user has typed a value in a field or to make sure it matches a certain format, for example, a length of 20 characters. Fields with Special Behavior Notes has several fields that you can place on a form that will cause a side effect. In this case, a side effect is a specific behavior that takes place if the special field is on the form when certain events fire. Several of the special fields are used in workflow applications that have implemented the push methodology and serve the purpose of mail-enabling documents. Table 10.12 describes some of the most often-used special fields. TABLE 10.12

Special Fields Field Name

Trigger Event

Field Value

$$Return

Web submit of a form

Display a text message to Web client

SaveOptions

Document save

1 to allow documents to be saved, 0 otherwise

SendTo

Document save

User ID of person to send document to

CopyTo

Document save

User ID of person to send copy to

BlindCopyTo

Document save

User ID of person to send blind copy to

Encrypt

Document save

1 to encrypt mailed document, 0 otherwise

MailOptions

Document save

1 to automatically mail, 0 otherwise

ReturnReceipt

Document save

1 to receive a receipt, 0 otherwise

Sign

Document save

1 to add an electronic signature, 0 otherwise

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

470

Chapter 10



Application Design

For mail-enabling documents in workflow, the SendTo field is one of the most important special fields. It must be present for documents to be mailed automatically. In fact, other special fields, like MailOptions, rely on the presence of SendTo for mailing purposes. HIDE WHEN ATTRIBUTES

Special fields are normally created as editable text fields and can be placed on a form and hidden from users using Hide When attributes. This makes the field available programmatically and for execution at trigger time but doesn’t present unnecessary information to the user. A field’s property box allows you to set Hide When attributes. Figure 10.19 shows the options to set to hide a field from all users but leave it visible to programmers. FIGURE 10.19

Hide fields from users

When Hide When attributes are applied to a field, all fields on that line of the form are hidden. Hide When is paragraph-based, which means the hide behavior will stay in effect until a carriage return line feed (CRLF) character is reached. The exception to this is for fields and text placed inside table cells; table cells can be hidden independently regardless of whether a CRLF has been reached.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

471

Hide When attributes can also be applied to any text, any fields (not just special fields), images, buttons, actions, shared actions, and sections. The paragraphbased hiding applies to these design elements as well.

Presentation Design Forms and fields are the design elements used to create user documents. With documents created, the next challenge is to present the information to database users, providing a way to create or retrieve information. Notes does not provide direct access to documents; rather, views and folders are the mechanism used to present collections of documents to users.

Views Views are the most important document presentation element in Notes. Simply put, if an application has a solid set of forms and a good set of views, you have a workable application. A view is a filtered row-column list of documents in a database. Each document can be opened to drill down to the complete document contents. A view, then, is a collection of documents that appear in Notes as a scrollable list, as shown in Figure 10.20. FIGURE 10.20

Views: a list of documents

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

472

Chapter 10



Application Design

The view design note stores a description of the view structure. It does not contain the view itself. Views are dynamic pointer structures used to index and access documents in an NSF. As documents are added or deleted to the NSF, the pointer structure (or index) is updated. These pointer structures appear on-screen to users, presenting one row of data for each document. Document Presentation The documents displayed in the rows are determined through the coding of a view selection formula. The selection formula filters out documents that don’t meet the selection criteria and, therefore, defines the documents that should be included in the view. Formulas are used in views in three ways: 

Code a view selection criteria formula.



Code a value for a column.



Code a form formula to determine the form to use to present document data.

For instance, if you have a CompanyName field on a form, you might code a view selection formula that would display only documents where the CompanyName field was a certain value, like “ABC Corporation.” Assuming the documents were created with the “Company” form, the view selection criteria would look like this: Select form=“Company” and CompanyName=“ABC Corporation” Your selection criteria should be as exact as possible in order to build an efficient view. The more general your selection criteria, the more documents will appear in the view collection. View indexes can consume quite a lot of space and memory. A column in that same view might have the formula “CompanyAddress”, which would display the value stored in the document’s CompanyAddress field. Columns can display values from fields on the document, calculations, and icons. While formulas are used to determine the data that appears on a user’s screen, view and column properties determine how the data looks. VIEW PROPERTIES

The Properties box is traditionally where visual attributes of a design element are set. A view’s Properties box, shown in Figure 10.21, contains settings that affect how the view as a whole is displayed.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

FIGURE 10.21

473

View properties

View properties exist to do all of the following: 

View name and alias.



Add a comment describing the view.



Set the Style to Standard row-column or to Calendar.





Mark the view to be the default view that opens when the database opens. Mark the view to be the default view (a database must have one default view).



Collapse the view hierarchy when the view is opened.



Show Response documents using an indented hierarchy on-screen.



Show the view in the View menu in the Notes client.



Set colors for the view background and for the alternate rows.



Determine row and heading spacing.



View index refresh frequency.

COLUMN PROPERTIES

Column attributes are set in the column Properties box as shown in Figure 10.22.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

474

Chapter 10



Application Design

FIGURE 10.22

Column properties

You can control how each individual column of data is displayed. Settings include the following: 

Column title and width



Whether to hide the column (useful for programming sort values)



Whether to display twisties (collapsible categories of documents)



Whether to display the column as an icon



Sorting criteria (ascending, descending, or both)



Creating totals for a numeric column



Font, color, and alignment for the data in the columns



Font, color, and alignment for the column heading



Number and date formatting

One of the column settings you’ll want to take advantage of for view performance is the clickable heading for sorting a column in ascending, descending, or both orders. Since every view is an index into a collection, if you can minimize the number of views you need by making good use of dynamic column sorting, you’ll be improving the overall performance of your database. Re-sorting an open view is faster than opening a different view.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

475

Types of Views Most of the views created in a server-based NSF are shared views, meaning that anyone who has access to the NSF can use the views. There are basically two types of views, shared or private, but there are nuances that expand the following list to six types of views. Table 10.13 lists and describes the types of views. TABLE 10.13

View Types View Type

What It Means

Shared

Available to all database users

Shared, contains documents not in any folders

Available to all database users and displays only documents not found in any folders

Shared, contains deleted documents

Available to all database users and displays only documents not marked for deletion

Shared, private on first use

Becomes private to the user when opened

Shared, desktop private on first use

Becomes private to the user when opened and is stored in the user’s DESKTOP5.DSK file, not the NSF file

Private

Available only to the user who created it

Categorized Views Regardless of its type, a view can be grouped, or categorized, based on a column value. When a view is categorized, the category becomes an expand or collapse on-screen region for the user. Selecting the option to display twisties for categories will help your users to know they are working with a collapsible area.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

476

Chapter 10



Application Design

Embedded Views Normal and categorized views generally display on the right-hand side of a Notes screen, take up most of the user’s screen, and list the documents in a rowcolumn arrangement. As an alternative to the default presentation, views can be embedded within a form or a page. The documents render in the same rowcolumn arrangement, but graphics, text, and fields can be placed on the same screen as the view to add functionality and make the presentation a bit nicer. Embedded views have their own set of properties, as shown in Figure 10.23, that are configured in addition to view and column properties. FIGURE 10.23

Embedded view properties

When used with categorized views, embedded views take on the additional display capability of being able to render a single category of the categorized view. The Show single category event, shown in Figure 10.24, is used for this purpose. FIGURE 10.24

Show single category

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

477

Single category views can reduce the number of overall views in your database, minimizing database size and improving database performance. Consider the example of a categorized view that lists wines from around the world and displays them according to their vineyard regions. You can embed the categorized view in a page, write a formula in the Show single category event to dynamically show one of the categories, and use the view as a link destination from a world map. Clicking Argentina in the world map would display the single category of all wines from Argentina. If you don’t use single category views, then to create this clickable world map navigation, you would need to create separate views for each wine region. View Applet Whether a view is presented using its normal presentation method or is embedded in a form or a page, a special view applet can be used to display views to Web users. By default, when Domino renders a view to a browser, it is converted to HTML. With the view applet, a browser uses Java and XML to render data retrieved from the Domino server. The look and feel of a view rendered with the applet has the following nice advantages over the default HTML rendering: 

Twisties for expanding and collapsing rows without generating a new HTML page for each expand or collapse configuration



Columns that can be resized by the browser user



Horizontal and vertical scroll bars



Increased number of row-column color and font options

View Index As pointer structures to collections of documents, view indexes are dynamic. With documents and views as the heart of an application, maintaining healthy, accurate indexes is a necessity. Notes does this in the background using a task called the Notes Index Facility (NIF). NIF works on collections of documents, including views and folders. Whenever a view is accessed, the NIF is active. It handles the following tasks: 

Opening a view collection



Closing a view collection



Updating the documents in a view collection



Searching for a document in a view collection



Updating a view index by adding or deleting pointers

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

478

Chapter 10



Application Design

When changes (additions and deletions) to a view index or data collection are made, the back-end storage of data has changed. View settings control whether the view index and collection is manually or automatically updated. For users to see the change, the view needs to be refreshed. Using the view properties, you can set options to refresh the view in the following ways: 

Display a Refresh icon at the top left corner of the view for the user to click.



Refresh the view automatically before opening it.



For open views, refresh the view from the top row toward the bottom row.

Folders Like views, folders are a mechanism to allow user access to documents. Contrary to views, however, the contents of a folder are determined by the user. The user drags and drops pointers to documents into a folder, and the data appears as rows of documents as shown in Figure 10.25. FIGURE 10.25

Contents of a folder

The folder design note stores a description of the folder structure. Just like a view, folders themselves are dynamic pointer structures.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

479

Framesets Framesets are used in Notes to present data to users in an organized manner. A frameset is made up of multiple frames with each frame displaying an area on the screen. Frames do not overlap. Each frame in the frameset can operate independent of other frames; however, you can also code frame behavior so that clicking a link in one frame displays data in another frame. Both framesets and frames have properties that control how they display and behave. These settings represent the difference between using frames for presenting data over simple invisible border tables: 





Data in frames is both horizontally and vertically scrollable by the user. Frames can be resized by the user. Data in one frame can change based on formulas and links in other frames.

Frame content can be set using Notes links, URL links, or any named element in an NSF.

Outlines While framesets present information in different on-screen regions, outlines present information in a hierarchical structure. An outline can be used by a programmer to help build an application structure and by end users to navigate an application. As a named element, outlines can be used as frame content to provide clickable links to change data in other frames. Outline Entries An outline is made up of outline entries. The entries can link to any design notes in the NSF, including forms, pages, views, folders, documents, URLs, or other Domino databases. To be viewable in Notes, outlines have to be embedded in a page or form. Embedded outlines have the following properties that can be set to control how the outline looks and behaves: 

The size of the outline



Font choices and colors



Showing graphics or twisties for outline entries



Using HTML or Java applet for rendering to Web clients

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

480

Chapter 10



Application Design

Outline Applet Like the view applet discussed earlier, a Java applet can be used to present an outline to Web clients. This applet adds the following special behavior to an outline that isn’t available in the default HTML rendering to a Web client: 

Vertical and horizontal scroll bars



Mouse-over color effects on outline entries

Pages Pages in Notes are rich text containers used to present static information to users. Properties for a page control how it renders in the Notes client and a Web client and include settings like the following: 

Treating the page contents as HTML



Color for Web links that are active, visited, and unvisited



Background color



Launch attributes

The option to treat page contents as HTML means that Domino will not perform its on-the-fly conversion of the page contents to HTML when the page is requested from a browser. Instead, the page is passed directly to the browser and rendered as is. This is useful if you’re embedding HTML, XML, or JavaScript in your pages. Settings to control page behavior are available with the Page Properties box, as shown in Figure 10.26. FIGURE 10.26

Page properties

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Database Design

481

Page Contents The types of data that can be placed on pages are wide and varied. Since it is a rich text container, almost anything goes except for Notes fields. Pages don’t store data items for users since they cannot contain Notes fields. The following list gives you an idea of the kind of content a page can contain: 

Hotspot links to other destinations



HTML tags



JavaScript embedded in HTML tags



Buttons



Attachments



Graphics



Tables



Embedded elements

Embedded Elements While the focus of Pages is static information, embedding named elements can give Pages the ability to present nonstatic information. Embedded elements include the following: 

Outlines



Views



Navigators



Date pickers



Folders

From the above list, outlines and date pickers cannot be displayed at all unless they are acting as embedded elements. The method for embedding elements into a Page is a menu sequence similar to the following: Create  Embedded Element  Outline

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

482

Chapter 10



Application Design

Summary

The art of building a good Domino application is combining the design elements to create an effective solution to the business problem at hand. Forms, fields, views, and folders are important building blocks for a good application. In the next chapter, “Application Coding,” you’ll examine programming techniques for creating interactions within and between design notes as well as between databases.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Summary

483

Key Terms Before taking the exam, you should be familiar with the following terms: application back-end classes back-end document database default form Default Value event Domino Enterprise Connection Services (DECS) embedded element fields form form formula Formula language front-end classes front-end document Hide When attributes Hypertext Markup Language (HTML) input translation event input validation event items JavaScript LotusScript LotusScript Data Object (LS:DO) mouse-over Notes Index Facility (NIF)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

484

Chapter 10



Application Design

ODBC outline Page Properties box Secure Socket Layer (SSL) send SendTo Show single category event stored form template inheritance templates view view selection formula workflow

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

485

Review Questions 1. The users of Abigail’s Web application appreciate how the expandable

and collapsible categories organize the contents of the views. But at the same time, they’ll be unhappy if opening and closing the categories is slow. Which of the following view attributes will help improve the performance of expandable categories on views? A. Treat view contents as HTML. B. Use applet in the browser. C. Don’t show categories with zero documents. D. Restrict initial index build to designer or manager. 2. Brad is designing a form that will be used by Web users and Notes clients.

While most of the information is identical given the two different access methods, a handful of fields apply to the Web environment or to the Notes environment. Which of the following design elements will allow Brad to dynamically invoke fields at runtime depending on the access method, while providing the least amount of maintenance overhead? A. Shared fields B. Subforms C. Hide When criteria D. Sections 3. Calyn is writing a Notes application that will interact with Microsoft

Excel using Object Linking and Embedding. What type of Notes field should she place on the form if she plans on opening the OLE object from inside a Notes document? A. Text B. Rich text C. Combobox D. Shared

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

486

Chapter 10



Application Design

4. Dina has just taken over a Notes application from a programmer who

left the company before she arrived. On inspecting the design elements, she notices two subforms with similar names, Footer and tempFooter. Assuming tempFooter was unnecessary, Dina deletes the extra subform. The next day, users complain about not seeing some data that used to be in a document and getting the error message “Subform: tempFooter not loaded.” Apparently that subform wasn’t extra! What should Dina do to correct the problem? A. Recreate an empty subform named tempFooter. B. Recreate a subform named tempFooter with the exact contents it

had originally. C. Change the form that contains the subform to use the Footer sub-

form instead. D. Find a new job since the data is permanently gone and the users

are angry. 5. Eli is working on a Web site application that will sport lots of graphics

that will be used as image maps. Which of the following graphic formats will not be rendered in its native format? A. BMP B. GIF C. JPG D. TIF 6. Felicia is creating columns in a view to display documents that were

created based on the Company form. She’s attempted to get the information in a rich text field to be visible in the view. Why is she unable to do this? A. Rich text data is not stored in the NSF. B. Rich text data is not flagged as SUMMARY data. C. Rich text data is flagged as SUMMARY data. D. Rich text data must be marked as “Display images after loading”

on the form properties.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

487

7. Gerry has added an editable text field called Company_Name to his

form. He wants to set a starting value for the field, error-check it, and make sure that only certain types of values are valid in the field. In what order will the appropriate field events execute? A. Default Value, Input translation, Input validation B. Default Value, Input validation, Input translation C. Input translation, Default Value, Input validation D. Input validation, Default Value, Input translation 8. Heidi is inheriting the design for her database from one of the standard

Lotus templates. She has decided to customize one of the standard forms that is part of the template. When she completes her customization, which of the following should she also do? A. Enable inheritance in the source form in the template. B. Enable inheritance in the destination form in the database. C. Disable inheritance in the source form in the template. D. Disable inheritance in the destination form in the database. 9. Ivan is examining the data in the LicenseNumber editable text field of

the Vehicle documents in one of his production databases. He notices that some of the data appears with mixed case, some is completely in lowercase, and still other data is in uppercase. In which of the following events should he write code to help improve the integrity of the data? A. Default Value B. Input translation C. Input validation D. All of the above

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

488

Chapter 10



Application Design

10. Jacqueline has added a new field to the Product form and given it a text

label and a default value. Upon rolling it out to her production server, she notices that none of the existing documents are displaying the new field or the text label even when she goes into Edit mode. All the other fields appear to be displaying as normal. What might explain this? A. The default value is invalid. B. The documents are using stored forms. C. The form will not be updated until the nightly Update task runs. D. The field is marked as SUMMARY. 11. Kelly is confused as to the difference between items and fields. Which

of the following is a correct statement distinguishing the two? A. Items are stored in design notes. B. Fields and items are the same thing; it just depends on whether

you’re using the Notes client or the Web browser. C. Fields are created when users type data into items on a form and

then save the document. D. Items are created when users type data into fields on a form and

then save the document. 12. Lyle has decided to use Notes to record all of his thoughts for the

music album he is working on. What he’d like to do is come up with a song title, store it in a document, and then, over time, capture thoughts for the song and associate each thought with a date time stamp in additional documents that can be displayed in a view. Which of the following view settings should he be sure to set if he wants the data grouped by song? A. Set the view name and alias. B. Collapse the view hierarchy when the view is opened. C. Show Response documents using an indented hierarchy on-screen. D. Set colors for the view background and for the alternate rows.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

489

13. Molly wants users to be able to add a picture of themselves to their

Personnel Profile by editing it through a Web browser. Which of the following will she need to add to the Personnel Profile form to accomplish this? A. Embedded Element—File Upload Control B. Rich text field C. Names field D. Subform 14. Nolan is weighing the advantages of using framesets over simply for-

matting the information in his database inside of invisible-bordered tables. Which of the following is not an advantage of framesets? A. Scrollable by the user. B. Resizable by the user. C. A separate design element is not needed. D. Data can be changed based on formulas and links. 15. Oscar has added entries to an outline to jump to each of his pages.

He’d like to use the outline as the first thing that opens when the database launches. Which of the following does he need to do to use the outline in this manner? A. The outline needs to be embedded in a page and the page set as the

database launch attribute. B. The outline needs to be placed in a frameset and the database

launch attribute set to launch the frameset. C. The outline needs to be placed in a subform before being set as the

database launch attribute. D. An outline cannot be launched in any way when a database first

opens.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

490

Chapter 10



Application Design

16. Porscha wants to use a graphical front end in Notes to link to existing

data. Ideally, she’d like to include graphics that match the product branding the marketing department folks are pushing. Since the front end will not store user data, which of the following would be a good design element choice? A. Page B. Form C. Subform D. View 17. Quinton is building a template that will refresh a production database

on his home server and a remote server. The production database replicates between the two servers. What is the best way to push design changes out to the remote server? A. Place the template on both the home server and the remote server. B. Place the template on the home server and let the Replication task

push data and design changes out to the remote server. C. Place the template on the remote server and let the Design task

update the information on the home server. D. Place the template on a local machine and push the changes auto-

matically out with replication. 18. Randi is building a new database to manage marketing source codes

and campaign information. She’d like the form to contain fields for the codes but would like the information to be organized in a way that users don’t get bogged down with too much information at one time. Which of the following will help her create an organized approach to the information on the form? A. File Upload Control B. Fields C. Subforms D. Sections

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

491

19. Sherri is creating a view that will display both main documents and

Response documents. She wants the Response documents to appear indented under the main documents, but instead of showing data from the Response document, she wants to show an icon to represent the Approval field. If the value of the Approval field is “Approved,” she wants a smiling-face icon to appear. If the value of the Approval field is “Denied,” she wants a frowning-face icon to appear. Which of the following attributes will she need to set in the Properties box? A. Set the view property to show main documents. B. Set the view property to show icons. C. Set the column property to show icons. D. Set the column property to show Response documents in a hierarchy. 20. Tasha wants to examine the attributes of a piece of information that

was collected in a form using an editable text field. The document has been previously saved. How can she examine the attributes and the value of the field at the same time without opening the document? A. Use the document Properties box and examine the item on the

Fields tab. B. Use a view to display the field’s attributes. C. Program a formula to display the field’s attributes on a page. D. Edit the document and unhide the field’s attributes. 21. Ute is running into hard drive space constraints on his production

server. He’s in the middle of designing a new application that will be deployed shortly and start consuming some of his precious space. Which of the following should he avoid if he wants to limit the size of documents to the smallest size possible? A. Shared fields B. Subforms C. Sections D. Stored forms

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

492

Chapter 10



Application Design

22. Virginia wants to remove data associated with the Gender field in

previously stored documents. On inspecting the fields using the document Properties box, she notices that there is no $Title field present. If she modifies the form and deletes the Gender field, what does she accomplish? A. This eliminates the field from the form structure and deletes the

data from previously stored documents. B. This deletes the data from previously stored documents but does

not delete the field from the form. C. This does not delete data from previously stored documents but

does delete the field from the form. D. The form is not modified since $Title is not present. 23. Walter is planning a lecture on stargazing. To collect his thoughts and

organize his ideas, he’s decided to use Notes to store his lecture notes. He’s designed a form and created one document so far. Since most of the documents will have some of the same information, he’s used copy and paste techniques to quickly create 10 lecture documents. Which of the following is a true statement about the lecture documents? A. Only one document exists with nine pointers to the original document. B. Ten documents exist, each with their own unique document ID

and Note ID. C. Ten documents exist, each with identical unique document IDs. D. Ten documents exist, each with identical Note IDs. 24. Xena has coded a form that contains a utility task that will execute code

when a button is clicked. The code is used only in one place in her application. Which of the following should she have used to create the code? A. Action B. Shared action C. Shared field D. Subform

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

493

25. Yvette has designed an application for Jill that makes use of embed-

ded views, including one that categorizes the projects she’s assigned to her staff members. Jill would like to make the project view available to her staff, but she only wants each staff member to be able to see their own projects. Given the scenario of embedded categorized views, which of the following techniques can Yvette use to give Jill what she wants? A. Show view using Java applet. B. Show single category event. C. Show view as HTML. D. This is not possible in R5. 26. Zulia wants to include a Close button on every form she designs. Her

application has 20 forms. She’d rather not create 20 buttons executing the same code. What should she create instead? A. Action B. Shared action C. Shared field D. Subform

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

494

Chapter 10



Application Design

Answers to Review Questions 1. B. Using the view applet in a Web application will retrieve the data

from the server and store it in browser memory for fastest access. Treating the view contents as HTML actually disables collapsible categories, so this is not an option. The option to suppress categories with zero documents won’t affect the expanding since there is nothing to expand! And finally, restricting the initial index build to designer or manager will affect the initial opening of the entire contents of the view, not the performance of the collapsible categories. 2. B. Dynamic subforms can be invoked at runtime based on a formula,

for example, using the @ClientType formula. Designing two subforms, one for the Web and one for Notes, would solve the problem. Hide When criteria is a reasonable answer. However, each of the Hide When fields would need unique names, while with subforms you can use a field with the same name on the two subforms. Shared fields are not appropriate since they are intended for multiple use on more than one form, and in this case we want to use a single form. Sections will not provide any value since they cannot be dynamically invoked. 3. B. Rich text fields function as generic containers, able to store all kinds

of data, much like Binary Large Objects (BLOBs) in the relational world. For interactions with OLE objects, rich text fields are required. Shared fields is a tempting choice because the name makes you think of sharing data between Excel and Notes; however, shared fields refer to a field created once and reused on many different forms. Text fields are limited to storing character data only, and Combobox fields present text data in drop-down list format.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

495

4. B. Deleting a subform affects all the documents that were created

using the form that contained the subform. While the data in the documents created with the subform is still intact, without the fields that were defined in the subform, data cannot be displayed. Recreating the subform with the exact fields on the original will allow the data to be displayed. Recreating an empty subform named tempFooter would eliminate the error message the users see, but it would not solve the problem of the missing data. Changing the form to use a different subform would also eliminate the error message but not display the missing data. While the last answer may be a programmer’s initial reaction, don’t panic; the data is still there! 5. D. Domino R5 renders BMP, GIF, and JPG graphic files in their native

format. All other formats are converted to, stored, and rendered as 256-bit BMP files. 6. B. Only data flagged as SUMMARY can be displayed in a view; rich

text is not SUMMARY data. All field data, including rich text data, is stored in the NSF. The option to “Display images after loading” is a database property that applies to Notes clients displaying graphics in forms and pages, not views. 7. A. The Default Value event fires if the field has no value when the

form is opened. When the document is saved or refreshed, the input translation event fires, doing things like putting text into uppercase. After input translation and when a document is saved or refreshed, the input validation event fires, performing tasks like checking the length of the data entered. 8. D. Heidi should mark the option on the Design Properties box of the

form design not to prohibit design refresh, therefore disabling inheritance at the design note level. If you inherit from a template and don’t protect an individual design note, each night when the template refreshes the database, any changes you made to the design note are overwritten.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

496

Chapter 10



Application Design

9. B. A formula coded in the input translation event can convert typed

data to uppercase before it is saved to disk. Using the Default Value event will not help because the user can type over whatever default value is supplied; based on this, answer D is incorrect as well. The input validation event is not used to convert data, but it could be used to make sure the user types a value in the LicenseNumber field. 10. B. Documents that store the form in the document will never have

their form structure updated after the document is initially saved. Future changes to the form structure only affect new documents created when stored forms are in use. If the default value was invalid, the field would appear empty and the text label would be displayed, so this is an incorrect answer. The nightly Update task on the server might have fooled you just because of the word Update, but what this task does is update views on the server, not document contents. Finally, fields marked as SUMMARY can display in a view, but this flag does not affect whether the field displays in a document. 11. D. The statement says it all; items are created when users type data

into fields on a form and then save the document. Items are referred to as Notes Items. Fields are stored in design notes, not items. The client access mode plays no part in distinguishing an item from a field. 12. C. To create a one-to-many relationship between song documents and

comment documents, a document-response (parent-child) relationship should be set up. Given this, the data will be grouped by song if he sets the option to show Response documents using an indented hierarchy. Setting a view name is certainly required, but an alias is not. Collapsing the view when it opens and setting alternate row colors will make the view more pleasing to look at, but neither will help group the data by song. 13. A. The File Upload Control can be used to allow Web clients to upload

information into a server-based NSF. If the environment was the Notes client, a rich text field would be used for a file attachment. The Names field does not apply since it lists the names of users in the database’s ACL or the Domino Directory. If the File Upload Control was embedded in a subform, answer D would be partially correct.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

497

14. C. Tables do not have their own design notes, in direct contrast to

framesets. The remaining answers are all advantages of using framesets over tables. 15. A. Outlines cannot be used directly; they must be embedded in either

a page or a form. By embedding the outline in a page, the database can launch the page to display the outline. The frameset option is a good guess, but the outline still needs to be embedded in either a page or a form to be usable in a frameset. Placing the outline in a subform will not help display it unless that subform is in turn embedded in a form. 16. A. As a rich text container for all kinds of non-user-entered data, a

page is the best option presented. A form would certainly work, but since no fields are required for user data, a page is good enough. A subform embedded in a form would also work but is not the best option for the same reason a form was not the best option. A view could act as a front end to data since document data is displayed by views; however, it’s not very graphical unless it is embedded in a page that contains graphics. 17. B. The Design task on the home server will update the production data-

base on the home server using the template on the home server. Once the production database is up to date, the design changes will be propagated to the remote server using the Replication task. If the template is placed on both servers, your databases may end up with duplicate design objects. Local machines doing replication or design refresh always require manual intervention and are never automatic. 18. D. Sections are collapsible and expandable by the users. They are the

best bet for simplifying and organizing large amounts of information on a form. Fields and subforms may be components of the final form, but sections are the mechanism that will help organize the fields and the subforms as well as the form itself. File Upload Control does not apply since there is no mention of Web clients or the need to upload information. 19. C. View columns can be set to display icons instead of text values.

This is a column property, not a view property.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

498

Chapter 10



Application Design

20. A. The fields and their attributes are available for inspection without

opening the document by using the document Properties box and the Fields tab. A view cannot display a field’s attributes, only its value. Programming a formula to display the field’s attributes on a page sounds like a technical challenge and may be fun for some, but not all. Regardless, it won’t work since you’d need a field to write the formula in and pages don’t contain Notes’s fields. Field attributes are not stored as viewable information in the document, hidden or unhidden. 21. D. Storing the forms in the documents will take up more disk space

than not storing the form in the document. Shared fields, subforms, and sections will not increase the size of the data stored in the document when stored forms are not used. 22. C. Deleting a field from the form structure does not affect the item of

data already stored on existing documents. The absence of the $Title field denotes that the form is not stored in the document, and therefore, design changes to the form will be reflected in the view mechanism of previously stored documents. 23. B. Each document in Notes, whether it’s a design note or a data note,

has a Note ID that identifies it uniquely within a database. In addition, each document has a unique document ID that identifies it across all Domino servers. Copying and pasting will correctly create the 10 documents, each one with unique identifiers. 24. A. A single-use action would do the trick. Shared actions, shared fields,

and subforms are all reusable components that should be used when they will appear in more than one place in the application. 25. B. The Show single category event allows a formula to be written for cate-

gorized, embedded views that will show one of the view categories at a time. The options to use a Java applet or HTML will not help limit the data to one category or another; however, both are valid display options for embedded views. While showing a single category in a categorized view wasn’t possible in R4, R5 makes single-category views a reality.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

499

26. B. A shared action to close a form can be coded once and reused on

every form. This way, the code is stored in one place for easy maintenance and smaller database size. Single-use actions would require writing the code 20 times in 20 action buttons. Using shared fields and subforms won’t execute utility code using a button.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Chapter

Application Coding

11

LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Plan applications integrated with the Web
Design applications based on appropriate coding alternatives (C)
Design applications based on appropriate coding alternatives (Formula Language)
Design applications based on appropriate coding alternatives (JavaScript)
Design applications based on appropriate coding alternatives (Java)
Design applications based on appropriate coding alternatives (LotusScript)
Read HTML
Read simple JavaScript
Correct HTML
Modify simple JavaScript
Modify simple LotusScript
Plan applications based upon impact of replication on HTML
Plan applications based upon impact of replication on the NOTE ID
Plan applications based upon impact of replication on the UNID

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

I

n the Domino Designer integrated development environment (IDE), the programming you do creates interactions within and between design notes and within and between databases. Several programming alternatives are available to you, and all work within Domino’s object-based, event-oriented programming model. In this chapter, you’ll learn about the event model, how to write code for events, and how to choose the right programming language for the task at hand.

Adding Code to a Database

F

act: the nuts and bolts of a good application are good forms and views. Why, then, do you need any code? Aren’t forms and views complete objects themselves? Simply placing fields on a form, creating documents from the form, and then displaying the documents in a view will certainly serve the purpose of collecting, storing, and displaying information to your users. Hold on, though; what if you want to provide default values for a field? Or convert field data to uppercase before storing it? Or ask the user a question interactively with a pop-up window? All of these require code. This code is the glue that fills in the seams of your database, making it into a robust, complete application for your users.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Adding Code to a Database

503

Code Placement Once the basic design objects are created for your application (forms, views, pages, etc.), the code you write is generally added to your application in three places: 

Object events



Properties box formulas



Agents

Events The Domino event model provides code-driven access to many aspects of a design object. You can think of events as points in time when code executes during the use of a design object. Sometimes an event fires in response to changes in the environment, like the click of a button. In other cases, events behave like static properties that are given a value. Click Events A click event is a place to write code that will be triggered by a user clicking a freestanding button, an action button, or a hotspot. Buttons and hotspots can be placed on most design objects including pages, forms, views, and navigators. Action buttons can be added to forms and views. Action buttons differ from freestanding buttons since they appear on a button bar located along the top horizontal edge of the form or view on an action button bar and are not freestanding. Figure 11.1 shows how two buttons would appear on a button bar. FIGURE 11.1

Action buttons

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

504

Chapter 11



Application Coding

Field Events Each field placed on a form has an entire set of events that control its behavior. Table 11.1 lists the events and describes each event’s purpose. TABLE 11.1

Field Events Event Name

Event Description

Default Value

Initial value given to a field when a document is first created

Input Translation

Reformat user input before saving to disk

Input Validation

Test for valid user input values before saving to disk

HTML Attributes

Set field-related HTML attributes (such as size) for a Web client

OnBlur

Triggered as focus leaves a field in a Web client

OnChange

Triggered when data value changes in a field in a Web client

OnClick

Triggered when left mouse button is clicked in a Web client

OnDblClick

Triggered when left mouse button is double-clicked in a Web client

OnFocus

Triggered when an object has focus in a Web client

OnKeyDown

Triggered by the keyboard downstroke of a key

OnKeyPress

Triggered when the key on a keyboard is released

OnKeyUp

Triggered as focus leaves a field in a Web client

OnMouseDown

Triggered when the mouse button is clicked

OnMouseMove

Triggered as focus leaves a field in a Web client

OnMouseOut

Triggered as focus leaves a field in a Web client

OnMouseOver

Triggered when the cursor moves over an area

OnMouseUp

Triggered when the mouse button is released

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Adding Code to a Database

TABLE 11.1

505

Field Events (continued) Event Name

Event Description

OnSelect

Triggered as focus leaves a field in a Web client

(Options)

Global settings for a field

(Declarations)

Global declarations for a field

Entering

Triggered as focus is given to a field in a Notes client

Exiting

Triggered as focus leaves a field in a Notes client

Initialize

Triggered as document is being loaded into memory and displayed

Terminate

Triggered as document is being closed

Field events for an editable field appear in the Object viewer as shown in Figure 11.2. FIGURE 11.2

Field events

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

506

Chapter 11



Application Coding

Form Events As containers of fields and graphics, forms have events that control the overall behavior of the container including some static events like Window Title. Table 11.2 lists the form events and describes each event’s purpose. Figure 11.3 shows how these events appear in the Object viewer. TABLE 11.2

Form Events Event Name

Event Description

Window Title

Static or computed text label for window title bar

HTML Head Content

Code that passes through to the HTML tag

HTML Body Attributes

Code that passes through to the HTML tag

WebQueryOpen

Agent called when a document is opened from the Web

WebQuerySave

Agent called when a document is saved from the Web

HelpRequest

When F1 is pressed, formula in this event fires

Target Frame

Specifies the name of a frame to display this form

JS Header

Code that passes through to the JavaScript header

OnClick

JavaScript event detecting a single click

OnDblClick

JavaScript event detecting a double click

OnHelp

JavaScript event triggered by a click of F1 key

OnKeyDown

JavaScript event detecting a down motion on a key

OnKeyPress

JavaScript event detecting a held-down key

OnKeyUp

JavaScript event detecting an up motion on a key

OnLoad

JavaScript event detecting the loading of a document

OnMouseDown

JavaScript event detecting a left mouse key down

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Adding Code to a Database

TABLE 11.2

507

Form Events (continued) Event Name

Event Description

OnMouseMove

JavaScript event detecting the movement of the mouse

OnMouseOut

JavaScript event detecting a mouse leaving an area

OnMouseOver

JavaScript event detecting a mouse hovering on an area

OnMouseUp

JavaScript event detecting a left mouse key up

OnReset

JavaScript event detecting the reset of a form

OnSubmit

JavaScript event detecting the saving of a form

OnUnload

JavaScript event detecting the unloading of a document

(Options)

LotusScript options coding area

(Declarations)

LotusScript variable and method declaration area

QueryOpen

Fires when a document is being opened (loaded)

Query ModeChange

Fires when a document changes to or from readedit mode

PostModeChange

Fires after a document changes mode

PostRecalc

Fires after a document has been refreshed

QuerySave

Fires as a document is being saved

PostSave

Fires after a document has been saved

QueryClose

Fires as a document is being closed (unloaded)

Initialize

Fires when a form is being loaded to set values

Terminate

Fires when a form is being unloaded to reset values

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

508

Chapter 11



Application Coding

FIGURE 11.3

Form events

View Events When views display documents, they are opened, closed, and navigated. Each of these different activities is associated with events that can contain code to customize view behavior. Table 11.3 lists the view events and describes each event’s purpose, and Figure 11.4 shows how the events appear in the Object viewer. TABLE 11.3

View Events Event Name

Event Description

View Selection

Selection formula to choose documents to display

Form Formula

Form to show document data from this view

HelpRequest

Invoke view help using F1

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Adding Code to a Database

TABLE 11.3

509

View Events (continued) Event Name

Event Description

Target Frame (single click)

Frame to show view data when view row is single-clicked

Target Frame (double click)

Frame to show view data when view row is double-clicked

(Options)

LotusScript options coding area

(Declarations)

LotusScript variable and method declaration area

QueryOpen

Fires when view is being opened and before it’s on-screen

Postopen

Fires after a view is on-screen

Regiondoubleclick

Fires when a region in a calendar view is double-clicked

QueryOpenDocument

Fires just before opening a document from the view

Queryrecalc

Fires just before a view is recalculated

Queryaddtofolder

Fires before a document is dropped into a folder from a view

Querypaste

Fires before a document is pasted into a view

Postpaste

Fires after a document is pasted into a view

Querydragdrop

Fires before a drag-drop operation in a calendar view

Postdragdrop

Fires after a drag-drop operation in a calendar view

Queryclose

Fires before a view is closed

Initialize

Fires when a view is being loaded to set values

Terminate

Fires when a view is being unloaded to reset values

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

510

Chapter 11



Application Coding

FIGURE 11.4

View events

Properties Box Formulas A small percentage of the coding in Notes actually takes place in the Properties box. In general, the Properties box is used to set the look and feel of an object and not its behavior. However, some objects allow Properties box formulas, which are special-purpose tasks that are coded as part of the properties or attributes of an object. Three examples of this type of formula are as follows: 

Controlled access sections formulas



Hide When formulas



Field formulas

Formulas written in a Properties box affect the behavior of an object. The coding for a Properties box can only be written using Formula Language, which is one of the built-in languages available in the Domino IDE.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Adding Code to a Database

511

Controlled Access Sections For controlled access sections, an access formula is written to determine who is allowed to edit information contained in the collapsible section. The access formula is written as a condition in an if-then-else statement. If the condition contained in the access section’s Properties box is true, then only those users are allowed to edit the information. For instance, in Figure 11.5, only the users in the [AccountingEdit] role can edit the information contained in the section shown below. FIGURE 11.5

Controlled access formula

Hide When For Hide When attributes, a formula can be written to control when an object appears. Objects like fields, sections, and buttons can be hidden based on formulas that evaluate to a true condition. Figure 11.6 demonstrates a formula that will hide this object if the document is new (meaning not previously saved).

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

512

Chapter 11



Application Coding

FIGURE 11.6

Hide When formula

Fields Field formulas are often used to determine values for option lists presented as choices to a user. The following field types are candidates for this type of formula: 

Dialog list



Checkbox



Radio button



Combobox



Listbox

In Figure 11.7, a formula is used to calculate the value for a field based on a view. This results in a choice list for the user that can be used with all the field types above.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Adding Code to a Database

FIGURE 11.7

513

A field value calculation

Agents In contrast to events and properties, which are associated with design objects, agents themselves are design objects. These design objects are selfcontained units of code stored in the NSF but separately from fields, forms, and views. Agents can be called from many different places within an application and are triggered in one of three ways: 

Interactively by users



By environment changes



Scheduled to run on a timed basis

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

514

Chapter 11



Application Coding

The Agent Builder area in Domino Designer, shown in Figure 11.8, is where you write the code that executes when an agent is triggered. FIGURE 11.8

The Agent Builder

Coding an agent to do a task involves deciding on a trigger, choosing the documents that should be acted on, and writing code in an appropriate language to carry out the task. Now that we know where code is written in Domino, let’s explore the different language coding options available to write the code and determine when to use which option.

Programming Options

The programming options available to build Notes applications increase with each new release of the product. Domino Designer R5 provides coding alternatives that vary in skill level from simple to complex. In increasing order of difficulty, Domino’s built-in coding alternatives are shown in Table 11.4. TABLE 11.4

Internal Code Alternatives Type of Code

Description

Simple Actions

Built-in preprogrammed utility tasks

Formula Language

Declarative, task-oriented subroutines and functions

LotusScript

BASIC-like procedural programming language

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

TABLE 11.4

515

Internal Code Alternatives (continued) Type of Code

Description

HTML

Tagged language for formatting output for browsers

JavaScript

Web browser–embedded scripting language

Java

Object-oriented programming language

In addition to the language options built into the Domino IDE, external languages can be used to interact with the Notes NSF data format and to create custom user interfaces into stored data. Table 11.5 presents a few of the external language choices that can be used. TABLE 11.5

External Code Alternatives Type of Code

Description

C

Traditional procedural programming language

C++

Object-oriented programming language

Java

Object-oriented programming language with Web presence

Visual Basic

Traditional event-oriented programming language

C and C++ are the languages that the Domino Application Programming Interface (API) is written in and that can be used for complex, low-level interactions.

Since Domino is an IDE, direct access to low-level code is not available. Instead, all interactions with Domino objects (stored or in memory) are done using the Domino Object Model. As you can see from Figure 11.9, the object model is a layer that external coding options must utilize to interact with the Domino environment.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

516

Chapter 11



Application Coding

FIGURE 11.9

Domino Object Model interactions

C Database

C++ LotusScript Java

Domino Object Model

OLE CORBA

Items Company Name Address City State/Province Postal Code Telephone

Documents

ODBC

With all these coding options, choosing the right one for the job can seem a daunting task. Let’s examine the nuances of each option.

Simple Actions The concept of simple actions in Notes is to provide quick access to a task through the click of a mouse. They are specialized, built-in, preprogrammed procedures that provide a non-programming way to perform simple, oftenused tasks.

Be careful not to confuse Actions (a button with a click event where code can be written) with Simple Actions (a type of code that can be written). The names are far too similar for comfort!

Simple actions are added to an application using a wizard-like interface to choose a task, as shown in Figure 11.10.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

FIGURE 11.10

517

Coding a simple action

Simple actions also have a more specialized version known as system actions. System actions focus on core tasks like opening a document in Edit mode.

System actions and simple actions are not supported when invoked from a Web browser; consider formulas as an alternative.

Formula Language Formula Language is a built-in task-directed language that is used in many places within a Domino application. As a language, formulas are slightly more complex than coding simple actions and less complex than working with LotusScript. Events that support the use of Formula Language are identified with a diamond icon to the left of the event title, as shown in Figure 11.11.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

518

Chapter 11



Application Coding

FIGURE 11.11

Formula events

When code is stored in an event, the event’s icon is shaded, while events without code show the icon as an outline image.

Some areas in Notes require Formula Language to be used, not allowing other language choices. Table 11.6 lists the field, form, and view events that require Formula Language. TABLE 11.6

Formula Language Events Object

Event

Editable fields

Default Value, Input Translation, Input Validation

Forms

Window Title, WebQueryOpen, WebQuerySave

Views

View Selection, Form Formula

Formula Language consists of two pieces: 

@Commands



@ functions

@Commands @Commands simulate tasks that are normally executed from the Notes client menu as well as a few specialized non-menu tasks. @Commands carry out a series of steps, making them similar to subroutines in other languages.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

519

As an example of an @Command, consider the series of steps required to save a document using the menu: you click the File menu and then select the Save menu option. These two steps can be automated using an @Command. Here’s what the document save sequence would look like using an @Command: @Command([FileSave]) @Commands and Web Clients Since @Commands simulate menu-driven tasks in the Notes client, a majority of @Commands are not valid in a Web browser. If the database property “Web access: use JavaScript when generating pages” is enabled, the following @Commands will work when invoked from a Web browser: @Command([FileSave]) @Command([FileCloseWindow]) @Command([ViewRefreshFields])

When placed in a button on a form, the combination of @Command([FileSave]); @Command([FileCloseWindow]) is how to code a Submit button for Web input forms.

@ Functions @ functions behave much like functions in other languages and always return some kind of result. The result is either returned to the field that called the function or used as an interim value within a larger calculation. There are approximately 185 functions in R5, with more added as needs evolve over time. Formulas are covered in detail in the Designer Fundamentals 510 exam, so you should already be familiar with how they work. The following is a list of the functions available in R5:

@Abs

@DeleteField

@IsDocBeing Loaded

@Modified

@Sqrt

@Abstract

@DialogBox

@IsDocBeing Mailed

@Modulo

@Subset

@Accessed

@Do

@IsDocBeing Recalculated

@Month

@Success

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

520

Chapter 11



Application Coding

@Acos

@DocChildren

@AddToFolder

@IsDocBeing Saved

@Name

@Sum

@DocDescendants @IsDocTruncated

@NameLookup

@Tan

@Adjust

@DocFields

@IsError

@Narrow

@Text

@All

@DocLength

@IsExpandable

@NewLine

@TextToNumber

@AllChildren

@DocLevel

@IsMember

@No

@TextToTime

@AllDescendants @DocMark

@IsModalHelp

@NoteID

@Time

@Ascii

@DocNumber

@IsNewDoc

@Now

@Today

@Asin

@DocParentNu mber

@IsNotMember

@OptimizeMailA ddress

@Tomorrow

@Atan

@DocSiblings

@IsNumber

@Password

@Trim

@Atan2

@Document UniqueID

@IsResponseDoc

@Password Quality

@True

@Attachment Lengths

@Domain

@IsText

@Pi

@Unavailable

@Attachment Names

@EditECL

@IsTime

@PickList

@Undelete Document

@Attachments

@EditUserECL

@IsUnavailable

@Platform

@UpperCase

@Author

@Elements

@IsValid

@Posted Command

@URLGetHeader

@Begins

@EnableAlarms

@Keywords

@Power

@URLHistory

@BrowserInfo

@Ends

@Language Preference

@Prompt

@URLOpen

@Certificate

@Environment

@LaunchApp

@ProperCase

@UserAccess

@Char

@Error

@Left

@Random

@UserName

@CheckAlarms

@Exp

@LeftBack

@RefreshECL

@UserName Language

@ClientType

@Explode

@Length

@RegQueryValue

@UserNamesList

@Command

@Failure

@Like

@Repeat

@UserPrivileges

@Contains

@False

@Ln

@Replace

@UserRoles

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

521

@Cos

@Fontlist

@Locale

@Replace Substring

@V2If

@Created

@FormLanguage

@Log

@Return

@V3UserName

@Date

@GetDocField

@LowerCase

@Right

@V4UserAccess

@Day

@GetPortsList

@MailDbName

@RightBack

@ValidateInternet Address

@DbColumn

@GetProfileField

@MailEncrypt SavedPreference

@Round

@Version

@DbCommand

@HardDelete Document

@MailEncrypt SentPreference

@Second

@ViewTitle

@DbExists

@Hour

@MailSave Preference

@Select

@Weekday

@DbLookup

@If

@MailSend

@Set

@Wide

@Db Manager

@Implode

@MailSign Preference

@SetDocField

@Word

@DbName

@Inherited Document UniqueID

@Matches

@SetEnvironment

@Year

@DbTitle

@Integer

@Max

@SetField

@Yes

@DDE Execute

@IsAgentEnabled

@Member

@SetProfileField

@Yesterday

@DD EInitiate

@IsAppInstalled

@Middle

@SetTargetFrame

@Zone

@DDEPoke

@IsAvailable

@MiddleBack

@Sign

@DDETerminate @IsCategory

@Min

@Sin

@DeleteDocument @IsDocBeing Edited

@Minute

@Soundex

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

522

Chapter 11



Application Coding

@ Functions and Web Clients While a majority of @ functions can be invoked from a Web browser, some cannot. The functions that deal with Domino security and those that deal with opening dialog windows interactively make up a large part of the functions that do not translate to the Web. The following is a list of the functions that are not available in a Web client. @Certificate

@DocParentNumber

@MailSavePreference

@DbCommand

@DocSiblings

@MailSend

@DDEExecute

@Domain

@MailSignPreference

@DDEInitiate

@Environment

@PickList

@DDEPoke

@GetPortsList

@Platform

@DDETerminate

@IsAgentEnabled

@Prompt

@DeleteDocument

@IsCategory

@Responses

@DialogBox

@IsDocBeingMailed

@SetEnvironment

@DocChildren

@IsExpandable

@Unique

@DocDescendants

@IsModalHelp

@URLGetHeader

@DocLevel

@MailDbName

@URLHistory

@DocMark

@MailEncryptSaved Preference

@UserPrivileges

@DocNumber

@MailEncryptSend Preference

LotusScript LotusScript is a robust, BASIC-like programming language, making it more complex to code than Simple Actions and Formula Language. It is also, however, more powerful since it provides conditional selection statements, iteration, and access to non-Notes data.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

523

Programming in LotusScript Events that support LotusScript are identified with a scroll icon to the left of the event name. Agents can also be coded in LotusScript. Programming in LotusScript requires a good understanding of the Domino Object Model in terms of events, properties, and methods that are available and when to use them. Domino Object Model Domino is an object-based, event-oriented language. Access to data stored in an NSF and design objects defined in an NSF is done through class libraries. These classes are defined by Lotus and provide an Application Programming Interface (API) to the Domino world. Domino objects are split into three families: front-end classes, back-end classes, and external data access classes. Front-end classes provide access to the things a user sees on screen, while back-end classes provide access to stored data. External data classes let a Notes database interact with external data sources through code. BACK-END CLASSES

Back-end classes interact with data stored on disk and not presented onscreen. Accessing stored data through classes is done through a hierarchy of individual objects that are used together to drill down to the individual data elements in an NSF. Here are a few of the most often-used back-end classes: 

NotesSession



NotesDatabase



NotesView



NotesDocument

Consult the Domino Designer Help for a complete list of all classes. Even though back-end documents may be created without the aid of the user interface, Domino still enforces unique document IDs, storing the values in the unid$ variable.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

524

Chapter 11



Application Coding

FRONT-END CLASSES

A separate set of classes deals with the information displayed on the screen for users. These are known as the front-end or user interface classes. Some of the more frequently used front-end classes include the following: 

NotesUIWorkspace



NotesUIDatabase



NotesUIView



NotesUIDocument

Whenever you work with data from a form using the front-end classes it is treated as text data; other data types are not recognized.

EXTERNAL DATA USING ODBC

Notes can act like a data source for external applications or be the application pulling data from external data sources. Open Database Connectivity (ODBC) is a popular middleware method for interacting with data sources, as depicted in Figure 11.12. FIGURE 11.12

ODBC as middleware

ODBC Notes

External data source

To use the Notes ODBC code library to access external data, the statement UseLSX “*LSXODBC” is added to the (Options) event of a form or object to make it available to all objects on the form. For Notes to act as an ODBC data source, the NotesSQL driver must be installed on the server or workstation hosting the NSF file. The ODBC driver lets Notes act like a relational database for the purpose of pulling data out of or pushing data into the NSF. When languages like C, Visual Basic, and Delphi use the ODBC driver to access Notes data, they bring to the table full programmatic control for read/write access to an NSF. When third-party tools like Crystal Reports retrieve data from Notes, the ODBC driver is the mechanism that connects the report engine to the stored Notes data.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

525

The NotesSQL ODBC driver is available free from www.lotus.com. At the time this book went to print, the current version was 2.06, which works with Release 4.6 and Release 5 of the Notes product.

USING CLASSES

Classes can be treated as data types. Just as you would declare a variable of a data type–like number, you can declare a variable that is of a class type. Here’s a simple comparison: Dim X as Number Dim db as NotesDatabase Here, NotesDatabase is a class in the Domino Object Model, while Number is a primitive data type. The Dim statement dimensions, or declares, a variable that reserves memory space for it. With a data type declared, the next step is to assign an initial value. Again using the comparison example, the variables X and db are initialized: X = 2741 Set db = New NotesDatabase X is a variable that stores the integer value 2741 through direct assignment using the assignment operator. The assignment operator is only valid when used with built-in data types, like Number, so for class variable assignments, we have a different operator: Set. In the example above, the db class variable is assigned a reference to a NotesDatabase, and with it initialized, you can then access all the properties and methods in the NotesDatabase class through the variable reference db.

The process of initializing a class reference variable is known as instantiating the class; the class is an abstract concept and once you create something of that type through instantiation, the result is an object that can be referenced as a variable.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

526

Chapter 11



Application Coding

PROPERTIES AND METHODS

Every class, like the NotesDatabase class, has a set of properties and methods associated with it. Let’s define properties and methods: Properties Attributes of the class, e.g., NotesDatabase has a FileName attribute. Methods Behavior relevant to the class, e.g., NotesDatabase has a Compact method. Code to access the FileName attribute and invoke the Compact method in the NotesDatabase class looks like this: Dim db As New NotesDatabase("APSServer01","winemaster.nsf") Dim file As String Dim sizedelta as Long file = db.FileName sizedelta = db.Compact In the five lines of code, here’s what was happening: Line 1

Declared a class variable db and initialized it to the winemaster.nsf on the server APSServer.

Line 2

Declared a variable to store the filename.

Line 3

Declared a variable to store the space reduced number for the Compact operation.

Line 4

Assigned the variable file to the FileName property of the db class reference using dot notation.

Line 5

Assigned the variable sizedelta to the result of calling the Compact method for the db class reference using dot notation.

Dot notation is used to access class properties and call class methods.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

527

FIELDS ON FORMS

Using dot notation, the values of all internal fields and programmer-created fields are available in LotusScript. To access them, however, you must traverse the Domino Object Model class hierarchy. For instance, to access the internal field called Form on a document that has its form stored separately from the document, you need to drill down from the top of the hierarchy to the document itself. You can both access and set form variables this way. Dim session As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument Set db = session.CurrentDatabase Set doc = New NotesDocument( db ) doc.Form = "Product Profile" Call doc.Save( True, True ) Here’s what was happening in these seven lines of code: Line 1

Declared a class variable session and instantiated it to the current Notes session using the keyword New.

Line 2

Declared a class variable db to reference a NotesDatabase.

Line 3

Declared a class variable doc to reference a NotesDocument.

Line 4

Instantiated the class variable db, setting it up to reference the currently open database in the current Notes session.

Line 5

Instantiated the class variable doc, creating a new document in the database referenced by the class variable db.

Line 6

Assigned the Form variable on the new document to be “Product Profile.”

Line 7

Saved the new document.

Debugging LotusScript If you’re human, there’s a good chance that code you write just might have errors in it every now and then. Within Domino, there is a code debugger for working through problems in LotusScript programs. Figure 11.13 shows the debugger environment. The debugger can be toggled on and off using the menu options Files  Tools  Debug LotusScript.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

528

Chapter 11



Application Coding

FIGURE 11.13

The LotusScript debugger

Use the debugger to step through code one line at a time, set break points, and watch values change during a subroutine.

Special Scripts You’ve noticed by now that most LotusScript code is written against field and form events. What do you do, however, if you want to use the same LotusScript code in two different forms? Should you code it twice? No! Domino provides two different kinds of special scripts that can be invoked by global calls within a database. Database Scripts While many events deal with things that transpire in fields or forms, several events occur at the database level. For instance, whenever a document is deleted anywhere in the database, you could pop up an “Are you sure?” message by using a database script. The code for this is shown in Figure 11.14. Database scripts are stored and accessed using the following path: Design Panel  Resources  Other  Database Script.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

FIGURE 11.14

529

Database script example

Script Libraries Script libraries are another way to store and access code that will be used throughout a database. This code, however, is not written against events; instead, it consists of user-defined subroutines and functions that you call from other places in the database. This is a great way to write and access reusable LotusScript code. Script libraries are stored and accessed from the Resources area in the Design Panel using the path Design Panel  Resources  Script Libraries Figure 11.15 demonstrates a subroutine that is used to delete orders from a database. Since an order may be deleted from many places within a database, placing the code in a script library is a good idea. FIGURE 11.15

A module in a script library

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

530

Chapter 11



Application Coding

@LotusScript and Web Clients As a scripting language, LotusScript requires the presence of the Lotus engine to run. It is an interpreted language that is dynamically executed at runtime. Since it exists only within the Lotus environment, LotusScript code cannot execute in a Web browser. Since Web clients operate in a stateless HTTP mode, however, a browser can send a request to a Domino server, which in turn executes an agent in the server environment. Agents are often written in LotusScript. WebQueryOpen and WebQuerySave are two events intended to operate in exactly this manner. Figure 11.16 depicts these events as they exist in the interaction between a Web browser and a Domino server’s Notes database. FIGURE 11.16

Web events: WebQueryOpen and WebQuerySave

Conversion to HTML WebQuerySave Web submit Save to disk Web request

Domino server

WebQueryOpen NSF

Display HTML page Web browser

WebQueryOpen The WebQueryOpen event requires that an @Command call an agent that executes on the Domino server. If the event calls an agent, the agent is invoked just before the document is converted to HTML and rendered back to the browser. In Figure 11.16, imagine that an agent named RetrieveCurrentCustomerList exists. To invoke the event from a browser, the WebQueryOpen event would be coded as follows: @Command([ToolsRunMacro]; “RetrieveCurrentCustomerList”) The ToolsRunMacro command invokes the named agent on the server.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

531

WebQuerySave The WebQuerySave event also uses the ToolsRunMacro command to execute an agent invoked from a Web browser. When this event has a value, the agent is called just prior to when user data is saved to disk. This is an excellent opportunity to validate the user input before making it a permanent part of the NSF.

WebQueryOpen and WebQuerySave have no effect in a Notes client.

HTML Like Formula Language, HyperText Markup Language (HTML) is a taskdirected language that is not as complex as full programming languages like LotusScript and Java. Its specific purpose is to customize Domino information for presentation in a Web client, which means it has no effect in the Notes client. You can also embed URLs directly in HTML on pages and forms for quick navigation.

URLs URLs can be added directly to a form to navigate to another location and to code buttons. URLs are also useful for passing field values from one document to another during the user’s navigation of a site. If a URL contains spaces by virtue of the Notes named element containing spaces, e.g., a form named “Product Profile,” spaces need to be replaced with some kind of a distinguishable character like an underscore. This replacement of characters is necessary because when Domino does its on-the-fly conversion of data to HTML, white space is removed, and in the case of URLs, that would make them invalid.

HTML Code Generation When a Web client requests data from a Domino server, the information is located and retrieved from the appropriate NSF file, converted to HTML, and sent back to the Web browser for rendering. This on-the-fly conversion of data to HTML means that you maintain your information as an NSF instead of as HTML. This has the advantage of easier code maintenance; however, since the HTML is being automatically generated for you, you don’t have direct control over the HTML formatting.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

532

Chapter 11



Application Coding

In the cases where you want specific control over browser formatting, you can tailor an NSF by directly adding HTML tags. Table 11.7 lists where in Domino HTML can be written. TABLE 11.7

HTML Code Locations Area

Code Location

Form events

HTML Head Content event, HTML Body Attributes event

Field events

HTML Attributes event, HTML tab in Properties box

Text on Forms

Text attribute “Pass-Thru HTML”

$$Return field

Default value event of field

As an example of how to embed HTML on a form, consider that you want to code a custom Submit button using HTML. You would type it directly onto the form and mark the text as Pass-Thru HTML using the Text menu. The following HTML would add a button to your form with the text on the button reading “Click to Submit.”

The angle brackets (< >) are required to surround all HTML you type on a form in order to be processed correctly as HTML. Use the $$Return field to format a more personalized Web form submission message for users. The default message on submitting a form is “Form Processed.” If the $$Return field is present and has a valid value, a customized message can be returned. The value for the $$Return is generally a combination of HTML, Formula Language statements, and literal text, as shown in Figure 11.17. FIGURE 11.17

Code for a $$Return field

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

533

Hiding HTML Since HTML does not apply to Notes clients, all Pass-Thru HTML and the $$Return field are generally hidden from Notes clients using the setting shown in Figure 11.18. Hiding Objects in the Notes Client

FIGURE 11.18

Hidden HTML is stored in the database and, therefore, will replicate with the NSF between servers. Replication and HTML Replication technology only works on objects stored inside the NSF file. So while Domino can serve data to a Web browser from external HTML files, the HTML files cannot be replicated between servers.

JavaScript JavaScript, like HTML, is a language that is geared for Web clients. In fact, JavaScript is often used in combination with HTML in Domino. The purpose of the language is to use a simple command syntax to manipulate Web documents and their components. Since Notes documents are a similar concept to Web documents, it is a natural direction that JavaScript be effective

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

534

Chapter 11



Application Coding

for both types of documents, and as such, there are places within the Notes client that support JavaScript execution.

For JavaScript to work in a Notes client, the user preference option “Enable JavaScript” must be enabled using the menu options File  Preferences  User Preferences  Additional Options.

Programming in JavaScript In the Domino environment, JavaScript is used for data validation, presentation, and functionality outside of Domino’s capabilities. Writing JavaScript code in Domino can be done in the following places: 

Field events



Form events



Subform events



Page events



Actions



Buttons



Action hotspots



Directly on a form or page by embedding it in HTML

Figure 11.19 shows a set of JavaScript events as they appear in the Domino Designer Object viewer. FIGURE 11.19

JavaScript events

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

535

Client Support Each client supports varying levels of JavaScript events and code. If the client supports the event, then the code written in the event will execute. When writing applications that will be used in a Notes client and in a Web client, use JavaScript in events that work in both places. For instance, for document processing, use the following events to write JavaScript code for both types of clients: 

OnLoad



OnUnload



OnSubmit

To process fields using JavaScript events, use the following events for both types of clients: 

OnFocus



OnBlur

Table 11.8 gives you an idea of which events are supported in which client type and how some of the JavaScript events map to LotusScript events. TABLE 11.8

JavaScript Event Support LotusScript Event Equivalent

JavaScript Event

Web Client

Notes Client

JSHeader







OnBlur







Exiting

OnFocus







Entering

OnClick




OnDblClick




OnHelp




OnKeyDown




OnKeyPress




OnKeyUp




Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

536

Chapter 11



Application Coding

TABLE 11.8

JavaScript Event Support (continued)

JavaScript Event

Web Client

Notes Client

LotusScript Event Equivalent

OnLoad







PostOpen

OnMouseDown




OnMouseMove




OnMouseOut




OnMouseOver




OnMouseUp




OnReset




OnSubmit







QuerySave

OnUnload







QueryClose

Expect differences between which events and which code works in Internet Explorer versus Netscape versus Notes clients.

GLOBAL JAVASCRIPT FUNCTIONS

The JS Header event for a form gives you a place to write JavaScript functions that can be called from other objects in the form, in a sense creating global functions. This is a good place to put global error handlers and global variable declarations. To call functions that are stored in the JS Header event, a JavaScript function call can be placed in any event. For instance, if you want to read a cookie that you previously stored on the user’s machine and you’ve written a JavaScript function named getCookie to do that, you call the cookie code in the form’s onLoad event with a statement like getCookie();. When Domino converts an NSF to HTML on-the-fly in response to a browser request, the code in the JS Header event is placed into the HTML tag.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

537

JavaScript and HTML JavaScript code can be embedded directly in Domino forms and pages within HTML tags. The HTML tags need to identify the Script language being used, and if the browser supports that language, the code will execute when the form is loaded or the code action is called. A starting and ending Script tag is required, as shown in the following code:

You can use HTML to add buttons to a form as well and call a JavaScript validation routine. Building on the Submit button discussed earlier, the following code would place two buttons on a Domino form, one labeled “Submit” and the other labeled “Reset.” When the Submit button is clicked, the JavaScript onClick event fires, calling the JavaScript function checkFields, which takes no parameters.

Document Object Model Just as the Domino Object Model provides an access method to the properties and methods in LotusScript, JavaScript uses the Document Object Model to access properties and methods associated with Web pages and forms. The JavaScript Document Object Model deals with the user interface aspects of data, making it similar to the front-end classes in the Domino Object Model. The Document Object Model is a hierarchy that you traverse in code to access low-level components. Table 11.9 describes the high-level Document Object Model components, and Figure 11.20 graphically depicts their relationship to one another.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

538

Chapter 11



Application Coding

FIGURE 11.20

Document Object Model Window

Document

Applets

Links

Images

Forms

Buttons

Fields

TABLE 11.9

Document Object Model Components Java Script Object

Description

Domino Object Mapping

Window

Controls interactions with user’s display including pop-up boxes

Currently open form, page, view, frame

Document

Controls interactions with the contents of the Web page

Notes document

Applets

Controls interactions with applets

View applet, Rich Text applet, imported applets

Links

Controls jumps to other pages

Hotspot links and actions

Images

Container for graphics

Graphics on pages or forms

Forms

Container for data input fields

Domino form

Buttons

Controls click input interactions

Buttons on a Domino form

Fields

Controls data input interactions

Fields on a Domino form

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

539

Arrays Each of the JavaScript Document Objects shown in Table 11.14 is implemented in code as a storage array. To interact with the object, you access the object’s array. For instance, to interact with the Domino form named “ProductProfile,” you would use the following JavaScript code, in which a Domino form name is preceded by an underscore character: document.forms[0]._ProductProfile Arrays in JavaScript use 0 as a lower bound, so accessing the 0th element of the forms array is accessing the first available form. A document in a Web browser may consist of multiple forms; however, Domino presents just one form at a time so you’ll always access the 0th element in the array. Table 11.10 explains the JavaScript object and code needed to access the components of a Domino form and the HTML tag that is used at conversion time. TABLE 11.10

Document Objects versus Domino Objects JavaScript Object Type

Domino Field Type

Array Subscript Access

Applets array

Action bar, view applet, Rich Text applets, custom applets

document.AppletName

Links array

Actions, link hotspots, action hotspots

document.HotspotName

Images array

Attachments, image resources, pictures

document.PictureName

Forms array

Domino forms

document.forms[0]._ formName

Buttons

Buttons

document.forms[0].ButtonName

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

HTML Tag

540

Chapter 11



Application Coding

Accessing Fields Fields in a Notes document can be accessed using JavaScript objects by calling out the document’s forms array and the field name in dot notation: document.forms[0].FieldName Accessing the value stored in the field through JavaScript is done using the value property: document.forms[0].FieldName.value Table 11.11 maps JavaScript objects to Domino fields and HTML tags. TABLE 11.11

Accessing Domino Fields with JavaScript JavaScript Object Type

HTML Tag

Text, Date/Time, Number, Names, Authors, and Readers

Text object

Rich Text

TextArea object

Password

Password object

Dialog list, Listbox, and Combobox

Select object

Radio button

Radio object

Checkbox

Checkbox object

Any field with the Hide When attribute in effect

Hidden object

Domino Field Type

Hidden editable fields can’t be accessed from a Web client or a Notes client using JavaScript unless the form attribute “Generate HTML for all fields” is active; hidden fields in Read mode are never available to a Notes client through JavaScript.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

541

Field Validation By drilling down through the Document Object Model, you can access individual fields and validate their input values before submitting the data to the Domino server. One of the most important benefits that JavaScript brings to the table is its ability to do client-side processing in a Web environment, which is not possible with LotusScript or Formula Language. Two JavaScript mechanisms that help do this are variables and alert messages. VARIABLES

Variables in JavaScript are created using the var keyword. In this example, the variable frm is created to represent the current form. The result is easierto-read, easier-to-maintain code. var frm = window.document.forms[0]; ALERT MESSAGES

Alert messages are the JavaScript equivalent of the Formula Language @Prompt or the LotusScript MessageBox. Using conditional statements and alert messages gives you client-side field validation. Here’s a JavaScript validation for the CompanyName field on a form: if (this.form.CompanyName.value == '') { alert('You must provide a Company Name.'); this.form.CompanyName.focus(); }; LANGUAGE NUANCES

From the preceding code, a few nuances about the JavaScript language should be pointed out: 

JavaScript is a case-sensitive language.



Semicolons end JavaScript statements.



Curly braces act as begin and end delimiters on code blocks.



this is a reference to the current document.



this.form refers to the current open form.



this.form could have been replaced with a variable.



this.form.CompanyName is an example of a field.



this.form.CompanyName.value is an example of a value.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

542

Chapter 11



Application Coding





Single quotes are generally used to surround string values. A null string is denoted with two single quotes (no blanks in between), which is what is being tested in the if condition.

JavaScript’s strength is in its ability to process the on-screen document. Watch in future versions of Notes as support for JavaScript increases in both Web clients and the Notes client.

Java Java is a multiplatform object-oriented programming language that stands alone and can interact with the Domino Object Model. This means that Java can be used inside Domino and outside Domino to work with Domino data. Inside Domino, Java code can be written for agents as an alternative to Simple Actions, Formula Language, and LotusScript. Java code can be written directly into the Agent coding area or imported as executable class files. External to Domino, Java applications can be written to manipulate Domino data without ever needing to be in the Domino IDE. So even though Java is limited internally to agents, as a language, it represents one of the more powerful programming options since it can interact with Domino, server resources, relational databases, and anything on a network. As such, Java is often used with server-side applications known as servlets that interact with data and network resources.

Java Classes The Java language deals with classes and objects. A class is an abstract concept, while an object is a concrete, individual representation of a class. Examine the statements below to gain an understanding of the relationship between classes and objects: 

Mammals are a class.



Humans are a subclass of class.





Cate is an object created by making a specific instance of the human subclass. Because we know Cate is a human, we know other things about her automatically, like she is warm-blooded, breathes oxygen, and has a spine.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

543

So classes are the building blocks from which you create, meaning program, objects into existence. To write good programs, you interact with Java classes. A few of the Java classes that are included in the Java Application Programming Interface (API) are as follows: java.lang Access to all base language data types and operators java.io Input and output, both interactive and file-based, through streams java.net Access to network resources like sockets, telnet, and URLs java.util Access to containers like arrays and vectors and to utility classes java.awt Access to the Abstract Windowing Toolkit to build user interfaces JDBC Java Database Connectivity (JDBC) provides class-based access using Java to relational data sources in a manner similar to how ODBC is used with OLE and LotusScript interactions. Notes databases can be a JDBC data source. This means that Java programs can retrieve data natively from Notes and relational databases. Java is the favored method to retrieve data using a Web browser client over an HTTP connection.

The JDBC driver is also available as a free download from the www.lotus.com Web site.

Java Agents Java code can be written directly in the Domino IDE in the agent area. A Main method is automatically set up for you that establishes an object reference to the current Notes session and a second object reference to determine the context in which this agent will run: Session session = getSession(); AgentContext agentContext = session.getAgentContext(); Writing code in Java requires that you understand that classes behave like data types to help create object references. With an object reference established, properties and methods of the class are available for inspection and

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

544

Chapter 11



Application Coding

manipulation. Figure 11.21 takes the same code just examined and identifies what is happening with each of its pieces. FIGURE 11.21

Java code identified Class type

Object reference variable

Method call

Session session = getSession(); AgentContext agentContext = session.getAgentContext();

Class type

Object reference variable

Accessing an object property

Agent Context The AgentContext class contains the methods and properties needed to allow Java to interact with the Domino Object Model to manipulate Notes data. With the session and agentContext objects instantiated, a database class variable can be created to access the methods and properties of the database using dot notation in a similar way to how it was done in Lotus Script. Figure 11.22 shows the Agent Builder configured to allow you to write a Java agent. FIGURE 11.22

Writing Java agents

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Programming Options

545

Adding the following line of Java code to the instantiated session and agent context references establishes db as an object of type Database that references the currently open database. Database db = agentContext.getCurrentDatabase(); Taking the example a bit further, the following two lines of code will create a new document in a database and save it: Document doc = db.createDocument(); doc.save(true, true); The thought process of working with the Domino Object Model is the same whether you use Java or LotusScript; what differs between the two is the syntax of the class libraries.

Imported Java Agents As a robust programming tool, you can write Java programs that operate outside the Domino environment and execute at the command line. There is no debug facility available for Java in R5, so it may be desirable to use a Java IDE like VisualAge or VisualCafe to develop your Java agents. These tools are very good at their jobs and are intended for serious development of Java code. If you do use a third-party tool, you need a way to reference the Notes objects that exist in Domino. Lotus has provided the agentrunner.nsf, commonly known as the AgentRunner application, to aid in the development, testing, and debugging of Java code that will execute in a Domino environment. The Agent Runner application serves the same purpose the AgentContext class does for code developed internal to Domino. Figure 11.23 shows the Agent Runner database application provided with Domino. FIGURE 11.23

The AgentRunner application

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

546

Chapter 11



Application Coding

Programming in Java As an object-oriented language, the architecture of Java is completely class based. A class defines everything in Java. As in LotusScript, instantiations of a class are known as objects, and these objects have properties and methods used to code behavior. Again LotusScript, the Domino Object Model, is used to access Notes components from the Java language, albeit with a slightly different syntax. Language Nuances Like all languages, mastering the syntax is essential. Here are few nuances about the Java language that should help you: 

Java is a case-sensitive language.



Semicolons end Java statements.



Curly braces act as begin and end delimiters on code blocks.



Classes are used for virtually all programming interactions.

Since Java is used only for coding agents, no user interface (front-end) classes exist to manipulate data on a user’s screen; Java is intended for backend processing only.

Summary

Y

ou should now be familiar with all the coding options available to you in Domino Designer. To summarize the chapter, and therefore the coding options, Table 11.12 describes your options and provides pointers on when to use which option. TABLE 11.12

Summary of Coding Options Coding Option

Difficulty

Strength

Weakness

Simple Actions

Noncomplex

No programming

Limited tasks

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Web Capable? No

Summary

TABLE 11.12

Summary of Coding Options (continued) Coding Option

Difficulty

Strength

Weakness

Formula Language

Noncomplex

Direct access to Notes data

Not a robust programming language

Some

LotusScript

Complex

Complex control over documents and Notes user interactions

No effect in Browser client

No

HTML

Noncomplex

Web formatting

No effect in Notes client

Yes

JavaScript

Complex

Complex control over documents and Web user interactions

Limited use in Notes client

Yes

Java

Complex

Complex control over documents and Notes/Web user interactions

Limited to agents

Yes

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Web Capable?

547

548

Chapter 11



Application Coding

Key Terms Before taking the exam, you should be familiar with the following terms: alert message back-end class field event Formula Language front-end class input translation input validation input value Java JavaScript JS Header LotusScript URL

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

549

Review Questions 1. Arielle has created cascaded views to track Products by Region, Prod-

ucts by ProductCode, and Products by Name. Since the application will be used by Web clients invoking a URL, what should be done to make sure the views display? A. Enable the Java applet for Web access. B. Replace all spaces with a plus sign (+) in the view name. C. Rename the views so they are each one word, e.g., ProductsByRegion. D. Nothing; the views will display with a URL as is. 2. Brice is doing field validation on a form that will be filled in by Web-

browser users. He’s coded the following JavaScript code in the onBlur event for the CompanyName field. When does the alert message display? if((this.form.CompanyName.value == 'Type here!') || (this.form.CompanyName.value == '')) { alert('You must provide a Company Name.'); this.form.CompanyName.focus(); }; A. Only when there is no value in the CompanyName field. B. Only when the phrase ‘Type here!’ appears in the CompanyName field. C. When the CompanyName field is either blank or the phrase ‘Type

here!’ appears. D. When the CompanyName field has the focus.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

550

Chapter 11



Application Coding

3. Cleo is building a Web site that makes heavy use of URLs. Which of

the following is a true statement regarding URLs that she should keep in mind as she codes? A. URLs can be used in HTML on pages and forms for quick navigation. B. URLs must be coded with spaces instead of the underscore character. C. URLs cannot be used to pass values from one document to

another. D. URLs cannot be used to open Domino objects like forms and views. 4. Damian has used the following LotusScript code in the PostSave event

of a form. Sub Postsave(Source As Notesuidocument) Set orderDoc = source.Document Call SyncLineItems (orderDoc) End Sub When the code executes, it generates the error “Variant does not contain an object.” What modification should Damian make to fix the code? A. Dim orderDoc As NotesDocument B. Set orderDoc As NotesDocument C. Dim orderDoc As New NotesDocument D. Set orderDoc As New NotesDocument 5. Erica has been using input validation events on her fields. She would

like to convert the code to LotusScript. In which of the following events should she write the new code so that it executes while the user is interacting with the field containing the code? A. Initialize B. Entering C. Exiting D. OnBlur

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

551

6. Fletcher wants to make sure the data in the VehicleColor field is

always stored with initial capitalization. Which of the following combinations of events and code will help him? A. Default Value event with the @Yes formula B. Input translation event with the @ProperCase formula C. Input validation event with the @Success formula D. Input translation event with the @Explode formula 7. Gabrielle is coding a URL link that needs to dynamically provide the

document’s unique ID value for the ParentID= part of the URL. Which of the following formulas will work for her? A. @InheritedDocumentUniqueID B. @DocumentUniqueID C. @InheritedDocumentUniqueID D. @Text(@DocumentUniqueID) 8. Harrison is coding URL navigation directly into a form using HTML.

He is going to allow the user to navigate to the form named “Product Profile.” Will coding this form name directly work, or should Harrison do something additional to make it work in a URL? A. Yes, coding it directly in a URL will work just fine. B. No, coding it in a URL will require putting an underscore (_)

character as a prefix on the name. C. No, coding it in a URL will require converting all spaces to some

distinguishable character. D. No, the element name can’t be coded in a URL; instead, the

Document Unique ID must be used.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

552

Chapter 11



Application Coding

9. Ilana is examining some code found in the Properties box in an appli-

cation. She doesn’t think code could be written anywhere except in the programmer’s pane. All of the following, however, can be written in the Properties box except for which one? A. Controlled access sections formulas B. Hide When formulas C. Field formulas D. Default Value formula 10. Jason is coding several buttons that will appear on his Web form.

Which of the following language choices should he avoid? A. Simple Actions B. @ functions C. JavaScript D. @Commands 11. Kayla is converting 300 HTML pages into a Domino NSF application.

It will take her some time to do this, so she’d like to go in stages, phasing out chunks of HTML pages at a time. Her application, therefore, will make use of Domino’s ability to access and serve HTML files external to an NSF. What should she keep in mind as she’s setting up replication of her application to remote servers? A. HTML located within an NSF does not replicate. B. HTML located outside an NSF does not replicate. C. Hidden HTML in an NSF does not replicate. D. HTML will not replicate unless the “Web access: use JavaScript to

generate pages” option is active.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

553

12. Leo has coded the following HTML in the $$Return field on his Web

input form. Why isn’t the $$Return displaying the message correctly? "Thank you for your submission" A. Pure text cannot be used in the $$Return field; only formulas are

allowed. B. The starting HTML tag for H1 needs a forward slash in front of it. C. The ending HTML tag for H1 needs a forward slash in front of it. D. HTML needs to be in an event and cannot be a field value. 13. Manoj has designed a stunning Web site that consists of static pages

that are only ever rendered in a Web browser. He’s written a large amount of HTML directly on the form. Which of the following properties should he invoke so that the HTML renders correctly? A. Text attribute, Pass-Thru HTML B. Text Properties box HTML tab C. Database property “Web access: use JavaScript when generating

pages” D. Notes user preferences to enable HTML 14. Nicole is making heavy use of JavaScript in her application. In fact,

several of the routines she’s written in one of the forms are called from every field on the form. Where should she store this code to maximize code reuse? A. onBlur event B. (Options) event C. JS Header event D. (Declarations) event

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

554

Chapter 11



Application Coding

15. Ozzie’s Web form is presenting the fairly unimpressive message “Form

Processed” when users submit their data using the Submit button. Which of the following can he use to customize the “Form Processed” message? A. $$Return B. onSubmit event C. onClick event D. onUnload event 16. Paulette has coded the following JavaScript as part of a subroutine.

What is the line of code doing? var frm = window.document.forms[0]; A. The var keyword is a variable that now represents the current

on-screen document. B. The frm keyword is a variable that now represents the current

on-screen document. C. A new window has been opened in the browser. D. This is a miscoded if statement with the condition being if frm

equals window.document.forms[0]. 17. Queenie has opened up an NSF that she is unfamiliar with and sees the

following line of code typed in a form; what kind of code is it and what is it doing?

A. HTML code that is displaying a JPG image in a fixed width and

height B. Java code that is displaying an applet in a fixed width and height C. JavaScript code that is validating the information in the src field D. LotusScript code that is formatting an image resource

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

555

18. Rachael is instantiating an object reference variable for a Notes data-

base class. Which is the correct technique to do this? A. db = New NotesDatabase B. Set db = New NotesDatabase C. db = New NotesDatabase; D. Set db := New NotesDatabase; 19. Sam has several LotusScript routines that he wants to use on multiple

forms in his database. Which of the following can he use to store the LotusScript routines once and reuse them many times in a database? A. Script Libraries B. Database Script C. (Options) events D. Shared actions 20. Theresa is new to Domino programming and has not programmed

previously. Which of the following would be a good choice to learn first because it is less complex than the other language choices? A. Formula Language B. LotusScript C. JavaScript D. Java 21. Ulrike is ready to code his first application using Domino. He was a

JavaScript programmer in a former life, so he’s going to use his skills to build a really cool application. Both Notes clients and Web browsers will use the application. What should he remember to do? A. Create a $$Return field for execution in Notes clients. B. Enable the form property for encrypting data. C. Only add JavaScript to field properties. D. Hide any JavaScript that doesn’t execute in the Notes client.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

556

Chapter 11



Application Coding

22. Vivian is going to write code to interact with the Document Object

Model. Which language will she use to do this? A. Formula Language B. Java C. JavaScript D. LotusScript 23. William is writing some LotusScript for a Notes-only application. He’s

confused about which set of classes to focus on. Which of the following is a true statement that would help clarify the difference between the available classes? A. Back-end classes interact with data stored on-disk and not presented

on-screen. B. Front-end classes interact with data stored on-disk and not presented

on-screen. C. ODBC classes interact with data stored on-disk and not presented

on screen. D. Front-end classes cannot be used in the Notes client. 24. Xeno is coding Formula Language code in events. Which of the following

events does not allow Formula Language code? A. Default Value B. Input translation C. Input validation D. onBlur

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

557

25. Ying wants to create a Submit button for Web input forms using Formula

Language. To do this, what must he remember to do? A. Enable the user preferences property to allow JavaScript in the

Notes client. B. Enable the database property “Web access: use JavaScript when

generating pages.” C. Enable the form property “Web access: use JavaScript when gen-

erating pages.” D. Formula Language cannot be used to create a Submit button. 26. Zelma has written the following code for a button that will pop up a

dialog box on the Web; why isn’t the code executing? @Prompt([YESNO];”Confirmation”;”Are you sure you want to save this document?”) A. Yes/No buttons aren’t valid in the Web environment. B. @Prompt is not valid in the Web environment. C. Saving a document can only be done in the Notes client. D. Dialog boxes cannot be used in any form on the Web.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

558

Chapter 11



Application Coding

Answers to Review Questions 1. B. The spaces are not allowed in a URL and need to be replaced with

either a plus sign or a question mark. Enabling the Java applet for view access will affect whether scroll bars and roll-over colors work once the view is displayable. Renaming the views would work but is unnecessary if the spaces are eliminated with a question mark or plus sign. 2. C. The if statement used presents two conditions with an or symbol

(the double vertical bars) between them; when either condition is true, the alert action will fire. 3. A. URLs in HTML pages provide quick navigation because Domino

does not have to translate them to HTML on-the-fly, they’re already HTML. That makes it a direct access link and relatively fast. The remaining answers are all false statements. 4. A. The Dim keyword must be used to declare the orderDoc back-end

document object before it can be set equal to the front-end document currently on-screen. Using the New keyword instantiates new memory for the document and would result in creating a brand-new document, rather than accessing the current order document. 5. C. The field Exiting event will fire after a value is typed in the field and

as the field loses focus, making it a good candidate for field validation. The Entering event fires as the field obtains focus, negating its use in field validation. The Initialize event fires when the field is first loaded from memory and placed on-screen, way before user interaction, making it unusable for field validation. Finally, the onBlur event is useful for field validation but only with the JavaScript language. 6. B. @ProperCase will provide initial capitalization on words when

used in the input translation event. The Default Value event provides a starting value only and does not change data input by a user. @Yes and @Success both return the value 1 and do not change data. @Explode is used with list manipulation.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

559

7. D. Returning the @DocumentUniqueID converted to a text value is

appropriate for a URL, since URLs are text strings. @Inherited DocumentUniqueID returns the parent’s Document Unique ID so it is not the correct value. If a document is not inherited from another document, @InheritedDocumentUniqueID will actually return the @DocumentUniqueID, but using it would return inconsistent results in this situation. 8. C. Since HTML removes white space (in all places not just) in URLs,

the URL should be coded with a replacement character for the blank. The prefix of an underscore (_) is reminiscent of JavaScript form access, and while a Document Unique ID will work in a URL, who would want to type that ugly thing? 9. D. Default Value is an event that can only be coded in the Program-

mer’s pane for the field. Formulas for controlled access sections, Hide When attributes, and field formulas for dialog lists and the like can all be written in the Programmer’s pane. 10. A. Simple actions will not be visible from the Web, while many @

functions and some @Commands will be visible. JavaScript code is visible from a Web client. 11. B. Only objects stored in an NSF can be replicated between servers. If

the HTML is stored in the NSF, hidden or otherwise, it will replicate. 12. C. As a tagged language, HTML requires starting and ending tags to

delimit and format the data that appears between the tags. An ending tag is the same as the starting tag except that a forward slash precedes the tag, so would be an appropriate ending tag. 13. A. The text properties to mark direct coding on a form as Pass-Thru

HTML will tell Domino not to convert it but instead to render it directly. 14. C. The JS Header event for a form gives you a place to write JavaScript

functions that can be called from other objects in the form. Both (Options) and (Declarations) events apply to LotusScript, not JavaScript. The onBlur event is specific to each field, so it is not appropriate for storing global code.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

560

Chapter 11



Application Coding

15. A. Customizing the $$Return field’s value can be used to format a

more personalized Web form submission message for users. While onUnload is reasonable since it fires when a Web page or form is unloading from memory, the $$Return is intended for exactly this purpose, so you might as well take advantage of it! The onSubmit and onClick events do not generate automatic processing messages. 16. B. frm is a variable that represents the currently open document using the

forms array. 17. A. The img src tag in HTML displays an image; optional parameters to

the tag can set the width, height, alternate text, and border width. 18. B. The Set statement is used to initialize objects that have been instanti-

ated. The other statements are incorrect for a variety of reasons, including no direct assignment operator will initialize an object reference, Lotus Script statements do not end with semicolons, and the assignment operator is a single equal sign instead of a colon–equal sign pair. 19. A. Script Libraries allow for code that is written once to be accessed by

many objects within a database. Database scripts are similar in concept; however, they focus on database-wide events rather than on global user scripts. 20. A. Formula Language is a less complex language than LotusScript,

JavaScript, and Java, and since it is used in many places in Domino, it is a good starting point. 21. D. Since not all JavaScript works in a Notes client and this application

will be used in both environments, any code that doesn’t execute in a Notes client should be hidden. 22. C. JavaScript interacts with information in a Web paradigm using the

Document Object Model. Java and LotusScript use the Domino Object Model, while Formula Language uses nothing since it has direct access to Domino data. 23. A. The OLE and LotusScript back-end classes manipulate stored data

or create new data that is stored directly to disk, bypassing the user interface. 24. D. The onBlur event is specific to JavaScript, while the remaining

events all allow only Formula Language code. Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

561

25. B. Enabling “Web access: use JavaScript when generating pages” is a

database property, not a form property. Enabling JavaScript in the Notes client will not affect whether a browser can submit a form. 26. B. The @Prompt performs a Notes client user interface interaction

and is therefore invalid on the Web.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Chapter

Application Security

12

LOTUS EXAM COMPETENCIES COVERED IN THIS CHAPTER
Design a secure application
Design applications for consistent ACL enforcement
Design applications for replication
Design applications to restrict author access to documents
Design applications to restrict reader access to documents
Design applications which control document access
Design applications which control document access through authors fields
Design applications which control document access through reader fields
Design applications with read only view security
Design applications with section security
Design applications with view security
Plan application security based on Notes authentication
Plan application security based on number of Users
Plan application security based on Password encryption
Plan application security based on the Domino directory
Plan application security based on User Ids
Plan application security based on Web authentication
Plan applications based on authentication characteristics
Plan applications based upon impact of replication on agent security

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com


Plan applications based upon impact of replication on document distribution
Plan applications based upon impact of replication on hops
Plan applications based upon impact of replication on how background agents run
Plan applications based upon impact of replication on server involvement
Plan for Design distribution based on ACL impact
Set up ACLs for application security
Set up ACLs for replication
Set up Authors Fields for applications security
Set up Authors Fields for replication
Set up groups for application security
Set up groups for replication
Set up Readers fields for application security
Set up Readers fields for replication
Set up roles for application security
Set up roles for replication
Set up web users for applications security

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

T

he first Domino application you ever wrote probably didn’t include any security features in it beyond the basic ACL settings. Life was simple then, wasn’t it?! By the time you rolled out your fifth or tenth application, the need for security couldn’t be ignored. In this chapter, you’ll explore the multitude of security options that can be built into an application to keep bad things from happening to good data.

Top-Down Database Security

D

omino takes a layered, top-down approach to application security. The layers start with the operating system hosting the Domino server and end with the smallest of storage elements, fields. The stairs shown in Figure 12.1 depict this stepwise approach to security. FIGURE 12.1

Top-to-bottom security Network OS Domino server Database View & Form Document Section Paragraph Field

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

566

Chapter 12



Application Security

You can apply one level or many levels to your application. With each level you take advantage of, the better protected is your application.

The ACL Revisited

I

n Chapter 9, “Application Planning,” the Access Control List (ACL) was introduced as part of the security service provided by Domino through the Domino Directory. Each database has an ACL, acting much like a front door to a house. If you have a key to open the door, you can get into the house. That doesn’t guarantee you can get into all the rooms, since they may have additional locks on them, but you are, indeed, in the house. A deeper look at the ACL is in order to solidify some of the concepts previously introduced as well as to add to your knowledge of how the ACL protects an application.

User Types The ACL contains a list of all the users, servers, and groups who are granted some level of access to a database. It may also contain users, servers, and groups who are specifically denied access. Each entry in the ACL is also associated with a user type. When a user attempts to access a database, the identity and type of the user are checked for a match in the ACL. The six user types are shown in Table 12.1. TABLE 12.1

User Types Type

Description

Unspecified

Anyone who does not have a Person or Server document in the Domino Directory.

Person

A Person document exists in the Domino Directory.

Server

A Server document exists in the Domino Directory or is a remote server.

Mixed group

A group made up of persons and servers.

Person group

A group made up of only persons.

Server group

A group made up of only servers.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

The ACL Revisited

567

The -Default- entry is always set to the Unspecified user type, as shown in Figure 12.2. FIGURE 12.2

Unspecified user type

The user type provides a way for Domino to make sure that a server.id is not being used to log into a Notes client and to limit groups to types for added security checking.

Access Levels One of seven access controls is available to each user, server, or group in a database’s ACL. In ascending order of power, the levels determine a user’s right to unlock the front door of a database: 

No Access



Depositor



Reader



Author



Editor



Designer



Manager

No Access No Access means what it says. If you’re unlucky enough to be associated with the No Access tag, you’re not getting into the database. Well, with one exception, which you’ll find out about in just a bit. The No Access level is most often used to lock down databases by being applied to the -Default- entry in the ACL. Any user, server, or group that is not listed explicitly in the ACL will use the default access granted to the database, and every database must contain a -Default- entry. If the -Default- is No Access, then access to the database must be gained by explicit entry in the ACL.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

568

Chapter 12



Application Security

Depositor One level up from No Access is Depositor-level access. With this privilege, users can create and save new documents but cannot see them. This access is useful for applications like Mail-In databases and servers that will replicate data to another server but never need to receive data back or see the information.

Reader Reader access provides read-only interactions to the data in a database. Many Web applications use this access level to protect a portal database acting as a front end for links that jump to completely different databases and have higher, tighter security.

Author The Author access privilege includes all the capabilities of Reader access and allows users to create documents. Users can only edit documents they created or authored.

Editor Editor-level access allows users to create and edit documents. Unlike Author access, however, users can edit documents that were created by other users. Reader privilege is included.

Designer The Designer privilege is reserved for programmers who make design changes and replication changes to a database application. It includes Reader and Editor access.

Manager Manager access is the highest access level and adds the following two privileges on top of the rights granted to Designers: 

Modify the ACL.



Delete databases.

When a database is first created, the user ID creating the database is granted Manager access. Programmers creating new applications give themselves Manager access, and when they promote their applications to a production server, the Domino system administrator typically downgrades their access from Manager to Designer. Programmers are Delete-key trigger happy, with a nasty habit

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

The ACL Revisited

569

of deleting files by accident, so it’s a good thing to take Manager rights away immediately!

Access Levels and Replica Databases When a user makes a local replica copy of a database, the user is creating a new database. That means the user has Manager access to the database. Not only that, but when a person creates a new replica, there is a check box that makes copying the database’s Access Control List optional.

Since copying a database’s ACL is optional when a new replica or copy is made, encrypting a database is the best way to protect the data from unauthorized use.

So imagine your typical user making a replica copy of the Domino Directory on a laptop. Now, with Manager access, the user can add, modify, and delete documents that wouldn’t normally be accessible on a server. They can even delete the database itself! That doesn’t mean the changes will replicate since replication is governed by the ACL of the replica copy, but the user is led down a garden path thinking they’re in complete control. Fortunately, Notes has a security option to keep things on track.

Enforcing a Replicating ACL Preventing changes that violate the intended ACL is done using the security option Enforce A Consistent Access Control List Across All Replicas Of This Database. This option is found on the Advanced tab of a database’s ACL as shown in Figure 12.3. FIGURE 12.3

Enforce A Consistent Access Control List

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

570

Chapter 12



Application Security

Replicating ACLs The option to enforce a consistent ACL works on all replicas whether they are local or server-based. However, there is the issue of legitimate changes to the ACL that take place on a server by users with Manager access. These are changes that should be allowed! The question is which server should have the right to make the ACL change. Here’s the scenario: a database manager in San Francisco updates the ACL, and a database manager in New York updates the ACL. When the two servers replicate later, Domino has to decide which ACL is in effect. Since ACL changes replicate and the users had the rights to change the ACL, the usual replication rules are in effect. There is the possibility that both changes to the ACL affected the same entry, and if they were not changed identically, an invisible replication conflict could occur. It’s invisible because there is no Replication Save Conflict document to signal the collision. To avoid situations like this, you can choose one server from those that are replicating to be the Administrative Server. This ACL setting is shown in Figure 12.4. FIGURE 12.4

Setting the Administrative Server

With one server acting as the Administrative Server, only ACL changes made on that server will replicate between servers. ACL changes made on other servers will be overwritten.

Replication Enabling a server to replicate a database means that the server is treated as a user of the database. The server’s user type and identity are checked and associated with the access level granted. Keep a few things in mind for servers that are replicating: 

Each server involved in replication must be in the ACL either explicitly or as part of a group.



Each server should be identified with the User Type of Server.



Each server should have an access level appropriate to the task.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

The ACL Revisited

571

If the task at hand involves modifying data, for instance, the server will need Editor access to the database. In all cases, the server’s access is enforced just as if it were a user. Table 12.2 shows a breakdown of what access a server should have depending on the tasks it is trying to carry out. TABLE 12.2

Server Replication ACLs Access Level Required by Server

Task to Be Carried Out During Replication

Manager

Replicate ACL changes.

Designer

Replicate design changes.

Editor

Replicate creation of new documents and changes to all documents.

Author

Replicate creation of new documents and changes to documents created by the server.

Reader

Replicate all documents created, modified, and deleted by users.

Depositor

Replicate creation of new documents.

No Access

Deny replication privileges to a server.

If a server doesn’t have appropriate access, replication stops and an entry is made in the Notes log file as to when and why the replication halted.

Access Levels and Web Clients Securing an application to be accessed from the Web involves identifying the users and securing document contents. As with Notes client users, a database’s ACL is used to identify the users and grant or deny access.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

572

Chapter 12



Application Security

Web Users The Domino system administrator creates a Web user by adding a Person document to the Domino Directory. The Person document stores the user’s login name and Internet password; the password is encrypted in the document. The Web user’s login name can then be listed directly in a database’s ACL and given an explicit privilege appropriate to that user. Any user or group with Author access or above is challenged to enter a password.

Users with a Notes user ID can additionally have an Internet password. It does not have to be the same as the password on the Notes ID.

Anonymous Not all Web users will have a Person document in the Domino Directory. In fact, many Web sites are read-only and you’re never asked to identify yourself. In Domino, the username is passed from the Web browser to the server as a CGI variable, and if you’re not logged in with a specific Web username, the text Anonymous is passed as your identity. Any users who access the database as Anonymous are granted the access level applied to the special group, Anonymous, if it exists in the ACL. If the Anonymous group does not exist, the ACL of the -Default- entry is applied.

Maximum Internet Access Whether you log in as Anonymous or using a Web username and password, each database has a maximum Internet access level associated with it that will limit a Web client’s access. You can choose to set the access to any of the seven access-control levels using the Advanced area of a database’s ACL. This option is always in effect, so you need to make sure it’s set high enough to allow Web users appropriate access to the application. The maximum Internet access level overrides any explicit or Anonymous access level granted to Web clients in the ACL. This setting in the ACL is shown in Figure 12.5. FIGURE 12.5

Maximum Internet access

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

The ACL Revisited

573

If Secure Socket Layers and x.509 certificates are being used to authenticate Web users instead of the normal Domino Directory username and password, the maximum Internet setting is ignored.

Access Levels and Groups Groups appear in the Domino Directory and can be used in a database’s ACL. By using groups, you can apply access control to a group of people or servers rather than to individuals.

Creating Groups Groups are created by Domino system administrators and are often coowned with an appropriate power user who can help manage the adding and removing of individuals as group members. It is better to use a group name in an ACL than an individual name, especially in companies that have high employee turnover. Maintaining centralized groups is easier than maintaining distributed database ACLs with individuals. For instance, when someone new joins the company, if the system administrator adds them to appropriate groups when the ID is being created, then that person automatically gets access to the databases that have the group name in the ACL. The alternative is maintaining databases individually as users come and go, and well, there goes the day at the beach.

Special Groups There are several special groups used in an ACL. Domino creates one of them automatically, while system administrators create others. Some of the names of

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

574

Chapter 12



Application Security

the groups in your organization might differ from the ones shown in Table 12.3, but you probably have a group that serves the described purpose. TABLE 12.3

Special Groups

Group Name

Purpose

Anonymous

Used to grant access to users without ID files (such as Web users).

LocalDomainServers

Used to group servers inside your Domino network; this group is the only group automatically maintained by Domino.

OtherDomainServers

Used to group servers outside your Domino network.

DenyAccess

Used to group together users and servers who should be denied access.

Terminate

Used to group together users who have left the company.

DominoAdmins

Used to group together Domino administrators.

Don’t know who’s in a group? You can look up this information in the Domino Directory on the server in the Groups area.

Determining Access Rights A database’s ACL can be quite a busy place with the names of users and groups piling up. When users are listed individually and in a group or when a user is in multiple groups, you need a few rules to help you determine what access level will be applied. Individual versus Group If you’re in the ACL of a database as both the member of a group and as an individual, assuming they are different, which access level will be used? The most specific or explicit entry is the one that governs your access. For example, if you’re a member of the WineReviewers group, have Editor access to the

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

The ACL Revisited

575

WineMaster database, and are listed individually in the ACL with Reader access, Reader access applies to you. Figure 12.6 demonstrates the concept. FIGURE 12.6

Groups and individuals in an ACL

Multiple Groups If you are a member of multiple groups that appear in the ACL, you receive the highest access granted to any of the groups. For instance, if you’re in the WineReviewers group with Editor rights and in the WineMakers group with Author rights, you will access the database with Editor access. If any roles are associated with the groups, you receive the roles for all the groups of which you are a member. Let’s talk more about roles in the upcoming section.

Roles Roles are similar to groups in that they treat users as a unit. The fundamental difference between the two lies in where they are created and who creates them: 



Roles are created by database designers and exist only in an individual database. Groups are created by system administrators and exist in the Domino Directory for all databases to access.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

576

Chapter 12



Application Security

Both roles and groups can be used to apply security to a database; however, roles do not appear as entries in a database ACL. Instead, roles are associated with an ACL entry. For instance, the AccountingAR group might have the [AbleToSignCheck] role. This would give users in the AccountingAR group some type of extra privilege not normally associated with the group, in this case, the ability to sign checks. The power of Roles comes from the developer’s ability to create, maintain, and apply them as needed without system administrator intervention. Remember, though, that roles only exist inside a database, so if you need to have an [Approvers] role in multiple databases, you’ll have to create, assign, and apply it in each database.

Creating Roles The Roles area in the ACL lets you add, rename, and remove roles. A role can be created with any name you like as long as it’s 15 characters or fewer with no spaces. The name should be something that describes what the role will be used to do. Role names appear with square brackets around them, as shown in Figure 12.7. The brackets should be used whenever the role is referred to in Domino code. FIGURE 12.7

Roles

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

The ACL Revisited

577

Assigning Roles After creating a role, the next step is to assign users, servers, or groups to the role from the ACL. With an entry selected, the bottom-right roles area on the ACL allows a checkmark to be placed next to the role that is to be associated with the entry. In the example shown in Figure 12.8, the DominoAdmins group has the [Approvers] role. FIGURE 12.8

Assigning a role

Applying Roles With a role created and users assigned to it, the last step of putting roles to work is to apply the role in Domino code or to a design element. roles can be used in many design elements, including the form access list shown in Figure 12.9.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

578

Chapter 12



Application Security

FIGURE 12.9

Applying a Role

Form and View Security

Forms and views have security options built into them that are turned off by default but are easy to turn on. The purpose of both form and view security is to add additional security to the documents created from the form or shown in a view by controlling who can create and read the documents.

Form Access Lists Granting users ACL access to a database as Author or Editor gives them the ability to create and read documents in the database…wait, make that all documents in the database. What if there are multiple forms in the database

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Form and View Security

579

and you want some users to be able to create and modify data using one form but not all the others? The ACL helps by having let them in the front door, but now you want to put a few locks on some of the inner bedroom doors. Form access lists can help with this. There are two kinds of form access lists and both are activated on the Security tab of a form’s Properties box: 

Form read access list



Form create access list

The form read list is used to limit which users will be allowed to see documents created with the form. When the default of anyone with Reader access and above is not selected, the list below becomes a scrollable window listing all entries and Roles in the ACL. Additional users can also be selected directly from the Domino Directory or local Address Book using the blue People icon. Similarly, the form create list is used to restrict who can create documents using the form. When the default of anyone with Author access and above is deactivated, available choices are all entries and Roles in the ACL or entries in the Domino Directory.

View Access Lists Like form read access lists, view access lists limit who can see data. When a user is not in the view access list and its default is not in effect, the user will simply not see the view. This is a useful technique to minimize scrolling through many views since views will only appear for users with the view access. The view access list is set using the Security tab in the view’s properties, as shown in Figure 12.10.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

580

Chapter 12



Application Security

FIGURE 12.10

View access list

The view access control slows a user down by not presenting the view to them on-screen, but it might not stop a determined user. If users have proper rights, they can create their own views, perhaps even mimicking the view selection criteria in the view to which you applied security. To truly disallow access to information in views, document security is needed.

Document Security

D

ocument security in Notes places information inside a document to limit who can work with a document. This is different from form access security, which acts much like a locked door to a room. With document security, you’re inside the room because form access allowed it, but there may be things in the room that are locked, such as bookcases and desks. You can lock access to a document in two ways: 

Lock the entire document using special fields.



Lock parts of the document using section and field security.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Document Security

581

Securing an Entire Document Using special fields, you can lock users out of an entire document for both creating and reading purposes. In addition, you can grant access to users that have fairly low access in the ACL. The special fields are 

Reader Names



Author Names



$PublicAccess

Reader Names Fields One of the field types available in a form is Readers. The field is usually editable or computed and can have any name you want. The field’s value determines whose security rights will be affected. Figure 12.11 shows how to set the field type and value type. FIGURE 12.11

Creating a Readers field

When a Readers field is placed on a form, it can be used to limit who will be able to see the resulting document. The value that is programmed for the field can be the result of a formula or hard-coded and will result in a single user or list of users that can read the document. The server names of replicating servers also need to be in the field value since servers can’t replicate what they can’t see. Here are the rules to remember when working with Readers fields. 









Readers fields affect users with Reader access and above in a database. Readers fields are normally hidden from all users using Hide When properties. Readers fields can have their value computed by a formula. Readers fields can contain users, roles, groups, and servers as valid entries. Readers fields are ignored if no value was programmed for the field.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

582

Chapter 12



Application Security

To best describe the use of Readers fields, consider the case of Mark and George. Both fellows have Reader access to a database. Within the database are documents with a Readers Names field on them, and the value of the Readers Name field is “George.” This means that even though Mark has Reader access to the database, he will not be able to see (and therefore read) the documents because he is not listed in the Readers field.

Author Names Fields Authors fields are similar in concept to Readers fields but affect the creation and editing of documents instead of the reading of documents. Figure 12.12 shows how to create an Authors field. FIGURE 12.12

Creating an Authors field

The presence of an Authors field on a form has an immediate effect, limiting future edits on the document. Formulas are also a valid way to populate the field at runtime. Server names need to be in the field for replicating new documents and modified documents since servers can replicate what they don’t have access to. Here are the points to remember when working with Authors fields. 



Authors fields only affect users with Author access in a database. Authors fields are normally hidden from all users using Hide When properties.



Authors fields can have their value computed with a formula.



Authors fields can have users, roles, groups, and servers as valid entries.



Authors fields are in effect even if no value was programmed for the field and will prevent anyone from editing the document after it is saved…oops.

Let’s use George and Mark again to best describe Authors fields. This time, both fellows have Author access to a database. Within the database are documents with an Author Names field on them, and the value of the Author Names field has been hard-coded as “George.” This means that even though Mark has

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Document Security

583

Author access to the database, he will not be able to edit documents that he created using the form because he is not listed in the Authors field. If an Author Names field contains a group or a role, Authors fields can be used to limit the editing of documents to a group of users within a database.

Reader fields and Authors fields offer two of the tightest security locks available in Domino.

Public Access Documents Unlike Readers and Authors fields, $PublicAccess is not a field type but, rather, a field used to create a public access document. Public access documents in Notes are design notes that contain the reserved field $PublicAccess. Users who normally have No Access or Depositor access to the database can access these documents. Public Access Explained At first blush, the concept of public access seems like a security hole, not a security feature. Well, before you’re compelled to run and whisper to the tabloids, let’s explain why it’s in Notes. Consider the situation in many large companies between bosses and their administrative assistants. Bosses are invariably too busy to handle the management of their daily calendar, so they delegate the task to their admin. In Notes, calendars are stored in the mail file, and usually, one would want things in the mail file to be absolutely private. Indeed, you might have Manager access to your own mail database, while the default access is No Access. With the entry of Calendaring & Scheduling into the Notes product in R4.5, it became necessary to grant read/write access to the calendar while, at the same time, preventing access to all other documents in the mail database. The solution? Public access documents. Using calendar profiles, public access documents were created in the mail file for administrative assistants to be able to manage calendars they didn’t own without being able to read the mail. The public access concept can be used in any database and is often used to make documents in Web applications available to users who normally have No Access or Depositor rights. To use this feature, two things must be present: 

Access control settings must allow access to public documents.



Design elements must exist to create public documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

584

Chapter 12



Application Security

Access Control Settings A database has to allow the use of public documents. This is enabled in the ACL using the optional check box settings for each of the levels as shown in Figure 12.13. FIGURE 12.13

ACL public access settings

Of the seven levels in the ACL, some, like Manager, are automatically enabled to use public access documents. Other levels, like No Access, need the optional privilege enabled. Table 12.4 outlines which ones are automatic and which are optional. TABLE 12.4

The ACL Public Access Privilege

Access Level

Ability to Read Public Documents

Ability to Write Public Documents

Manager

Automatic

Automatic

Designer

Automatic

Automatic

Editor

Automatic

Automatic

Author

Automatic

Optional

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Document Security

TABLE 12.4

585

The ACL Public Access Privilege (continued)

Access Level

Ability to Read Public Documents

Ability to Write Public Documents

Reader

Automatic

Optional

Depositor

Optional

Optional

No Access

Optional

Optional

Design Element Settings The following design elements can be treated as public access documents in a database: 

Forms



Pages



Outlines



Views



Agents

Forms, pages, and views all have a Security tab on their Properties info box. Here, you’ll find the check box to set the option Available To Public Access Users. The setting for Outlines is also in the Properties box but is located on the one and only tab available, Outline Info. For all design elements except forms, marking the check box adds the $PublicAccess field to the document. To make documents created from forms available as public access documents, you need to do three things: 





Place a special computed text field, $PublicAccess, on a form and give it a value of “1”. Mark the Available To Public Access Users form property on the Security tab. Allow a view to show the public access documents by marking the Available To Public Access Users view property on the Security tab.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

586

Chapter 12



Application Security

To make an agent available as a public access document, use the Options button in the Agent design area and select the now-familiar setting, Available To Public Access Users. This is shown in Figure 12.14. FIGURE 12.14

Public access agents

The special fields of Readers, Authors, and $PublicAccess allow or prevent a user from working with an entire document. You can refine this security mesh even further by denying or granting access to select areas and fields that lie within a document.

Securing Parts of a Document Once inside a document, there are two ways you can additionally restrict a user’s ability to interact with the data: 

Controlled Access Sections



Field encryption

Controlled Access Sections Sections provide the ability on a form or a page to organize and secure a subset of information. They are presented to the user as collapsible and expandable areas in a document. Sections come in two flavors: 

Standard



Controlled Access

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Document Security

587

Both kinds of sections can be dynamically hidden from users through the use of the Hide When tab in the Section Properties box.

Standard sections are primarily used to organize and simplify the presentation of information to a user. They can be used on both pages and forms but offer no additional security to a document. Controlled Access Sections, on the other hand, offer increased security by reserving an area on a form for editing by a subset of the database users. A Controlled Access Section limits who can edit the data in the section, not who can read the data. The data is visible to and available for reading by all users with appropriate access to the document. This is handy for creating reserved areas on the form such as For Accounting Use Only. Figure 12.15 demonstrates how to associate the security on a section with a role. FIGURE 12.15

Controlled Access Section

The users who are allowed to edit the document are determined by a formula you write on the Formula tab of the Section’s Properties box. In the example shown above, access has been limited to those users associated with the [AccountingEdit] role. One way to think about how to write the access formula is to imagine the pseudo code for an if-then statement in your head and then write the condition part of the statement in the Section’s Formula

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

588

Chapter 12



Application Security

tab. For instance, the pseudo if-then statement for the access granted above would be If the user is a member of the [AccountingEdit] role, then grant section Edit rights. The condition part of an if must evaluate to True or False. Here, the condition is “is a member of the [AccountingEdit] role”. If the condition is True, then Edit rights are granted. Controlled Access Sections are a good way to control access to a group of fields within a document. Field-level security, however, is only available with field encryption.

Field Encryption The most granular level of security available in Notes is field encryption. Any field in a Notes form can be encrypted. If you’ve ever sent an encrypted mail message to someone, it was the $Body field containing the text of your memo that was encrypted. Once a field is encrypted, if you don’t have an encryption key to access it, the field appears blank on the screen. Encrypting a field in a document is a three-step process: 1. Create an encryptable field. 2. Create an encryption key. 3. Apply the encryption key to the form that contains the encryptable field.

Creating Encryptable Fields Using the Password type for a field automatically enables it to be encrypted. However, any field of any type can be enabled for encryption. Once a field is enabled for encryption, the border box around the field on the form displays in red.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Document Security

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

589

590

Chapter 12



Application Security

To make a non-Password type field ready for encrypting, use the field’s Advanced tab on the Properties box and set the Security Options to enable encryption for this field. Password-type fields automatically enable this security option. Being encryptable, however, does not mean the field is automatically encrypted. You’ll need to create an encryption key to do that. Creating Encryption Keys Encryption keys are created in the Notes client, not the Design client, and are stored in the ID file of the user who creates the key in addition to your private key. The new keys are referred to in Notes as secret encryption keys, and you can store as many as you need in your ID file. To create a new key or receive a key and add it to your ID, use the Notes client menu sequence File  Tools  User ID. Figure 12.16 shows the encryption of a user ID. FIGURE 12.16

Creating an encryption key

After you have a key created for your application, you can mail it to users who will need it or export it so that you can copy it to disk.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Agent Security

591

With version 5.0.3 and earlier, consider creating encryption keys with the International client for applications that are to be used around the world, because keys created with the North American client cannot be used outside North America or added to the International IDs.

Applying Encryption Keys With a key created and fields ready to encrypt, the last step in encrypting a field is to apply a key to the form that contains the field you want to encrypt. This is done using the Security tab on the Form Properties box and using the drop-down box to set the default encryption key to a named key that you created. That’s it…three steps, and field encryption is in place! Now, when a user types a value in the field, it will be stored in the database in a garbled, non-human-readable format.

Agent Security

T

he last bit of security to discuss is not related to documents at all but, rather, to code that may touch documents. Since agents are code that can run unattended on a server, tight security is applied at several levels to ensure that the data in documents is kept safe. In databases that replicate, one server should be designated to run agents that modify documents and let the document changes replicate. This will avoid Replication Save Conflicts that would occur if all replicating servers ran the agent. Figure 12.17 shows an agent that is set to run on a particular server.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

592

Chapter 12



Application Security

FIGURE 12.17

Choosing a server for an agent

Who Can Create Agents To create shared agents in a database, you need a minimum of Designer access. The database ACL has an optional privilege that grants the right to create LotusScript and Java agents, shown in Figure 12.18. FIGURE 12.18

ACL to create LotusScript and Java agents

When an agent is created or modified, the user ID of the person saving the document becomes the agent’s signer. Background agents generally run with the access control of an agent’s signer, and if the agent sends e-mail, it will appear to be from whichever user signed the agent.

Many organizations set aside a special user ID that is used to sign agents for mail purposes so that when a programmer leaves the company, the agents continue to run without interruption.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Agent Security

593

Who Can Run Agents Users can run shared agents if they have a minimum of Reader access to a database or if the agent is marked as a public document. However, an agent always respects the ACL, and the agent will be unable to take an action that is not within the user’s access privilege. For instance, if an agent deletes documents, the person invoking the agent must have the appropriate ACL privilege to delete documents, otherwise the agent will fail.

Types of Agents There are three types of agents, and two of them are strictly controlled at the server level by restrictions in the Domino Directory. Table 12.5 lists the types of agents. TABLE 12.5

Types of Agents Type

Description

Formula Agent

Agents written using the Notes Formula Language

Restricted Agent

LotusScript or Java agent that affect database contents

Unrestricted Agent

LotusScript or Java agent that affect external file systems

Of these agents, formula agents are not restricted from server execution in any way. Restricted and unrestricted agents, on the other hand, have a place in the server document that lists who is allowed to run this type of agent.

Web Agents Agents invoked by Web users can run with either the access level granted to the Anonymous group in the ACL or with the access of the specific Web user doing the invoking. The default is to run as Anonymous. To run the agent as a specific Web user, the agent property Run As Web User must be marked. This setting is shown in Figure 12.19.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

594

Chapter 12



Application Security

FIGURE 12.19

Running an agent as a Web user

Summary

By now you’ve grown to appreciate just how secure you can make a Domino application. Perhaps the best way to summarize is to provide a cheat sheet in the form of Table 12.6, which lists where to find all the settings in the Domino Designer. Enjoy! TABLE 12.6

Finding Security Settings Security Setting

Where to Find It

ACL

Menu options File  Database  Access Control.

Author Names fields

In a form, create field type of Authors.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Summary

TABLE 12.6

595

Finding Security Settings (continued) Security Setting

Where to Find It

Controlled Access Section

In a form, create Section, Controlled Access and write a grant access formula on the Formula tab of the Section Properties box.

Database encryption

Database properties, Database Basics tab, Encryption Settings button.

Enforce a consistent ACL

Advanced tab of database ACL.

Field encryption

Field Advanced tab, Security Options area with a value of Enable Encryption For This Field and apply an encryption key using Form properties Security tab to set the default encryption key.

Form access list

Form properties, Security tab.

Hide When criteria

Object properties info box, Paragraph Hide When tab.

Maximum Internet access level

Advanced tab of database ACL.

Public Access

ACL check box options and design element check box option; forms must contain $PublicAccess field as well.

Reader Names fields

In a form, create field type of Readers.

Run agent as web user

Design tab of Agent properties.

User Type

Top-right corner of the ACL.

View access list

View properties, Security tab.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

596

Chapter 12



Application Security

Key Terms Before taking the exam, you should be familiar with the following terms: Access Control List (ACL) Anonymous Authors field Controlled Access Section encryption form access list (form security) form create access list (form security) form read access list (form security) Hide When public access Readers field roles user type view access list (view security)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

597

Review Questions 1. Alex is listed in the ACL of a database directly as an individual with

Reader access. He is also a member of the ProductManagers group in the Domino Directory, which has Author access, and the ProductEditors group, which has Editor access. The database replicates to remote servers. Which access level does Alex actually receive? A. Manager B. Editor C. Author D. Reader 2. Beth has written an agent that will be invoked by Web browser users in

an application that forces each user to log in. Which of the following should she add to her application to tighten up Web security? A. Add Anonymous as an ACL entry and give it Author access. B. Sign the agent with an ID that has Manager privileges. C. Add Anonymous as an ACL entry and give it Editor access. D. Set the agent property to run as a Web user. 3. Cody has a bet with his office mate. Cody believes that since he has

Designer access to a database that replicates regularly he can write LotusScript and Java agents that Web users can execute. What do you know to be true of agents that Cody has forgotten? A. LotusScript agents can’t be invoked by Web users. B. Java agents can’t be invoked by Web users. C. Having Designer access doesn’t guarantee that you can create

LotusScript/Java agents. D. You need Manager access to create LotusScript/Java agents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

598

Chapter 12



Application Security

4. Debbie needs to prevent users from deleting documents created with a

certain form. Which of the following will not help her? A. Add form security through the form access list to prevent deletions. B. Deactivate the optional Delete documents privilege from the ACL. C. Set all users up with Reader access. D. Deactivate the optional Delete documents privilege for -Default- access. 5. Elliott’s application makes heavy use of Hide When criteria to hide

things from Web users or Notes users depending on the type of client. Which of the following design components can he hide? A. View B. Form C. Controlled Access Section D. Subform 6. Readers fields are part of an application that Faye just took over from

a programmer who left the company. Which of the following would best describe Reader Names fields? A. Readers fields prevent users with Reader access from seeing documents. B. Readers fields allow users with Reader access to see all documents. C. Readers fields allow documents to be viewed only by the users or

groups listed in the Readers field. D. Readers fields prevent documents from being viewed by the users

or groups listed in the Readers field.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

599

7. Gary successfully tested his LotusScript agent in development mode,

but when he moved it to the production server and set it to run every night at 1:00 A.M., the agent fails to run. The agent writes an external text file using data in the NSF file. Which of the following might be the problem? A. Lack of rights in the Server configuration document to run

restricted LotusScript agents. B. Lack of rights in the Server configuration document to run

unrestricted LotusScript agents. C. Lack of rights in the ACL to create LotusScript/Java agents. D. Agents cannot be run at 1:00 A.M. since that is when Domino carries

out many system maintenance tasks. 8. Haley has placed an Authors field on her form and will use it to pre-

vent certain users from creating and editing documents. To guarantee that this subset of users can read the documents, what should she do? A. Add a Readers field with the subset of usernames as the field value. B. Set the ACL of the subset of users to Reader. C. Set form security to limit reading to the subset of users. D. Nothing; if you have Author access, you can read the documents. 9. Ian wants to limit the availability of a view to certain users. The users

are arranged in groups in the ACL. How can he accomplish his goal? A. Use view security and the view access list to make the view visible

only to the appropriate groups. B. Create a role for reading the views and link it to the groups. C. Use Readers fields on the documents to prevent them from appearing

in the view. D. Encrypt the documents to prevent them from appearing to all users.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

600

Chapter 12



Application Security

10. Jamie is designing the security for a Web application. Which of the

following security mechanisms do not apply to Web clients? A. Access Control List B. Hide When C. Reader Names fields D. Encryption 11. Kendall’s application contains both Readers and Authors fields. The

application replicates with four remote servers. What does he need to do to make sure that the documents that have Readers and Authors fields on them replicate correctly? A. The names of the remote servers must be in the ACL with Manager

access. B. The names of the remote servers must be in the ACL with Reader

access. C. The names of the remote servers must be in the Readers fields. D. The names of the remote servers must be in the Authors fields. 12. Lisa has had a request from the accounting department. It seems that

all users should be allowed to create new orders with the Order form in the Domino sales application, but only the Accounting department group should be allowed to edit the documents after they’ve been saved the first time. All users should still be able to see all orders. What can Lisa do to implement this request? A. Give all users Author access to the database and use an Authors

field on the Order form with the Accounting department group as its value. B. Give all users Editor access to the database and use an Authors

field on the Order form with the Accounting department group as its value. C. Give the Accounting department group Editor access to the database

and all other users Author access. D. Give the Accounting department group Editor access to the database

and all other users Depositor access.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

601

13. The Domino servers in Marco’s organization are set up in a hub-and-

spoke configuration, with each spoke server replicating databases with the server. Given that only the hub server modifies documents in the Company Announcements database and users can make personal views, what ACL level should the spoke servers have in the database? A. Manager B. Designer C. Reader D. Depositor 14. Nellie works in Marco’s hub-spoke organization. She has a database

that creates daily news articles. The news articles are never modified, so the hub server simply needs to push the data to the spoke servers. What security access should she give the spoke servers in her database? A. Manager B. Designer C. Reader D. Depositor 15. Otis has a template and a database on the Dallas server that replicates every

hour to the Seattle and Detroit servers. Once changes are inherited into the Dallas database, they’ll replicate to the other servers. What minimum access level should each of the servers have in the database’s ACL? A. Manager B. Designer C. Editor D. Author

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

602

Chapter 12



Application Security

16. Paige wants users to be unable to edit the unit_selling_price field on

existing Product documents. All users have Author access to the database, and Paige knows that they can edit the information on documents they originally created. How can she prevent them from editing the unit_selling_price field after the document is originally saved? A. Add an Authors field to the form. B. Apply form security using the form access list. C. Set the unit_selling_price field property Security Options: Must

Have At Least Editor Access To Use. D. Encrypt the unit_selling_price field. 17. Quentin is about to change his password. To give him maximum

protection, which of the following should he do? A. Make the password all lowercase. B. Make the password 20 characters long. C. Make the password a combination of upper- and lowercase letters

and numbers. D. Embed his driver’s license number in the password. 18. Reba wants to protect the data in the Sales Contacts database from non-

Notes and unauthorized Notes users. The application is replicated by Sales team members to their laptops and used when traveling. Which of the following will best protect the local data? A. Configure each workstation’s Execution Control List. B. Show each user how to encrypt local databases. C. Change the ACL on the server’s database before users make local

copies. D. Set the Anonymous access level to No Access.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

603

19. Scott is determined to protect his application from malicious changes on

the remote servers to which he replicates, so he has marked the option to enforce a consistent ACL on all replicas. If someone with Manager access changes the ACL on the database on one of the remote servers, what will happen the next time the database replicates? A. The ACL changes will be replicated back to Scott’s server. B. Replication of the database will fail. C. Replication of the database will succeed and a note will be generated

to all users with Manager ACL. D. The ACL change will be propagated to all servers with the replica. 20. Tatum has given the group ContentManagers Author access to the

website.nsf database and has created the role [WebContentEditor] and associated ContentManagers with it. An Authors field is included on the content documents and formulas that check for the [WebContentEditor] role. The website.nsf replicates outside the company firewall to a Domino ISP hosting service. Which of the following is a true statement about the ISP’s server? A. It should have Manager access to the website.nsf. B. It should have Anonymous access since it is a Web server. C. It should be included in the LocalDomainServers group in the ACL. D. It should be listed as a member of ContentManagers and the

[WebContentEditor] role. 21. Ute needs to apply field-level security in a form. Which of the following

security mechanisms can do this? A. Controlled Access Sections B. Roles C. Hide When D. Encryption

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

604

Chapter 12



Application Security

22. Valerie wants to make several fields available for viewing at all times

but editable by only a subset of database users. Which of the following can she use? A. Roles B. Access Control C. Section Editing D. Hide When 23. Winston’s company wants him to build a Domino Web site that consists

of a portal homepage available to all Internet users with additional areas on the site that require a user ID and password. How can this be done easily in Domino? A. Design two NSFs, the portal with Anonymous access as Reader

and the other with a minimum of Author access. B. Design two NSFs, the portal with Default access as Reader and the

other with a minimum of Author access. C. Design one NSF with the portal and other areas and give Anony-

mous Reader access. D. Design one NSF with the portal and other areas and give default

Reader access. 24. Xenia’s agent is set to run each night at 2:30 A.M. and will modify

documents on a set of three servers that replicate with one another. There is the potential for Replication Save Conflicts unless Xenia does the following: A. Runs the agent at different times on different servers B. Schedules the agent to run on only one server C. Schedules the agent to start running only after it’s completed

running on a remote server D. Runs the agent locally and then replicates the changes manually

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Review Questions

605

25. Yetta added an Authors field to the MarketingInfo form but forgot to

program a value for the field. The database has a Default access of Author for all users. Based on this, what will the users experience when working with the documents? A. They’ll be able to create new documents but not to edit their

documents. B. They’ll be able to create and edit their own documents but not

those created by other users. C. They’ll be able to read documents they created but not those created

by other users. D. They’ll be able to create new documents but not to edit documents

created by other users. 26. Zola has created the [PricingEditorRole] role and assigned users in the

ProductEditorGroup to use it. The role will be used to restrict who can edit the unit selling price on the product form. To do this, which of the following should she use? A. A Controlled Access Section that assigns Editor access to the

[PricingEditorRole] B. An encrypted field for unit selling price C. An Authors field for unit selling price D. Editor access for users in the ProductEditorGroup

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

606

Chapter 12



Application Security

Answers to Review Questions 1. D. The most specific or explicit ACL applies, so Alex receives Reader

access. If Alex is removed from the ACL as an individual, he receives Editor access, which is the higher of the two groups. 2. D. Setting the agent property option to Run Agent As Web User forces

a login prompt so that the identity of the user running the agent is known. The agent will then run with the ACL of the user. The user must be listed in the ACL either through individual entry or a group that contains the user. The Anonymous ACL entry will not work, since it does not force a login. Signing the agent with Manager privileges would not be advisable, especially if the agent isn’t set to run as a Web user…definitely a security hole. 3. C. The privilege to create LotusScript/Java agents is an optional check box

privilege for Design access and below, so the option would need to be enabled in order for Cody to win his bet. LotusScript agents can be invoked by Web users and run on the Domino server. Java agents can be invoked by Web users and run in the browser. Manager access automatically grants you the privilege to create LotusScript/Java agents, but you do not need it since Designer would suffice if the option is active. 4. A. Form security does not control the ability to delete documents created

using the form; rather, it controls who can read or create documents using the form. All the other answers are steps that can be taken to keep Delete capabilities out of the wrong hands. 5. C. Hide When attributes can be applied to Controlled Access Sections,

but they are not available for forms, views, and subforms. 6. C. Reader Names fields refine the ACL and limit access to the doc-

uments created with Readers fields to only those users or groups listed as values in the field. All other users, regardless of their access level, will be prevented from seeing the documents.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

607

7. B. Writing external files to the operating system requires the server

privilege to run unrestricted agents. Since the programmer was able to successfully create and test the LotusScript agent, answer C is invalid, and while Domino does indeed carry out many system maintenance tasks at 1:00, you can still write agents to kick off at this time. 8. D. Author Names fields apply only to users with Author access. If you

have Author access, you automatically have Read access. Adding a Readers field would restrict the visibility of the document, and Haley is trying to limit create and edit only; likewise with setting form security. 9. A. The view access list can be set to limit who can see a view, and group

names as well as roles and individuals are allowed as entries. Using a role without the view access list would not help. Using Readers fields would apply document-level security, which is good; however, Ian wants the entire view not to be visible to most users, so view security makes sense. Finally, encrypting the documents would hide the encrypted fields on the document and not the view. 10. D. Encryption is not available because it relies on the private key stored

in a user ID file, which Web users don’t have. The remaining security options all apply to Web users. 11. C. For documents with Readers fields to replicate, the servers

involved in the replication must appear in the Readers field so that they can read the documents. If a server can’t read a document, it can’t replicate it. 12. A. Authors fields apply to users with Author access, so by using an

Authors field, you can limit the future editing of documents to the group names in the Authors field. Depositor access would prevent users from seeing documents after they were created. 13. C. Since the spoke servers never make changes to the database, Reader

access in the ACL is sufficient for them.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

608

Chapter 12



Application Security

14. D. One-way replication can be created by setting the source server’s ACL

to Depositor. This will let the server create new documents but not receive any changes. Since the news articles are created and never modified, Depositor access on the server is sufficient. 15. B. For design changes to replicate from one server to another, the

servers must have a minimum access of Designer. Manager would also work, but it is not the minimum. 16. C. Setting the property Security Options: Must Have At Least Editor

Access To Use would limit the editing of the field on existing documents but still allow editing on newly created documents. Form security does not provide protection down to the individual field level. Encrypting the field would make it invisible to users, which is not desired. 17. C. Using a short, memorable combination of mixed-case letters together

with numbers provides strong security. And the driver’s license number might be just such a number, but there’s no guarantee! 18. B. Encrypting local databases is the best way to protect local data-

bases since the private key of the user who encrypted it would be required in order to open the database. Configuring the ECL will not prevent local copies from being made by unauthorized Notes users while disabling the copying of the ACL itself, which is also the reason that changing the server database ACL will not help. Setting the Anonymous access level to No Access will help, but encryption is best. 19. B. Replication will fail and an entry will be made in the Notes log file

describing the problem. Since Scott is enforcing the ACL at his server, no ACL changes will be sent back and none will be propagated. 20. D. The server should be listed as a member of the

ContentManagers group and the [WebContentEditor] role so that the Authors field allows replication of the content documents. Domino Web servers should not have Anonymous access since they need to be listed as user type of Server and not Unspecified.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Answers to Review Questions

609

21. D. Encryption can be applied at the field level and, when viewed by

users without the right key, simply appears as a blank field. Hide When can be used to hide a field; however, the data is still stored as clear text, visible through the document’s properties. Controlled Access Sections can control the editing of a field but not the viewing. Finally, roles cannot be applied directly to fields. 22. C. Controlled Access Sections will allow the field values to be viewable

by all users who have document access. While Roles might be useful for calculating who should be allowed to edit the section and might even be useful with Hide Whens, section editing is the best choice. 23. A. Using two databases, one secure and one open, allows the first level

of security to start at the database level, opening the option for additional security mechanisms like database encryption. 24. B. Agents that modify documents and replicate between servers can help

avoid conflicts by setting the agent to run on one server and then letting those changes replicate out to other servers. You cannot control the scheduling of agents between different servers and can’t give them different times in the same agent. 25. A. Leaving an Authors field blank means that the user who created

the document cannot edit it. It would require Editor access or above to edit the document, and since the default access is Author, editing the documents would not be possible. 26. A. To allow edit access on part of a document to a subset of users, use a

Controlled Access Section that specifies the role. Encrypting the field would hide it in Edit and Read mode, and no mention in the question was made of hiding it during Read mode. An Authors field controls who can create and edit documents in their entirety and therefore does not apply. Assigning Editor access to the ProductEditorGroup is a good idea; however, it will not restrict edit access within a document, only to documents as a whole.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Appendix

510 Practice Exam

A

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

612

Appendix A




510 Practice Exam

Practice Exam 1. Art is listed in the WineMaster database with Author access. A Readers

field exists on the Reseller form in the WineMaster database. No Authors field exists on the form. The Readers field does not contain any value when Reseller documents are created. What effect does this have on Art? A. He can author Reseller documents but not read them. B. He can read Reseller documents but not author them. C. He can read or delete Reseller documents. D. He can read and author Reseller documents. 2. Brittney has a user that she refers to as “Rambo.” At least once a month,

Rambo accidentally deletes documents from the WineMaster database and runs to Brittney to see if they can be recovered. What combination of features in R5 will help Brittney save Rambo from herself? A. An agent used with the “before new mail arrives” trigger B. Enabling soft deletes used with the @UndeleteDocument function C. View buttons used with JavaScript code D. Enabling hard deletes used with the @UndeleteDocument function 3. Chip is a good Notes programmer and will be using a template data-

base to write his code before pushing it into his production database. Which file extension is typically used for Notes templates? A. BOX B. NSF C. NTF D. NS4

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

613

4. Daisy has decided that the first thing she wants users to see when they

open her database is a Microsoft Excel spreadsheet containing the production targets for the current month. How can she accomplish this goal? A. Create a document link in a page. B. Paste the spreadsheet into the About database document and set it

to launch automatically. C. Create a document link to the spreadsheet in the About database

document and set it to launch automatically. D. This cannot be done since only Lotus 1-2-3 spreadsheets can be

used as spreadsheet document links. 5. Elmo wants to create a field on the Product Profile document that

contains a list of users and groups who can edit that type of document. Which field type should he associate with the new field? A. Authors B. Editor C. Names D. Readers 6. Faith’s users have noticed different behavior on a section in a document

depending on who is logged into the database. Some users can see the section and others can’t. This problem happens regardless of whether the application is being used by Notes clients or Web clients and is consistent in that the same users consistently cannot see the section. What feature did Faith most likely use? A. Different access levels for different users B. A controlled access section C. Hide When properties on the section D. A section with encrypted field data

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

614

Appendix A




510 Practice Exam

7. Graham has decided to give his database a robust title, namely, “The

WineMaster Production Customer Reporting Database.” Unfortunately, this title is generating an error! What is the maximum title length for a database? A. 8 characters B. 12 characters C. 32 characters D. 64 characters 8. Heidi wants to override the soft deletion settings in the database she

created by allowing users to click a button to permanently delete certain documents. Which of the following will allow her to do this? A. @HardDeleteDocument. B. Turn off the soft delete property for the database. C. @DeleteDoc. D. None. Once soft deletes are enabled for a database, they cannot be

overridden. 9. Ira’s user ID is contained in a group that has No Access as its privilege

level in the WineMaster database. However, he is listed directly in the ACL with Manager access. What access does he have to the database? A. No Access B. Manager C. Reader D. Depositor 10. Juliette wants all users to be able to read and edit all documents in the

database. What minimum ACL privilege is appropriate? A. Manager B. Editor C. Author D. Reader

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

615

11. Regardless of which client Kevin uses (Notes or Web), he is unable to

retrieve documents that he soft deleted from a database just moments ago. What is the likely cause for the problem given that the database property to enable soft deletes has been turned on? A. A database property setting an alternate database has not been set. B. Soft deletes only work for Notes clients. C. Soft deletes only work for Web clients. D. The database property setting a $Undelete expire time has not

been set. 12. Lissette has Manager access to a database, and she wants Sharon to be

able to modify the replication and settings schedule for a database once it’s in production. What minimum access level does Sharon need to perform this task? A. Manager B. Designer C. Editor D. Author 13. The WineMaster ACL includes only the groups WineTasters,

WineReviewers, and WineMakers. WineTasters has Editor access, WineReviewers has Manager access, and WineMakers has Author access. Malcolm is a member of all the groups. Which access level does Malcolm ultimately have in the WineMaster database? A. Manager B. Editor C. Author D. No Access

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

616

Appendix A




510 Practice Exam

14. Angie needs to choose a field type to display three choices to a user

where they are allowed to pick only one. Which field type is the best choice? A. Text B. Radio button C. Combobox D. Check box 15. Ben’s users have decided that they want to rename the Product Profile

form to Vineyard Products. Ben has written a good deal of code that uses the name Product Profile. What attribute of a Notes form would make this change easy to implement? A. The global search and replace method built into Domino Designer B. Stored forms C. Using numbers in the form name D. A form alias 16. Cheyenne wants to rename the Winery field on the Product Profile

form to the more globally acceptable name of Vineyard. She will rename the field by assigning the value of the Winery field to a new field called Vineyard and then deleting the Winery field. If she makes no change to the Product Profile form in Designer, what effect will it have on existing documents in the database? A. The data items associated with the Vineyard field will not be able

to be viewed with the Product Profile form. B. The Winery data item will stay in the documents, and the Vineyard

data item will be added to the existing documents with a null value. C. Existing documents will be updated and the field renamed

automatically. D. The existing documents will need to be recreated.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

617

17. Dean has added a field to the Vineyard Profile form to recalculate the

phase of the moon each time the document is saved. Which field value type is appropriate for this somewhat odd calculation? A. Editable B. Computed C. Computed For Display D. Computed When Composed 18. Eileen’s Product views contain a column with the numeric ProdCode

field from the documents. She would like the column to display the text “Product #” immediately followed by the ProdCode field. Which of the following column formulas will accomplish this? A. Product #ProdCode B. “Product #” + ProdCode C. “Product #” + “ProdCode” D. “Product #” + @Text(ProdCode) 19. Francesco has added the Products by Region view to his form as an

embedded view. He would like to refine what the embedded view is showing to confine it to only wines in France. How can this be accomplished in Notes? A. Use the Show Single Category embedded view event. B. Set a view property to limit the embedded view. C. Categorize the view by Region. D. Create and embed a new view that shows only the region France.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

618

Appendix A




510 Practice Exam

20. Gidget has added several freestanding buttons to a form that is used in

the Notes client. Unfortunately, the form contains many fields, and users have to scroll down several pages to see the entire document. This means that the buttons are sometimes not visible. What can she do to allow the buttons to be visible at all times? A. Anchor the buttons to the top of the form using an HTML tag. B. Re-create the buttons as form action buttons on the Action Bar. C. Set the pixel location of the freestanding buttons. D. Re-create the buttons as a view action button on the Action Bar. 21. Herb wants to add a field to the Home Page that displays the current

date, but he doesn’t want the date to be stored in the database. What type of field should he use? A. Editable B. Computed C. Computed For Display D. Computed When Composed 22. Ida wants the first column in her view to show the document’s order

position relative to the other documents. For instance, the number 1, then 2, then 3, etc. Which would be the easiest way to code this column value? A. Use the default Simple Function, which is the position number. B. Hard code the number 1 as a formula value. C. Use the special variable Form. D. This cannot be done in a view.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

619

23. Jasper wants to add a column to his view that will combine a field from

the document with a hard-coded text phrase. Which type of column value should he choose? A. Text B. Simple Function C. Field D. Formula 24. Karla is in charge of designing this year’s Opinion Survey form. A key

design feature of the form is that it should not capture the Notes user ID of the person completing the form. What Notes feature will accomplish this? A. Mark the field property “Anonymous” for all fields. B. Mark the form property “Anonymous Form.” C. Give users Depositor access. D. Add the special field $Updated to the form. 25. Lawrence accidentally deleted the Disclaimer subform from the

WineMaster database. The subform was embedded in the Vineyard Profile form. Which of the following will occur when a user opens a document that was created using the Disclaimer subform? A. When the document opens, a Form event will pop up to say

“Hello World!” B. The onLoad event will not allow the document to be opened. C. When the document opens, the user will see an error message

saying that the subform could not be loaded. D. The document will open normally because the subform was

included in the original form, which was not deleted.

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

620

Appendix A




510 Practice Exam

26. Marianne’s editable fields use the Native OS style to allow them to

look like input boxes. However, they seem to all be the same size regardless of the data the user is entering, and the users are complaining that they can’t see all of their data. What can Marianne do to resolve this situation? A. Set the size property to dynamic height. B. Set the size property to fit to window (%). C. Set the style to Notes style. D. Nothing—the Native OS style sets the size to a fixed height and

width, which cannot be overridden. 27. Alexis has hotspot links in one frame that, when clicked, will display

information in a different frame. Setting the target frame for the links is set in which design element’s Properties box? A. Hotspot B. Frameset C. Button D. Target frame 28. Bruce has created a page that contains graphics and links. This page

will be the workhorse for the application. Which type of additional content should he avoid? A. Tables B. Embedded navigators C. Shared image resources D. Fields

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

621

29. Cindy has added a set of four hotspot buttons to a page. She is not

using any Hide When properties on the buttons. In order to guarantee that all four buttons will display on the Web, what should she remember to do? A. Enable the database property Web Access: Use JavaScript When

Generating Pages. B. Enable the Visible property on the buttons. C. Position the buttons in an invisible border table. D. Convert to action buttons since hotspot buttons are not visible on

the Web. 30. Darryl has a request from his users to create a multi-pane way of

showing views and forms on the same screen. Which of the following design elements will help him do this? A. Framesets B. Tables C. Outlines D. Agents 31. Ella wants a graphic with hotspots to launch as soon as her database

is opened. In which design element can she place this graphic and have it open automatically when the database is accessed? A. Navigator B. Form C. Table D. Outline 32. Fritz has created an outline and has clicked the Use Outline button.

What did this do for him? A. Created a blank structure to populate with forms and views B. Generated a blank page C. Generated an outline with entries for existing views and forms D. Created a blank page and embedded the outline in it

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

622

Appendix A




510 Practice Exam

33. Geovanna has coded an agent that will be invoked from a hotspot. She

currently has it coded using the Manually From The Agent List trigger, but the agent is not working when she codes a call to it in her hotspot. Which of the following triggers would fix the problem? A. On Schedule Never B. Manually from the Actions menu C. If documents have been created or modified D. If documents have been pasted 34. Harvey wants his frameset to allow a link clicked in one frame to

display data in a different frame. Which of the following frame properties should he be sure to set for the frame that contains the link that will be clicked? A. Web access B. Frame name C. Value D. Default target frame 35. Ilene wants to add several buttons to her page, but wants to guarantee

that the buttons will appear at the top of the page regardless of whether a Notes client or a Web client is used. What kind of button should she use? A. Freestanding button B. Hotspot button C. JavaScript button D. Action button 36. Jarvis wants to use a Notes link that will jump him to another position

within the same document. Which kind of link should he use? A. Database B. View C. Document D. Anchor

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

623

37. Krystal has used the Windows Paint program to create a bitmap

(BMP) graphic file. She wants to use the BMP in multiple places in her database. What can she do to conserve time and resources when bringing this image into Notes? A. Set the File Preferences to compress the image. B. Copy and paste the image only into design elements that require it. C. Create an image resource for the BMP file. D. Embed the BMP in a table. 38. Leif is coding an agent in Domino Designer. Which of the following

types of coding requires the least amount of programming skill? A. Formula B. Simple action C. LotusScript D. Java 39. Marilyn likes to use rich text fields because users can format the text

with bolding, font changes, and italics. In which of the following design elements are rich text fields invalid? A. Forms B. Pages C. Subforms D. Tables 40. Angelo uses Andy as his nickname at work. The system administrator

has set up an alternate name for him in Notes where Angelo is his primary name and Andy is his alternate name. What formula would a programmer use to retrieve his alternate name in a Names field? A. @UserNameLanguage(1) B. @User(1) C. @UserName(1) D. @UserName(Alternate)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

624

Appendix A




510 Practice Exam

41. Becki wants her view selection formula to include main documents

that contain the phrase “ABC” in the Company field as well as all Response documents and Response to Response documents to the main document. Which of the following formulas will do this? A. SELECT Company = “ABC” & @AllDescendants B. SELECT Company = “ABC” & @AllChildren C. SELECT @Contains( Company ; “ABC”) | @AllDescendants D. SELECT @Contains( Company ; “ABC”) | @AllChildren 42. Chet wants to use the syntax @Command([OpenPage] ; “HomePage”)

in his database. Where can this command be used? A. Action button B. Field default value formula C. URL D. View selection formula 43. Donna has built a calendar view to track the trucks that deliver the

product to the distributors. She has a button on the view that displays it in two-week blocks. Which command did she use? A. @Command([CalendarFormat] ; “2” ) B. @Command([Calendar] ; “2” ) C. @Command([Calendar] ; “14” ) D. @Command([CalendarFormat] ; “14” )

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

Practice Exam

625

44. Eddie has coded two enrollment subforms: one for use from a Web

client and one for internal Notes users. The subforms are named EnrollWeb and EnrollNotes, respectively. Which of the following formulas will include the appropriate subform at runtime? A. @If(@ClientType = “Notes” ; “EnrollWeb” ;

“EnrollNotes” ) B. @If(@ClientType = “Notes” ; “EnrollNotes” ;

“EnrollWeb” ) C. @If(@BrowserInfo = “Notes” ; “EnrollWeb” ;

“EnrollNotes” ) D. @If(@BrowserInfo = “Notes” ; “EnrollNotes” ;

“EnrollWeb” ) 45. Francine wants to set the ServingTemperature field based on the value

in the WineColor field. Which of the following statements correctly sets the temperature for red, white, and blush wines? A. @If(WineColor = “Red” ; “Serve room temperature” ;

WineColor = “White” ; “Serve chilled” ; WineColor = “Blush” ; “Chill”) B. @If(WineColor = “Red” then “Serve room temperature”

else if WineColor = “White” then “Serve chilled” else if WineColor = “Blush” then “Chill”) C. @If(WineColor = “Red” ; “Serve room temperature” ;

WineColor = “White” ; “Serve chilled” ; WineColor = “Blush” ; “Chill” ; “”) D. @If(WineColor = Red ; Serve room temperature ;

WineColor = White ; Serve chilled ; WineColor = Blush ; Chill ; “”)

Copyright ©2001 SYBEX, Inc., Alameda, CA

www.sybex.com

626

Appendix A




510 Practice Exam

46. Gilbert wants to code the formula @If(@Length(@Trim(ProdCode))