Vertec Python Interfaces

Das Modul "vtcapp"

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

Das Modul hat folgende Methoden / Funktionen:

Methode/FunktionBeschreibungBeispielcode

__doc__

Dokumentation einer Funktion.

print vtcapp.__doc__

>>> Interface module to host application.

argobject Aktuelles Vertec Objekt. Diese Variable ist immer verfügbar, der Aufruf kann also ohne vtcapp. erfolgen. projekt = argobject
beginsystemcontext() Aktiviert innerhalb des Scripts die erweiterten Berechtigungen. Muss am Ende endsystemcontext() aufrufen, um die erweiterten Berechtigungen wieder freizugeben. Ist im Python-Editor aus Sicherheitsgründen nicht erlaubt.

try: vtcapp.beginsystemcontext()

main()

finally: vtcapp.endsystemcontext()

createobject(klasse: string) Erstellt neues Objekt der angegebenen Klasse.

leistung = vtcapp.createobject("OffeneLeistung")

currentlogin(): Projektbearbeiter Aktuell angemeldeter User

bearbeiter = vtcapp.currentlogin()

print bearbeiter.name

>>> Christoph Keller

deleteinvalidobjects() Löscht ungültige Objekte des aktuellen Logins.

vtcapp.deleteinvalidobjects()

disableevents() Eventsscripting ausschalten. Muss mit enableevents() wieder eingeschaltet werden. Benötigt erweiterte Berechtigungen.
Diese Funktion wird oft verwendet, wenn man ein gewisses Attribut anpassen möchte, welche eigentlich einen Event ausführen würde. Ist im Python-Editor aus Sicherheitsgründen nicht erlaubt. Achtung: Nach dem enableevents() darf es keine msgbox() mehr haben, sonst werden die nicht aufgerufenen Events nachträglich aufgerufen.
# Ganzes Script
try:
vtcapp.enableevents()
main()
finally:
vtcapp.disableevents()

# Teil eines Scripts
vtcapp.enableevents
()
rechnung.datum = date.today()
vtcapp.disableevents()
dologin(loginname: string, passwort: string): boolean Wechselt den aktuellen Login in Vertec. Rückgabewert: Login erfolgreich oder nicht.

vtcapp.dologin("keller", "")

enableevents() siehe disableevents()
endsystemcontext() siehe beginsystemcontext()
evalocl(expression: string): expressiontype Globale OCL Expression auswerten.

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

evaloclstring(obj: object, expStr: string): string OCL Expression innerhalb eines Strings auswerten. Rückgabewert: vollständig ausgewerteter String.

print vtcapp.evaloclstring(argobject,\ "Bearbeiter: %name% ist %stufe.asstring%")

>>> Bearbeiter: Christoph Keller ist
Senior Consultant

evaltovariable(obj: object, ocl: string, varname: string) Wertet eine OCL aus und speichert den Wert in eine OCL Variable. Die Variable kann man nur mit eval() auf das Objekt abfragen.

vtcapp.evaltovariable(argobject,\
"kuerzel+' - '+name", "userinfo")

print argobject.eval("userinfo")

>>> CK - Christoph Keller

executereport(rootObj, optarg, berichtObj, [saveAs, showDialog, doPrint, showApp])

Ab Version 5.8. Erlaubt den Aufruf und das Ausführen von Office- und von internen Reports.

  • rootObj: Das Objekt, auf dem der Report ausgeführt wird.
  • optarg: Entspricht der optionalen Adresse auf dem Druckdialog. Optionales Argument. Wenn nicht verwendet, Parameter mit None angeben.
  • berichtObj: Eine Vertec Bericht-Definition (Klasse Bericht) oder ein Pfad für das Office-Template. Falls ein Bericht Objekt angegeben,  wird der Report aufgrund der Definition ausgeführt.
    Die Einstellungen des Bericht-Objekts für Speichern unter und Dialog anzeigen können via die entsprechenden Argumente dieser Methode noch übersteuert werden.
  • saveAs: Pfad zum Speichern des Berichts (falls Office-Bericht). Dieser String kann auch OCL Expressions (mit % getrennt) enthalten.
    Falls ein Leerstring angegeben wird, dann wird kein File gespeichert.
    Wenn None übergeben wird, werden die SaveAs-Einstellungen aus dem Report Objekt (berichtObj) übernommen.
  • showDialog: Anzeige von Dialog mit Speichern unter etc. (falls Office-Bericht)
  • doPrint: Bericht direkt ausdrucken. Falls true, wird der Bericht direkt ausgedruckt. Bei Word-Berichten wird Word dann nicht angezeigt.
  • showApp: Gibt an, ob die Applikation offen angezeigt werden soll (wird nicht beachtet mit doPrint).

Einen Word-Report für Rechnung anzeigen, ohne Dialog und ohne ein File zu speichern:

vtcapp.executereport(rech, None,\
rechTempl, "", showDialog=False)
Die Variable rechTempl muss das Bericht Objekt für eine Rechnung enthalten, die Variabel rech das Rechnungsobjekt.
executefile(filepath)

Öffnet das angegebene File auf dem Client (ohne Web App).

Kann auch verwendet werden, um ein Programm zu starten (z.B. "calc.exe").

vtcapp.executefile("calc.exe")

öffnet den Windows Rechner.

executefolder(folderpath)

Öffnet den angegebenen Ordner auf dem Client (ohne Web App), z.B. im Windows-Explorer.

vtcapp.executefolder("C:\Arbeitsverzeichnis")
executeurl(url)

Öffnet die angegebene URL auf dem Client (alle Apps).

Zum Beispiel eine Website im Browser öffnen:

vtcapp.executeurl("www.vertec.com")

Oder eine Vertec Breadcrumb URL:

vtcapp.executeurl("vertec://CK-676/eigene+Projekte-49/COMINSTALL-2880/")
getmemberwithsql(obj: object, membername: string, where: string, order: string): list of objects SQL Statment auf einen Linktyp ausführen. SQL: Hole alle Offene Leistungen auf Projekt, die den Betrag>200 haben, ohne alle Offene Leistungen des Projektes zu laden. OCL: projekt.offeneleistung ->select(xwertext>200) würde nach offeneleistung gleich alle laden.

projekt = argobject li=vtcapp.getmemberwithsql(projekt,\ "offeneleistungen", "xwertext>200", "")
print len(li)

>>> 3

getpropertyvalue(propname: string): propertytype Hole Wert eines Propertys.

print vtcapp.getpropertyvalue("globaldokpfad")

>>> C:\Programme\Vertec\Dokumente

getwithsql(klasse: string, where: string, order: string): list of objects Globale SQL Statment ausführen.

liste = vtcapp.getwithsql("Adresseintrag",\ "standardstrasse like 'Badenerstr%'", "")

inputbox(caption: string, prompt: string, default: string): string Einfaches Eingabefeld anzeigen.
  • caption: Titel des Forms
  • prompt: Einleitungstext
  • default: Default-Wert

print vtcapp.inputbox("Titel", \
"Geben Sie einen Text ein:", "")

>>> test

log(category: string, level: int, msg: string)

Log Message in Vertec Logging System. Levels vorhanden:

  • 10: Debug Log
  • 20: Info Log
  • 30: Warning Log
  • 40: Error Log
  • 50: Fatal Log
projekt = argobject
leistung = projekt.eval("offeneleistungen->first")
if leistung:
try:
leistung.xwertext = 0
except:
vtcapp.log("Leistungen anpassen",\
30, "Keine Berechtigung")
msgbox(msg: string) Message Box anzeigen (Versionen vor 6.0)

Als Titel wird Information und als Dialogtyp (Kombination Button / Zeichen) immer Info verwendet.

vtcapp.msgbox("Das ist ein Test")

msgbox(text: string [, int buttons: int, title: string]): int

Message Box anzeigen (Versionen ab 6.0)

Die Funktion wurde der entsprechenden VisualBasic-Funktion (vertec.msgbox) angeglichen und unterstützt nun (optionale) Argumente für Buttons und Title.

Der Aufbau der Buttons und der Rückgabewerte funktioniert wie bei der VB-Variante gemäss Win32 MessageBox Funktion. Siehe Informationen dazu im Artikel msgbox/inputbox: Beschreibung der Parameter.

readinivalue(section: string, value: string, default: string): string Werte lesen aus dem Vertec.ini File.

print vtcapp.readinivalue("database",\ "servername", "")

>>> XY:C:\Programme\Vertec\DB\VertecDemo.fdb

scriptexecute(scripttext, argobject=None)

Ermöglicht den Aufruf eines Vertec Scripts.

  • scripttext: Als Scripttext wird der eigentliche Code übergeben. Dies kann zum Beispiel der Text eines in Vertec registrierten Scripts oder aber auch ein Codetext selbst sein.
  • argobject: Mit diesem Parameter können Sie das Objekt angeben, auf dem das Script ausgeführt werden soll. Wird dieser Parameter weggelassen, wird das Script auf dem aktuellen Vertec-Objekt aufgerufen.
projektListe = vtcapp.evalocl("Projekt.\
allinstances->orderby(code)")
scripttext = vtcapp.evalocl("scripteintrag->\
select(bezeichnung='Projekt kopieren')->\
first.scripttext")
vtcapp.scriptexecute(scripttext)
selectfromlist (caption: string, text: string, col1caption: string, col2caption: string, default: string, list: list of tuple): string Erstellt einen Auswahldialog gemäss den Angaben.
  • caption: Titel des Forms
  • text: Einleitungstext
  • col1caption: Spaltentitel 1
  • col2caption: Spaltentitel 2
  • default: Default Rückgabewert
  • list: Liste mit den Values
projektliste = []
projekte= vtcapp.evalocl("Projekt.\
allinstances->orderby(code)")

for projekt in projekte:
projektliste.append((projekt.code,\
projekt.betreffend))

print vtcapp.selectfromlist\
("Projekt auswählen",
"Wählen Sie das Projekt aus:", "Code",
"Betreffend", "", projektliste)

>>> COMINSTALL
setlanguage(langcode: string [, persistent: boolean=False]) Stellt die Sprache in Vertec um.

vtcapp.setlanguage("EN")

setresourceplanvalue
(bearbeiter, projekt, phase, date, intervalType, value)

intervalTyp: 0 = Tag, 1 = Woche, 2 = Monat,

value: Wert in Minuten.

date: Es wird die Periode mit dem Value gefüllt, in der das Datum ist. Am besten nimmt man das Datum am Anfang der Periode, dann gibt es keine Unklarheiten.

Setzt einen Ressourcenplanwert. Verfügbar ab Vertec Version 5.7.0.16
showcustomdialog(dialogdefinition, initialwerte) Dialog-Funktion, mit welcher in Python Scripts Dialoge definiert und vom Script angezeigt werden können. Verfügbar ab Vertec Version 6.1. Eine detaillierte Beschreibung finden Sie im Artikel über die Python Dialoge.
showdetailform(obj: object) Form eines Objektes anzeigen

leistung = \
vtcapp.createobject("Offeneleistung")

vtcapp.showdetailform(leistung)

sqldateliteral(datum: date): date Diese Methode ergibt das richtige Datumsformat für SQL-Abfragen, je nach verwendetem Datenbankserver

import datetime
myaktivitaeten = vtcapp.getwithsql('aktivitaet', 'datum <= %s' % sqldateliteral(datetime.date.today()), '')

sqlwhere(where: string): string SQL Where Clause auf den aktuell verwendeten Datenbankserver anpassen.

vtcapp.sqlwhere("code like 'GH_%'")

strtodate(strDate: string): date Wandelt einen String in ein Datum um.

print vtcapp.strtodate('1.10.09')

>>> 2009-10-01 00:00:00

translate(txt: string): string Übersetzt einen GUI Text in die aktuelle Vertec Sprache.

vtcapp.setlanguage("EN")
print vtcapp.translate("Leistung")

>>> Service

updatedatabase() Speichert Änderungen in die Datenbank.

vtcapp.updatedatabase()

validateobjects() Validiert neuerstelle Objekte. Diese sind, sofern sie keine Regeln verletzen, danach nicht mehr ungültig.
vtcapp.validateobjects()

Datumsfunktionen für Python

Ab Version 5.7 gibt es für Python folgende neue Datumsfunktionen. Sie alle befinden sich im Modul vtcapp.

FunktionErklärung
incmonth(datum, int): datum inkrementiert Monat (+ oder -) und liefert das neue Datum zurück
incyear(datum, int): datum inkrementiert das Jahr (+ oder -) und liefert das neue Datum zurück
incday(datum, int): datum inkrementiert den Tag (+ oder -) und liefert das neue Datum zurück
incminute(datum, int): datum

inkrementiert Minuten (+ oder -) und liefert neues Datum zurück.

Das Datum, das übergeben wird, muss im Format Datetime sein, also einen Zeitteil haben.

firstdayofmonth(datum): datum liefert das Datum des ersten Tages im selben Monat zurück
lastdayofmonth(datum): datum liefert das Datum des letzten Tages im selben Monat zurück
firstdayofyear(datum): datum liefert das Datum des ersten Tages im selben Jahr zurück
lastdayofyear(datum): datum liefert das Datum des letzten Tages im selben Jahr zurück
thismonday(datum): datum liefert das Datum des Montags in derselben Wochen zurück
formatminutes(integer): string liefert Stunden-Minuten-Darstellung gemäss Einstellung in Vertec zurück
strtominutes(string): integer Interpretiert einen Stunden-Minuten string und liefert Anzahl Minuten gemäss Einstellung in Vertec
strtodate(string): datum Interpretiert einen Datumsstring gemäss Windows Ländereinstellungen (siehe Anmerkungen zur Verwendung von strtodate weiter unten).
ocldate(datum): string Liefert OCL encodedate string aufgrund eines Datumswertes (siehe Beispiel)

Beispiel

import datetime

vtcapp.ocldate(datetime.date(2012,01,31))

liefert encodedate(2012,1,31) zurück.

Anmerkung zur Verwendung von strtodate

Die Verwendung von strtodate ist heikel, da der String je nach Windows Ländereinstellungen interpretiert wird. So liefert die Expression vtcapp.strtodate('31.01.2012') einen Fehler, wenn es sich nicht um deutsche Ländereinstellungen handelt.

Im Code sollte deshalb immer die Python Datumsfunktion datetime.date(year, month, day) verwendet werden (siehe obiges Beispiel). Soll jedoch beispielsweise vom User ein bestimmtes Datum über eine Inputbox abgefragt werden, kann man das so machen, dass man ihm einen Datumsvorschlag im richtigen Format präsentiert, welcher von ihm entsprechend abgeändert werden kann. Dafür werden im Script zuerst die Ländereinstellungen abgefragt und das Datum entsprechend formatiert.

import locale
from datetime import datetime, date
from vtcapp import incmonth, lastdayofmonth

locale.setlocale(locale.LC_ALL, "")

#---default bis Datum: letzter Tag des letzten Monats
heute = date.today()
bis = lastdayofmonth(incmonth(heute, -1))

# Frage den Benutzer nach dem Datum. Datum gemäss Windows-locale dargestellt.
res = vtcapp.inputbox('Vertec', 'Bis-Datum für die Berechnung', bis.strftime('%x'))
if not res:
return
bis = vtcapp.strtodate(res).date()

Das Modul "vtcforms"

Dieses Modul wird verwendet, um eigene Forms zu erzeugen und anzuzeigen. Es hat folgende Funktionen:

Methode/FunktionBeschreibung
Application() Das Application-Objekt. Wird verwendet, um eine Messagebox anzuzeigen.

Das einzelne Vertec Datenobjekt

Für einzelne Objekte gibt es folgende Methoden:

Methode/FunktionBeschreibungBeispielcode

Eval(OCL:string)

oder

eval(OCL:string)

Evaluiert eine OCL-Expression auf dem Objekt

projektcode = argobject.eval("code")
delete() Löscht das Objekt in Vertec obj.delete()
getmemfootprint(): integer

Ab Version 5.8. Liefert als Resultat die Anzahl Bytes, welche das Objekt im Memory belegt (Memory Footprint).

Der Wert wird wie folgt bestimmt:

Instanz des Objekts

+ Summe der Instanzen aller Member

+ Grösse des Wertes jedes Members (bei Strings die Länge)

+ MemFootPrint aller owned linked Objekte (z.B. Phasen des Projekts).

Es ist zu beachten, dass es sich dabei um eine Annäherung handelt, da die Grenze, was bei einem Objekt alles gezählt werden muss, nicht genau gezogen werden kann.

Folgendes Script gibt den Memory-Bedarf aller Projekte im System aus:

r = vtcapp.evalocl("projekt")
for projekt in r:
print projekt.code + ' ' + \
str(projekt.getmemfootprint())

IsTypeOf(Classname:string)

oder

istypeof(Classname:string): boolean

Prüft, ob das Objekt vom Typ Classname ist.

True oder False.

obj = argobject # das aktuelle Objekt \
ist eine Firma in Vertec
obj.IsTypeOf("Projekt")
>>> 0 # false

obj.istypeof("Firma")
>>> 1 # true
hasattr(object, name): boolean

Überprüft, ob ein Objekt ein entsprechendes Member hat.

obj = adresse
if hasattr(obj, "vorname"):
print obj.vorname
getattr(object, name[, default])

Gibt den Wert eines Members zurück.

getattr(obj, "vorname")

ist äquivalent zu obj.vorname. Manchmal benötigt man getattr, weil man ein Member beispielsweise in einer Methode als Parameter bekommt und dann so abfragt.

Gibt es auf dem Objekt kein Member dieses Namens, gibt die Methode den default zurück, falls ein solcher angegeben ist. Ansonsten gibt es einen AttributeError.

getattr(obj, "vorname", "")
projekt = argobject
if hasattr(projekt, "offeneleistungen"):
liste = getattr(projekt, "offeneleistungen")
for leistung in liste:
print leistung.text

setattr(object, name, value)

Beschreibt das Attribut name des Objektes object mit dem Wert value.

So kann man beispielsweise durch die Zusatzfelder eines Objektes loopen und die gefundenen Attributnamen nuzen, um die Attribute zu beschreiben.

Dieser Code erstellt ein neues Objekt vom gleichen Typ wie das argobject und kopiert die Inhalte alle Zusatzfelder auf das neue Objekt.

source = argobject
target = vtcapp.createobject\
(source.eval('ocltype.asstring'))
zusatzfelder = source.zusatzfelder
for z in zusatzfelder:
zName = z.metazusatzfeld.fieldname

Nun weiss man den Namen des Zusatzfeldes, aber würde man es mit target.zName ansprechen, gäbe es eine Fehlermeldung "target has no attribute zName". Also verwendet man setattr:

setattr(target, zName, getattr(source, zName))
vtcapp.showdetailform(target)

Classname eines Objektes

Der Zugriff auf den classname funktioniert in Python nur über OCL:

obj.eval('ocltype.asstring')

Methoden auf einzelnen Objekten vom Typ "Rechnung"

Methode/FunktionBeschreibungBeispielcode
makeverrechnet([raiseException])

Ab Version 5.8. Verrechnet eine offene Rechnung.

Das Argument raiseException ist ein Boolean (Wahr/Falsch), welcher angibt, ob Fehler beim Verrechnen bzw. beim Verrechnen rückgängig gemeldet werden sollen.

raiseException ist optional, Default-Wert ist True.

Wenn raiseException False ist, dann werden Fehler beim Verrechnen ignoriert, die Rechnung bleibt dann einfach offen.

rechnung = argobject
rechnung.makeverrechnet(False)
makeoffen([raiseException])

Ab Version 5.8. Setzt eine verrechnete Rechnung wieder auf offen (Verrechnen rückgängig).

Das Argument raiseException ist ein Boolean (Wahr/Falsch), welcher angibt, ob Fehler beim Verrechnen bzw. beim Verrechnen rückgängig gemeldet werden sollen.

raiseException ist optional, Default-Wert ist True.

Wenn raiseException False ist, dann werden Fehler beim Verrechnen rückgängig ignoriert, die Rechnung bleibt dann einfach verrechnet.

rechnung = argobject
rechnung.makeoffen(False)
buchen([raiseException])

Ab Version 5.8. Bucht eine Rechnung in die Buchhaltung.

Das Argument raiseException ist ein Boolean (Wahr/Falsch), welcher angibt, ob Fehler beim Buchen bzw. beim Stornieren gemeldet werden sollen.

raiseException ist optional, Default-Wert ist True.

Wenn raiseException False ist, dann werden Fehler beim Buchen ignoriert, die Rechnung ist dann einfach nicht gebucht.
rechnung = argobject
rechnung.buchen()
stornieren([raiseException])

Ab Version 5.8. Storniert eine gebuchte Rechnung.

Das Argument raiseException ist ein Boolean (Wahr/Falsch), welcher angibt, ob Fehler beim Buchen bzw. beim Stornieren gemeldet werden sollen.

raiseException ist optional, Default-Wert ist True.

Wenn raiseException False ist, dann werden Fehler beim Buchen ignoriert, die Rechnung ist dann einfach nicht storniert.
rechnung = argobject
rechnung.stornieren()
importZahlungen()

Ab Version 5.8. Importiert die Zahlungen zur aktuellen Rechnung. Funktioniert nur, wenn die Debitorenschnittstelle den Zahlungsabgleich unterstützt.

argobject.importzahlungen()

Methoden auf einzelnen Objekten vom Typ "Projekteintrag"

Unter dem Begriff Projekteintrag werden Leistungen, Spesen und Auslagen zusammengefasst.

Methode/FunktionBeschreibungBeispielcode
makeverrechnet()

Ab Version 5.8. Setzt eine offene Leistung, Spese oder Auslage auf verrechnet.

Das funktioniert nur, wenn sich die Leistung, Spese oder Auslage nicht auf einer Rechnung befindet, ansonsten wird ein Fehler geworfen.

argobject.makeverrechnet()
makeoffen()

Ab Version 5.8. Setzt eine verrechnete Leistung, Spese oder Auslage auf offen.

Das funktioniert nur, wenn sich die Leistung, Spese oder Auslage nicht auf einer Rechnung befindet, ansonsten wird ein Fehler geworfen.
argobject.makeoffen()

04.03.2013 | 28.10.2016: Schreibfehler bei showdetailform korrigiert: Anführungszeichen fehlten bei vtcapp.createobject("Offeneleistung").
Produktlinien: Expert
Module: Leistung & CRM