Vertec XML Interface

Authentication

Session Handling

Requests

• Query objects (query)
• Create objects (create)
• Change objects (update)
• Delete objects (delete)

Responses

• Queryresponse
• Createresponse
• Updateresponse
• Deleteresponse

Special Cases

• Custom Field Items
• Writing keys / tags
• Queries of keys / tags
• Set a value to null
• Yes/No Values (Boolean)
• Set mlstring field
• Set date values

Sample Applications

Testing the xml extension

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

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

Object

• <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 object

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>

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.  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): NVProjektidee
• 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:    NVProjektideeENProject ideaITIdea progettoFRIdée projet

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

Company with reference number

The Reference number field on the company is a string field, so it can contain both text and numbers.

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

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>