Advance Method
Advance Method
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.
Evaluates the action table for this process instance and executes appropriate actions. This method is called internally by the Collaboration Data Objects (CDO) workflow event sink, and does not need to be used by most applications.
Applies To
Type Library
Microsoft CDO Workflow Objects for Microsoft Exchange
DLL Implemented In
CDOWF.DLL
Syntax
[Visual Basic]Function Advance
(
eEventType As CdoWfEventType,
varReceived As Variant,
varUserID As Variant,
[pConnection As ADODB.Connection]
) As Boolean
[C++]HRESULT Advance ( CdoWfEventType eEventType, VARIANT varReceived, VARIANT varUserID, _Connection* pConnection, VARIANT_BOOL* pbEnd );
Parameters
- eEventType
The event type can be one of the events in the CdoWfEventType Enum. Only use this method if you are writing your own workflow event sink.- varReceived
The received message that initiated the workflow transition. This parameter should be empty for any event other than OnReceive.- varUserID
The security ID of the user currently modifying the message. This can be a security identifier (SID) of type VT_ARRAY | VT_UI1 and value is SAFEARRAY of bytes corresponding to the SID, or it can be a string of the form domain\username of type VT_BSTR and value is BSTR.- pConnection
Advance includes an input parameter that is a pointer to a Microsoft ActiveX Data Objects (ADO) connection. The workflow engine uses this parameter to supply the same session as the ProcessInstance to SendWorkflowMessage(). This ensures that e-mail sent in conjunction with the ProcessInstance transaction is committed or aborted along with ProcessInstance. If you are calling Advance from Microsoft Visual Basic Scripting Edition (VBScript), this parameter has to be a valid Connection or Nothing. If you do not supply a valid Connection or set this to Nothing, a Type Mismatch error is generated.- pbEnd
If the return value is TRUE, it means the ProcessInstance entered a state marked as the end state. You indicate an end state by using the CdoWfEndState(8) constant in the Flags field of the ActionTable.
Return Value
Returns S_OK if successful, or an error value otherwise.
Remarks
If you are using the Workflow Designer for Exchange 2000 Server, you do not need to use this method. The built-in workflow components take care of calling this method based on your selections.
This method with its supporting implementation is called the workflow engine. Normally, you will not need to use this method, as the workflow event sink invokes it for you in response to an event in your folder. When the event sink calls, the engine looks for a row in your ActionTable that matches the CdoWfEventType passed to it and contains a condition field that evaluates to TRUE. If it does not find a match with a TRUE condition, it treats it as an error and returns the code CDOWF_NO_CONDS_MATCHED. If you want to allow editing of a workflow document without changing state, enter a transition in your ActionTable with a TRUE condition and no action.
Examples
You must bind to the ProcessInstance before every call to Advance, and you must save the ProcessInstance after every call to Advance. This is the only supported behavior for Advance. The following example illustrates the correct sequence.
Bind to ProcessInstance item Call Advance Save ProcessInstance item
Bind to ProcessInstance item Call Advance Save ProcessInstance item
[Visual Basic]
Dim eventType As CdoWfEventType 'Assume OnChange action for this example eventType = cdowfOnChange
Dim varReceived As Variant 'If this is a correlated e-mail response 'Get the item that initiated the event 'Call it Row for this example varReceived = Row
Dim varUserID As Variant 'Get the security ID of the user that initiated the event 'Call it Sid for this example varUserID = Sid
Dim pConnection As New ADODB.Connection 'FolderURL is the URL of the folder where you run your workflow pConnection.Open folderURL pConnection.BeginTrans
Dim oPI As New CDOWF.ProcessInstance 'URL is the ProcessInstance URL oPI.DataSource.Open URL, pConnection, adModeReadWrite
'You need this connection to the PrivateURL of the WorkflowAccount 'only if you are using sendworkflowmessage in the action Dim pInboxConnection As New ADODB.Connection Dim PrivateURL As String pInboxConnection.Open PrivateURL
Dim bEnd As Boolean bEnd = oPI.Advance(eventType, _ varReceived, _ varUserID, _ pInboxConnection)
'If Advance fails then call OnAbort If Err.Number <> 0 Then oPI.OnAbort varReceived, varUserID 'Undo changes caused by advance pConnection.RollbackTrans Else 'commit transaction oPI.DataSource.Save pConnection.CommitTrans End If
' Close connections. pConnection.Close pInboxConnection.Close Set pConnection = Nothing Set pInboxConnection = Nothing
See Also
Send us your feedback about the Microsoft Exchange Server 2003 SDK.
Build: June 2007 (2007.618.1)
© 2003-2006 Microsoft Corporation. All rights reserved. Terms of use.