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. The operations are specified using variables, generic features of VBScript, and M-Files API.

Examples of event handler use:

  • Object permissions can be set to change automatically when the object properties are changed.
  • Certain basic documents can be added to every new project through a pre-defined project model.
  • Specified Word documents can always be saved as PDFs, so that when a Word file is checked in, it is saved to the server in PDF format as well.
  • Data related to photos, such as date and image size, can be automatically added to the metadata of the photo document.
  • If the user adds a new value to the value list, the event handler can be used to check that the added value is entered correctly.
  • Logging in to M-Files can be prevented outside working hours, for instance during night time and weekends.
  • Downloading certain files can be monitored, downloading large numbers of files can be prevented, or an alarm of suspicious downloads can be sent to the administrator.
Note: The M-Files API documentation is available online: M-Files API. For more information about using VBScript in M-Files, see the How do I write VBScript code for M-Files purposes? tutorial.

Do the following steps to create a new event handler:

  1. Open M-Files Admin.
  2. In the left-side tree view, expand a connection to M-Files server.
  3. Right-click a vault.
  4. Click Event Handlers.
    Result:The Event Handlers dialog is opened.
  5. Click the Add Event Handler... button.
    Result:The Add Event Handler dialog is opened.
  6. Use the Select event drop-down menu to select the event for which you want to create an event handler.
    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
  7. In the Name field, enter a descriptive name for the new event handler and click OK to close the Add Event Handler dialog.
    Example:Check for duplicate titles.
    If you have more than one event handler of the same type, you may change their execution order by selecting the event handler in the Event Handlers dialog and clicking either the up or down arrow button along the right corner of the dialog.
  8. Back in the Event Handler dialog, click Edit Code.
    Result:The Edit VBScript Code window is opened.
  9. Enter the code to be executed when the event handler is invoked, and then close the Edit VBScript window.
    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
  10. Back in the Event Handlers dialog, click OK to save your changes and to close the Event Handlers dialog.
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.