Use the Vertec XML extension, data in Vertec can be queried, created, modified and deleted from the outside. It is therefore suitable for Vertec connections to third-party systems of all kinds.
Operating mode
Cloud Suite
|ON-PREMISES
Modules
Services & CRM
Budget & Phases
Purchases
Resource Planning
Business Intelligence
The Vertec XML extension is provided by the XML server, which is integrated into Cloud Server and thus runs automatically as soon as a running cloud server Cloud Server.
Note On-Premise: For the XML server to be active, the following setting must be settings in Vertec.ini:
[CloudServer] XML Server = true
The communication is based on the Request/ Response Schema. A client sends an XML-formulated request via HTTP POST and receives a response in XML as a result. The encoding is UTF-8, both when sending and receiving data.
The format of the XML messages used is based on the SOAP specification. Full SOAP compatibility is not implemented, especially the handling of XML namespaces is missing. Namespaces can be used in requests, but are ignored. The response messages also do not use namespace information.
The structure of the XML messages is basically always the same. For example, every message, whether request or response, always contains the basic element Envelope
with a sub-element Body
, in which the message is transported:
<Envelope> <Body> </Body> </Envelope>
Authentication to the XML server is done via Api token. This must be provided as Bearer
token in a Authorization
header. The also provided URL
corresponds to your Vertec address, i.e. the URL with which you access your Vertec e.g. via a Web App, followed by /xml
.
Example in Python:
import requests url = 'https://firma.vertec-cloud.com/xml' api_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ODc5ZDQ3OTItZmQxNi00ZWFjLWI5MzUtYT...' headers = {'Authorization': 'Bearer {}'.format(api_token)} xmlquery = """ <Envelope> <Body> <Query> <Selection> <ocl>projektbearbeiter</ocl> </Selection> </Query> </Body> </Envelope> """ response = requests.post(url, headers=headers, data=xmlquery) print(response.text)
/xml
the token is first checked for validity.a separate Vertec session process can be started per XML session to avoid performance problems with running sessions.
For this purpose, the Authorization
Header optional on VertecSessionTag
with any string value (e.g. '1'). A maximum of 36 symbols is allowed.
headers = {'Authorization': 'Bearer {}'.format(api_token), 'VertecSessionTag': '1'}
For each different combination of API token and VertecSessionTag, a new session is started automatically.
The following operations are possible via XML Request:
To test requests, Vertec sets the endpoint /xml/query
You can find a detailed description of this in the section Testing the xml extension The following examples are therefore written in such a way that you can put them directly into the Body
Insert part.
To query objects using XML Message, the query block is <Query>
-Element packed.
It contains the sub-elements:
<Selection>
: The Selection Element specifies which objects are queried.<Resultdef>
: The Resultdef element specifies which information of the selected objects should be returned.The response to a query (query) is returned in a Queryresponse element.
In Selection
Element The objects are queried. The following sub-elements can be used:
Element | description | Sample code |
---|---|---|
<objref> |
Query of individual objectsWith the In the same For a global query via OCL or SQL, the |
Single object: <Query> <Selection> <objref>676</objref> </Selection> </Query> Several single objects: <Query> <Selection> <objref>676</objref> <objref>12345</objref> </Selection> </Query> |
<ocl> |
Query via OCLIn
The filtering and sorting of the result list is done directly in OCL with the familiar Ocl operators ( Pay attention to high- high-performance access. |
OCL on one <Query> <Selection> <objref>1206</objref> <ocl>ownprojects</ocl> </Selection> </Query> Global OCL query:
<Query>
<Selection>
<ocl>projektbearbeiter->orderby(name)</ocl>
</Selection>
</Query> |
<sqlwhere> |
Query via SQLThe query via SQL is always global and cannot be combined with an OCL expression or a single object. It is used to query filtered lists directly from the database in a performance-optimized manner. For unfiltered lists (all objects of a class), use the Query via ocl instead. An SQL query is constructed as follows:
The executing user must have administrator rights or the SQL Query right. |
<Query> <Selection> <ocl>OffeneLeistung</ocl> <sqlwhere>fixedprice = 1</sqlwhere> <sqlorder>datum</sqlorder> </Selection> </Query> |
In Resultdef
Element the desired values are queried via OCL. These are then entered per object of the Selection
returned.
The basis for the OCL is the result or the result list of the Selection
. In order to create valid OCL expressions, you need to know what type (class) these results are. All Members listed on the corresponding class in the Vertec Model Browser are available (also calculated data fields (derived attributes).
As usual in OCL, you can not only query individual members, but also navigate through the model and calculate values. Keep in mind that the query is applied querying each object in the results list, and make sure that performance-optimized access for performance.
a convenient way to compile valid OCL expressions is to use the Ocl expression editor in the List Settings of a list in Vertec that contains objects of the same type as the results from the Selection
.
In Resultdef
Element The following subelements can be used:
Element | description | Sample code |
---|---|---|
<member> |
Query a single memberSpecifies a member of the result object in OCL. If the specified member is a stand-alone object, the Vertec object ID is returned (in the example for the member |
<Query> <Selection> <ocl>Session.allInstances->first.login.ownprojects</ocl> </Selection> <Resultdef> <member>code</member> <member>betreffend</member> </Resultdef> </Query> |
<expression> |
Query via OCL expressionFor conditions (
|
<Query> <Selection> <ocl>Session.allInstances->first.login.ownprojects</ocl> </Selection> <Resultdef> <member>code</member> <member>betreffend</member> <expression> <alias>OffeneLeistungen</alias> <ocl>offeneLeistungen.wertext->sum</ocl> </expression> </Resultdef> </Query> |
A Resultdef
Element is not mandatory. If only a single value is requested, this element can also be omitted. For example, the (global) Selection <ocl>projektbearbeiter->size</ocl>
returns the number of quantity. The Queryresponse then returns <Value>Anzahl</Value>
.
To create an object, a Create
Element used.
For each object that is to be created, a sub-element with the <Klassennamen>
of the object.
In it, for each member and association to be written, a sub-element with the <membernamen>
to be inserted.
<objref>
which contains the internal ID of the object to be linked.<Create> <OffeneLeistung> <bearbeiter><objref>1206</objref></bearbeiter> <projekt><objref>1195</objref></projekt> <minutenint>45</minutenint> </OffeneLeistung> </Create>
All classes are available in the Vertec Model Browser, which Persistent
are and no check mark at Abstract
have, and all members who do not Derived
are. Note that class names are always uppercase, members and associations are always lowercase.
The response to a Create Request is returned in a Createresponse element.
To change an existing object, a Update
Element used.
For each object to be changed, a sub-element is inserted with the object’s <Klassennamen>
. It contains the following sub-elements:
<objref>
: This specifies the internal ID of the object to be changed. It is important that this is specified at the top, i.e. before the other attributes, otherwise the changes will not be carried out.<membernamen>
inserted:<objref>
is inserted, which contains the internal ID of the object to be linked.<Update> <Projektbearbeiter> <objref>1206</objref> <kuerzel>CKE</kuerzel> <eigProjekte><objref>1192</objref></eigProjekte> </Projektbearbeiter> </Update>
The response to an update request is returned in an Updateresponse element.
To delete an object, a Delete
Element used.
This contains the objects to be deleted as sub-elements.
<objref>
: Specify the internal ID of the object to be deleted.<Delete> <objref>12345</objref> <objref>25088</objref> </Delete>
The response to a delete request is returned in a Deleteresponse element.
The response for a Query Request is QueryResponse
Item returned.
It contains the following sub-elements:
Return value | description | Sample response |
---|---|---|
Object |
With Resultdef Definition
|
<Envelope> <Body> <QueryResponse> <Projekt> <objid>1195</objid> <betreffend>Prozessberatung</betreffend> <code>PROCESS CONSULTING</code> <OffeneLeistungen>15’037.75</OffeneLeistungen> </Projekt> <Projekt> <objid>1192</objid> <betreffend>Laufende Betreuung</betreffend> <code>JOB MANAGEMENT</code> <OffeneLeistungen>16’644.85</OffeneLeistungen> </Projekt> </QueryResponse> </Body> </Envelope> |
Value |
If the result of the Query Requests is not an object, but a value, it is
|
<Envelope> <Body> <QueryResponse> <Value>7</Value> </QueryResponse> </Body> </Envelope> |
None |
If there is no return value, an empty |
<Envelope> <Body> <QueryResponse/> </Body> </Envelope> |
Date values are returned in ISO 8601 format.
The response to a Create Request is displayed in a CreateResponse
Item returned.
This contains for each created object the following sub-elements:
<Klasse>
: For each object, an element is returned with the object’s class, with the following sub-elements:<objid>
: Return the internal ID of the newly created object<isValid>
: Indicates whether the generated object is valid in Vertec (1
) or not (0
).<Envelope> <Body> <CreateResponse> <OffeneLeistung> <objid>12019</objid> <isValid>1</isValid> </OffeneLeistung> </CreateResponse> </Body> </Envelope>
Invalid Objects are still created in the system. These must be actively added (Update) or deleted (Delete). Alternatively, a Vertec full-featured app can be opened and the entries can be edited manually or are automatically deleted when the app is closed.
The response to an Update Request is UpdateResponse
Element returned, with a subelement:
<text>
: Indicates how many objects have been changed. <Envelope> <Body> <UpdateResponse> <text>Updated 1 Objects</text> </UpdateResponse> </Body> </Envelope>
The response to a Delete Request is returned in a DeleteResponse
element, with a sub-element:
<text>
: Indicate how many objects were deleted. <Envelope> <Body> <DeleteResponse> <text>Deleted 1 Objects</text> </DeleteResponse> </Body> </Envelope>
description | Sample code |
---|---|
Custom field itemsWriting values in Additional Fields works the same way as with normal members. As an element, simply the The different types of additional fields are written via XML as follows:
Custom field items are queried via OCL. |
Custom field item Project status on a project phasephase <Update> <Projektphase> <objref>5491</objref> <Projektstand>1</Projektstand> </Projektphase> </Update> |
Writing keys/tagsFor setting Keys and Tags via XML there are the following elements:
|
<Update> <Projektbearbeiter> <objref>4019</objref> <kuerzel>ABC</kuerzel> <keyvalue> <key>ExternalId</key> <value>123465</value> </keyvalue> <tag> <add>selected</add> </tag> </Projektbearbeiter> </Update> |
Queries of keys/tagsThe query of existing Keys and Tags takes place via OCL directly on the queried objects. |
<Query> <Selection> <ocl>projektbearbeiter->select(hasTag('selected'))</ocl> </Selection> </Query> |
Set a value to NULLTo clear (set to NULL) a value that is already set, you can assign an empty value to the attribute. In the example, the per diem is cleared on the user. |
<Update> <Projektbearbeiter> <objref>300</objref> <tagespauschaleext/> </Projektbearbeiter> </Update> |
Yes/No Values (Boolean)Yes/No values (Booleans) are given with
When querying Boolean values, there is a difference between built-in fields and custom field items. Build-in Boolean fields such as active on projects return ![]() However, the setting is the same in both cases, namely as described above with |
<Update> <Projekt> <objref>2880</objref> <aktiv>1</aktiv> </Projekt> </Update> If you need a uniform Queryresponse, you can specify an Expression that controls the return value for additional fields instead of custom field item simple <expression> <alias>myboolean</alias> <ocl>if zusatzfeldbool('myboolean') then 1 else 0 endif</ocl> </expression> |
Set MLString fieldFor Mlstring, a “record separator” with the code 30 (Hex 1E) is required, depending on the language and the term. It is not possible to set individual languages, all languages are always set. So if you do not specify one of the languages, it is empty afterwards, even if something was specified before the update request. Please note the following notes:
|
<Update> <Report> <objref>34741</objref> <designation>NVProjektideeENProject idea</designation> </Report> </Update> |
Set date valuesDate values must be specified in ISO 8601 format regardless of regional settings.
|
<Update> <OffeneLeistung> <objref>34743</objref> <datum>2025-07-01</datum> </OffeneLeistung> </Update> |
Application | Request | Example code |
---|---|---|
Company with reference numberThe Reference number field on the company is a string field, so it can contain both text and numbers. |
Query | <Query> <Selection> <ocl>Firma</ocl> <sqlwhere>referenz like '123456789'</sqlwhere> </Selection> </Query> |
Create a companyThe language of the company is indicated with an integer:
The address and the communication channels are independent objects and must be written separately (see below). The Createresponse returns the internal ID internal ID of the newly created company’s company which can then be used for further work. |
Create | <Create> <Firma> <name>Goldhaus AG</name> <zusatz>Standort Testenhausen</zusatz> <referenz>123456789</referenz> <sprache>1</sprache> <betreuer><objref>1206</objref></betreuer> </Firma> </Create> |
Determine address objectThe address or the corresponding address object is automatically created by Vertec when an address entry is created. To determine the address object, we ask – e.g. on the newly created company – Company |
Query | <Query> <Selection> <objref>4562</objref> <ocl>defaultadresse.adresse</ocl> </Selection> </Query> |
Write address dataWe can now write the address on the determined Address Object. |
Update | <Update> <Adresse> <objref>2865</objref> <adresse>Hauptstrasse 1</adresse> <plz>9999</plz> <ort>Testenhausen</ort> <kanton>Zürich</kanton> <land>Schweiz</land> </Adresse> </Update> |
Create communication channelsTo use a Communication Channel (class name:
The following fields are written:
If the newly created CommsChannel on the address entry is to be marked as Standard, it must additionally be linked to the address entry depending on the internal type of the Commaveragetypes address as follows:
Note: If a CommsChannel of this type is already marked as the default on the address entry, this will be removed as the previous default. |
Create | Query of the type, here 'T’ for phonephone <Query> <Selection> <ocl>kommMittelTyp->select(internerTyp='T')</ocl> </Selection> </Query> Create CommsChannel and link it as default: <Create> <KommMittel> <typ><objref>142</objref></typ> <eintrag><objref>4562</objref></eintrag> <zieladresse>043 219 87 65</zieladresse> <bezeichnung>Zentrale</bezeichnung> <fromDefaultTelefon><objref>4562</objref></fromDefaultTelefon> </KommMittel> </Create> |
Create a contact
|
<Create> <Kontakt> <firma><objref>4562</objref></firma> <name>Duck</name> <vorname>Donald</vorname> <gender>male</gender> </Kontakt> </Create> |
|
Assign a project to a keyword folderAssign a project’s here with internal ID) |
<Update> <Projekt> <objref>1170</objref> <ordner><objref>31426</objref></ordner> </Projekt> </Update> |
For testing Xml requests, a simple web interface is available at /xml/query
append this extension to the back of your Vertec URL in your browser.
Please note that this will allow you to access your real database and changes to your real data will affect your real data. We recommend that you set up an independent Test Installation for testing.
In the field API Token
the Api token is entered.
In the field XML Request
the body element of the Xml requests is entered.
The Xml response is displayed below after clicking on Submit Request
: