Config Set XML

The config set definition consists of the following elements:

<?xml version="1.0" encoding="utf-8"?>
<configset name="Spezial" author="Vertec AG">
  <comment>
  Das ist ein Kommentar, der das Configset noch näher beschreibt.
  </comment>
  <requirements/>
  <references>
    <entryid-reference class="OrdnerOeffentlich" alias="OrdnerOeffentlich0" entryid="FolderPublicFolders" />
  </references>
  <objects>
    <object class="Ordner" alias="Ordner_Spezialauswertungen0">
      <member name="Bezeichnung">Spezialauswertungen</member>
      <member name="Parentordner">
        <reference-object alias="OrdnerOeffentlich0" />
      </member>
    </object>
    <object class="ExpressionOrdner" alias="ExpressionOrdner_Projektegross1">
      <member name="Bezeichnung">Projekte gross</member>
      <member name="Parentordner">
        <reference-object alias="Ordner_Spezialauswertungen0" />
      </member>
      <member name="Expression">Projekt.allInstances-&gt;select(offeneLeistungen.wertExt-&gt;sum &gt; 10000)</member>
    </object>
  </objects>
  <settings />
</configset>

The configset element is the main element of a config set. It contains the following attributes:

• author: Author of the config set. The value from the Author field in the config set builder is entered automatically.
• name: Name of the config set. The value from the Name field in the config set builder is entered automatically.

<configset name="Spezial" author="Vertec AG">
...
</configset>

The configset element contains the following subelements:

The comment element is a sub-element of configset and contains any comment.

 <comment>Das ist ein Kommentar, der das Configset noch näher beschreibt.</comment>

The requirements element is a sub-element of configset. It can contain ocl-requirements as sub-elements.

Requirements can be used to define preconditions that must be met in order for the config set to be loaded. This can be any OCL expression. The requirements are entered in the Elemente field in the Config Set Builder.

If no requirements are specified, the element is specified as follows:

<requirements />

The ocl-requirement is a sub-element of requirements. It contains any OCL expression that must return True in order for the config set to be imported. It can be used to query preconditions that must be met for the import of the config set, e.g. ensuring that a certain additional class is not yet occupied.

<requirements>
    <ocl-requirement>ClassSettings.allInstances->select(klasse='ZusatzKlasse0')->size = 0</ocl-requirement>
</requirements>

Starting with Vertec version 6.6, the optional Message argument can be used to send a meaningful message to the user if a requirement is not met. No translation of the text takes place. The message is output as it is stored.

    <ocl-requirement message="ZusatzKlasse26 ist bereits in Verwendung.">
ClassSettings.allInstances-&gt;select(klasse='ZusatzKlasse26'-&gt;size = 0
    </ocl-requirement>

The version-requirement exists from 6.4 and allows you to specify the minimum Vertec version required to use the config set. The syntax is as follows:

<requirements>
    <version-requirement>6.3.0.12</version-requirement>
</requirements>

The following shall apply:

• If a config set is imported with a version requirement and the Vertec version is smaller than the specified version, an error is reported and the config set cannot be imported.
• If a config set with version requirement is imported in an older version of Vertec without implementing the version requirement feature, an error is also reported and the config set cannot be imported. Therefore, for config sets with this specification, a Vertec version 6.4 or higher is required.

The references element is a sub-element of configset and can itself contain the sub-elements entryid-reference and ocl-reference.

This is a list of references that are used within the config set. Each reference is given a unique name within the config set.

If no references are specified, the element is specified as follows:

<references />

The entryid-reference element is a sub-element of references. It references an object based on its class and its entry ID. This way, objects that already exist in the target system are identified. It contains the following attributes:

• class: Class of the object with EntryId
• entryid : Entry ID of the object
• alias : internal alias for use within the configuration set

    <entryid-reference class="OrdnerOeffentlich" alias="Alias_Parentordner" entryid="FolderPublicFolders" />

entryid-references are entered automatically when creating the config set via the config set builder.

The ocl-reference element is a sub-element of references. It references an object by specifying an OCL expression. The OCL expression is evaluated globally. Thus, an object present in the target system can be identified and worked with in the config set. It contains the following attributes:

• expression: OCL expression which must result in a single object.
• alias: internal alias for use within the configuration set.

    <ocl-reference expression="TimSession.allInstances->first.login" alias="aktBearb" />

ocl-references are entered in the Elemente field in the config set builder.

The objects element is a sub-element of configset. Contains the objects to be created by the configset.

The objects including all sub-elements are automatically entered when the config set is created via the config set builder.

It contains the following sub-elements:

The object element is a sub-element of objects. Represents an object to be created by the Configset. Contains a collection of member elements. Attributes:

• class: class name of the object
• alias: alias of the object

The member element is a sub-element of object. Represents a property of an object. Attributes:

name: Name of the member (property)

The content of a member element is one of the following:

• Simple text for simple values (string, num, boolean, etc)
• object Element for objects that belong to the parent object and are also created by the Configset.
• reference-object Element for references to objects already included in the configset or assumed as a reference.

The reference-object element is a sub-element of member. Represents an object that is already included elsewhere in the configset. Attributes:

• alias: Alias of the referenced object.

<objects>
    <object class="Ordner" alias="Ordner_Spezialauswertungen0">
        <member name="Bezeichnung">Spezialauswertungen</member>
        <member name="Parentordner">
            <reference-object alias="OrdnerOeffentlich0" />
        </member>
    </object>
    <object class="ExpressionOrdner" alias="ExpressionOrdner_Projektegross1">
        <member name="Bezeichnung">Projekte gross</member>
        <member name="Parentordner">
            <reference-object alias="Ordner_Spezialauswertungen0" />
        </member>
        <member name="Expression">Projekt.allInstances-&gt;select(offeneLeistungen.wertExt-&gt;sum &gt; 10000)</member>
    </object>
</objects>

The settings element is a sub-element of configset. It contains system-setting elements, which represent the system settings to be set by the configset.

settings Elements are entered in the Elemente field in the config set builder.

The system-setting element is a sub-element of settings. It can be used to set an existing system setting. Attributes:

• name: The name is the PropertyName. You can find this in the description of the respective system setting.
• alias: for object properties: alias of the object to be set (must be included in the configset or in the external references)

    <system-setting name="GlobalDokPfad">C:\Dokumente</system-setting> 

As of Vertec 6.4.0.10 it is also possible to create new system settings.

• If you want to change existing system settings, use the system-settings as described above and specify the corresponding rows in the config set builder interface.
• If you want to create new system settings, you insert them as an object directly into the XML after exporting the config set for the first time. This procedure is described below.

System settings do not have an entry ID and are therefore identified by their name (PropertyName). The system settings are inserted directly as objects. Example:

  <objects>
    <object class="StringProperty" alias="StringProperty_0">
      <member name="PropertyName">GlobalLogopath</member>
      <member name="PropertyValue">D:\Bilder\Logos</member>
      <member name="PropertyCaption">Ablagepfad für Logos</member>
      <member name="Gruppe">0</member>
      <member name="AuswahlTyp">Path</member>
      <member name="Scope">Global</member>
      <member name="Masked">false</member>
    </object>
  </objects>

Which members exist and how to set them is described in the article Creating Vertec system settings.

If an imported config set is exported again, the system configuration object remains as an object in the XML file, so manual entry only needs to be done once.

update

The update element is a sub-element of configset and can itself contain the sub-elements before-import and after-import. This allows Python code to be executed immediately before or after the actual import of the config set.

The Python code is entered directly in the respective element (plain python code).

before import

The Python code provided in the before-import is automatically executed,

• after checking the requirements and the references
• before processing the objects and settings

<update>
    <before-import>
print "Plug-in wird importiert durch {}".format(vtcapp.currentlogin())
    </before-import>
</update>

after-import

The Python code provided in the after-import is automatically executed,

• after processing the objects and settings

<update>
    <after-import>
ord = vtcapp.getobjectbyentryid('Ordner', "ObjFolder")
neword = vtcapp.getobjectbyentryid('Ordner', "NewObjFolder")
neword.ordeintraege.extend(ord.ordeintraege)
ord.delete()
    </after-import>
</update>