Event handlers

With event handlers, you can specify operations to take place automatically when certain events occur. For example, after an object is edited or before a new value list item is created.

Important: When you develop new extensions or edit existing ones, we recommend that you replace VBScript content with Vault Application Framework (VAF) compatible code for future compatibility. For information on the benefits of VAF over VBScript, refer to The Vault Application Framework in M-Files Developer Portal.

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 predefined 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.

To create an event handler:

Open M-Files Admin.
In the left-side tree view, expand a connection to M-Files server.
Open the context menu for a vault.
Select Event Handlers.
Result:The Event Handlers dialog is opened.
Select Add Event Handler.
Result:The Add Event Handler dialog is opened.
Use the Select event drop-down menu to select the event for which you want to create an event handler.
Example: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
In Name, enter a name for the new event handler and select OK.
Example:Check for duplicate titles.

If you have more than one event handler of the same type, to change their execution order, select the event handler in the Event Handlers dialog and click the up or down arrow button.
Back in the Event Handler dialog, select Details.
Result:The VBScript - Details dialog is opened.

Enter the code to be executed when the event handler is invoked, and then close the VBScript - Details dialog.

Example:This code in the BeforeCreateNewObjectFinalize event could be used to show an error to the user in this a following situation: They are about to create a document (the metadata card is filled and the user selects Create) and the vault 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

Back in the Event Handlers dialog, select OK to save your changes and to close the Event Handlers dialog.

The new event handler is added to the selected vault and your code is executed whenever the event handler is invoked.