Editing VBScript Code

Edit VBScript Code

VBScript code is edited in the Edit VBScript code window. The VBScript code is executed whenever a property value is recalculated; in other words, whenever a property is edited. VBScript creates the value and finally assigns it to a variable called Output. This value is stored as the value of the property in the object metadata.

The simplest piece of VBScript to formulate an automatic value might look like this:

Output = "Automatic value"

Usually an automatic value uses other object properties, for example, by concatenating them. VBScript code can utilize the property values and basic information of the same or another object, with the aid of the following VBScript variables that are made available:

CurrentUserID

Variable name: CurrentUserID

Variable data type: Number (see M-Files API)

Variable use: The CurrentUserID variable contains the ID of the user who performed the action that triggered the script.

DisplayID

Variable name: DisplayID

Variable data type: TypedValue (see M-Files API)

Variable use: The DisplayID variable contains the object's unique ID. This ID is displayed to users in the property area of M-Files Desktop when the object is selected in the list. DisplayID can contain both numbers and letters. Often, DisplayID is the same as the object's internal ID whose value can be retrieved with the ObjVer variable. The internal ID can only contain numbers. DisplayID and the internal ID are usually different when the object has been imported from an external database.

MFScriptCancel

Variable name: MFScriptCancel

Variable data type: Number (see M-Files API)

Variable use: The MFScriptCancel variable contains the error code which is used by the scripts to display error messages to users. M-Files often adds detailed data to error messages; this can be prevented with the error code of the MFScriptCancel variable.

Example: Err.Raise MFScriptCancel, "This is the error message shown to the user."

ObjVer

Variable name: ObjVer

Variable data type: ObjVer (see M-Files API)

Variable use: The ObjVer variable contains the complete unique ID of the target version, consisting of the object type ID, object internal ID, and object version.

PropertyValues

Variable name: PropertyValues

Variable data type: PropertyValues (see M-Files API)

Variable use: The PropertyValues variable contains all current property values of the target version (such as Name, Project, and Customer). Each property value is stored in PropertyValues as a variable of the type PropertyValue.

A certain property value can be retrieved with the SearchForProperty method. For more information, refer to the M-Files API documentation.

PropertyDef

Variable name: PropertyDef

Variable data type: PropertyDef (see M-Files API)

Variable use: The PropertyDef variable contains the information about the property value being calculated, such as the property value definition ID, name, and data type.

LastUsed

Variable name: LastUsed

Variable data type: TypedValue (see M-Files API)

Variable use: The LastUsed variable is available only if a customized automatic number is being calculated. The value of an automatic number usually depends on the previous calculation; for example, in ordinary consecutive numbering, the automatic value is incremented by one each time. When you are setting up customized automatic numbering, the result of the previous calculation can be retrieved by using the LastUsed variable.

For example, simple automatic numbering that increments by one could be implemented with the following simple VBScript code: Output = LastUsed + 1.

Output

Variable name: Output

Variable data type:TypedValue (see M-Files API)

Variable use: When VBScript code starts to run, the Output variable contains the current value of the property being calculated (but not for automatic numbering).

The main purpose of VBScript code is usually to create a new value and assign it to the Output variable, which is then stored in the object's metadata. If the VBScript code does not set the value of the Output variable, the property value in the metadata remains the same.

The value of the Output variable can in simple cases be set with a simple statement, for example: Output = 123.

If the datatype of the value being calculated is, say, Choose from list, the SetValue method is recommended for setting the value of the Output variable (see M-Files API), for example, as follows: Output.SetValue MFDatatypeLookup, 101.

Vault

Variable name: Vault

Variable data type: Vault (see M-Files API)

Variable use: The Vault variable represents the document vault which is used in running the script. With the identifier, the script is able to handle the document vault contents in the same way as is possible with the M-Files API interface. In an error situation, all changes made to the document vault through the Vault entity will be canceled.

The use of Vault entity with scripts entails certain limitations. The scripts cannot, through Vault entity, change the state of the object which the script is run to. The state change refers to checking the object out, checking the object in, undoing the check-out and deleting and destroying the object. Also, all other objects that are checked out in the script must be checked in during running of the same script.

VaultSharedVariables

Variable name: VaultSharedVariables

Variable data type: NamedValues (see M-Files API)

Variable use: The VaultSharedVariables variable is a collection of named values which are stored in the document vault database. With the variable, the scripts can store their own values in the database so that they are also available to other scripts. The allowed data types for the named values are integer variables, Booleans, and strings.

In the following example, value 123 is stored as a named value and the number-based calculated value is then set as the value:

VaultSharedVariables( "Message" ) = 123

Output = VaultSharedVariables( "Message" )

Sample code

The following sample code creates an automatic value for the "Proposal Title" property by utilizing the proposal number and customer information in the object version metadata. The ID of the Proposal Number property is 1156 and the ID of the Customer property is 1288. For example, if a document has the proposal number 5577 and the customer is ESTT, the code below creates the following string as the title of the proposal: "Proposal #5577 / ESTT".

Option Explicit

' Get proposal number.

Dim szNumber

szNumber = PropertyValues.SearchForProperty( 1156 ).TypedValue.DisplayValue

' Get customer.

Dim szCustomer

szCustomer = PropertyValues.SearchForProperty( 1288 ).TypedValue.DisplayValue

' Create proposal title.

Dim szName

szName = "Proposal #" & szNumber & " / " & szCustomer

' Set result.

Output = szName

The documentation for the M-Files API is installed in the folder Start / Programs / M-Files / Documentation / M-Files API. For more information on creating automatic values with VBScript code, contact [email protected]. Support for working with the M-Files API and writing VBScript code are available from the M-Files technical support staff for a separate fee.