Property Definition Automatic Values

An automatic value can be set for a property. This means that, for example, invoices can be consecutively numbered. An automatic value can also contain text, in which case it is a combination of other properties. For example, to create proposal headings in a set format such as Class/Product/Customer, these properties (Proposal/Mach20A/ESTT Corporation) can be used to automatically create the headings.

Automatic values offer increased utilization of document and object metadata in storing and searching for information. In addition, using automatic values makes the naming of documents and objects more consistent and reduces the need for repeated data entries.

Automatic values are especially useful for naming objects (for more information, see New Class) and in automatically including metadata in document content (for more information, see Add M-Files Property).

Warning: VBScript execution errors can cause new object versions to not be created. They can also cause external object type synchronization to not complete. This prevents updates also to other objects of the same object type. VBScript execution errors are recorded in the Windows event log.

Automatic numbers and values

A property can have an automatic number or an automatic value.

An automatic number is calculated once and it does not change. Ths is useful, for example, in different company's internal processes and record-keeping.

An automatic value is calculated always when a new object version is created. It can contain other properties, usually by concatenating two or more properties. For example, if a document name (automatic value) is defined as Class (Customer), the document name can get the value Proposal (ESTT). If the automatic value is created with the class and customer name (Proposal (Customer A)), the automatic value changes to (Proposal (Customer B)) when another customer is selected.



Property definition with automatic numbering.

The example above illustrates a property with consecutive numbering in single whole number increments (increment: 1). The last value used is set as 1000. Thus, the next object to use this property will be numbered as 1001. The calculation order value is 100 (see Calculation order below).

Simple automatic numbering

Generates an incrementing numerical value. The increment can also be specified in the Increment field. The default value is one (1).

Customized automatic numbering (VBScript)

Generates an automatic number that can contain letters, numbers, or both. Creating a customized automatic number is specified in more detail with M-Files API and generic features of VBScript.

The following M-Files variables can be used with this script: PropertyDef, Output, LastUsed, ObjVer, DisplayID, Vault, CurrentUserID, CurrentUserSessionInfo, PropertyValues, VaultSharedVariables, SavepointVariables, TransactionCache, MFScriptCancel, GetExtensionObject, MasterTransactionID, CurrentTransactionID, ParentTransactionID. For more information about the variables, refer to Available VBScript Variables.

The desired custom value is assigned to the Output variable, for example Output = "Automatic value". For more information on specifying customized automatic numbering, see Specifying an Automatic Property Value Using VBScript.

Simple concatenation of properties

Conjoins selected properties (for instance Proposal/Device/Customer). Any characters or text can be inserted between the selected properties. For example: Proposal: Customer (Project) or Proposal, Customer, Project.

A list of available placeholders can be opened when specifying an automatic value for a property. The Add Placeholder… button opens the list of property definitions and other placeholders available for use.

Alternatively, you can add the placeholders to the field manually. They are used by bracketing them with % characters. For instance, %PROPERTY_23% (%PROPERTY_21%) could give us "John Smith (09/25/2016 12:39 PM)", assuming that 23 is the ID for the Last modified by property and 21 the ID for the Last modified timestamp property.

Besides the ID, you can also add the placeholders using aliases. To specify an alias placeholder, use the syntax %PROPERTY_{Property.Definition.Alias}%. For more information on defining aliases, see Assigning Aliases for Metadata Definitions.

Indirect placeholders

Indirect placeholders are metadata indirectly related to an object. For example, if a contract is related to a customer object, the country of the customer is indirect metadata for the document.

To specify the customer's country as an indirect placeholder the syntax %PROPERTY_1079.PROPERTY_1090% is used, where 1079 is the property definition ID for Customer and 1090 is the property definition ID for Country.

Alternatively, you can add indirect placeholders using aliases. In the previous example, the syntax with aliases would be %PROPERTY_{PD.Customer}.PROPERTY_{PD.Country}% , where PD.Customer is the alias for the Customer property definition and PD.Country is the alias for the Country property definition.

Calculated value (VBScript)

Creating an automatic value can be specified in more detail with M-Files API and generic features of VBScript.

These M-Files variables can be used with this script: PropertyDef, Output, ObjVer, DisplayID, Vault, CurrentUserID, CurrentUserSessionInfo, PropertyValues, VaultSharedVariables, SavepointVariables, TransactionCache, MFScriptCancel, GetExtensionObject, MasterTransactionID, CurrentTransactionID, ParentTransactionID. For more information about the variables, refer to Available VBScript Variables.

The custom value is assigned to the Output variable, for example Output = "Automatic value". For more information on specifying calculated values, see Specifying an Automatic Property Value Using VBScript.

Last value used

The starting value for consecutive numbering or values. The default is zero (0). The value can be changed; for example, consecutive numbering can start at 3000.

Calculation order

Calculation order determines the order in which automatic values are calculated (from smallest to greatest). This is significant when several automatic values are used and their combinations form new automatic values.

For example, calculation order is crucial if the name of an object is an automatic property value consisting of two other automatic values. These two automatic values should be calculated first and their combined value afterward.

The values themselves make no difference other than that the calculation order proceeds from smallest to greatest. The calculation order values for different properties can be, for example, 10, 12, 17 and 20. The property with the calculation order number 10 is thus calculated first, followed by the property with the calculation order number 12, and so on.

Recalculate

The Recalculate command is available in M-Files Admin task area (or by right-clicking a property in the Property Definitions list and selecting Recalculate) when a property with an automatic value is selected. You can choose between recalculating empty values or recalculating all values.

Recalculate Empty Values

Calculates automatic values for properties that have not been calculated yet. This is the default for calculating automatic values. Changes to settings only apply to new values. For example, if you edit the Last value used field, only new objects will have the new value. Old values are preserved; that is, once defined, a value does not change.

Recalculate All Values

Recalculates the automatic values of all properties. Recalculate All Values thus also recalculates previously defined values. For example, if consecutive numbering is used and the Last value used is changed, this function renumbers all existing objects.

Naming a template without using automatic values

Document templates work differently when automatic values are used. All properties in the template metadata work without the calculation of an automatic value. Thus, in templates, automatic property values work as if they were not automatic. Their values can be defined normally and the server does not calculate an automatic value for the property.

For example, objects in the Proposal class may use automatic values in their titles (such as Proposal <number> - <customer name>). However, it makes sense to name the Proposal class templates as templates; titles using automatic properties only make sense for actual proposals, not templates. Thus, the template might be called Proposal Template, while the actual proposal documents created using the template will have names formulated with automatic values, such as Proposal 35 - ESTT.

For more information, refer to Using Document Templates and New Class.