Extracomm Blog

A programmatic way to get/set Out of Office profile in Lotus Notes

Alex Chan  May 7 2015 10:00:00 AM


Thanks to Kevin, he has created a LotusScript class which allows developers to manipulate OOO profile information in your Notes applications easily. This class allows you to:
  • get or set Out-of-Office profile for yourself or on behalf of someone else
  • query other people Out-of-Office status

The class works in conjunction with OOO Manager. So, you need to have OOO Manager in place on one of your Domino server.

Use method GetOOOProfile(username) to get the OOO profile of the user.
Use method SaveOOOProfile(profile) to save the OOO profile after changes.

Below is a sample program to get and set OOO profile for any user.
Option Public
Option Declare
Use "OOOManager_LS"

Sub Initialize
' Create an instance of the OOOManager class for server "Server/ACME"
Dim ooomgr As New OOOManager("Server/ACME")                
Dim profile As OOOProfile

' Get an instance of the OOOProfile class for user "John Doe/ACME"
Set profile = ooomgr.GetOOOProfile("John Doe/ACME")        

If Not (profile Is Nothing) Then                ' OOO Profile found
' Modify the properties of the OOOProfile
Set profile.LeavingDate = New NotesDateTime("Today") ' Set Leaving Date  
Set profile.ReturnDate = New NotesDateTime("Tomorrow") ' Set Return Date
profile.SpecifyHours = False ' Do not display the time component for the leaving date and return date  
profile.AppendReturnDateToSubject = True ' Append return date to the subject line          
profile.DateFormat = OOO_DATETIME_FULL ' Display date in full date format                
profile.AdditionalBodyText = "If you need immediate assistance, please contact:" _
& Chr(13) & "For Sales: sales@extracomm.com" _
& Chr(13) & "For Support: support@extracomm.com"
profile.ExcludeInternetAddresses = False
profile.Enable = True                ' Enable OOO notification

If ooomgr.SaveOOOProfile(profile) Then  ' OOOProfile has been saved successfully
' Display the latest properties after saving the OOOProfile
Messagebox "Save result: " & ooomgr.ReturnMsg & Chr(13) &  _
"Enable: " & profile.Enable & Chr(13) &  _
"Leaving date: " & profile.LeavingDate.LocalTime & Chr(13) &  _
"Return date: " & profile.ReturnDate.LocalTime & Chr(13) & _
"Specify hours: " & profile.SpecifyHours & Chr(13) & _
"Subject: " & profile.ComputedSubject & Chr(13) & _
"Body: " & profile.ComputedBody & Chr(13) & _
"Additional body text: " & profile.AdditionalBodyText & Chr(13) & _
"Append return date to subject: " & profile.AppendReturnDateToSubject & Chr(13) & _
"Date format: " & profile.DateFormat & Chr(13) & _
"OOO type: " & profile.OOOType & Chr(13) & _
"Exclude Internet addresses: " & profile.ExcludeInternetAddresses
Else
' Display the error code and error message if necessary
Messagebox "Save Error " & ooomgr.ReturnCode & ": " & ooomgr.ReturnMsg
End If

Else
' Display the error code and error message if necessary
Messagebox "Error " & ooomgr.ReturnCode & ": " & ooomgr.ReturnMsg
End If
End Sub



To retrieve other people OOO status, you can use methods:
  • GetOOOStatus(username_or_groupname As String)
  • GetOOOStatusXML(username  As String)

Below is a sample program how you can retrieve other people OOO status.
Option Public
Option Declare
Use "OOOManager_LS"
Sub Initialize
' Create an instance of the OOOManager class for server "Server/ACME"
Dim ooomgr As New OOOManager("Server/ACME")                
Dim resultArray As Variant
Dim paramArray As Variant

' Get the OOO status for user "John Doe/ACME" as a string array
resultArray = ooomgr.GetOOOStatus("John Doe/ACME")        

If resultArray(0) <> "" Then        ' OOO status has been successfully retrieved
Forall s In resultArray
paramArray = Split(s, ooomgr.Delimiter  ' Use the Split function to separate each delimited string
' Display the attributes of the OOO entry
Messagebox ("IsValid: " & paramArray(0) & Chr(13) &  _
"Username: " & paramArray(1) & Chr(13) &  _
"ErrorMsg: " & paramArray(2) & Chr(13) &  _
"OOOEnable: " & paramArray(3) & Chr(13) &  _
"LeavingDate: " & paramArray(4) & Chr(13) &  _
"ReturnDate: " & paramArray(5) & Chr(13) &  _
"SpecifyHours: " & paramArray(6))
End Forall
Else
' Display the error code and error message if necessary
Messagebox "Error " & ooomgr.ReturnCode & ": " & ooomgr.ReturnMsg
End If
End Sub











Script Library and sample code database
Image:A programmatic way to get/set Out of Office profile in Lotus Notes
OOOManagerLib.nsf  (updated on Jun 4 2015)


Class OOOManager

Properties:
Name Remark
String ServerName
String Delimiter Defaults to "%~%".
Integer ReturnCode Read-only.
Defaults to 0.
String ReturnMsg Read-only.
Defaults to "".




Methods:
Name Remark
Sub New (servername As String) Return an OOOManager instance for a specific server.
Function GetOOOProfile(username As String) As OOOProfile Return an OOOProfile instance for a specific user.

If error occurs, this function will return Nothing, while the ReturnCode property and ReturnMsg property will contain the corresponding error code and error message respectively.
Function SaveOOOProfile(profile As OOOProfile) As Boolean Return True if the OOO profile of a specific user has been enabled, disabled or updated successfully. In addition, the following return code and return message will be set to the ReturnCode property and ReturnMsg property respectively:


ReturnCode ReturnMsg
OOO_PROFILE_SAVE_ENABLED_CODE = 1001 OOO_PROFILE_SAVE_ENABLED_MSG = "Out of Office notification has been enabled"
OOO_PROFILE_SAVE_DISABLED_CODE = 1002 OOO_PROFILE_SAVE_DISABLED_MSG = "Out of Office notification has been disabled"
OOO_PROFILE_SAVE_UPDATED_CODE = 1003 OOO_PROFILE_SAVE_UPDATED_MSG = "Out of Office profile has been updated"



If error occurs, this function will return False, while the ReturnCode property and ReturnMsg property will contain the corresponding error code and error message respectively.
Function GetOOOStatus(username_or_groupname As String) As Variant Return the OOO status of a specific user or user group as a string array. Each element in the array is a delimited string, which contains the attribute values of an OOO entry for a user. You can use the LotusScript Split function to separate the delimited string into a string array of attribute values with the following structure:


Element Position Description
0
IsValid:   indicate whether OOO entry for a user has been retrieved successfully or not.

"1" means OOO entry has been retrieved successfully.
"0" means OOO entry cannot be retrieved.
1
Username:   the name of the user.
2
ErrorMsg:  indicate the reason why an OOO entry cannot be retrieved.
3
OOOEnable:   indicate whether OOO notification for a user has been enabled or not.

"1" means OOO notification has been enabled.
"0" means OOO notification has not been enabled.
4
LeavingDate:   the leaving date in case OOO notification has been enabled.
5
ReturnDate:   the return date in case OOO notification has been enabled.
6
SpecifyHours:   indicate whether the leaving date and return date will include the time component.

"1" means the leaving date and return date will include the time component.
"0" means the leaving date and return date will be date only.



If error occurs, this function will return an array with a single empty string element, while the ReturnCode property and ReturnMsg property will contain the corresponding error code and error message respectively.
Function GetOOOStatusXML(username  As String) As String The purpose of this function is similar to the GetOOOStatus function, but it will return an XML string instead of a string array. The resulting XML string looks like this:

Image:A programmatic way to get/set Out of Office profile in Lotus Notes

If error occurs, this function will return an empty string, while the ReturnCode property and ReturnMsg property will contain the corresponding error code and error message respectively.



Class OOOProfile

Properties:
Name Remark
String ServerName Read-only.
String Username Read-only.
Boolean Enable
DateTime LeavingDate
DateTime ReturnDate
Boolean SpecifyHours
String Subject
String ComputedSubject Read-only.
The resulting subject line to be displayed in the profile.
String ComputedBody Read-only.
The resulting body line to be displayed in the profile.
String AdditionalBodyText
Boolean AppendReturnDateToSubject
String DateFormat Possible values:
OOO_DATETIME_DEFAULT = "DEFAULT"
OOO_DATETIME_SHORT = "SHORT"
OOO_DATETIME_MEDIUM = "MEDIUM"
OOO_DATETIME_LONG = "LONG"
OOO_DATETIME_FULL = "FULL"
OOO_DATETIME_PATTERN1 = "PATTERN1"     (i.e. DD/MM/YYYY)
OOO_DATETIME_PATTERN2 = "PATTERN2"     (i.e. MM/DD/YYYY)
OOO_DATETIME_PATTERN3 = "PATTERN3"     (i.e. YYYY/MM/DD)
OOO_DATETIME_PATTERN4 = "PATTERN4"     (i.e. DD MMM, YYYY)
OOO_DATETIME_PATTERN5 = "PATTERN5"     (i.e. MMM DD, YYYY)
OOO_DATETIME_PATTERN6 = "PATTERN6"     (i.e. day, DD MMMM, YYYY)
OOO_DATETIME_PATTERN7 = "PATTERN7"     (i.e. day, MMMM DD, YYYY)
String OOOType Read-only.
OOO_TYPE_AGENT = "AGENT"
OOO_TYPE_SERVICE = "SERVICE"
Boolean ExcludeInternetAddresses



Methods:
Name Remark
Sub New(servername As String, username As String) Return an OOOProfile instance for a specific user.

Raise errors under some conditions.
Sub Reset() Reset the property values of the current OOOProfile instance to the ones previously retrieved or saved.
Function Save() As Integer Possible return values:
OOO_PROFILE_SAVE_ENABLED_CODE = 1001
OOO_PROFILE_SAVE_DISABLED_CODE = 1002
OOO_PROFILE_SAVE_UPDATED_CODE = 1003

Raise errors under some conditions.