Session Object Model Reference
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
The Session object is a run-time object made available by the workflow engine. The Session object makes it possible to access workflow information and application data at run time.
All Session object properties can be set using the Session.Item.Property syntax.
The Session object provides the following properties and methods:
| Properties | Description |
|---|---|
| Application Property | Provides application properties. |
| AppConnection Property | Returns a Microsoft® ActiveX® Data Objects (ADO) connection to the workflow-enabled database. |
| Item Property | Returns the current properties of an item. |
| OriginalItem Property | Returns the original values of the properties of the item. |
| RowPermissions Property | Returns the list of roles that have permissions to access the current item. |
| User Property | Returns the Microsoft® Windows® SAM Account Name of the current user. |
| UserRoles Property | Returns all the roles of which a specified user is a member. |
| Methods | Description |
|---|---|
| IsMember()Property | Checks whether the current user is member of a specific role. |
| UserList Property | Returns user information from the user directory. |
Application Property
Access: Read only
Data type: ADODB.Recordset
Default: Application registration information
Range: N/A
Returns a single row recordset with all the properties of the current application, as registered in the modSystem database. The schema of the recordset matches the schema of the modApplications table in the modSystem database.
Example
Dim App, WebUrl
Set App = Session.Application
WebUrl = App("WebServer") & "/" & App("Folder")
AppConnection Property
Access: Read only
Data type: ADODB.Connection
Default: Connection to the workflow-enabled database
Range: N/A
Provides an ADO connection to the workflow-enabled database. The connection is created the first time the property is used in the script code. For trigger-generated events, the connection is bound to the same transaction in which the trigger is being executed.
IsMember Method
IsMember( Role As String )
Data type: Boolean
| Parameter | In/Out | Description |
|---|---|---|
| Role | In | Name of a database role. |
Checks whether the current Windows user, as identified by the user's SAM Account Name, is a member of the specified database role. Returns True if the user is a role member; otherwise, False. This method uses the information that relates users and roles stored in the modUserRoles table.
Item Property
Access: Read/Write
Data type: ADODB.Recordset
Default: Item recordset
Range: N/A
Returns a one-row recordset containing all the current values of the item that triggered the workflow event. All values in the Item recordset are updateable. After changes are made to the recordset, Session.Item.UpdateBatch method must be called to commit the updates to the database.
Updates in Script and the Potential for Infinite Recursion
The Workflow Designer for SQL Server prevents infinite recursion during updates made to an Item column by means of a workflow event. The potential for recursion exists, because the conditions for transitions are evaluated independently of each other. Updates to an item can cause a variety of conditions that could loop the item through the states infinitely if the loop is not interrupted.
If the workflow engine is invoked to perform the same transition on the same item twice within the context of a single transaction, the following events occur:
- The OnExit event for the state fires a second time
- The OnChange event for the state fires a second time
After the item enters the next state, no further conditions are evaluated; therefore, no further script is executed, and the item remains in that state.
For example, you can specify a condition that triggers script which forces items coming into state 1 to transition to state 2. In state 2, you can specify a condition with script that forces an item into state 3. In state 3, you can specify a condition with script that forces an item to state 1. Each condition is evaluated independently of the other conditions on other states. If an item enters the workflow that meets the conditions for transition in each state, the second time it moves from state 1 to state 2 within the context of the current transaction, the script for state 2 is executed. After the script for the OnEnter event for state 2 is executed, which moves the item to state 3, the workflow engine stops executing script, and the item remains in state 3 despite meeting conditions to transition again.
The following event sequence occurs if an item meets all of the transition conditions in the example:
State 1 OnCreate
State 1 OnEnter, which contains code to go to state 2
State 1 OnExit
OnChange State 1 to State 2
State 2 OnEnter, which contains code to go to state 3
State 2 OnExit
OnChange state 2 to state 3
State 3 OnEnter, which contains code to go to state 1
State 3 OnExit
OnChange state 3 to state 1
State 1 OnEnter, which contains code to go to state 2 and which occurred once before, so the Workflow engines stops after the state 2 OnEnter script is executed:
State 1 OnExit
OnChange state 1 to state 2
State 2 OnEnter, which contains code to go to state 3
The item stays in state 3, but the code for State 3 OnEnter is not executed, and the loop ends.
OriginalItem Property
Access: Read only
Data type: ADODB.Recordset
Default: Original Item recordset
Range: N/A
Returns a one-row recordset with all the original values of the item that has triggered the workflow event. The original values show the changes that are being made to various properties of the item. They can be used to filter acceptable changes to non-workflow columns, to verify row-level rules for the current item, and so on.
There is a performance cost involved in providing the original values in the Session object. The Workflow Designer provides a way to control whether or not those values for each table should be provided at run time (for details, see The Workflow Engine Model). It is recommended you enable the OriginalItem recordset only if the workflow event script requires those values.
RowPermissions Property
Access: Read only
Data type: ADODB.Recordset
Default: Row permissions recordset
Range: N/A
Returns a recordset with all the roles that have access to the current row (Item) and the permissions granted to each role. It can be used to find out the permissions of the current user on the Issue properties and enforce those permissions in the event script code.
User Property
Access: Read only
Data type: String
Default: SAM Account Name
Range: N/A
Returns the SAM Account Name (for example, "domain\user") of the current user. The user name can be stored in the row, for instance in a CreatedBy or ModifiedBy field. In addition, it can be used to filter the modUserList table to locate user-related information such as the manager or direct reports. (For more information, see the UserList method.)
UserList Method
UserList( Filter As String )
Data type: ADODB.Recordset
| Parameter | In/Out | Description |
|---|---|---|
| Filter | In | (Optional) ADO filter applied to the UserList recordset. |
Returns a recordset with the same schema as the modUserList table in the modSystem database. If a filter expression is provided, it is applied to the output. For example, this property can be used to select the manager or all the direct reports of the current user.
UserRoles Property
Access: Read only
Data type: ADODB.Recordset
Default: Current user roles recordset
Range: N/A
Returns a recordset with all the database roles of which the current user is a member. Because security is based on roles, this information can be used to determine the level of security granted to the current user.
See Also
Workflow Scripting Reference | Workflow Events | Order of Workflow Events | Logger Object Model Reference