1. Purpose of this PHP application
2. How it works
3. Configuration of PHP files
4. Lotus Domino configuration and LotusScript agent

Purpose of this PHP application
This application provides GUI to Lotus Domino mail database. It allows user to view Inbox, Sent and Drafts views. User can also create and send new emails, save new emails as draft, edit and delete existing emails. In the views user can see 100 first documents, viewing more documents or navigating to next documents set is not supported yet.
Same PHP code can with some adjustments be used to access other databases than mail.


How it works
These are the steps application takes to show Inbox view:

1. Obtain session cookie from Domino server or use previously obtained cookie.
If the cookie already exists (which can happen if the user has already logged in), check if that cookie is still valid and if it is go directly to the requested view.

2. Determine if Domino session cookie is still valid
a) In case the session cookie exists, but has expired on Domino server, any request from our application will generate the Domino login screen. The PHP application recognises that Domino server is requesting user login and presents it's own login screen to the user.
b) In case Domino session cookie does not exist, application sends a request to Domino server to get the XML view and if the response is login form, shows login screen to the user, otherwise it processes the view and presents it in HTML form.

3. Ask user for his Domino username and password
User is presented with a login screen and types his Domino username and password there.

4. Send login request
Application sends a request to the specified Domino database ($url_login) using "?Login" URL command.
POST http://server.com/db.nsf?Login
PAYLOAD: username=myname&password=password

Note: We could also use GET command for loggin in, but we do not want the username and password to be displayed in the server logs:
GET http://server.com/db.nsf?Login& username=myname&password=password

5. Process response from login request
The result is either a login screen or the default first page in the database. If the result is not a login screen, we get the session cookie from it ("Set-Cookie" header) and discard the rest of the response.

6. Request the Inbox view
We send request to fetch the Inbox view and append Cookie header with previously received cookie value to that outgoing request. The syntaxt of the request is following:
POST http://server.com/db.nsf/($Inbox)?ReadViewEntries&Count=100
HEADER:
Cookie: DomAuthSessId=A1234B326353C35353D32563; path=/;

7. Read design of the view to map columns
To determine what are the names of the columns in the fetched XML view, we get the design of the view with URL command ?ReadDesign: http://server.com/db.nsf/($Inbox)?ReadDesign.
Without this step we would need to point out columns by it's position in the view (1,2,3) instead of using column titles (From, Date, Subject)

8. Process XML from view design and view documents
We use XML parser to find all mail documents in the view and get certain fields from them. Documents in XML source are separated by VIEWENTRY element and fields are separated by ENTRYDATA element.

9. Output HTML back to the web browser
We create a HTML table and show one mail document per table row.


Configuration

1. URL to be used for logging in
$url_login = "http://mydominoserver7.com/mail/jdoe.nsf";
URL path to obtain session cookie. Can be any database which allows user to open it. This database is used only for initial login (?Login URL command) and is not used for anything else. It can be names.nsf or a dummy database.
ACL in the database:
Default: Depositor (or higher)
Anonymous: No Access
Instead of Default entry, you can specify separate access level for each individual name.

2. URL to Domino database which contains our LotusScript agent
$url_agentdb = "http://mydominoserver7.com/mail/jdoe.nsf";
URL to the database which contains LotusScript agent. Can be any database which a logged in user can open.
Read more info in LotusScript Agent section for purpose of the agent.
ACL in the database:
Default: Author (or higher)
Anonymous: No Access
Instead of Default entry, you can specify separate access level for each individual name.

3. Name of the agent used for taking actions on individual documents
$agent_name="ProcessDocWebAction";
The name of the agent can be changed if needed. The agent must be located in the database specified in $url_agentdb variable.

4. Computed path to mail database of the current user
$url_maildb = "http://server.com/" . $_SESSION["MailDB"];
$_SESSION["MailDB"] is set from the value received from the LotusScript agent. The agent finds user's document in the server NAB and reads MailFile field value from that document. So the resulting variable is: "http://server.com/mail/jdoe.nsf" . This value is fetched only once and then saved in user's PHP session container.
Note: We *can* get same value by parsing ($Users) view in names.nsf on server instead of using agent for this, but we use agent for other things anyway, so why not include even this functionality.

Lotus Domino configuration and LotusScript agent

LotusScript agent specified in $agent_name variable and by default called "ProcessDocWebAction" is used for:
- getting path to user's mail database
- creating new mail documents and sending them to recepient
- getting fields from individual documents thus simulating opening the document
- saving new documents as draft
- saving existing individual documents after editing them

Agent can be placed in any database which a logged in user can open. Same agent can be used for all users.
ACL of the agent's database:
Default: Author (or higher)
Anonymous: No Access
Instead of Default entry, you can specify separate access level for each individual name.

For testing purposes you might want to disable sending mails and just save them in the "Sent" view. In this case just comment out the Call maildoc.Send(False) code line.

Important: agent must be set to "Run as web user". This property ensures that person who triggers the agent can not access unauthorised information in Domino databases even if that person has full control over PHP server and PHP application.