Python Scripts in Vertec

Vertec hat eine Python Engine eingebunden, um benutzerdefinierte Scripts auszuführen und Vertec damit steuern zu können. Aus einem Vertec Pythonscript heraus ist wiederum das ganze Vertec Objektmodell zugänglich.

Ein Python Script kann entweder im Script Editor oder in einem Text-Editor erstellt werden. Scripts, die immer wieder verwendet werden, können im Vertec registriert werden (nur Linie Expert). Sie sind dann über den Menüpunkt Aktionen oder im Kontextmenü über die rechte Maustaste abrufbar. Siehe dazu den Artikel über das Registrieren von Scripts.

Weitere Informationen:

• Vertec Python Funktionen
• Kurzeinführung in die Python Programmierung
• Python Standard Library auf https://docs.python.org/library.

• Der Script Editor
• Die Python Konsole
• Die Variable "argobject"
• Das Modul "vtcapp"

• Funktionen ohne Parameter aufrufen
• "eval" (eine OCL Expression auswerten)
• Funktionen definieren
• Funktionen aus einem anderen Script aufrufen
• Ein Modul erneut laden
• Globale Variablen definieren

Um Python Scripts zu erstellen und auszuführen gibt es den Script Editor. Diesen öffnen Sie über Menü Einstellungen > Script Editor.

Der Script Editor kann auch über den Button Script Editor in einem Scripteintrag geöffnet werden. In diesem Fall enthält er den Scripttext des entsprechenden Scripteintrags.

Der Script Editor ist in diesem separaten Artikel detailliert beschrieben.

Ein wichtiger Teil des Script Editors ist die Möglichkeit, auf dem aktuellen Objekt eine Python Anweisung auszuführen und das Ergebnis zu sehen, also die Konsolen-Funktionalität. Um dies zu erleichtern, gibt es ab Vertec 6.3 eine Python Konsole, welche für Benutzer mit Administratorenrechten zur Verfügung steht.

Die Konsole kann über das Menü Einstellungen sowie über das Tastaturkürzel F3 ein- und ausgeblendet werden:

Am unteren Rand des Vertec-Fensters wird die Konsole angezeigt:

Die Höhe der Konsole kann mit der Maus verändert werden:

Mit Rechtsklick in die Python-Konsole erscheint ein Kontext-Menü mit Option zum Löschen des Konsolen-Inhalts.

Die Variable argobject liefert das zur Zeit aktuelle Objekt (den aktuellen Eintrag) in Vertec. Dies ist der Eintrag, welcher im aktiven Fenster von Vertec als Haupteintrag ausgewählt ist, z.B.:

projekt = argobject

Registrierte Scripts können aber auch auf einem einzelnen Objekt in der Liste per Rechtsklick aufgerufen werden. Das argobject ist dann das einzelne Objekt. Möchte man im Script jedoch auf den aktuellen Eintrag in Vertec, im Beispiel also auf den Container "Eigene Projekte" zugreifen, gibt es dafür die Variable currentobject:

Dieser Unterschied ergibt sich auch in Eventscripts. Wird dieses beispielsweise ausgelöst, wenn sich ein Zusatzfeld auf einer bestimmten ZusatzKlasse ändert, ist argobject das Objekt der auslösenden ZusatzKlasse. Würde das Feld aber im Einzelfenster einer anderen Klasse verändert, wäre dieses Objekt das currentobject und somit das zur Zeit aktuelle Objekt in Vertec.

Mit der Vertec Installation wird eine Vertec Python Library mitgeliefert. Diese ist nach der Installation automatisch verfügbar und heisst vtcapp. Zu dieser Tabelle gibt es die Hilfe-Funktion help(vtcapp), welche alle Informationen dazu auflistet:

Das Modul vtcapp hat folgende wichtige Methoden und Funktionen (es sind nur die wichtigsten aufgeführt, die vollständige Liste findet sich im Artikel Vertec Python Funktionen):

leistung=vtcapp.createobject("OffeneLeistung")

>>> bearbeiter = vtcapp.currentlogin()
>>> bearbeiter.name
Christoph Keller

projektListe = vtcapp.evalocl("Projekt.allinstances->orderby(code)")

Beim Aufruf einer Funktion, welche keine Parameter erwartet, ist es sehr wichtig, dass die Klammern nicht vergessen gehen. Beispiel:

vtcapp.currentlogin #Falsch, Funktion wird nicht aufgerufen, es wird eine Fehlermeldung ausgegeben
vtcapp.currentlogin() #Richtig

Mit eval wird auf einem Objekt bzw. auf einer Liste von Objekten eine OCL Expression ausgewertet.

Beispiel:

 # Rechnung
 obj = argobject
 Leistungen = obj.evalocl("leistungen")

 # Summe von Leistungen
 SummeLeistungen = Leistungen.evalocl("if self->first.rechnung.verrechnet then\
 oclastype(VerrechneteLeistung).wertext else oclastype(OffeneLeistung).wertext endif->sum")

Globale OCL-Variablen (also solche, die sich auf das gesamte Vertec und nicht auf ein einzelnes Objekt oder eine einzelne Liste beziehen) werden über vtcapp.evalocl ausgewertet (siehe Das Modul vtcapp weiter oben).

Innerhalb des Scripts werden Funktionen mit def<funktion>: definiert:

def ChangeText(leist):
    leist.text = ...

Danach kann im Code darauf zugegriffen werden:

ChangeText(argobject)

In Python ist es möglich, eine Funktion aus einem anderen Script aufzurufen. Funktionen, welche öfters bzw. in mehreren Scripts verwendet werden, sollten in einem eigenen Script (Modul) ausgelagert werden.

import <scriptname> #Scriptname des Moduls
<scriptname>.<funktion>

• vtcapp muss in diesen Modulen explizit importiert werden (import vtcapp)
• systemcontext() ist systemweit, auch wenn man in einem Script etwas aus einem anderen Modul aufruft.
• Das aufgerufene Modul darf kein Leerzeichen im Namen haben.

In Vertec Versionen vor 6.4 werden die Imports nur beim ersten Aufruf geladen. Vertec merkt sich, dass dieses Modul (Script) geladen ist, und lädt es nicht wieder, auch wenn es im Code erneut aufgerufen wird. Das bedeutet: Wird das Modul bzw. das Script im Hintergrund geändert, haben diese Änderungen keinen Effekt, wenn das geänderte Modul bereits geladen wurde.

Mit dem Befehl reload kann ein Modul neu geladen werden. Dies kann einmalig im Python Editor ausgeführt werden oder auch direkt im Script nach dem import-Befehl integriert werden:

import scriptclass
reload(scriptclass)

Vertec Versionen ab 6.4 machen das automatisch. In der gleichen Session werden geänderte Module beim nächsten Aufruf neu geladen. Andere Sessions erkennen den geänderten Scriptcode zwar via Notif Server, laden das Modul aber nicht erneut.

Unterschied zwischen lokalen und globalen Variablen:

• Lokale Variablen können nur innerhalb der Funktion verwendet werden und müssen für jede Verwendung in einer anderen Funktion als Parameter übergeben werden.
• Globale Variablen werden einmal initialisiert und sind in jeder Funktion im gleichen Script verfügbar.

Globale Variablen deklariert man ausserhalb von Funktionen. Um eine globale Variable innerhalb einer Funktionen zu verwenden, muss sie mit global geladen werden:

Leistung = argobject # globale Variable deklarieren

def WertExtAendern(betrag):
    global Leistung # globale Variable verwenden
    Leistung.xWertExt = betrag

def BearbeiterSetzen(bearbeiter):
    global Leistung
    Leistung.bearbeiter = bearbeiter