Event Handlers

With event handlers you can define different operations that are executed when certain events occur, such as after an object is modified or before a new value list item is created, and so on. The operations are specified using variables, generic features of VBScript, and M-Files API.

Examples of event handler use:

Note: The documentation for the M-Files API is located in Start > Programs > M-Files > Documentation > M-Files API. For more information about VBScript code and M-Files API, go to www.m-files.com/api. Instructions on writing VBScript code and working with the M-Files API are available for a separate fee from M-Files customer support ([email protected]).

Do the following steps to create a new event handler:

Steps

  1. Open M-Files Admin.
  2. In the left-side tree view, expand the desired connection to M-Files Server.
  3. In the left-side tree view, right-click the desired document vault and select Event Handlers from the context menu.
    The Event Handlers dialog is opened.
  4. Click the Add Event Handler... button.
    The Add Event Handler dialog is opened.
  5. Use the Select event drop-down menu to select the event for which you want to create an event handler.
    For example, if you want to create an event handler that is invoked whenever a new object is about to be created, select the BeforeCreateNewObjectFinalize event.
    For the list of available events and their descriptions, see Available Event Handlers
  6. In the Name field, enter a descriptive name for the new event handler and click OK to close the Add Event Handler dialog.
    For example, Check for duplicate titles.
  7. Back in the Event Handler dialog, click Edit Code.
    The Edit VBScript Code window is opened.
  8. Enter the code to be executed when the event handler is invoked, and then close the Edit VBScript window.
    For example, the following code in the BeforeCreateNewObjectFinalize event could be used to display an error message to the user when they are about to create a new object (that is, the metadata card is filled with the necessary information and the user clicks the Create button) and the document vault already contains an object with the same title:
    ' The ID of the title property.
    
    Dim titleProperty
    titleProperty = MFBuiltInPropertyDefNameOrTitle
    
    ' Find the title property of the current object.
    
    Dim currentTitleProp
    currentTitleProp = PropertyValues.SearchForProperty(titleProperty)
    
    ' Get the title of the object.
    
    Dim currentTitle
    currentTitle = currentTitleProp.Value
    
    ' Search for objects on the basis of title.
    
    Dim titleSearch
    Set titleSearch = CreateObject("MFilesAPI.SearchCondition")
    Dim titleExpression
    Set titleExpression = CreateObject("MFilesAPI.Expression")
    titleExpression.SetPropertyValueExpression titleProperty, MFParentChildBehaviorNone, Nothing
    Dim titleTypedValue
    Set titleTypedValue = CreateObject("MFilesAPI.TypedValue")
    titleTypedValue.SetValue MFDatatypeText, currentTitle
    titleSearch.Set titleExpression, MFConditionTypeEqual, titleTypedValue
    Dim SearchResults
    Set SearchResults = Vault.ObjectSearchOperations.SearchForObjectsByCondition(titleSearch, false)
    
    ' If an existing object with the same title was found, raise an error.
    
    If SearchResults.Count > 1 Then
    
        Err.Raise MFScriptCancel, _
        "The document vault already contains an object with the same title. Please choose another title."
    
    End if
  9. Back in the Event Handlers dialog, click OK to save your changes and to close the Event Handlers dialog.

Results

The new event handler is added to the selected document vault and the code that you have defined is executed whenever the event handler is invoked.