Scripting Workflow Actions

  • Article

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 built-in functionality of workflow actions can be enhanced using Microsoft Visual Basic® Scripting Edition (VBScript). Because the script within a workflow process is executed on the server, the compatibility of VBScript with less capable Web browsers is not a consideration.

Within each action, you can add script to fulfill the requirements of your team solution. To extend the capabilities of your workflow beyond the scripting language, you can invoke stored procedures from within your script. For example, you can call a stored procedure that uses the Microsoft ActiveX® Data Objects (ADO) connection and Session object to work with data. For information about the stored procedures used in a team solution, see Stored Procedures.

The workflow scripting environment provided by Microsoft Access Workflow Designer for Microsoft SQL Server™ reflects standard code coloration and has a basic script verification feature. Script is created, edited, and viewed on the Shared Script tab of the Access Workflow Designer Workflow Process pane.

When writing script for workflow actions, you must be familiar with the available events and the order in which they are executed. In addition, it is critical to understand how these events loop and the consequences of changing the names of script procedures. This topic covers the following issues and refers you to other pertinent information.

  • Script Procedures

  • Workflow Events

  • Order of Events

  • Loop Suppression

  • Naming Script Procedures

  • Making Actions Available Offline

For additional tips about scripting and samples, visit the Microsoft Office Developer Web site at http://msdn.Microsoft.com/officedev.

Script Procedures

A single action, such as moving from one state to another, can trigger several different events, which occur in a particular sequence. The events in Access Workflow Designer are slightly different from the events you may be familiar with in Access or Visual Basic where, when an event occurs, the code associated with the event is triggered.

In Access Workflow Designer, for each of the workflow events, there are two associated script procedures-a validation and an action. The validation script procedure must return a value of True for the associated action script procedure and the workflow action to be executed.

Workflow Events

There are seven actions or action events: OnCreate, OnTransition, OnDelete, OnEnter, OnExit, OnChange, and OnTimeout. These action events serve two purposes-they represent valid actions in your workflow process, and they are used as events to trigger scripts.

Note   Although these seven action events may be referred to as workflow actions in some places and as workflow events in others, they are the same thing.

For example, if you want to design a workflow process where a new record can be set to a state called Active or a state called Review, then each of these states must include a Create action. Similarly, if you want to make it possible for a record to be deleted regardless of its current state, you must add a Delete action to each state in your workflow process. For more information about workflow actions, see Workflow and Adding and Modifying Actions for States. The workflow process

You can provide a friendly name for action events that are displayed in the workflow diagram. In the following graphic, the OnCreate action associated with the Open state is named New.

Workflow events fall into two categories-those that do not implicitly modify the workflow state, such as OnChange and OnTimeout, and those that generate a state transition, such as OnCreate, OnTransition, and OnDelete. Every time there is a state change, there are corresponding OnEnter and OnExit events.

OnTimeout events, which are only available when a team solution is online, are regulated by the SQL Server Agent and executed at a designated time defined by that agent. All the other events are triggered by user interaction with the data.

Note   Any event can be used to generate a state change using script.

For each of these events, there is a validation script procedure and an action script procedure. When you choose a script procedure in the Design tab, the associated code is added to the Shared Script tab in the Workflow Process pane.

The validation script procedure must return a value of True for the action script to be executed. In addition, during transitions, all validations that are defined must return True before any action script is executed.

For example, take the case of a state transition from Open to Resolved. If you have OnExit and OnEnter events defined for Open and Resolved respectively, the validation script procedures for OnExit of Open, OnTransition between Open and Resolved, and then finally OnEnter of Resolved must all return True for the corresponding action script procedures to be executed. If True is returned for all of the validation script procedures, the action script procedures occur in the same order: OnExit of Open, OnTransition between Open and Resolved, and finally OnEnter of Resolved.

****Note   ****OnEnter and OnExit are special case actions that fire each time a state is entered or exited regardless of the transition that caused the entry or exit.

By default, each validation script procedure returns True. For example:

Function State1_Validate_OnCreate()
    State1_Validate_OnCreate = True
End Function

You can modify the validation script procedure to make it conditional. For example:

Function State1_Validate_OnCreate()
   If CheckValue = 1 then
       State1_Validate_OnCreate = True
   End if
End Function

In the previous example, if the CheckValue variable is not equal to one, the associated action script procedure is not executed. CheckValue could be a variable, an item from the Session object, or a call to a function.

The following example uses the Session.Item property to look at a date field called DateModified. If it is equal to today's date, then the validation script returns a value of True.

Function State1_Validate_OnCreate()
     If session.item("DateModified") = now Then
        State1_Validate_OnCreate = True
    End If
End Function

For more information regarding workflow events, see Workflow Action Events. For information about selecting events, see Choosing an Action Script Procedure.

Order of Events

The two special case events, OnEnter and OnExit, are executed in a specific order depending on the type of transition event that occurs. All the validation scripts that are defined must return True, or the transition does not occur, and none of the associated action events are executed.

The following sections describe the order that the events are executed for each type of transition event. For more detailed information, see Order of Workflow Events.

OnCreate

  • OnCreate Þ OnEnter

OnCreate event executes when the user attempts to save the record to the database. If you want values to be inserted as soon as a record started, use the default value property of a control on your data access page or on your form rather than using script.

OnTransition

  • OnExit (State A) Þ OnTransition (State A to State B) Þ OnEnter (State B)

Evaluate your scripting requirements to determine the event to use. For example, if you want something to happen every time a state is entered, use the OnEnter event; however, if you want different things to happen depending on the previous state, use the OnTransition event.

OnDelete

  • OnExit (State B) Þ OnDelete (State B)

Tip   Because the OnDelete event can occur for more than one state, you may find yourself repeating scripts or function calls to have a procedure run when you delete a row. Instead of adding script for each delete transition, add a Being Deleted state to your workflow diagram. Then, you only must add script to that one state.

Loop Suppression

If you make a state transition from within a state-bound event (for example, using script triggered by an OnChange (edit) event), this causes the same OnExit, OnTransition, and OnEnter events to occur.

Because you may have code within the OnEnter event of the next state to evaluate and transition it to yet another state, looping could occur. Because looping indefinitely can cause SQL Server to hang or crash, Access Workflow Designer implements loop suppression by caching all the states the record has transitioned to during the current transaction context. When it is detected that you have been in a state previously, the transition to the state is made possible, but the loop is broken, because any subsequent OnExit, OnTransition, and OnEnter events are not executed.

For example, if you have a workflow process that enforces the following transitions:

State A Þ State B Þ State C

  • An issue in State A is moved to State B.

  • The OnEnter event of State B triggers code that evaluates a condition and moves to State C.

  • The OnEnter event of State C triggers code that evaluates a condition and moves back to State A.

  • The OnEnter event of State A triggers code that evaluates a condition and moves to State B. At this point, you have looped back to your starting point.

  • Although you entered State B previously during the transaction context, the entry is made possible, and the OnEnter event is executed. The OnEnter of State B evaluates and moves to State C again.

The loop is broken here. The OnExit of State B, OnTransition from B to C, and OnEnter State C are not executed.

So, you loop completely through the events, and only the first transaction is executed twice.

Naming Script Procedures

In the Shared Script tab of the Workflow Process pane, you can change the name of validation or action script procedures. However, this does not update automatically the script procedure name on Design tab, nor does it automatically associate the script to the action. You must select manually the new procedure name from the procedures list on the Design tab.

Note   If you receive an "unknown name error," you probably have a mismatched script procedure and script procedure name. Use the procedure list on the Design tab to select an existing script procedure name.

For more information regarding naming script procedures, refer to Workflow Scripting Guidelines and Script Procedure Names.

Making Actions Available Offline

By default, any action you add to your workflow process is available while users are working online or offline. If you want to prevent certain actions from being made while a team solution is offline, select the action in the Actions list and on the Design tab in the Workflow Process pane. Then, disable the This action can be performed offline****option for that action.

If this option is disabled, that action and any associated script are not permitted while the team solution is offline.