Additional fields

The list of existing fields in Vertec is specified by the model and cannot be changed. However, additional fields are available if you want to add additional information to data (e.g. order probability on project).

Additional fields are managed under Settings > Customizing > Additional fields. Each additional field is based on an additional field class. To create an additional field, click on additional field in the New menu or right-click on the folder.

The additional fields appear in the individual view of the relevant entries on the Further information page:

In addition, you can place them in a different location via customizing.

Translation of selection type additional fields

Starting with Vertec 6.5.0.15, the strings in selection type additional fields are translated if the additional field definition (AdditionalFieldClass) has an entry ID.

• For a selection type additional field in a list:
  • Expression: zusatzfeldint(<name>)
  • Control: cmbZusatzfeld
  • Renderer: rndZusatzfeld
  the selection options are translated if the additional field definition has set an entry ID.
• The translated text also appears in unselected rows in the list.
• If a translated selection type additional field is used as the first field of an additional field class, then the string representation of an additional field class instance points to the translated value. The additional field class instance does not need to have an entry ID (the entry ID on the additional field class definition is sufficient).
• All three of the following variants can be used in the code to configure??? the selection type additional field:
  • Configuring??? the selection index (integer value)
  • Configuring the translated text in the selected language
  • Configuring the untranslated text (native language)

If you have defined selection type additional fields and want to translate them, define an entry ID on the relevant additional field definition. You can find out how to do this in the article Languages/Terms ??? in the section Translations from version 6.4.0.9 .

You can also view and show additional field items in lists, use them in scripts and reports, or filter them in an Expression folder by accessing them via OCL. Querying via SQL folder is also possible.

It is important to note that the additional field items on already existing Vertec objects are not created until they are accessed accordingly. Before they are not present in the database, which is Access via SQL but essential.

When are additional fields created?

Creating new objects

When a new object is created, all associated additional field classes are created.

New additional field class is created on an existing object

For already existing objects, the additional field classes are created in the following operations:

• When displayed in a Detail window .
• Per Scripting the field is created when it is described: projekt.jahr = 2022 (Example: integer add-on field jahr on project). It can also simply according to initialized shall be: projekt.jahr = 0
• Per Scripting the field is also created when it is read, but only via OCL. This means: the read access via Python (e.g. myyear = projekt.jahr ) does not create the field, but read access via OCL does: myyear = projekt.evalocl("zusatzfeldint('jahr')")
• Via List settings when the “writing” field is accessed in a column. It doesn’t have to be really writing, but it has to be so that Vertec feels that it could be written: zusatzfeldasstring(...) for example, does not work, since this is a read-only access; zusatzfeldint(...) on the other hand, creates the field, because this expression can also be used to write. (Note: This restriction only applies to list settings. For read access via OCL in scripts, as described in point 3, this does not apply, there the field is also created for read-only access)

The reason for the somewhat complex behavior of variants 3 and 4 is the optimization, which returns the default value for a non-existent additional field item, since a write access should only be prevented due to a display, but no error message should appear.

The field is only accessible via SQL (e.g. via SQL folder) after it has been created. Therefore, the custom field items on classes of which objects already exist should always be created directly.

Creating additional fields for existing objects

After creating an additional field, you can Run script , which creates the field on all existing objects, such as:

projects = vtcapp.evalocl(“project”)
for project in projects:
    project year = 0

vtcapp.updatedatabase()

How the different additional field types are initialized can be found in the section Python below.

The various additional field classes can be accessed via OCL as follows:

• add-on fieldAsString(name): returns the value of an add-on field, regardless of its type, as a string value.
  • Depending on the type, the field is queried as follows:

    Additional field type	Operator	Default return value (if nothing has been explicitly set yet)
    String	custom field item	Empty string
    True, False	additional fieldbool	Wrong
    Integer number	additional fieldint	0
    Minutes	additional fieldint	0
    Fixed-point number	additional fieldcurr	0.00
    Date	additional field date	NULL
    Image	additional field blob	NULL
    Object	additional fieldobj (see tips below)	NULL
    Selection	additionalfieldint (returns the position of the selection) additionalfieldasstring (returns the selection text)	0 First value of the list
    Text	zusatzfeld	Empty string
    ANSI Text (Legacy)	additional field blob	NULL

    Example: All addresses marked as ABC addresses (True,False Additional field “ABC address” on address):

    address entry->select(additional fieldbool('ABC address’))

Python

Access to additional field classes in Python is simple via the additional field name, e.g. projekt.jahr .

Read-only access ( myyear = projekt.jahr ) does not create the field (see section When are custom field items created above), on the other hand, the write access already exists ( projekt.jahr = 2022 ). If you want to create the field without setting a value, it can be initialized as follows:

The different additional field classes can be accessed via SQL as follows:

For a detailed description and examples, see SQL expressions for SQL folders.

Additional field classes can also be placed in lists and pages via customizing. The following matrix applies to the selection of the control:

<AddressReferenceBox Label=”Address” 
    ValueExpression=”additional fieldobj('character address’)” />

<PathBox Label=”File” 
    ValueExpression=”additional field('File’)” SelectType=”FileOpen” />

<PathBox Label=”File” 
    ValueExpression=”additional field('File’)” ShowNavLinkButton=”True” SelectType=”FileOpen” />

<PathBox Label=”Path” 
    ValueExpression=”additional field('path’)” SelectType=”Folder” />

<PathBox Label=”Path”
    ValueExpression=”additional field('path’)” ShowNavLinkButton=”True” SelectType=”Folder” />

<TextBox Label=”Zeichen” ValueExpression=”zusatzfeld('Zeichen’)” />

<CheckBox Label=”True, False” 
    ValueExpression=”additional fieldbool('TrueFalse’)” />

<TextBox Label=”Integer” 
    ValueExpression=”additional fieldint('integer’)” />

<TextBox Label=”Minutes” ValueExpression=”additionalfieldint('Minutes’)” 
    Converter=”Minutes” />

<TextBox Label=”Fixed point number” 
    ValueExpression=”additional fieldcurr('fixed point number’)” />

<DatePicker Label=”Date” 
    ValueExpression=”additional fielddate('Date’)” />

<TextArea Label=”Text” 
    ValueExpression=”additional fieldblob('Text’)” Lines=”4” />

<Image Label=”Image” 
    ValueExpression=”additional fieldblob('image’)” Height=”150” />

<AddressReferenceBox Label=”Address” 
    ValueExpression=”additionalfieldobj('ObjectAddress’)” />

<TreeReferenceBox Label=”Folder” 
    ValueExpression=”additionalfieldobj('Objectfolder’)” 
    BrowseClass=”Container” SelectFilter=”AbstractFolder” />

<AdditionalFieldComboBox Label=”Object” 
    ValueExpression=”additionalfieldobj('Object’)” />

<AdditionalFieldComboBox Label=”Selection” 
    ValueExpression=”additional fieldint('selection’)” />

<TextArea Label=”Text” ValueExpression=”zusatzfeld('Text’)” Lines=”4” />

In most cases, this results in the same result on the interface, because in the end it is usually a string.

The main difference is with selection extension fields. These are implemented internally as integer custom field items. This means that the expression extensionint(name) returns a number. If the text of the selection is to be shown, the expression extensionasstring(name) should be used.

Similarly, the type-specific OCL operators return NULL values if the custom field item is NULL, but this is not a problem in most cases, since NULL values are rendered as empty strings. If a NULL value causes problems, this can be avoided by using the extension fieldAsString.

The extensionObj operator for querying object extension fields may result in errors when applied to a list of objects in an OCL expression. The error message is:

TBoldObjectList.AddElement: Element not a TBoldObject

Example: Object add-on field 'Branch’ on project user. Point to an address, for example.

openservices.processor.additional fieldobj('branch’)->asset->size

should indicate the quantity of different branches in a list of services. But gives the above error.

openservices.processor->collect(additional fieldObj('branch’)->oclasType(UserEntry))->asset->size

Applying additionalfieldObj to a list is equivalent to an implicit “collect” operation, which fails because additionalfieldObj does not return the linked object directly, but the linked field.

Converting the type to a compatible object type (the actual type of the object or User Entry) solves the problem. For the type conversion to take place, the collect operation to be explicitly formulated.