Vertec XML Interface

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

Created: 13.06.2022
Machine translated
Updated: 03.07.2025 | Article updated.

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>

Table of contents

Authentication

Session Handling

Requests

Responses

Special Cases

Sample Applications

Testing the xml extension

Authentication

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)

Session Handling

  • For an XML request on /xml the token is first checked for validity.
  • It then checks whether a Vertec session is already running for this token. If so, the request for this session is passed.
  • If no corresponding session exists yet, one is created (or removed from the Idle Pool).
  • An XML session has a session timeout of 5 minutes. If no new request for the session is received during this time, the session is completed. On-Premises this value can be adjusted in Vertec.ini if necessary.
  • If the session was exited due to the timeout, a new session is simply started. Thanks to the idle sessions, the delay is minimal even with a new session.

Start multiple session processes

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.

XML Request

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.  

Query objects (query)

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.

Selection

In Selection Element The objects are queried. The following sub-elements can be used:

Element description Sample code
<objref>
Query of individual objects

With the <objref> Element Individual Vertec objects can be queried by their Internal id.

In the same Selection several Vertec objects can also be interrogated in succession in this manner.

For a global query via OCL or SQL, the <objref> Element omitted.

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 OCL

In <ocl> Element can be given an Ocl expression expression. This is applied as follows:

  • Is a single  <objref> Element specified, the OCL is executed on it.
  • Is not <objref> Element specified, the OCL is executed globally.
  • Are several <objref> Elements specified, the OCL is not executed.

The filtering and sorting of the result list is done directly in OCL with the familiar Ocl operators (->select(), ->orderby() etc.).

Pay attention to high- high-performance access.

OCL on one <objref> Element:

<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 SQL

The 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:

  •   <ocl>: In the auxiliary element <ocl> the class name is specified. This is always capitalized. All classes are available in the Vertec Model Browser, which can be used in the Table Mapping field OWN and can therefore be found in the database under this name.
  • <sqlwhere>: In <sqlwhere> Element specifies the WHERE clause, i.e. the filter that is used on the <ocl> declared class is to be used.
  • <sqlorder>: Optional. The result list from <sqlwhere> can be used with the    <sqlorder> Element to be sorted.

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>

Resultdef

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 member

Specifies 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 projekt). Any number of members can be listed.

<Query>
    <Selection>
        <ocl>Session.allInstances->first.login.ownprojects</ocl>
    </Selection>
    <Resultdef>
        <member>code</member>
        <member>betreffend</member>
    </Resultdef>    
</Query>
<expression>
Query via OCL expression

For conditions (if-then-else-endif), calculations (mb1+mb2, ->sum etc.) or values of a linked object (Associations in the Vertec Model Browser), the <expression> Element used. It contains two sub-elements:

  • <alias>: Here you can specify the name under which the calculated value is output. Spaces and special characters are not allowed.    
  • <ocl>: The <ocl> Element contains the Ocl expression.    
<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>.

Create objects (Create)

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.

  • Members: For Members, the value to be entered is entered. Pay attention to the data type.
  • Associations: For association, the object to be linked must exist in Vertec and be known.
    • It becomes a sub-element  <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.

Change Objects (Update)

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.
  •   each member and association to be written, an element with the <membernamen> inserted:
    • Members: For Members, the value to be entered is entered. Pay attention to the data type.
    • Associations: For association, the object to be linked must exist in Vertec and be known.
      • a sub-element <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.

Delete objects (Delete)

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.

XML Response

QueryResponse

The response for a Query Request is QueryResponse Item returned.  

It contains the following sub-elements:

Return value description Sample response
Object
  • <Klasse>: For each object, an element is returned with the object’s class, with the following sub-elements:
With Resultdef Definition
  • <name>: Furthermore, all values requested under Resultdef are listed as individual items with the name of the requested member/association/alias.
    • If these objects are independent objects (e.g. when querying an association), the object reference (internal ID) in a <objref> Sub-element returned.
<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 <Value> Returns an element containing the query value.  

  • For Boolean (True/False) values, 1 for True and 0 returned for False.
<Envelope> 
  <Body> 
    <QueryResponse> 
      <Value>7</Value> 
    </QueryResponse> 
  </Body> 
</Envelope>
None

If there is no return value, an empty <QueryResponse /> Item returned.  

<Envelope> 
  <Body> 
    <QueryResponse/>
  </Body>
</Envelope>

Date values are returned in ISO 8601 format.

CreateResponse

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.  

UpdateResponse

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>

DeleteResponse

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>

Special cases

description Sample code
Custom field items

Writing values in Additional Fields works the same way as with normal members. As an element, simply the <name> of the additional field.

The different types of additional fields are written via XML as follows:

  • Symbols, text: pass text as value, without quotation marks
  • Boolean (true/false): 0 for false, 1 for True. See also description below.
  • Integer: Integer
  • Minutes: Integer
  • Fixed point number: Number with decimal places. Specify without thousand separators.  
  • Date: ISO 8601 format, see below.  
  • Selection: Integer with the position in the selection list, starting with 0

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/tags

For setting Keys and Tags via XML there are the following elements:

  • <keyvalue> with the sub-elements <key> and <value>
  • <tag> with the sub-elements <add> and <remove>
<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/tags

The 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 NULL

To 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 0 and 1 set:

  • 0: No
  • 1: Yes

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 1 and 0, but Boolean additional fields return Y and N.

However, the setting is the same in both cases, namely as described above with 0 and 1.

<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 <member> query:

<expression>
  <alias>myboolean</alias>
  <ocl>if zusatzfeldbool('myboolean') then 1 else 0 endif</ocl>
</expression>
Set MLString field

For Mlstring, a “record separator” with the code 30 (Hex 1E) is required, depending on the language and the term. &#30; is used.  

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:

  • The term is the same in all languages:  
    • Set only the NV (native): NV&#30;Projektidee&#30;
  • The term is different in different languages:
    • Set only the NV (Native) term (see above) and, if the term is not already translated automatically, enter a Translation Entry in Vertec to translate the entered term into the other languages.
    • Alternatively, set NV and the required languages (DE, DD, EN, IT, FR) in which the term differs from NV:    NV&#30;Projektidee&#30;EN&#30;Project idea&#30;IT&#30;Idea progetto&#30;FR&#30;Idée projet&#30;
<Update>
    <Report>
        <objref>34741</objref>
        <designation>NV&#30;Projektidee&#30;EN&#30;Project idea&#30;</designation>
    </Report>
</Update>
Set date values

Date values must be specified in ISO 8601 format regardless of regional settings.

  • Date: YYYY-MMMKTDD
  • Date and time: YYYY-MM-DD HH:MMMKTSS
<Update>
  <OffeneLeistung>
    <objref>34743</objref>
    <datum>2025-07-01</datum>
  </OffeneLeistung>
</Update>

Sample applications

Application Request Example code
Company with reference number

The 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 company

The language of the company is indicated with an integer:

  • 0: EN
  • 1: EN
  • 2: FR
  • 3: IT

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 object

The 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 defaultadresse.adresse (see also Uml model addresses) and receive the internal ID of the address object as a response.

Query
<Query>
  <Selection>
    <objref>4562</objref>
    <ocl>defaultadresse.adresse</ocl>
  </Selection>
</Query>
Write address data

We 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 channels

To use a Communication Channel (class name: KommMittel) on an address entry, two things must be known in advance:

  • The of the address entry addresse.g. of the new company created above) on which the means of communication is to communication channel created.
  • The of the Type Of Means Of Communication (class name: KommMittelTyp) in Vertec.

The following fields are written:

  • type: <objref> with the internal ID of the CommMittelType
  • entry: <objref> with the internal ID of the address
  • Target: The actual telephone number or e-mail address, URL, etc.
  • Designation: Optional. To show displayed in the list of communication channels on the address and for the sake of clarity.

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:

  • T: fromDefaultTelefon
  • M: fromDefaultMobile
  • E: fromDefaultEmail
  • H: fromDefaultHomepage
  • L: fromDefaultLinkedIn
  • F: fromDefaultFax

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
  • company = internal ID of the company
  • gender = male for male, female for female, or one of the additional genders defined in the system settings Address.
 
<Create>
  <Kontakt>
    <firma><objref>4562</objref></firma>
    <name>Duck</name>
    <vorname>Donald</vorname>
    <gender>male</gender>
  </Kontakt>
</Create>
Assign a project to a keyword folder

Assign a project’s here with internal ID)    1170) a keyword folder (here with internal ID    31426) to be added.

 
<Update>  
  <Projekt>
    <objref>1170</objref>
    <ordner><objref>31426</objref></ordner>
  </Projekt>
</Update>

Testing the XML Extension

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:

Netherlands

United Kingdom