Home
HCL Domino Designer Basic User Guide and Reference
This guide provides information on using HCL Domino Designer and programming language reference information.
Application Design
Welcome to the Application Design section of Domino® Designer Help.
Adding automation to applications
Automation in an application speeds up repetitive tasks, handles workflow, updates information, performs calculations, runs programs, and checks for errors.
Testing agents

HCL Domino Designer Basic User Guide and Reference
This guide provides information on using HCL Domino Designer and programming language reference information.
- What's new in Domino Designer 12?
  The following features are new for developers in HCL Domino® Designer 12.
- Accessibility and keyboard shortcuts
  Accessibility features assist users who have a disability, such as restricted mobility or limited vision, to use information technology content successfully.
- Application Design
  Welcome to the Application Design section of Domino® Designer Help.
  - Introduction to Domino® Designer
    Welcome to Domino® Designer. Domino Designer is an integrated application development environment that lets developers and Web site designers create, manage, and deploy secure, interactive applications.
  - Planning an application
    Before you begin any design work, create a plan for how users will access and use your application. At the minimum, your application plan should address these questions:
  - Creating an application
    All Domino® applications begin with a Domino database. Domino databases are the containers for your application. Databases hold the data, logic, and design elements for your application. Your Domino application can be made up of one or more Domino databases.
  - Designing pages
    Pages and forms are similar in certain ways. A page is a database design element that displays information. Pages can be used anywhere in your application that you have text, graphics, or an embedded control, such as an outline, to present to the user. A page or form can contain the following:
  - Designing forms
    Forms, like pages, display information. Everything that can be done with a page can be done with a form. What sets forms apart from pages is that forms can be used to collect information. A form provides the structure for creating and displaying documents, and documents are the design elements that store data in the database. When a user fills out the information in a form and saves it, the information is saved as a document. When a user opens the document, the document uses the form as a template to provide the structure for displaying the data.
  - Designing fields
    A field is the part of an application that collects data. You create fields on forms, subforms, or in layout regions. Each field stores a single type of information. A field's field type defines the kind of information a field accepts, such as text, numbers, dates, or names. When a user, either in a Notes® client or a Web browser, creates a form, fills out the information in the fields, and saves the form, the data in the fields is stored in an individual document. The contents of the fields can then be displayed in documents and views or can be retrieved for use in formulas. A field can be used on a single form, or you can create shared fields for use in multiple forms in a database.
  - Designing framesets
    A frameset is a collection of frames and can add structure to your Web site or Notes® database. A frame is one section, or pane, of the larger frameset window and is independently scrollable.
  - Designing views
  - Designing navigation for an application
    You can use the following navigational tools in your application:
  - Adding automation to applications
    Automation in an application speeds up repetitive tasks, handles workflow, updates information, performs calculations, runs programs, and checks for errors.
    - Actions
    - Preferstrings property (NotesHTTPRequest - LotusScript)
      Controls the format used for the output of international characters.
    - Agents
      Agents are stand-alone programs that perform a specific task in one or more databases. Agents are the most flexible type of automation because they:
    - Events
      When users work in Domino® design elements, Domino tracks their operations as events (for example, opening a database, opening a view, opening a document). You can attach programming tasks to these events.
    - Creating a form, subform, page, or view action
    - Action bar
    - Creating and inserting shared actions
    - Creating a button
    - Creating a text pop-up
    - Creating a formula pop-up
    - Creating an action hotspot
    - Creating a program for an event
    - Creating an agent
    - Examples of agents to run before Web users open or save documents
      To perform error checking, field validation, and other processing before Web users open or save documents, create a shared agent that runs manually. Then write a formula that uses @Command([RunAgent]) or @Command([ToolsRunMacro]) to run the agent and attach it to the WebQueryOpen or WebQuerySave form events. This simulates the LotusScript® QueryOpen and QuerySave form events that aren't supported on the Web.
    - Setting up agent security using the Security tab
      Beginning with Domino® Designer 6, you can set up basic security for an agent by using the Security tab of the Agent Properties box. This tab contains the following options:
    - Security for agents on servers and the Web
    - Troubleshooting agents
      You can experience problems running agents at several points during agent development, deployment, and implementation. Try the following to help diagnose any problems.
    - Testing agents
    - Profiling agents and Web services
      Calls to Domino® Objects in agents or Web services written in LotusScript® or Java™ can be monitored and their elapsed times reported.
    - Viewing the agent log
    - Notes® server console commands
      These server console commands support agent debugging:
    - Agent Manager debugging information
      You can specify that the Agent Manager record debugging information in these ways:
    - NotesLog Class
      Use the NotesLog class in LotusScript® and in Java™ agents that run in the background. Add the NotesLog class to your agent code to record run-time information. It is particularly helpful for capturing variable values, error handling, and verifying code logic. By default, the NotesLog class records information to the Agent Log. When you set up items you want recorded, make sure you don't exceed the Agent Log limit.
    - Simple actions for automation
      Use the following simple actions with shared and unshared actions, buttons, action hotspots, picture hotspots, and agents. To access a list of simple actions, select Simple actions from the Run pull-down list and click Add Action.
    - Using LotusScript® for automation
      Use LotusScript® for shared and unshared actions, buttons, action hotspots, picture hotspots, script libraries, events, and agents. LotusScript can be used to access data in Notes® databases and in external applications. For example, you can use LotusScript to change a value in one document based on values in other documents or modify database ACL lists.
    - Restricted LotusScript® and Java™ agent operations
      Note that restricted operations are available only to users with unrestricted access; restricted operations are not available to users with restricted access.
    - Formulas for automation
      Use formulas for shared and unshared actions, buttons, formula pop-ups, hotspots, events, specific infoboxes, and agents.
    - JavaScript™ for automation
      Use JavaScript™ for shared and unshared actions, buttons, action hotspots, picture hotspots, script libraries, and events. JavaScript Version 1.3 is currently supported.
    - Table of supported JavaScript™ objects for automated components
      This table lists the JavaScript™ objects that are available for automated components and which browsers support the event. This table assumes you are running the Notes® browser, Internet Explorer 5.0 or later.
    - Actions and agents names
      The names you give to manually-run agents appear as choices in the Actions menu. The names you give to form actions and view actions appear as choices in the Actions menu and on the action bar. The names are case sensitive and can be any combination of characters, including letters, numbers, spaces, and punctuation.
    - Hiding automated components
      When you create most automated components, you can hide them under varying conditions. Use the Hide When tab located on many Properties boxes to specify when to hide it.
  - Developing applications using third-party tools and WebDAV
    As you are developing an application, you may want to supplement the tools provided with Domino® Designer with tools of your own choosing. For example, you may have a favorite graphics editor you use to design images for your application, or you may have a favorite HTML editor that you want to use to design pages. You launch and use third-party tools from within Designer.
  - Connecting to enterprise data
    Incorporating back-end data into everyday business processes maximizes the value of a Domino® Designer application. Designer includes a range of technologies for the security and control of business processes, forms routing, and approvals management. With enterprise integration technologies, you can incorporate traditionally difficult-to-reach data into your business applications.
  - Including Java™ applets in applications
    Applets are self-contained Java™ programs that can run in your Domino® application. Java applets are often used to add animation to Web applications. Although Java applets are mostly used for Web applications, you can also include them in the following elements of a Domino application:
  - Including Java™ servlets in Web applications
    A servlet is a Java™ program that is run by the Domino® Web server in response to a browser request. Servlets provide a convenient way to add powerful functionality to your Web application. In some ways, servlets act like CGI programs, but they are more tightly integrated with the server and can take advantage of special Java classes. For example, a servlet may connect to a relational database or enterprise system and get data in response to a Web browser request.
  - Including XML in Designer applications
    Extensible Markup Language (XML) is a standard for creating markup languages that describe the structure and meaning of data in a document. XML separates the content of a document from its presentation and provides a common format for transferring data across the World Wide Web (WWW) or company intranet. The result is a technology that makes data available regardless of the proprietary systems involved.
  - Including OLE objects in applications
    Using Object Linking and Embedding (OLE) and OLE tools lets you extend the capability of Domino® Designer. OLE technology lets you integrate data from other applications, such as spreadsheets, graphics tools, and other data sources, into your application.
  - Creating a workflow application
    Workflow applications let you automate tasks. These tasks most often involve automatically sending mail messages or automatically routing documents, such as tracking orders and project plans to be reviewed. All projects need one or more people to complete a series of tasks and can benefit from workflow applications because they guide the project through these tasks automatically. Workflow applications reduce overhead and errors, speed processes, and track the status of a project. For example, a workflow application might automatically send a document in a publishing company from writer to editor to proofreader to production. At each stage, an individual is responsible for specific tasks related to that document. Once the task is complete, the workflow application ensures that the individuals responsible for the next task are notified and receive the data they need to execute their part of the project.
  - Domino® Designer templates
    The templates described in the following table are available with Domino® Designer and are specifically intended for use by application developers.
  - Importing to and exporting from views
  - Developing applications using MAPI
    Domino® Designer Release 6 and later supports the messaging application program interface (MAPI), which allows mail integration between Domino and a MAPI-compliant messaging application, such as Microsoft™ Outlook, Microsoft Office applications, or user-written C++ programs.
  - Features to avoid using in Web applications
    Developers creating applications specifically for the Web, or for the dual purpose of serving Notes® and Web clients, should review the following tables for features that are not supported on the Web.
  - URL commands for Web applications
    You have a variety of options for programming a Web site. You can directly manipulate objects such as documents or views in an application using Domino® URL commands. Adding Domino URL commands as HTML in forms gives users shortcuts for navigating databases and performing other tasks quickly.
- Application Management
  Welcome to the Application Management section of Domino® Designer Help.
- Domino® Query Language
  Domino® Query Language (DQL) is a facility running on a Domino server that provides a terse, shorthand syntax for finding documents. It supports a wide variety and complexity of search terms. It leverages existing design elements, avoiding the need to write detailed code to access them. DQL consolidates all methods in Domino for searching document contents.
- Composite Applications - Design and Management
  Composite applications are a key element in a service-oriented architecture (SOA) and contextual collaboration strategy. The ability to create and edit composite applications lets you easily integrate different types of components and technologies.
- DB2® Access views
  Domino® Designer includes two types of design elements to assist you in managing data contained in DB2® enabled Notes® databases:
- Programming Overview and User Interface
  This section contains general guidelines and examples that show where to use Java, LotusScript, and the formula language.
- Formula Language
  This section documents the formula language.
- LotusScript® Language
  Welcome to the LotusScript® Language section of Domino® Designer Help.
- LotusScript/COM/OLE Classes
- Java/CORBA Classes
  This section documents the Java/CORBA classes.
- Connectors
  Connectors provide native access to a wide variety of DBMS products, ODBC, the platform File system, Enterprise Resource Planning systems, and Transaction Processing systems.
- Javadoc™ for Domino® Designer related APIs
  As part of providing additional Java™ reference documentation, Domino® Designer ships with a help plugin that contains Javadoc™ for additional Domino Designer related APIs.

Testing agents

About this task

You can test an agent in the following ways:

For agents that do not call other agents, use the Test menu command.
For agents that use LotusScript®, use the LotusScript® debugger.
For more complicated agents, create a test copy of the database you can work with before you work with the original database.

To use the Test menu command

Procedure

Select the agent and choose Agents - Test.
Read the Agent Log and check:
- How many documents would be processed (for formula and simple action agents)
- What action would be taken if the agent were actually run
If necessary, make corrections and run the test again.

To use the LotusScript® debugger

Procedure

Choose Tools - Debug LotusScript®.
Run the agent and the LotusScript® debugger appears. You can then review each step as the agent runs.
You can also use message boxes and print statements.

To create a test database

About this task

You may wish to make a test copy of an existing database before working with the actual database.

For agents that have multiple steps or complex tasks, split the process into several smaller tasks and create an agent for each. Test and fix each smaller agent first. When everything is working correctly, combine the agents into one. Then test the agent again.

Note: Java™ agents have a console tool to which agents can print messages. In Domino® Designer, choose Tools - Show Java™ Debug Console. In addition, you can use the remote debugging tool (Tools - Remote Debugging), which allows remote debugging of the LotusScript® in an agent script and allows the monitoring of the execution of Java™ agents.

Procedure

Choose File - Application - New Copy to make a test copy of the database, with documents.

If the agent works on mailed documents, the test database must be on a server, and a Mail-in Database document must exist in the Address Book.
Create test documents:
- If the agent works on mailed documents, mail a few documents to the test database.
- If the agent works on pasted documents, paste a few documents into the test database.
Optional: Create a debug document to write values to.
Run the agent.
Use other available debugging tools to catch errors and make corrections.
Rerun the agent until it is working correctly.
Copy the tested agent to the live database.