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:

Object permissions can be set to change automatically when the object properties are changed.
Certain basic documents can be added to every new project via 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 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

Open M-Files Admin.
In the left-side tree view, expand the desired connection to M-Files Server.
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.
Click the Add Event Handler... button.
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.
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
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.
Back in the Event Handler dialog, click Edit Code.
The Edit VBScript Code window is opened.

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

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.

Event Handlers

Steps

Results

In this chapter