WebSession Agent Class

Back in August 2007, Jake Howlett introduced a Web Session class for Domino Agents. I liked it a lot and saw the potential for reducing the amount of time to create web query open, web query save and web agents. I write a lot of web agents and often need to get query string, cookie and even form data. These items were missing from Jake's Web Session class. Also, the Web Session class required the programmer to instantiate the class when you wanted to use it. I thought that if you include the class in your agent you will want to use it. With that in mind, the Initialize function in the script library now instantiates a global web variable. I've added methods to get query string, cookie and form data items. With the advice of a co-worker I also protected the class variables by making them private and adding get methods for each variable. The only variables that I couldn't do this with were the lists that store query, cookie and form data information.

Now it's just as simple as calling the Web Session methods. I don't have to define DocumentContext, a NotesSession or implement and maintain functions to get query string, cookie or form data.

Sub getDoc
	Dim sKey As String

	sKey = web.getQueryString("unid")
	If Len(sKey) = 0 Then
		Call dspError("UNID is required: " & sKey)
		Exit Sub
	End If
	' ...	
End Sub

One of the problems with most functions that get query string data is that they use the Query_String_Decoded field which does not allow for a value to contain an "&" character. Also, they don't support the & entity. A problem that I ran into decoding the value data is that the @URLDecode formula function does not decode "+" characters. I ended up writing the following method to decode a value.

Public Function URLDecode(s As String) As String
	Dim retValue As Variant

	' The back slash "\" character is an escape character in Formula language. Escape "\" characters. The @URLDecode
	' function does not convert "+" characters to space so do it here.
	s = Replace(Replace(s, "+", " "),"\", "\\")
	retValue = Evaluate(|@URLDecode("Domino";"| & s & |")|)
	URLDecode = retValue(0)
End Function

Use of the Query_String field that is still encoded instead of the Query_String_Decoded field allows the use of a custom decoding function to get the value data.

Web Session methods.


Returns the current database As NotesDatabase.


Returns the current agent As NotesAgent.


Returns the DocumentContext As NotesDocument.


Returns the logged in user or server As NotesName.


Returns the path to the current database As String

web.getItemValue(sName As String)

Returns a query string, cookie or form data string that is equal to the passed name As String.

web.getQueryStringValue(sName As String)

Returns the value of the query string item equal to the passed name As String.

web.getQueryString(sName As String)

Returns the value of the query string item equal to the passed name As String.

web.getCookieValue(sName As String)

Used for compatibility with old agents. Returns the value of the cookie equal to the passed name As String.

web.getFormValue(sName As String)

Returns the value of the form item equal to the passed name As String.

web.JSONEncode(s As String)

Returns a string encoded in Javascript format As String.

web.XMLEncode(s As String)

Returns a string encoded for an XML data item As String.

web.URLEncode(s As String)

Returns a URL encoded string As String.

web.URLDecode(s As String) As String

Returns a URL decoded string As String.


Include the following in the Options section of your agent.

Use "WebSession"


Download the four files. Create a LotusScript Library and import the WebSession.lss file. Save the script library as WebSession.

For jsondoc.js, create an shared, scheduled (run never) agent and import the jsondoc.js.lss file into the agent. Save the agent as jsondoc.js. You can review the results of the agent in Firefox. IE will not display the .js file.

Repeat for the jsondoc.json and xmldoc.xml agents.



Gravatar Image1. Posted at 01/01/2008 11:43:48 by Jerry Carter

Hello Tanny,

Nice work. I especially approve of the instatiate on run concept - one I use myself as it makes the most sense given two options. Thanks for sharing!


Gravatar Image2. Posted at 02/22/2008 15:19:35 by Rob

Great stuff Tanny. I just subscribed to your blog after seeing your comments on CodeStore.

I've been coding mine over and over ... well, copy and paste at least. :) I think it's time to put my favorite code in a class of its own. (No pun intended!)

I think you have a typo in the part of this blog entry dealing with the getQueryString. There's an entry for getQueryStringValue with the description string truncated.



Gravatar Image3. Posted at 09/25/2008 12:59:59 by anthony galligani

I like this! For this function: web.getItemValue(sName As String) - when you say form data string do you mean it strips out the innerHTML of the input field?

Since it already does so much, why not add Request_content(0) variables (ie. post variables) to the mix? (I prefer to use post variables sometimes in web agents). There are some functions kicking about that parse these into name value pairs (although I'm sure you could write your own).

Gravatar Image4. Posted at 09/30/2008 22:07:04 by Tanny O'Haley

Hi Anthony,

The getFormValue() method gets data from the Request_content(0) field. The WebSession class has four lists, for query string values, cookie values, posted form values and all values. Use the getItemValue() method to retrieve items from the fourth list. The fourth list is handy if you have an agent that handles query string and form post values that can be the same. Let's say you have a field called "query", using the getItemValue() method allows an application to pass the query value as a posted form item or a query string item without the agent having to check each list.

Add a comment

Discussion for this entry is now closed.