Creating LotusScript agents

This section assumes that you are familiar with scripting LotusScript agents. The purpose of this section is to highlight aspects of the script that are specific to working with agtgdmno. It covers:

Inputs given to the agent by agtgdmno
Outputs given by the agent to agtgdmno

Once the scripts are written they must be added as to the agent database as Shared Code > Agents . See Lotus Domino Server for a list of supported operations. Note that the List and UserAttributes operations are performed by agtgdmno ; agents do not need to be created for these operations. The scripts for two sample agents (reset.ls and verify.ls) are provided in the samples\* directory.

If you cannot find the sample file, try re-running setup to modify your installation. Sample files are automatically installed with complete (typical) installations. You can select them in custom installations.

For more information on LotusScript refer to the Lotus Domino Designer documentation specific to your version.

Inputs given to the LotusScript agent by agtgdmno

A subset of the following inputs are loaded into the agent database when agtgdmno runs a LotusScript agent:

UserId
FullName
AccountId
ShortId
NewPassword
OldPassword
ModelId
GroupId
GroupName
CreationAttributes
UserAttributes

Depending on the operation, some or all of the inputs are loaded. You can use the following LotusScript segment in your agent script to extract these inputs.

REM First thing to do is find arguments for the operation
Dim session As New NotesSession
Dim agentDoc As NotesDocument

REM Parameters
Dim userId As String
Dim accountId As String
Dim shortId As String
Dim newPassword As String
Dim oldPassword As String
Dim modelId As String
Dim groupId As String
Dim groupName As String
Dim creationAttributes As Variant
Dim userAttributes As Variant

REM Get the parameters from the operation document
Set agentDoc = session.DocumentContext
userId = agentDoc.GetItemValue( "UserId" )(0)
accountId = agentDoc.GetItemValue( "AccountId" )(0)
shortId = agentDoc.GetItemValue( "ShortId" )(0)
newPassword = agentDoc.GetItemValue( "NewPassword" )(0)
oldPassword = agentDoc.GetItemValue( "OldPassword" )(0)
modelId = agentDoc.GetItemValue( "ModelId" )(0)
groupId = agentDoc.GetItemValue( "GroupId" )(0)
groupName = agentDoc.GetItemValue( "GroupName" )(0)
creationAttributes = agentDoc.GetItemValue( "CreationAttributes" )
userAttributes = agentDoc.GetItemValue( "UserAttributes" )

Note that both CreationAttributes and UserAttributes are stored as property lists. A property list has the following form:

(Attribute_Name_1 Attribute_Value_1 Attribute_Name_2 Attribute_Value_2 ....
 Attribute_Name_N Attribute_Value_N)

Outputs given by the LotusScript agent to agtgdmno

This section details the fields that the LotusScript agents must use to return information to agtgdmno .

ReturnCode

LotusScript agents must always set the ReturnCode field; an error is triggered by agtgdmno if it is not set. This field tells agtgdmno if the agent successfully completed its operation. ReturnCode can be set to:

0 LotusScript agent was successful

1 LotusScript agent was unable perform its operation To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ReturnCode", "<value>" )

ErrorMsg

You can use the ErrorMsg field to inform agtgdmno of any error conditions encountered by the LotusScript agent. To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ErrorMsg", "<error message>" )

ReturnValue

You must set the ReturnValue field for the following operations:

ispwexpired
isenabled
islocked
isacctexpired

ReturnValue is set to the either true or false. To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ReturnValue", "<true|false>" )

ReturnAccountId

You must set the ReturnAccountId field for the following operations:

create
rename
movecontext

ReturnAccountId is set to the new account ID for the user. To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ReturnAccountId", "<account ID>" )

ReturnShortId

You must set the ReturnShortId field for the following operations:

create
rename
movecontext

ReturnShortId is set to the new short ID for the user. To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ReturnShortId", "<short ID>" )

ReturnAttributes

You must set the ReturnAttributes field for the following operations:

create
update

ReturnAttributes is set to the new attributes for the user. To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ReturnAttributes", <attributes> )

ReturnAttributes is stored as property list. A property list has the following form:

(Attribute_Name_1 Attribute_Value_1 Attribute_Name_2 Attribute_Value_2 ....
 Attribute_Name_N Attribute_Value_N)

ReturnGroups

You must set the ReturnGroups field for the following operations:

create
update

ReturnGroups is set to the new attributes for the user. To set this field, use the following syntax:

Call agentDoc.ReplaceItemValue( "ReturnGroups", <groups> )

ReturnGroups is stored as a property list. A property list has the following form:

(Attribute_Name_1 Attribute_Value_1 Attribute_Name_2 Attribute_Value_2 ....
 Attribute_Name_N Attribute_Value_N)

Saving field values to the agent document

After all the return values have been set, you must include the following LotusScript line. This saves the values to the agent document:

Call agentDoc.Save(True, True)

In this section: