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 show additional field classes 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 fields on already existing Vertec objects are not created until they are accessed accordingly. Before they are not present in the database, which is, however, essential with access via SQL.

When are additional fields created?

Creating new objects

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

New additional field class is created on an existing object

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

• When displayed in a detail window .
• The field is created per scriptwhen it is described: projekt.jahr = 2022 (Example: integer additional field jahr on project). xxxIt can also simply according to initialized shall be: projekt.jahr = 0
• The field is also created per scriptwhen 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 really have to be 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, 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 additional fields on classes, for which objects already exist, should always be created directly.

Creating additional fields for existing objects

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

projekte = vtcapp.evalocl("projekt")
for projekt in projekte:
    projekt.jahr = 0

vtcapp.updatedatabase()

You can find out how the different additional field types are initialized in the Python section 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	zusatzfeld	Empty string
    True, False	zusatzfeldbool	Wrong
    Integer number	zusatzfeldint	0
    Minutes	zusatzfeldint	0
    Fixed-point number	zusatzfeldcurr	0.00
    Date	zusatzfelddate	NULL
    Image	zusatzfeldblob	NULL
    Object	zusatzfeldobj (see tips below)	NULL
    Selection	zusatzfeldint (returns the position of the selection) zusatzfeldasstring (returns the selection text)	0 First value of the list
    Text	zusatzfeld	Empty string
    ANSI text (legacy)	zusatzfeldblob	NULL

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

    adresseintrag->select(zusatzfeldbool('ABC-Adresse'))

Python

In Python you can access the additional fields very easily via the additional field name, e.g. projekt.jahr.

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

The various additional fields can be accessed via SQL as follows:

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

Additional fields can also be placed in lists and pages by means of customizing. The following matrix applies to the selection of the control:

<AddressReferenceBox Label="Adresse" 
    ValueExpression="zusatzfeldobj('ZeichenAdresse')" />

<PathBox Label="File" 
    ValueExpression="zusatzfeld('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="Pfad" ValueExpression="zusatzfeld('Pfad')" ShowNavLinkButton="True" SelectType="Folder" />

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

<CheckBox Label="True, False"
 ValueExpression="zusatzfeldbool('WahrFalsch')" />

<TextBox Label="Integer number"
 ValueExpression="zusatzfeldint('Ganzzahl')" />

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

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

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

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

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

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

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

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

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

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

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

The main difference is with selection type additional fields. These are implemented internally as integer additional fields. This means that the expression zusatzfeldint(name) returns a number. If the text of the selection is to be shown, the expression zusatzfeldasstring(name) should be used.

Similarly, the type-specific OCL operators return NULL values if the additional field is NULL. However, 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 zusatzfeldAsString.

The operator additional fieldObj for querying object additional 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 additional field 'Branch’ on project user. Indicates an address, for example.

offeneLeistungen.bearbeiter.zusatzfeldobj('Niederlassung')->asset->size

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

offeneLeistungen.bearbeiter->collect(zusatzfeldObj('Niederlassung')->oclasType(UserEintrag))->asset->size

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

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