Vertec Python functions

argobject

Current Vertec object. This variable is always available, so the call can be made without vtcapp..

project = argobject

bigetdata(source, dimensions, measures, from, till, currency=None)

As of Vertec 6.8. Python feature for querying Business Intelligence (BI) data.  

For a detailed description, see the article Python feature for querying bi data

projects = vtcapp.currentlogin().evalocl("ownprojects->select(active)")
result = vtcapp.bigetdata(projects, ["Project"], ["FeesExt"], None, None)
for project in projects:
    print("Fee: {}".format(result.get_value(project, "FeesExt")))

checkcreate(classname:string): int

Checks whether the current session has user rights to create objects of the specified class.

Returns 0 or 1 (False, True)

>>>  vtcapp.checkcreate('Project')
1

checkfeature(featurecode: string): boolean

Checks if a particular feature is licensed.

The feature codes are according to Vertec feature matrix (e.g. fcPhases for phases).

Returns False or True

>>>  vtcapp.checkfeature('fcPhases')
True

convertwordtopdf(wordDoc: string): string

Converts a Word document of type .docx to a PDF.

(name, file) = vtcapp.requestfilefromclient("Dokument wählen", r"C:", "Word|*.docx")
pdfDoc = vtcapp.convertwordtopdf(file)
vtcapp.sendfile(pdfDoc, 'aFilename.pdf' , True)

createoutlookmail(to, subject, body=”“, cc=”“, bcc=”“, attachments=[], show=True, onBehalfOf=”“)

Python method from version 6.4.0.4, which creates to create an email message on the client via Outlook.

Works with the Cloud App (and the Desktop App) and Outlook as a local Windows client.  

If you are working with the Web App or the New Outlook, the method sendmail() can be used (the “New OutlookOutlook for Windows is not a local Windows client, but a Web client, wrapped in a Windows program. createoutlookmail() does not work).  

• to: String. Recipient addresses, separated by ;, if more than one.
• subject: String. Subject of the email.
• body:
  • String. The actual email text. Can be HTML or plaintext. HTML is recognized as such and then created in the form of an Outlook HTML mail.
  • Starting with version 6.5.0.21, a Word document can also be used (see example below).

Optional:

• body: Optional as of version 6.7. If body not specified, an empty string or None, nothing is set in the created email.
• cc: String, Optional, Keyword*. Cc addresses, separated by ;, if more than one.
• bcc: String, Optional, Keyword*. Bcc addresses, separated by ;, if more than one.
• attachments: List of tuples, Optional, Keyword. List of attachments as a tuple of two strings[(file name, content)], see example below.
• show: Boolean, Optional, Keyword*. For True, the email is created and shown, for False, the email is saved in the drafts folder and not shown. Default value is True.
• onBehalfOf: String, Optional. Send the email with a different sender. Example: vtcapp.createoutlookmail("myemail@company.com", "Subject", onBehalfOf="noreply@vertec.com") opens an email with the sender noreply@vertec.com.

*Keyword means that you can specify the optional values with the parameter as a keyword, e.g. CC="abc@vertec.com". This way you do not need a specific quantity of commas as placeholders for unspecified optional values.

Examples:

• Simplest case, body as string:

  vtcapp.createoutlookmail("myemail@company.com", "aSubject", "Dies ist der einfachste Fall")

• Using Word documents as a body:

Note: Use tables in your Word documents and avoid tab stops, as they cannot be processed in the email.

1. The corresponding Word document must be loaded:

   (name, file) = vtcapp.requestfilefromclient("Dokument wählen", r"C:", "Word|*.docx")

2. Generate the email using the method:

   vtcapp.createoutlookmail('myemail@company.com', 'aSubject', file)

• show (specified by keyword):

  vtcapp.createoutlookmail("myemail@company.com", "aSubject", "aBodyText", show=False)

• Attachments:

  activity = argobject
  attachments=[('File1.txt', 'This is the content of file 1'),('Anhang.pdf', activity.content)] 
  vtcapp.createoutlookmail("myemail@company.com", "aSubject", "Eine E-Mail mit Attachments", attachments=attachments, show=False)

  The attachment name must not be empty.
• Body in HTML

  html="<html><body><p>Hallo</p><p>Dies ist eine Outlook Nachricht in HTML.</p><p>Es ist ziemlich einfach, verwenden Sie HTML BODY und P (Paragraph) wie hier dargestellt, und schon entsteht eine strukturierte E-Mail.</p><p>Möchten Sie <b>fettgedruckten</b>, <i>kursiven</i>, <u>unterstrichenen</u> Text, verwenden Sie die entsprechenden Tags.<span style=\"color: red\"> Sie können auch eine andere Farbe verwenden.</span></p><p>Freundliche Grüsse</p><p>Ihr Vertec Team</p></body></html>" 
  vtcapp.createoutlookmail("myemail@company.com", "aSubject", html)

createlist(classname, [list]): list

• classname: the class name of the objects that the list will contain. The class name is necessary so that the list itself contains static type information and can serve as a basis for evaluating OCL expressions.
• list (optional): the optional List argument allows constructing a list directly from another list. If the argument is not set, the generated list is empty and can be populated via append() or extend() method (see list of available methods on Vertec lists).

The python methods evalocl(), getwithsql(), and getmemberwithsql() automatically return vertec lists, see Vertec lists.

mylist = vtcapp.createlist('Project')
mylist.append(argobject)

or by specifying list:

mylist = vtcapp.createlist("Project", vtcapp.currentlogin().evalocl("ownprojects"))
mylist2 = list.evalocl("self->select(active)")

createobject(class: string)

leistung = vtcapp.createobject("OpenService")

currentlogin(): User

user = vtcapp.currentlogin()

currentobject

myobject = currentobject

disableevents()

As of Vertec 6.7.0.7 always use Disabledevents() instead.

With disableevents(), event scripting can be turned off, affecting the entire Vertec session (other Vertec sessions are not affected).

Used when you want to customize a certain attribute that would otherwise execute an event

. enableevents() can be switched on again.    

Requires extended user rights. Not allowed in the Python editor for security reasons.    

try:
    vtcapp.disableevents()
    invoice.entrydate = vtcapp.currentdate()
finally:
    vtcapp.enableevents()

DisabledEvents()

As of version 6.7.0.7. Must include with can be called:

with vtcapp.DisabledEvents():

Within this method, event scripting is turned off, affecting the entire Vertec session (other Vertec sessions or Desktop App are not affected).

Used, for example, to modify a certain attribute that would otherwise execute an event.

Require extended user rights. Not allowed in the Python editor for security reasons.

with vtcapp.DisabledEvents():
    invoice.entrydate= vtcapp.currentdate()

evalocl(expression: string): expressiontype

vtcapp.evalocl("user->select(active)")

evaloclstring(obj: object, expStr: string): string

Evaluate OCL expression within a string.

Returns: fully evaluated string.

>>> vtcapp.evaloclstring(argobject,"Bearbeiter %name% ist %level.asstring%")
Bearbeiter Christoph Keller ist Senior Consultant

evaltovariable(obj: object, ocl: string, varname: string)

Evaluates an OCL and saves the value in an OCL variable. The variable can then be queried globally with evalocl().

The variable name may be: self not used because this is a keyword. When used, an error message appears.

vtcapp.evaltovariable(argobject, "invoices->first", "varInvoice")

>>>  vtcapp.evalocl("varInvoice")
25050018, IT Consulting

executefile(command: string, [argumentString: string])

Feature to access files via Vertec Desktop App and Vertec Cloud App.

Command Line Parameters are also supported. You can optionally pass arguments for this. The previous simple case still works.

Parameter parsing is as follows:

• No parsing occurs in command. Spaces are interpreted as part of the path.
• Parsing occurs in argumentString, where spaces separate arguments unless they are enclosed in double quotation marks ““.

Only files of the type .doc, .docx, .xls, .xlsx, .pdf, .csv, .txt, .zip, .png, .jpg, .jpeg, .bmp, .gif, .eml and from Vertec 6.5.0.15 .ics can be executed directly (same Whitelist as sendfile()). For all others, there is a dialog asking if Vertec is allowed to open the file:

• If Yes, the path and name of the file will be remembered, and the dialog will not appear when the file is called again.
  This is done by an entry in the registry in the key: HKEY_CURRENT_USER\Software\Vertec\ExecuteFileWhiteList. The whitelisting applies only to the executable file and path, not to any arguments.
• If No, there is no write access to this part of the registry and the file cannot be remembered. A warning is written to the Logfile (Vertec.Cloud.log or Vertec.Desktop.log).

Examples

To open a Word file:

pfad = r'S:\Dokumente\Kontakte\Bistro Cooper\Brief.docx'
vtcapp.executefile(pfad)

The r in front of the path causes control characters to be ignored. Since the backslash is a control character in some combinations for Python, otherwise the path may be misinterpreted or fragmented, resulting in an error.

Open a file in Notepad++, using command line parameters:

vtcapp.executefile('notepad++.exe', r'-lpython "C:\Dokumente\Mein Script.py"')

executefolder(path: string)

Opens the specified folder on the client (without Web App), e.g. in Windows Explorer. The path must be accessible from the client.

If the folder does not exist yet, a message appears whether it should be created:

pfad = r'S:\Dokumente\Kontakte\Bistro Cooper'
vtcapp.executefolder(pfad)

The r in front of the path causes control characters to be ignored. Since the backslash is a control character in some combinations for Python, otherwise the path may be misinterpreted and an error may occur.

executereport(rootObj, optarg, reportObj, [saveAs, showDialog, doPrint, showApp]): report

Allows you to call and run Reports based on a report object. For
a table of availability with different systems, see the section further down.

• rootObj: The object on which the report will be run. Only a single object can be specified, not a list.
• optarg: Matches the optional address on the print dialog. Optional argument. If not used, specify parameters with None.
• reportObj: A Vertec report definition (class report). The report is executed based on this definition.
  • The settings of the report object for Save As and Show Dialog can still be overridden via the corresponding arguments of this method.
• saveAs: Optional. This string can also contain OCL expressions (separated by %).
  • Path (incl. file name) to save the report when Document Storage    Dateisystem oder DMS.
  • File name to save the report when Document Storage    Intern.
  • If an empty string is specified, no file is saved.
  • If None is passed, the saves under Settings are applied from the report object (reportObj).
• showDialog: Optional. Show the print dialog before execution. Possible Values: True or False.
  The display of messages such as “overwrite existing file” and “create new path” are controlled by this setting. If the parameter is not set, the corresponding setting from the report object (reportObj) is applied.
• doPrint: Optional. This value is only considered for legacy Office-generated reports prior to version 6.6.0.8. Possible Values: True or False. If True, the report is printed directly without opening the corresponding Office application.
• showApp: Optional. Specifies whether to open and show the report. Possible Values: True or False.

Examples

Show a Word report for invoice without dialog and without saving a filesave

rechTempl = vtcapp.evalocl("report->select(entryid='BerichtScriptInvoiceWithList')->first")
vtcapp.executereport(argobject, None, rechTempl, "", showDialog=False)

As of version 6.4.0.8 the method returns the report output as a byte string. This can be further processed and e.g. attached to an email via vtcapp.createoutlookmail().

invtempl = vtcapp.evalocl("report->select(entryid='BerichtScriptInvoiceWithList')->first")
pdf = vtcapp.executereport(argobject, None, invtempl, "", showDialog=False)
vtcapp.createoutlookmail("myemail@company.com", "aSubject", "aBody", attachments=[('invoice.pdf', pdf)])

executereport2(obj, optarg, template, [saveAs, showDialog, unused, showApp]): (report, activity)

Starting with version 6.4.0.22. Allow calling and executing Reports based on a report object.

The method returns a tuple consisting of the report output as a byte string and the corresponding activity.

For the description of the parameters see executereport() above.

For a table of availability with the different systems, see the section further down.

template = vtcapp.evalocl("report->select(entryid='BerichtScriptInvoiceWithList')->first")
reportdoc, activity = vtcapp.executereport2(argobject, None, template)

The method returns a tuple:

• Content of the resulting report document is (byte string).
• The created activity object or    None. An activity is only created when a report is saved.

execututeurl(url)

Opens the specified URL on the client (all full-featured apps).

The URL must be accessible from the client. The Web App must be a publicly accessible path, access to the local client is not possible.

For example, to open a website in the browser:

vtcapp.executeurl("https://www.vertec.com")

Or a Vertec Breadcrumb URL:

vtcapp.executeurl("vertec://CK-676/Own+projects-49/COMINSTALL-2880/")

the same also works as a short version, in which only the IDs are specified:

vtcapp.executeurl("vertec://676/49/2880/")

extractplaintext(file[, extension]): string

Vertec 6.8 or later. Used to extract (unformatted) text from files.

The method checks whether the passed file (bytearray) is one of the following types:

• PDF
• DOC(X)
• EML/MIME
• XLS(X)
• PPTX

If so, it extracts the text from these files and returns it as plaintext (string).

If the byte array does not represent any of the specified file types, or if reading the content fails, for example because the file is invalid or it is a password-protected PDF, a blank string is output.

Optional extension (from version 6.8.0.6): By specifying an extension, the file type is not determined based on the transferred file, but is specified via extension. Thus, the following file types are valid:        .pdf, .doc(x),    .eml/mime and .txt, and from version 6.8.0.7 .xls(x) and pptx. For TXT files, the content is interpreted as a plain text file. If an extension is specified and the passed file cannot be interpreted as such, an error message is returned instead of a blank string.

Document Storage Internal:

file = argobject.content
text = vtcapp.extractplaintext(file)

Document Storage File system/DMS:

filename, file = vtcapp.requestfilefromclient("Datei auswählen", r"C:\Dokumente", "PDF|*.pdf|DOCX|*.docx|EML|*.eml|MIME|*.msg")
text = vtcapp.extractplaintext(file)

fetchlinkmembers(objectlist, membername): objectlist

# Loop durch die Phasen von Projekten, welche mindestens eine Phase "erteilt" haben
projekte = vtcapp.getwithsql("Project", "bold_id IN (SELECT project FROM phase WHERE status=1)", "")
vtcapp.fetchlinkmembers(projekte, "phases")
for projekt in projekte:
    x = projekt.evalocl("phases->select(status=1)")

generateinvoicenumber()

Generates the next Vertec invoice number according to system settings invoice / invoice.

invoice = argobject
invoice.number = vtcapp.generateinvoicenumber()

getcurrentobject()

Returns the selected object in the tree and can be called from Ocl call operators using OCL call operators.

getmailattachment(content, idx): bytestring

From version 6.5. Allow you to download an email attachment of an activity.

Returns the contents of the attachment as a byte string.

Since the names of the attachments are not necessarily unique, it must be identified by Idx.

activity = argobject
filecontent = vtcapp.getmailattachment(activity.content, 0)

getmailattachments(content): list(string)

As of version 6.5. Return a list of attachment names of an activity.

filenames = vtcapp.getmailattachments(activity.content)

getmemberwithsql(obj: object, membername: string, where: string, order: string): list of objects

Allows querying members of an object via SQL.

The executing user must have administrator rights or the SQL Query right.

The extended user rights variant is available for granting temporary administrator rights.

project = argobject
servicelist = vtcapp.getmemberwithsql(project, "openservices", "xfeeext>200", "") 

getobjectbyentryid(classname: string, entryid: string): object

As of version 6.6.0.2. Get the object with the specified class and Entry Id

Both parameters must always be specified.

If the class classname does not exist or does not inherit from type Eintrag, an error is thrown.

If no or more objects are found, an error is thrown.

Note: The objects are loaded internally via SQL. Thus, only objects already stored in the database are found. For newly created objects, a vtcapp.updatedatabase() so that the object is found with this method.

folder = vtcapp.getobjectbyentryid("Folder", "KeywordFolderAdministration")

getobjectbyid(id: int, string or long*): object

Gets the object with the specified Internal Id.

If the id does not exist, an error is thrown.

Note: The objects are loaded internally via SQL. Thus, only objects already stored in the database are found. For newly created objects, a vtcapp.updatedatabase() so that the object is found with this method.

* As of Vertec 6.7.0.4.

obj = vtcapp.getobjectbyid(62162)

or

obj = vtcapp.getobjectbyid("62162")

getpropertyvalue(propertyname: string[, default=None]): value

Returns the value of the System Settings (Property) with the specified name (propertyname) back.

Optionally, a default Value. This is returned if the property with the specified name is not found. Default is None.

The return value depends on the type of property.

mycompany = vtcapp.getpropertyvalue("company")

getvertecserveraddress(): string

Returns the address where the Vertec Cloud Server is available from the Internet.

myurl = vtcapp.getvertecserveraddress()

Directly opens the Vertec App Portal in the browser:

vtcapp.executeurl(vtcapp.getvertecserveraddress())

getwithsql(class: string, where: string, order: string, [idfilterfeld: string, objectlist: list]): list of objects

This global SQL statement is used to filter lists to be filtered directly on the database in a performance-optimized manner (see the article Performance-optimized access to vertec objects).

A call via getwithsql() is only useful if a where clause is required. For unfiltered lists, use evalocl()() instead of getwithsql().

The executing user must have administrator rights or the SQL Query right. For granting temporary administrator rights, the variant of extended user rights is available.

• class: class name as string.
• where: SQL WHERE clause. This can also be done using the methods sqlwhere() and sqlwherebetweendate() can be created.
• order: SQL sort expression, usually a field name of the specified class.
  Can only be used if no idfilterfield/objectlist is specified.

• idfilterfeld: Name of the member by which the list should be filtered.
• objectlist: List of objects to be searched for in the field specified under idfilterfield.

In Vertec versions before 6.7.0.9 (before Firebird 5) lists (not the result list, but the filter criteria list, in the example on the right the projekte) of more than 1500 entries have to be worked with these filter criteria, otherwise an error message will appear.

Without optional filter criteria:

projektlist = vtcapp.getwithsql("Project", "bold_id IN (SELECT project FROM phase WHERE status=1)", "code")

With optional filter criteria:

projekte = argobject.evalocl("ownProjects")
leistungen = vtcapp.getwithsql("OpenService","", "entrydate", "project", projekte) 

getwithsqlbymember(class: string, member: string, expression: string, order [optional]: string): list of objects

• class: class name as string.
• member: Membername as string
• expression: comparison string (without delimiter). It can contain % wildcards, any string delimiter within
  the string will be escaped. The comparison is case-insensitive.
• order: SQL sort expression, usually a field name of the specified class.

When the feature is called, the user rights of the current user are checked on the member used for the selection. The user must have class-wide read permission on the member for the search to work. Otherwise, an error occurs.

projektliste = vtcapp.getwithsqlbymember("Project", "Code", "COM%")

importconfigset(xmltext: string/file): string

Before Vertec 6.7.0.7:

importconfigset(xmltext: string/file)

Import a config set into Vertec and apply it.

As xmltext, valid XML text is passed as a string (UTF-8) or a config set.

As of Vertec 6.7.0.7 the feature returns a string containing possible errors during the import.

(name, file) = vtcapp.requestfilefromclient("Config Set wählen", r"C:", "XML|*.xml")
vtcapp.importconfigset(file)

Or as an XML string:

xml="""<?xml version="1.0" encoding="utf-8"?>
<configset name="test" author="test"> <requirements /> <references/> 
<objects/> <settings> <system-setting name="GlobalDokPfad">C:\Dokumente</system-setting>
</settings></configset>""".encode('utf-8')
vtcapp.importconfigset(xml)

indexall([clean:boolean])

As of Vertec 6.8. Re-indexes all objects for Full Text Search.    

If clean is specified, the existing index is discarded and created.

vtcapp.indexall()

keeps the current index and supplements it with the changed objects.

vtcapp.indexall(True)

discards the existing index and creates it from scratch.    

indexclass(classname: string)

As of Vertec 6.8. Re-indexes objects of the specified class for Full Text Search.

If index configurations have been defined for the class passed with classname or if the System Settings for indexing documents or emails have been set for the class activity, all objects of this class are re-indexed with this feature.

If these conditions are not met, then nothing is done.

vtcapp.indexclass("Project")

indexlist(objectlist)

As of Vertec 6.8. The method takes a list of objects and re-indexes them for the Full Text Search.    

Objects for which no index should be written are automatically sorted out.

It is also possible to pass a single object as a list.

Indexing a single object:

vtcapp.indexlist([argobject])

Index list:

list = argobject.entries
vtcapp.indexlist(list)

 indexactivities(type: integer)

As of Vertec 6.8. This method can be used to re-index activities of a specific type for Full Text Search.    

One of the following values is passed as type:

• 0: Activities are re-indexed without document or email
• 1: All documents are re-indexed
• 2: All emails (incl. attachments) are re-indexed

vtcapp.indexactivities(1)

re-indexes all documents.

indexstatus(): dict

As of Vertec 6.8. Outputs indexing status information for Full Text Search-text search as a dictionary with the following information:

• IsAvailable: Boolean. True, if the server has been reached, otherwise False.
• OperationRunning: Boolean. True: A “complex” operation is current running. Only available if there is a connection to the index server.
• ProcessedObjectCount: Integer. Quantity of objects already processed. Only present if a “complex” operation is running.
• TotalObjectCount: Integer. Total number of objects to process. Only present if a “complex” operation is running.
• StatusMessage: String. Current status of the indexer.
• PercentCompletion: Double. Completed in percent (from 0 to 1). Only present when a “complex” operation is running.

This information is also output to the System Info in the new Indexing area.

Complex operations are indexall(), indexclass() and indexactivities()). Only one complex operation can be started at a time. If an attempt is made to start another, the Vertec Cloud Server acknowledges this with an error. indexlist() can be started at the same time, but when it is running, no additional complex operation can be started.    

print vtcapp.indexstatus()
{u'OperationRunning': False, u'IsAvailable': True, u'StatusMessage': u'idle'}

indexabort()

As of Vertec 6.8. Abort a current running indexing for Full Text Search.    

The queuing of the objects is canceled, already queued objects are indexed.

vtcapp.indexabort()

inputbox(caption: string, prompt: string[, default: string]): string

• caption: Title of the form
• prompt: introductory text
• default: Optional. Default value

The structure of the buttons and the return values works according to article msgbox/inputbox: description of the parameters.

vtcapp.inputbox("aTitle", "Geben Sie einen Text ein:")

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

Log Message in Vertec Logging System. Possible levels:

• 10: Debug log
• 20: Info log
• 30: Warning Log
• 40: Error log
• 50: Fatal Log

For more information, see Logging.

project = argobject
service = project.evalocl("openServices->first")
if service:
    try:
        service.xfeext = 0
    except:
        vtcapp.log("Change Service", 30, "Access denied on xfeeext")

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

Displays a message box.

The feature supports (optional) arguments for buttons and titles.

Buttons and return values work according to article msgbox/inputbox: description of parameters.

vtcapp.msgbox("Dies ist mein Text", 1, "Vertec")

msgtomime(msgcontent): mimecontent

From version 6.5.0.11. Convert .msg Convert files to MIME format.

Existing emails as .msg Files can be converted to be stored on an activity, for example via setemailcontent().

Note: With the Vertec Outlook App are stored directly on activities in MIME format.

(name, file) = vtcapp.requestfilefromclient("Email auswählen", r"C:", "Email|*.msg")
mimecontent = vtcapp.msgtomime(file) 
activity = vtcapp.createobject("Activity")
activity.setemailcontent(mimecontent)
vtcapp.showdetailform(activity)

pdfcombine(doc1:string, doc2:string): string

This method merges 2 PDF documents. The PDF documents are passed as a byte string.

newpdf = vtcapp.pdfcombine(pdf1, pdf2)

pdfextract(doc:string, pagefrom:int, pagetill:int): string

newpdf = vtcapp.pdfextract(pdf1, pagefrom, pagetill)

pdfpagecount(doc:string): int

pages = vtcapp.pdfpagecount(pdf1)

processbi(from: String, to: String, generator: String)

Method for calculating Bi data for the Business Intelligence module.

Corresponds to the calculation of the BI data on a Measure and triggers the calculation of the generator given as parameter.

From and To dates are specified as a string in the format “Year-Month”.

The generator must be specified in the same way as for the measures, i.e. “<Modulname>.<Generatorname>,” see example.

Requires administrator rights.

This method can also be automated, for example, via a planned task.

To calculate all generators of all active metrics, see the method vtcapp.standardprocessbi() below.

Example: From January 2024 to June 2025:

vtcapp.processbi("2024-01", "2025-06", "OffersGenerator.OffersGenerator")

querycallback(state): dict

Retrieves a callback previously registered via registercallback().

As soon as the callback has been performed, the feature returns a dictionary with all supplied parameters (including state). As long as the callback has not yet been performed, the function returns a dictionary with all supplied parameters (including state). None returned.

Callbacks that have already been successfully queried cannot be queried again, because the registration is then no longer available.

When querying via querycallback() in a loop (polling), it is important to have a delay with the help of    time.sleep Calls are built in so that the session is not blocked.

state=vtcapp.registercallback()
# Example only. Call via OAuth authentication instead.
vtcapp.executeurl("https://myserver.vertec-mobile.com/callback?State={}&message=ASecretMessage".format(state))
# Wait until browser is open.
time.sleep(3.0) 
values=vtcapp.querycallback(state)
print(values["message"])

readinvoicedocument(bytestream): resultobj

The readinvoicedocument() feature accepts vendor documents in the formats .pdf, .jpg and .png and processes the QR code contained therein (Swiss or EPC).

Returns a Python object with the following attributes:

*Optional data: will only be output if the QR code contains additional information.

name, receipt = vtcapp.requestfilefromclient("Belegdokument auswählen", r"C:\Dokumente", "*.pdf;*.jpg;*.png")
resultobj = vtcapp.readinvoicedocument(receipt)

suppliers = vtcapp.getwithsqlbymember("Address", "name", resultobj.Name)
supplier = suppliers[0]
currency = vtcapp.getwithsqlbymember("Currency", "designation", resultobj.Currency)[0]

creditor=vtcapp.createobject("Creditor")
creditor.supplier = supplier

if not creditor.documentdata:
    creditor.documentdata = vtcapp.createobject("DocumentData")
creditor.documentdata.data = receipt

creditor.accountnumber = resultobj.Account
creditor.reference = resultobj.Reference
creditor.currency = currency
creditor.amountgross = resultobj.Amount

if hasattr(resultobj, 'DocumentNumber'):
    creditor.number = resultobj.DocumentNumber

if hasattr(resultobj, 'DocumentDate'):
    creditor.entrydate = resultobj.DocumentDate

if hasattr(resultobj, 'DueDate'):
    creditor.xduedate = resultobj.DueDate

if len(creditor.outlays) == 1:
    outlay = creditor.outlays[0]
    outlay.quantity = None
    outlay.xfeeintfcgross = resultobj['Amount']

registercallback(): string

Registers a callback on the Cloud Server to transmit an authentication code.

This is required, for example, for Authentication via oauth. The return value is a randomly generated state string, which must be passed in the callback in order to be accepted.

The callback is executed as an http get request to the Cloud Server, as an example https://mein.vertec-cloud.com/callback?state=<statestring>&code=<authentisierungscode>.

The parameters transmitted with the callback can then be queried via querycallback().

state=vtcapp.registercallback()
# Example only. Call via OAuth authentication instead.
vtcapp.executeurl("https://myserver.vertec-mobile.com/callback?State={}&message=ASecretMessage".format(state))
# Wait until browser is open.
time.sleep(3.0) 
values=vtcapp.querycallback(state)
print(values["message"])

rendertemplate(templateString, data): unicode string

General-purpose template engine in Python, based on the Jinja2 template engine (http://jinja.pocoo.org). It is also available restrict scripting Cloud Suite and returns a Unicode string.

• The templateString argument can be a string or Unicode string, which can contain Jinja2 specific markups.
• With data the data from Vertec that is needed for rendering the text is passed:
  • Python Dictionary with string values as keys. Defines the variables available in the template.
  • Any quantity of keyword arguments that define the variables available in the template.
  • No further argument, the template will be processed without any data.

The main structures are as follows:

• A block is bounded with {% ... %}. It contains a control statement or a variable assignment.
  • {% if proj.code == "ABC" %} ... {% endif %}. An if statement in a block is used to output a range of the template conditional. A if must be completed by a endif. Optionally, a {% else %} in between is allowed.
  • {% for proj in projects %} ... {% endfor %}. A for statement allows repeating a template range. Must be completed by endfor.
• An expression is separated with {{ ... }}. An expression is evaluated in the context of the template and merged into the output of the template as a string.

# Beispiel Code für Ausgabe einer Projektliste
templateText = """
My own projects
===============
{% for proj in projects %}
Project: {{ proj.code }}, {{ proj.beschrieb }}
{% endfor %}
===============
"""
projects = vtcapp.evalocl("Session->first.login.ownProjects")
rendered_text = vtcapp.rendertemplate(templateText, projects = projects)
print rendered_text

renewdatabaseindexstatistics()

vtcapp.renewdatabaseindexstatistics()

requestfilefromclient(dialogTitle: string, directory: string, filter: string [, fileName: string]): (filename, file)

The format can contain several file types per filter.

• dialogTitle: Title of the dialog
• directory: Path of the directory to open in the dialog. If the path does not exist, the desktop is shown.
• filter: Filter expression to restrict the selection of files in the dialog. The filter expression changes with version 6.3.0.12, please see examples on the right.
• fileName: Absolute path of the file to be uploaded. This parameter is optional. If it is specified, no dialog will be shown in versions prior to 6.5.0.11.
  As of Vertec 6.5.0.11 a dialog will appear informing the user that Vertec wants to read this file, which he can acknowledge with Yes or No. If No, the process will be aborted and an exception will be thrown.

The method returns a tuple consisting of file names and file contents (before version 6.4.0.22 the method returns a tuple consisting of absolute file path including file names and file contents).

The maximum size of the file to be uploaded is 50 MB.
There is a blacklist of directories from which files may not be requested, e.g. the Windows environment variable SYSTEMROOT (typically C:\Windows).

If the user clicks on Cancel in the dialog, the error message appears in Python: RuntimeError: The file upload was canceled by the user.

Web App

If a client-side path is specified (parameter abspath), an error message appears in the Web App.

The start directory (parameters path) is ignored.

In versions prior to 6.4.0.8 the file dialog cannot show a custom dialog title. The parameter title is not considered until version 6.4.0.8.

For the filter, the designation is not shown, it only says “All support types (...)” and then the suffixes individually.

vtcapp.requestfilefromclient("Datei wählen", r"C:\Dokumente", "Python|*.py|Text|*.txt|XML|*.xml")

1. Wildcard must be specified (*.py instead of .py)
2. Filter expression consists of filter pairs, where each filter pair requires a name and an expression.
3. Pipes must be used as separators both between couples and within a couple between name and expression.
4. In case of multiple file extensions, they must be separated by semicolons instead of commas:

   vtcapp.requestfilefromclient("Datei wählen", r"C:\Dokumente", "Office Documents|*.docx;*.xlsx|Text|*.txt|XML|*.xml")

   Opens a dialog with the title “Choose File” in the directory C:\Documents, which allows you to upload Office, TXT or XML files.

A simple syntax is also supported:

vtcapp.requestfilefromclient("Datei wählen", r"C:\Dokumente", "*.txt")

Or a direct upload:

vtcapp.requestfilefromclient("", "", "", r"C:\Dokumente\MyFile.txt")

If a directory cannot be accessed, an error message is thrown:

vtcapp.requestfilefromclient("Datei wählen", r"C:\Windows\System32", "*.dll")

Version before Vertec 6.3.0.12:

vtcapp.requestfilefromclient("Datei wählen", r"C:\Dokumente", "Python|.py,Text|.txt,XML|.xml")

roundcurrency(amount, currency=None): float

Rounds the specified amount, taking into account the Project > Use rounding rules Use commercial rounding rules setting.

If a Currency is optionally entered, the value entered on it is also Runden auf taken into account.

Without currency indication:

amount = argobject.total
vtcapp.roundcurrency(amount)
5105.89

With currency indication:

amount = argobject.total
curr = argobject.currency
vtcapp.roundcurrency(amount, curr)
5105.9

search(term:string, [language:string, withsuggestions:boolean, datetimefrom: date, datetimeto:date, onlyactive:boolean]): SearchResult

Performs a Full Text Search in the indexed objects.

• term: The actual search term.
• language: Optional. Here you can specify a country abbreviation for the search. The language is only taken into account if it is also indexed (see System Settings Full Text Search). If a different value or None passed, the search is performed in the default language.    
• withsuggestions: Optional. True or False. Here you can specify whether similar terms should be taken into account. Default is False.
• datetimefrom, datetimeto: Optional. If from and/or to date is specified here, the results are filtered according to these dates.

• onlyactive: Optional, from version 6.8.0.3. True or False. This allows you to define whether only active or inactive objects should be found. By default, only active objects are shown via the search. The default of this feature is True. To show inactive objects as well, this property must be False can be set.

The method uses keyword arguments, so the optional parameters can be passed as follows:

• Without keyword, then the order must be followed:

  vtcapp.search("keller", "EN", False)

• With keyword (= parameter name), then the order does not play Role:

  vtcapp.search("keller", "EN", onlyactive=True, datetimeto=vtcapp.currentdate())

Returns a Python object of type SearchResult. It contains the following properties:

• objects: All business objects found with the search (as BoldObjectListAdapter).
• totalhitsapprox: Quantity of results found.
• items: List of SearchResultItems with the following properties:
  • object: The individual business object
  • score: Relevance value
  • fields: Location (in English)
  • date: date from index
  • fragments: List of text fragments.

A search returns a maximum of 500 business objects (SearchResultItems). These are sorted in descending order of relevance (score).

results = vtcapp.search("keller", "DE", False, datetimeto=vtcapp.currentdate())
for item in results.items:
    print item, item.fragments

With .objects you get a list of Vertec objects.    

results = vtcapp.search("consulting")
projects = results.objects.evalocl("self->select(oclIsTypeOf(Project))")

scriptexecute(scripttext, argobject=None)

Allows calling a Vertec script.

• scripttext: The actual code is passed as scripttext. This can be the text of a script registered in Vertec or a code text itself.
• argobject: This parameter allows you to specify the object on which the script should be executed. If this parameter is omitted, the script will be called on the current Vertec object.

proj = vtcapp.getobjectbyentryid("Project", "TemplateProject")
scripttext = vtcapp.evalocl("script->select(designation='Copy project')->first.scripttext")
vtcapp.scriptexecute(scripttext, proj)

selectaddress()

selectphase()

selectproject()

selectobjectintree()

From version 6.4.0.21. Allow calling the different search and selection dialogs for addresses, projects, phases and the tree directly from Python.

The methods support the following optional keyword arguments:

• selectaddress(string title, string classname, string filter)
  • title: Dialog title (Default: select Address)
  • classname: Address class in which to search, e.g. Firma. (Default: address)
  • filter: Additional SQL Filter condition (default: empty), e.g. only on active objects
  The address search dialog uses the default search definition according to system settings.
• selectphase(string title, string filter)
  • title: Dialog title (Default: select phases)
  • filter: Additional SQL Filter condition (default: empty), e.g. only on active objects
• selectproject(string title, string filter)
  • title: Dialog title (Default: select projects)
  • filter: Additional SQL Filter condition (default: empty), e.g. only on active objects
• selectobjectintree(string title, list entrylist, string browsefilter, string selectfilter)
  • title: Dialog title (Default: select Object)
  • entrylist: List of Vertec objects, which are displayed in the dialog as root elements.
  • browsefilter: Comma-delimited Filter for object types (e.g. Ordner, Expressionordner)
  • selectfilter: The selectfilter determines on which entries (classes and their subclasses) you can confirm the dialog and thus “selected,” also comma-delimited.

Return value is the selected object.

adresse= vtcapp.selectaddress(title="Address selection", classname="Contact", filter="firstname like '%S%'")

projekt = vtcapp.selectproject(title="Project selection", filter="code like '%S%'")

phase= vtcapp.selectphase(title="Phase selection", filter="code like '%S%'")

Kontakte = argobject.subordner
Kontaktordner = list(Kontakte)
Kontaktordner.append(argobject)
selected=vtcapp.selectobjectintree("Select object", Kontaktordner, "Folder, Contact", selectfilter="Contact")

selectfromlist (caption: string, text: string, col1caption: string, col2caption: string, default: string, list: list of tuple): string

• caption: Title of the form
• text: Introductory text
• col1caption: Column title 1
• col2caption: Column title 2
• default: Default return value or pre-selected row *)
• list: List of values to be shown for selection

The feature returns a string with the selected value. Only one value can be selected from the list.

*) To pre-select a row, the tuples of the list rows must consist of 3 elements. The third element is then the return value when the row is selected (this third column is invisible):

vtcapp.selectfromlist("","","","","2",[("one","eins","1"),("two","zwei","2")])

projectlist = []
projects = vtcapp.evalocl("Session->first.login.ownProjects")

for project in projects:
    projectlist.append((project.code, project.regarding))

vtcapp.selectfromlist("Project selection", "Select a project:", "Code", "Regarding", "", projectlist)

sendfile(file: string, filename: string, [showsavedialog: boolean], [openfile: boolean]): boolean

Sends a file or string (as a file) to a client.

Also works in Restricted Scripting mode.

• file: Here you can pass a string as file content or a Python file object.
• filename: Name of the file, if saved.
• showsavedialog: Optional. Default = False. Desktop and Cloud App The transferred file should be saved on the client saved or executed immediately depending on the client’s requirements and capabilities.
  A showsavedialog argument causes a save dialog to show displayed. By default, the desktop is shown as the locationshow
  If showsavedialog=false, the file is saved in the temp folder of the client’s having overwritten an existing file. This makes sense in connection with openfile=true, then the file is saved in Temp and opened immediately.

As of Vertec 6.5.0.11 the suppression of a dialog is only possible for the following file types (extensions). Whitelist:

.doc, .docx, .xls, .xlsx, .pdf, .csv, .txt, .zip, .png, .jpg, .jpeg, .bmp, .gif, .eml and from Vertec 6.5.0.15 .ics.
For all file types that are not on this whitelist, an error message appears.

• openfile: Optional. Desktop and Cloud App. If true, the file will be opened after saving. Default is true.

The combination showsavedialog=false and openfile=false does not make sense, as this saves the file in the temp directory and nothing else happens.

With the Web App as client, the file always appears as a download in the web browser. The arguments showsavedialog and openfile are irrelevant.

The method has a return value and returns True or False:

• True, if the file was saved,
• False if the file was not saved,
• The Web App always returns True because it cannot check if the file has been saved. When using the Web Web App we recommend that you turn on automatic download in your browser.

Example of a simple project export:

projekte = argobject.evalocl("ownprojects.list")
projektstr = ""
for projekt in projekte:
    projektstr += projekt.code + "\r\n"
vtcapp.sendfile(projektstr, 'projets.txt', True, True)

Example of how to send a locally available image:

filename = r"C:\Arbeitsverzeichnis\python_editor.png"
# opening for [r]eading as [b]inary
with open(filename, 'rb') as afile:
    vtcapp.sendfile(afile, 'aFilenameHere.jpg', True, True)

Files should be explicitly closed after use. Otherwise, they will only be closed by the garbage collector or, in case of failure, on the next exception. It is recommended to use open with with as in the example above.

sendmail(to, subject, body, [cc, bcc, fromSender, attachments])

Allows sending emails from Vertec with the requirements described in System Settings Email. This method can be used with all apps.

• to: String. Recipient addresses.
  • Using a semicolon ; several addresses can also be specified, without a distance between the addresses and the semicolon.
• subject: String. Subject of the email.
• body:
  • String: The actual email text. Can be HTML or plaintext. HTML is recognized as such and then created in the form of an Outlook HTML mail.
  • Starting with version 6.5.0.21, a Word document can also be used (see example below).

Optional:

• fromSender: String. if null or empty, the sender is removed from the system settings. User rights etc. are not checked, it must be ensured that the user is authorized to send emails under this sender, otherwise it will not work on the client side.
  • Note: cannot be overridden in the Cloud suite without own smtp.
• cc: String. If populated as CC recipient.
• bcc: String. If filled as BCC receiver.
• attachment: [(file name, content)]: If filled in, the attachment will be attached to the email.

Examples:

• Simplest case, body as string:    

vtcapp.sendmail("dokumentation@vertec.com", "Dokumentation", "Dies ist der einfachste Fall")

• Use Word documents as a body:
  Note: Use tables in your Word documents and avoid tab stops, as they cannot be processed in the email.

1. The corresponding Word document must be created and read:

in_file = open("C:\<yourPath>\BeispielWordFürEmail.docx", "rb")
dataFileData = in_file.read()

2. Use the method to generate the email:    

vtcapp.sendmail('dokumentation@vertec.com', 'Test E-Mail from Word', dataFileData)

setpropertyvalue(name, value)

Sets a system setting. The corresponding name is specified for each system setting.

vtcapp.setpropertyvalue('Sperrdatum', vtcapp.incmonth(vtcapp.currentdate(), -1))

setresourceplanvalue
(user, project, phase, date, intervalType, value)

Only Vertec versions before 6.6. From Vertec version 6.6 onward, use the setresourceplanvalue Methods on Users, Projects or Phases.

Sets a resource plan value.

• intervalType: 0 = day, 1 = week, 2 = month
• value: Value in minutes.
• date: The period is filled with the value in which the date is. It is best to take the date at the beginning of the period, then there are no ambiguities.

bearbeiter = vtcapp.currentlogin()
projekt = argobject

vtcapp.setresourceplanvalue(bearbeiter, projekt, None, vtcapp.firstdayofmonth(vtcapp.currentdate()), 0, 240)

showcustomdialog(dialog definition, initial values)

Dialog function with which dialogs can be defined in Python scripts and shown by the script.

showdetailform(obj: object)

service = vtcapp.createobject("OpenService")
vtcapp.showdetailform(service)

standardprocessbi()

Method for calculating Bi data for the Business Intelligence module.

Corresponds to the execution of the planned task supplied by default and triggers the calculation of all generators on all active measures.

Requires administrator rights.

To calculate individual generators, see the method vtcapp.processbi() above.

vtcapp.standardprocessbi()

strtominutes(string): integer

Display minutes is hours:minutes:

print vtcapp.strtominutes('1:30')
>>> 90

print vtcapp.strtominutes('1.50')
>>> 110

Display minutes is hours.Decimal:

print vtcapp.strtominutes('1.50')
>>> 90

sqldateliteral(date: date): string

aktivitaeten = vtcapp.getwithsql('Activity', 'entrydate = %s' % vtcapp.sqldateliteral(vtcapp.currentdate()), '')
for akt in aktivitaeten:
    print akt

sqlwhere(where: string): string

whereclause = vtcapp.sqlwhere("standardstreetaddress like 'Dachsweg%'")
adressen = vtcapp.getwithsql("Address", whereclause, "bold_id")
print whereclause

>>> upper(standardstreetaddress) starting with 'DACHSWEG'

query:string, from: date, to: date): string

Creates a SQL between clause with a date interval corresponding to the database server current in use, which is then getwithsql Statement can be incorporated.

today = vtcapp.currentdate()
whereclause = vtcapp.sqlwherebetweendate('entrydate', vtcapp.firstdayofmonth(today), today)
print whereclause

>>> entrydate between '01.08.2025' and '07.08.2025'

syncpayments()

Starting with version 6.4.0.22. Perform a global payment import.

If no debit interface with payment import is installed, the method reports an error.

vtcapp.syncpayments()

For example, the method can be registered as a planned task.

SystemContext()

As of version 6.6.

Activates Extended user rights within the script.

• Must be with the with-Statement can be called.
• Not allowed in the Python editor for security reasons.

with vtcapp.SystemContext():
    ...Code der vom Systemcontext profitiert.

translate(txt: string[, language:string]): string

Translates a text into the current Vertec language.

An optional parameter for the target language of the translation can be used.

See also article Multilingualism with vertec.

The current Vertec language is German:

>>> vtcapp.translate("Service")
Leistung

Specifying the target language:

>>> vtcapp.translate('Service', 'FR')
Prestation

updatedatabase()

vtcapp.updatedatabase()

validateobjects()

Validates rebuild objects. If they do not violate any rules, they are no longer invalid afterwards.

vtcapp.validateobjects()

versiontointeger(versionstring): int

>>> vtcapp.versiontointeger("6.8.0.7")
6800007

>>> vtcapp.versiontointeger("6.8")
680000