XML import interface

XML import schema

Requirements

The file \client\jboss\custom\configuration.bat must have the parameter SET XML_IMPORT_DIR= set. (e.g. SET XML_IMPORT_DIR=c:\Temp\xmlimport\monitored)
The CURSOR web service module must be licensed.
The directory must exist to allow starting the monitoring. In this directory, a subdirectory must exist with the Windows token of the user. Directory monitoring will not start if it doesn't exist

Import start

The importer starts when the application starts, provided the following requirements are met:

The parameter XML_IMPORT_DIR is set
The named directory exists
A subdirectory with the token of the current user (Windows user name) exists
No lock.txt file exists in the subdirectory with the user token

The monitoring of the import directory commences if these requirements are met.

The 'lock.txt' file

The file lock.txt ensures that only one client on the computer can initiate the import. If the file is deleted, the import monitoring is automatically stopped.
If the file is older than 24 hours at the start of the application, the file is deleted and the import is started.
The file is deleted when the application is closed normally. The file can be deleted manually if it was not automatically deleted due to e.g. a program crash to make sure that monitoring will commence again at the next program start.

Import workflow

The system checks every 10 seconds if there are new files with the ending xml. This time interval can be configured via a PropertyMapper entry:

SQL

 INSERT INTO PropertyMapper (Pk, id, property, PropertyType, principal, PropertyValue, CustLayer, Active, CreateDate, CreateUser, UpdateDate, UpdateUser, STATUS, RightPk, ClientNo, MassData)
VALUES ('SYSTEM.XMLImporter.ImportPeriod', '/de/cursor/jevi/client/swingclient/importer/SchemaXMLImporter$!!$ImportPeriod', '' ,'SYSTEM', '', '30000', 'CN' 1,
GETDATE(), 'TECH_USER', GETDATE(), 'TECH_USER', NULL, NULL, NULL, 0)

The time is stated in milliseconds, which means that '30000' represents 30 seconds. This entry can also be updated:

SQL

 UPDATE propertymapper SET propertyvalue = '50000' WHERE pk = 'SYSTEM.XMLImporter.ImportPeriod'

The system will check first, whether the file is part of the XML import or a file for the import via schema. It will be a schema import if a Config tag exists with the filled attributes "version" and testRun. If this is not the case, the file is moved to the failure subdirectory.
The import is then started.
If the import was successful, the XML file is moved to the success directory. The returned import result is also moved to the success directory. The file has the same name as the imported file, with the addition of _Result. If the file to be moved exists in the success directory, then the current date will be appended to the file name in milliseconds (System.currentTimeMillis) to make the file name unique.
If the import was not successful, the XML file is moved to the failure directory. If there was an XMLImportException during import, then the returned entries will also be moved to the directory failure (with the added ending _Result). Once again the rule applies that if the file already exists in the failure directory, then the milliseconds of the current date are appended.

Structure

Input

Tags and their attributes for input

Tags	attributes	Default value	Possible values	From version
Entries	-	-	-
Config	transactionTime	Value must be set	Time in seconds a transaction is permitted to take
	version	Value must be set	The version of the application into which the import should be done
	testRun	Value must be set	true, false
Entry	entity	Value must be set	All existing entities
	action	Value must be set	CREATE - create dataset UPDATE - Update dataset. Searches only below the parent dataset (where used in relation). UPDATE_OR_CREATE - Update dataset if one was found, otherwise create new one. Searches only below the parent dataset (where used in relation). LINK_AND_UPDATE - Update dataset and link to parent set. Searches below the parent dataset first and again on the main level if nothing is found. LINK_AND_UPDATE_OR_CREATE - Update dataset if one was found, otherwise create new one and link to parent set. Searches below the parent dataset first and again on the main level if nothing is found. DELETE_DATA - Set dataset to inactive. Searches only below the parent dataset (where used in relation). DELETE_LINK - Remove the link between this dataset and the parent. Searches only below the parent dataset (where used in relation).
	found	Value must be set	ZERO - No dataset found ONE - Exactly one dataset found N - None, one or several datasets found NO_SEARCH - No dataset search
	relation	Empty string	The matching relation between the current entry and the parent entry
	rightTemplate	Empty string	The rights template to be set. This only works for new creations, not for updates. The template must be of type Data right. The entity must be rightable.
Field	name	Must be set	The attribute name of the field to edit
	fieldType	VALUE	PK - The value is a primary key VALUE - The value is a display value
	identifyingField	false	true, false
	clearUnknown	false	true, false	13.2
	function	IS_EQUAL	IS_EMPTY - is empty IS_NOT_EMPTY - is not empty IS_EQUAL - is equal to IS_NOT_EQUAL - is not equal to STARTS_WITH - starts with STARTS_NOT_WITH - does not start with ENDS_WITH - ends with ENDS_NOT_WITH - does not end with CONTAINS - contains CONTAINS_NOT - does not contain IS_SMALLER_THEN - is less than IS_GREATER_THEN - is greater than IS_EQUAL_OR_SMALLER_THEN - is equal to or less than IS_EQUAL_OR_GREATER_THEN - is equal to or greater than	13.2
EntityLookupField	name	Must be set	The attribute name of the field to edit
	identifyingField	false	true, false	11.2
Link	pk	Must be set	The pk of the dataset to be linked
	entity	Must be set	The entity of the dataset to be linked
	relation	Must be set	The appropriate relation between the entry to be linked and the current entry

Entries

The 'Entries' tag is the basic element of the XML structure. It does not contain any attributes during input.

Entry

The Entry tag must be used for each dataset to be processed.

entity contains the entity of the dataset.
action contains the action to be executed.
found determines the number of data found at which an action is to be executed.
rightTemplate can attach a rights template to the dataset. This only works for new creations, not for updates. The template must be of type Data right. The entity must have rights assigned
relation is set depending on whether the Entry tag is nested or used at the main level and contains the relation between the two datasets.

XML

<Entry entity="Customer" action="CREATE" found="ZERO" rightTemplate="MSG-Dateien">
...
</Entry>

<Entry entity="Customer" action="CREATE" found="ZERO">
	...
	<Entry entity="Customer" action="DELETE_LINK" found="ONE" relation="rCuCu">
	...
	</Entry>
</Entry>

Config

The Config tag is used to configure the call, is mandatory and always looks the same. It is the first element in every file or every call.

transactionTime specifies the maximum time the call may last before it is rolled back.
version should contain the version of the application for which the call was written. This allows you to determine whether the application is compatible with the call.
testRun switches between the test mode and the actual import. The test mode simulates all import processes and rolls back the transaction at the end. The user receives information on how the import would have gone.

XML

 <Config transactionTime="300" version="9.2" testRun="false"/>

The transactionTime parameter defines how long the import process should last (in seconds). An import can last a maximum of 24 hours. (transactionTime = 86400)

Field

All values are specified in 'Field' tags.

name contains the attribute name of the field to be set.
identifyingField specifies whether this field is included in the search for existing data. Large text fields, such as the activity text, must not be labeled as identifying.
fieldType can specify that the key is not validated in the case of a lookup field. In this case, the Pk of the key would have to be specified directly instead of the key.
clearUnknown can specify, in the case of a lookup field, that the empty key is entered if the empty key is allowed in the field and the lookup value is not found.
function specifies how to search for the identifying fields. By default, the system searches for the specified value with parity. However, it is possible to specify that it must only contain, be larger or smaller, etc. Not every function may be set on every field type. See the table below for more details.

XML

<Field name="FirstName.ContactPerson" identifyingField="true" function="STARTS_WITH">
    <FieldValue>
        <stringValue>Cornelia</stringValue>
    </FieldValue>
</Field>
 
<Field name="DelegatedBy.Activity" identifyingField="false" fieldType="PK">
    <FieldValue>
        <stringValue>ged-personpk34#employee19</stringValue>
    </FieldValue>
</Field>
 
<Field name="Priority.Activity" clearUnknown="true">
    <FieldValue>
        <stringValue>UNKNOWNKEY</stringValue>
    </FieldValue>
</Field>

Different tags must be used depending on the data type of the field:

CODE

Datum: 							<dateValue>2008-04-20</dateValue> 		oder 	<dateTimeValue>2008-04-20T17:00:00</dateTimeValue>
 
Text: 							<stringValue>mein Text</stringValue>
 
Nachschlagefeld: 				<stringValue>BNE</stringValue>
 
Ganzzahl: 						<intValue>532</intValue> 				oder 	<longValue>253456345</longValue>
 
Zahl: 							<doubleValue>34.34</doubleValue>


Zahl mit hoher Genauerigkeit:	<bigDecimalValue>1234567890.0987654321</bigDecimalValue>
 
Wahrheitswert: 					<booleanValue>true</booleanValue>

Function	Can be used for data type
IS_EMPTY	Text, number, large text fields, date
IS_NOT_EMPTY	Text, number, large text fields, date
IS_EQUAL	Text, lookup field, number, logical value, date
IS_NOT_EQUAL	Text, lookup field, number, date
STARTS_WITH	Text, lookup field, large text fields
STARTS_NOT_WITH	Text, lookup field, large text fields
ENDS_WITH	Text, lookup field, large text fields
ENDS_NOT_WITH	Text, lookup field, large text fields
CONTAINS	Text, lookup field, date
CONTAINS_NOT	Text, lookup field, date
IS_SMALLER_THEN	Text, lookup field, number, date
IS_GREATER_THEN	Text, lookup field, number, date
IS_EQUAL_OR_SMALLER_THEN	Text, lookup field, number, date
IS_EQUAL_OR_GREATER_THEN	Text, lookup field, number, date

EntityLookupField

In order to populate lookup fields where the value is not known, use the EntityLookupField tag. The attribute name of the field to be populated is specified in name. Then any number of field tags can be specified to uniquely identify the value. These should each have the identifyingField attribute set to true.

XML

<EntityLookupField name="DefaultContactPerson.Activity">
	<Field name="FirstName.ContactPerson" identifyingField="true">
		<FieldValue>
			<stringValue>Cornelia</stringValue>
		</FieldValue>
	</Field>
	<Field name="LastName.ContactPerson" identifyingField="true">
		<FieldValue>
			<stringValue>Altenhain</stringValue>
		</FieldValue>
	</Field>
	<Field name="CustomerKey.ContactPerson" identifyingField="true">
		<FieldValue>
			<stringValue>CURSOR GIESSEN</stringValue>
		</FieldValue>
	</Field>
</EntityLookupField>

As of version 11.2, identifyingField can be used in the same way as the attribute on the field tag. This specifies whether this field is included in the search for existing data.

XML

<EntityLookupField name="DefaultContactPerson.Activity" identifyingField="true">
	<Field name="FirstName.ContactPerson" identifyingField="true">
		<FieldValue>
			<stringValue>Cornelia</stringValue>
		</FieldValue>
	</Field>
	<Field name="LastName.ContactPerson" identifyingField="true">
		<FieldValue>
			<stringValue>Altenhain</stringValue>
		</FieldValue>
	</Field>
	<Field name="CustomerKey.ContactPerson" identifyingField="true">
		<FieldValue>
			<stringValue>CURSOR GIESSEN</stringValue>
		</FieldValue>
	</Field>
</EntityLookupField>

Link

The link tag can be used to create links as an alternative to nesting datasets.

pk must contain the primary key of the dataset to be linked.
entity must contain the entity of the dataset to be linked.
relation must contain the relation between the current dataset and the dataset to be linked.

XML

<Link pk="ged-activitypkToepper4" entity="Activity" relation="rCoPeAc"/>

Output

All field tags marked as identifying, all link tags, and all EntityLookupFields are returned. There are also a number of other informative tags. An example of a return structure:

XML

<Entries success="true">
    <Config testRun="false" version="9.2" transactionTime="300"/>
    <Entry found="ZERO" action="CREATE" entity="Activity">
        <CompletionType>SUCCESS</CompletionType>
        <ModificationType>CREATE</ModificationType>
        <PrimaryKeys>
            <Pk value="3fnvmsi143btagn0Ac"/>
        </PrimaryKeys>
        <Field identifyingField="true" name="Subject.Activity">
            <FieldValue>
                <stringValue>Umstieg Lohn: Zentralverband Elektrotechnik</stringValue>
            </FieldValue>
        </Field>
        <Field identifyingField="true" name="FreeText2.Activity">
            <FieldValue>
                <stringValue>Umstieg kann erfolgen.</stringValue>
            </FieldValue>
        </Field>
    </Entry>
</Entries>

Tags and their return attributes

Tags	attributes	Default value	Possible values
Entries	success	Value is set in response	Status of the import: Success/Failure
ErrorMessage	-	-	-
CompletionType	type	Set appropriately by the system	SUCCESS, ERROR
ModificationType	type	Set appropriately by the system	CREATE, UPDATE, DELETE, LINK, UNLINK, NO_MODIFICATION
Pk	value	Set appropriately by the system	The Pk of the edited dataset

Entries

In the return structure, the entries tag has the success attribute. Using this attribute you can recognize at first glance whether the import has worked or whether an error has occurred somewhere.

XML

<Entries success="true">

ErrorMessage

Any error messages are displayed in the ErrorMessage tag. It can appear below Entry, Field and EntityLookupField.

XML

<ErrorMessage>Das Feld existiert nicht in dieser Entität!</ErrorMessage>

CompletionType

The CompletionType tag indicates whether an Entry was successfully processed or not.

XML

<CompletionType>SUCCESS</CompletionType>

ModificationType

The ModificationType indicates what has been changed in the Entry. For example, if the dataset was updated, UPDATE is shown here. If nothing happened, the value would be NO_MODIFICATION. NO_MODIFICATION can also be specified in the case of success, for example, if you only want to delete if exactly one dataset was found (found "ONE").

XML

<ModificationType>CREATE</ModificationType>

PrimaryKeys

The 'PrimaryKeys' tag is only for collecting the Pk tags and has no other attributes.

Pk

In Pk tags (in the value attribute), the Pks of all datasets are returned that had an effect on the processed actions. For example, the pks of created, updated, deleted or linked datasets are returned. As are the pks of all datasets found based on the identifying fields, if nothing was done because there was no uniqueness.

XML

<Pk value="3fnvmsi143btagn0Ac"/>

Tag order

The following tag order must be observed:

Config
Entry
- Field
- EntityLookupField
- Link
- Entry
  - Field
  - ...
Entry
...

XML

<Entries>
    <Config transactionTime="" version="" testRun=""/>
 
    <Entry entity="" action="" found="" rightTemplate="">
        <Field name="" identifyingField="">
            <FieldValue>
                <stringValue></stringValue>
            </FieldValue>
        </Fields>
        <Field name="" identifyingField="">
            <FieldValue>
                <stringValue></stringValue>
            </FieldValue>
        </Fields>
        <EntityLookupField name="">
            <Field name="" value="" identifyingField=""/>
        </EntityLookupField>
        <EntityLookupField name="">
            <Field name="" value="" identifyingField=""/>
        </EntityLookupField>
 
        <Link pk="" entity="" relation=""/>
        <Link pk="" entity="" relation=""/>
        <Link pk="" entity="" relation=""/>
        <Entry entity="" action="" found="" relation="">
        ...
        </Entry>
    </Entry>
 
    <Entry entity="" action="" found="" rightTemplate="">
    ...
    </Entry>
</Entries>

Actions

Create dataset

The following example imports an activity if no other activity with the same subject is found.

XML

<Entry entity="Activity" action="CREATE" found="ZERO">
    <Field name="Subject.Activity" identifyingField="true">
        <FieldValue>
            <stringValue>Bestätigung</stringValue>
        </FieldValue>
    </Field>
    <Field name="Text.Activity" identifyingField="false">
        <FieldValue>
            <stringValue>Der Eingang der Angebotsdokumente wurde bestätigt.</stringValue>
        </FieldValue>
    </Field>
    <Field name="DelegatedBy.Activity" identifyingField="false">
        <FieldValue>
            <stringValue>BNE</stringValue>
        </FieldValue>
    </Field>
    <Field name="DelegatedTo.Activity">
        <FieldValue>
            <stringValue>BNE</stringValue>
        </FieldValue>
    </Field>
    <Field name="ActStatusKey.Activity">
        <FieldValue>
            <stringValue>O</stringValue>
        </FieldValue>
    </Field>
    <Field name="ActTypeKey.Activity">
        <FieldValue>
            <stringValue>TELEIN</stringValue>
        </FieldValue>
    </Field>
    <Field name="StartDate.Activity">
        <FieldValue>
            <dateTimeValue>2008-04-20T17:00:00</dateTimeValue>
        </FieldValue>
    </Field>
    <Field name="EndDate.Activity">
        <FieldValue>
            <dateTimeValue>2008-04-27T17:00:00</dateTimeValue>
        </FieldValue>
    </Field>
    <Field name="FreeNumber1.Activity" identifyingField="false">
        <FieldValue>
            <doubleValue>42.0</doubleValue>
        </FieldValue>
    </Field>
    <Field name="DefaultOpportunity.Activity" identifyingField="false" fieldType="PK">
        <FieldValue>
            <stringValue>ged-opportunitypk3</stringValue>
        </FieldValue>
    </Field>
    <EntityLookupField name="DefaultContactPerson.Activity">
        <Field name="FirstName.ContactPerson" identifyingField="true">
            <FieldValue>
                <stringValue>Cornelia</stringValue>
            </FieldValue>
        </Field>
        <Field name="LastName.ContactPerson" identifyingField="true">
            <FieldValue>
                <stringValue>Altenhain</stringValue>
            </FieldValue>
        </Field>
        <Field name="CustomerKey.ContactPerson" identifyingField="true">
            <FieldValue>
                <stringValue>CURSOR GIESSEN</stringValue>
            </FieldValue>
        </Field>
    </EntityLookupField>
</Entry>

Delete dataset

A dataset can only be removed using the DELETE_DATA mode and not by setting the Active field. The following example deletes all inquiries with an inquiry value of 42.42 and the description "My inquiry".

XML

 <Entry entity="Opportunity" action="DELETE_DATA" found="N">
    <Field name="OpName.Opportunity" identifyingField="true">
        <FieldValue>
            <stringValue>Meine Anfrage</stringValue>
        </FieldValue>
    </Field>
    <Field name="Projectvalue.Opportunity" identifyingField="true">
        <FieldValue>
            <doubleValue>42.42</doubleValue>
        </FieldValue>
    </Field>
</Entry>

Here, on the other hand, only one dataset is specifically deleted; if several datasets meet the search criteria, nothing happens.

XML

<Entry entity="Opportunity" action="DELETE_DATA" found="ONE">
    <Field name="OpName.Opportunity" identifyingField="true">
        <FieldValue>
            <stringValue>Meine Anfrage</stringValue>
        </FieldValue>
    </Field>
    <Field name="Projectvalue.Opportunity" identifyingField="true">
        <FieldValue>
            <doubleValue>42.42</doubleValue>
        </FieldValue>
    </Field>
</Entry>

Reactivate dataset

If a deleted dataset is to be reactivated, the Active field must be set to true. Further updates can also be made in the same cycle. This example reactivates the Carl Meyer contact person, if deleted, and sets his type to H. If there is no Carl Meyer yet, he is created.

XML

 <Entry entity="ContactPerson" action="UPDATE_OR_CREATE" found="ONE">
    <Field name="MatchCode.ContactPerson" identifyingField="true">
        <FieldValue>
            <stringValue>CARL MEYER</stringValue>
        </FieldValue>
    </Field>
    <Field name="FirstName.ContactPerson" identifyingField="true">
        <FieldValue>
            <stringValue>Carl</stringValue>
        </FieldValue>
    </Field>
    <Field name="LastName.ContactPerson" identifyingField="true">
        <FieldValue>
            <stringValue>Meyer</stringValue>
        </FieldValue>
    </Field>
    <Field name="Sex.ContactPerson">
        <FieldValue>
            <stringValue>H</stringValue>
        </FieldValue>
    </Field>
    <Field name="Active.ContactPerson">
        <FieldValue>
            <booleanValue>true</booleanValue>
        </FieldValue>
    </Field>
</Entry>

Link datasets

To link datasets, these must be nested. It does not matter whether they are created, updated or just linked. This example links the contract with the "Contract with small print" label and the number "4815162342" to the project just created. Since all fields are marked as identifying, nothing is updated. If no such contract exists, one is created and then linked.

XML

<Entry entity="Project" action="CREATE" found="NO_SEARCH">
    <Field name="Matchcode.Project">
        <FieldValue>
            <stringValue>GROSSPROJEKT</stringValue>
        </FieldValue>
    </Field>
    <Field name="CoordinatorKey.Project">
        <FieldValue>
            <stringValue>BNE</stringValue>
        </FieldValue>
    </Field>
    <Field name="DefaultCustomer.Project">
        <FieldValue>
            <stringValue>DEUTSCHE BANK</stringValue>
        </FieldValue>
    </Field>
    <Entry entity="Contract" action="LINK_AND_UPDATE_OR_CREATE" found="ONE" relation="rCnPj">
        <Field name="ContTitle.Contract" identifyingField="true">
            <FieldValue>
                <stringValue>Vertrag mit Kleingedrucktem</stringValue>
            </FieldValue>
        </Field>
        <Field name="ContNo.Contract" identifyingField="true">
            <FieldValue>
                <stringValue>4815162342</stringValue>
            </FieldValue>
        </Field>
    </Entry>
</Entry>

Alternatively, the link tag can be used.

Delete dataset link

In order to remove the link between two datasets, but not the datasets themselves, the DELETE_LINK action is provided.

XML

 <Entry entity="Customer" action="UPDATE" found="ONE">
    <Field name="MatchCode.Customer" identifyingField="true">
        <FieldValue>
            <stringValue>ADAC MÜNCHEN ZENTRALE - INTERESSEN</stringValue>
        </FieldValue>
    </Field>
    <Field name="Name1.Customer" identifyingField="true">
        <FieldValue>
            <stringValue>ADAC e.V.</stringValue>
        </FieldValue>
    </Field>
    <Entry entity="Customer" action="DELETE_LINK" found="ONE" relation="rCuCu">
        <Field name="MatchCode.Customer" identifyingField="true">
            <FieldValue>
                <stringValue>CURSOR ENTWICKLUNG</stringValue>
            </FieldValue>
        </Field>
        <Field name="Name1.Customer" identifyingField="true">
            <FieldValue>
                <stringValue>CURSOR Software AG</stringValue>
            </FieldValue>
        </Field>
        <Field name="Name2.Customer" identifyingField="true">
            <FieldValue>
                <stringValue>Entwicklung</stringValue>
            </FieldValue>
        </Field>
    </Entry>
</Entry>

Update dataset

One or more datasets can be updated as follows.

XML

<Entry entity="ContactPerson" action="UPDATE" found="ONE">
    <Field name="MatchCode.ContactPerson" identifyingField="true">
        <FieldValue>
            <stringValue>BEN LINUS</stringValue>
        </FieldValue>
    </Field>
    <Field name="FirstName.ContactPerson">
        <FieldValue>
            <stringValue>Benjamin</stringValue>
        </FieldValue>
    </Field>
    <Field name="LastName.ContactPerson" identifyingField="true">
        <FieldValue>
            <stringValue>Linus</stringValue>
        </FieldValue>
    </Field>
    <Field name="Sex.ContactPerson">
        <FieldValue>
            <stringValue>H</stringValue>
        </FieldValue>
    </Field>
    <Link pk="ged-activitypkToepper4" entity="Activity" relation="rCoPeAc"/>
</Entry>

Handling of roles, addresses and telecommunications

The creation of business partner, contact person or employee roles is subject to special restrictions due to the special data structure.

If the user creates a role, then a person, an address and several telecommunications datasets are created automatically. Fields of the address are delegated in the business partner, which can be set directly when you create a new address or update an existing address. The same applies to telecommunications. An address and a telecommunication can only be processed depending on a role, i.e. the Entry must be specified nested.

The first example creates a new business partner where the address and telephone numbers are saved directly. The telecommunications is stored as a standard telecommunication. The address is stored as a display, postal and standard address.

XML

 <Entries>
    <Config transactionTime="2000" version="9.2.0" testRun="false"/>
    <Entry entity="Customer" action="CREATE" found="ZERO">
        <Field name="MatchCode.Customer" identifyingField="true">
            <FieldValue><stringValue>MUSTERMANN AG</stringValue></FieldValue>
        </Field>
        <Field name="Name1.Customer" identifyingField="false" >
            <FieldValue><stringValue>Mustermann</stringValue></FieldValue>
        </Field>
        <Field name="Name2.Customer" identifyingField="false" >
            <FieldValue><stringValue>AG</stringValue></FieldValue>
        </Field>
        <Field name="PeAddressType.Customer" identifyingField="false" >
            <FieldValue><stringValue>STRASSE</stringValue></FieldValue>
        </Field>
        <Field name="PeStreet.Customer" identifyingField="false" >
            <FieldValue><stringValue>Hauptstraße</stringValue></FieldValue>
        </Field>
        <Field name="PeStreetNumber.Customer" identifyingField="false" >
            <FieldValue><stringValue>1</stringValue></FieldValue>
        </Field>
        <Field name="PeCity.Customer" identifyingField="false" >
            <FieldValue><stringValue>Hauptstadt</stringValue></FieldValue>
        </Field>
        <Field name="PeZIP.Customer" identifyingField="false" >
            <FieldValue><stringValue>10000</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoCountry.Customer" identifyingField="false" >
            <FieldValue><stringValue>+49</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoCity.Customer" identifyingField="false" >
            <FieldValue><stringValue>01234</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoBase.Customer" identifyingField="false" >
            <FieldValue><stringValue>56789</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoExtension.Customer" identifyingField="false" >
            <FieldValue><stringValue>0</stringValue></FieldValue>
        </Field>
    </Entry>
</Entries>

If you want to enter additional fields for the address (for example, free fields), this must be done by updating the address, since the address is created automatically when the business partner is created. Several addresses can be linked to a business partner, so that identifying fields must be included. For business partner addresses, these are the fields Display address (DefaultCuAd.Address) or Postal address (LetterCuAd.Address).

In telecommunications, the field Standard telecommunications (IsDefault) is the identifying field.

XML

<Entries>
    <Config transactionTime="2000" version="9.2.0" testRun="false"/>
    <Entry entity="Customer" action="CREATE" found="ZERO">
        <Field name="MatchCode.Customer" identifyingField="true">
            <FieldValue><stringValue>MUSTERMANN2 AG</stringValue></FieldValue>
        </Field>
        <Field name="Name1.Customer" identifyingField="false" >
            <FieldValue><stringValue>Mustermann2</stringValue></FieldValue>
        </Field>
        <Field name="Name2.Customer" identifyingField="false" >
            <FieldValue><stringValue>AG</stringValue></FieldValue>
        </Field>
        <Entry entity="Address" action="UPDATE" found="ONE" relation="rCuAd">
            <Field name="DefaultCuAd.Address" identifyingField="true">
                <FieldValue><booleanValue>true</booleanValue></FieldValue>
            </Field>
            <Field name="LetterCuAd.Address" identifyingField="true">
                <FieldValue><booleanValue>true</booleanValue></FieldValue>
            </Field>
            <Field name="City.Address" identifyingField="false">
                <FieldValue><stringValue>Hauptstadt</stringValue></FieldValue>
            </Field>
            <Field name="CountryKey.Address" identifyingField="false">
                <FieldValue><stringValue>D</stringValue></FieldValue>
            </Field>
            <Field name="AddressType.Address" identifyingField="false">
                <FieldValue><stringValue>STRASSE</stringValue></FieldValue>
            </Field>
            <Field name="NameKey.Address" identifyingField="false">
                <FieldValue><stringValue>BÜRO</stringValue></FieldValue>
            </Field>
            <Field name="Street.Address" identifyingField="false">
                <FieldValue><stringValue>Hauptstraße</stringValue></FieldValue>
            </Field>
            <Field name="StreetNumber.Address" identifyingField="false">
                <FieldValue><stringValue>1</stringValue></FieldValue>
            </Field>
            <Field name="StreetNumberAddition.Address" identifyingField="false">
                <FieldValue><stringValue>a</stringValue></FieldValue>
            </Field>
            <Field name="ZIPKey.Address" identifyingField="false">
                <FieldValue><stringValue>10000</stringValue></FieldValue>
            </Field>
            <Field name="State.Address" identifyingField="false">
                <FieldValue><stringValue>Berlin</stringValue></FieldValue>
            </Field>
        </Entry>
        <Entry entity="Telecom" action="UPDATE" found="ONE" relation="CuTe">
            <Field name="IsDefault.Telecom" identifyingField="true">
                <FieldValue><booleanValue>true</booleanValue></FieldValue>
            </Field>
            <Field name="PhoneNoCountry.Telecom" identifyingField="false">
                <FieldValue><stringValue>+49</stringValue></FieldValue>
            </Field>
            <Field name="PhoneNoCity.Telecom" identifyingField="false">
                <FieldValue><stringValue>01234</stringValue></FieldValue>
            </Field>
            <Field name="PhoneNoBase.Telecom" identifyingField="false">
                <FieldValue><stringValue>56789</stringValue></FieldValue>
            </Field>
            <Field name="PhoneNoExtension.Telecom" identifyingField="false">
                <FieldValue><stringValue>0</stringValue></FieldValue>
            </Field>
            <Field name="NameKey.Telecom" identifyingField="false">
                <FieldValue><stringValue>BÜRO</stringValue></FieldValue>
            </Field>
            <Field name="Email.Telecom" identifyingField="false">
                <FieldValue><stringValue>info@mustermannag.de</stringValue></FieldValue>
            </Field>
        </Entry>
    </Entry>
</Entries>

In order to create an additional address, such as a P.O. box, and select it as the postal address of the business partner, the Postal or Display Address fields must be set correctly. In the example, a second address is created for the existing address and marked as the postal address.

XML

<Entries>
    <Config transactionTime="2000" version="9.2.0" testRun="true"/>
    <Entry entity="Customer" action="CREATE" found="ZERO">
        <Field name="MatchCode.Customer" identifyingField="true">
            <FieldValue><stringValue>MUSTERMANN3 AG</stringValue></FieldValue>
        </Field>
        <Field name="Name1.Customer" identifyingField="false" >
            <FieldValue><stringValue>Mustermann3</stringValue></FieldValue>
        </Field>
        <Field name="Name2.Customer" identifyingField="false" >
            <FieldValue><stringValue>AG</stringValue></FieldValue>
        </Field>
        <Field name="PeAddressType.Customer" identifyingField="false" >
            <FieldValue><stringValue>STRASSE</stringValue></FieldValue>
        </Field>
        <Field name="PeStreet.Customer" identifyingField="false" >
            <FieldValue><stringValue>Hauptstraße</stringValue></FieldValue>
        </Field>
        <Field name="PeStreetNumber.Customer" identifyingField="false" >
            <FieldValue><stringValue>1</stringValue></FieldValue>
        </Field>
        <Field name="PeCity.Customer" identifyingField="false" >
            <FieldValue><stringValue>Hauptstadt</stringValue></FieldValue>
        </Field>
        <Field name="PeZIP.Customer" identifyingField="false" >
            <FieldValue><stringValue>10000</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoCountry.Customer" identifyingField="false" >
            <FieldValue><stringValue>+49</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoCity.Customer" identifyingField="false" >
            <FieldValue><stringValue>01234</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoBase.Customer" identifyingField="false" >
            <FieldValue><stringValue>56789</stringValue></FieldValue>
        </Field>
        <Field name="PhoneNoExtension.Customer" identifyingField="false" >
            <FieldValue><stringValue>0</stringValue></FieldValue>
        </Field>
        <Entry entity="Address" action="CREATE" found="ZERO" relation="rCuAd">
            <Field name="AddressType.Address" identifyingField="true">
                <FieldValue><stringValue>POSTFACH</stringValue></FieldValue>
            </Field>
            <Field name="DefaultCuAd.Address" identifyingField="false">
                <FieldValue><booleanValue>false</booleanValue></FieldValue>
            </Field>
            <Field name="LetterCuAd.Address" identifyingField="false">
                <FieldValue><booleanValue>true</booleanValue></FieldValue>
            </Field>
            <Field name="City.Address" identifyingField="false">
                <FieldValue><stringValue>Hauptstadt</stringValue></FieldValue>
            </Field>
            <Field name="CountryKey.Address" identifyingField="false">
                <FieldValue><stringValue>D</stringValue></FieldValue>
            </Field>
            <Field name="NameKey.Address" identifyingField="false">
                <FieldValue><stringValue>BÜRO</stringValue></FieldValue>
            </Field>
            <Field name="ZIPKey.Address" identifyingField="false">
                <FieldValue><stringValue>10001</stringValue></FieldValue>
            </Field>
            <Field name="Street.Address" identifyingField="false">
                <FieldValue><stringValue>Postfach</stringValue></FieldValue>
            </Field>
            <Field name="State.Address" identifyingField="false">
                <FieldValue><stringValue>Berlin</stringValue></FieldValue>
            </Field>
        </Entry>
    </Entry>
</Entries>

When addresses and telecommunications are updated or newly created, the data in the dependent roles is updated.

Transfer of addresses

There is also special handling between the contact person and business partner:

With this XML structure, the contact person receives links to all business partner addresses:

XML

 <Entries>
    <Config transactionTime="350" version="13.1" testRun="false" />
    <Entry entity="Customer" action="UPDATE" found="ONE">
        <Field name="MatchCode.Customer" identifyingField="true">
            <FieldValue><stringValue>BEISPIEL GMBH</stringValue></FieldValue>
        </Field>
        <Entry entity="ContactPerson" action="CREATE" relation="rCustomerKey_ContactPerson" found="ZERO">
            <Field name="LastName.ContactPerson" identifyingField="true">
                <FieldValue><stringValue>Müller</stringValue></FieldValue>
            </Field>
            <Field name="FirstName.ContactPerson" identifyingField="true">
                <FieldValue><stringValue>Hans</stringValue></FieldValue>
            </Field>
        </Entry>
    </Entry>
</Entries>

But not:

XML

<Entries>
    <Config transactionTime="350" version="13.1" testRun="false" />
    <Entry entity="ContactPerson" action="CREATE" found="ZERO">
        <Field name="LastName.ContactPerson" identifyingField="true">
            <FieldValue><stringValue>Müller</stringValue></FieldValue>
        </Field>
        <Field name="FirstName.ContactPerson" identifyingField="true">
            <FieldValue><stringValue>Hans</stringValue></FieldValue>
        </Field>
        <Entry entity="Customer" action="LINK_AND_UPDATE" found="ONE">
            <Field name="MatchCode.Customer" identifyingField="true" relation="rCustomerKey_ContactPerson">
                <FieldValue><stringValue>BEISPIEL GMBH</stringValue></FieldValue>
            </Field>
        </Entry>
    </Entry>
</Entries>

Special feature: Actions on key tables (S_Keytab/KeyTabNum or KeyRange)

Essentially, the actions in the XML file are defined in the same way as described. However, there are some restrictions for actions on key tables that must be taken into account when using the XML import.

The actions are always executed at the highest level (TopLevel). It is not possible to nest multiple <Entry> entries because no relations exist under keys.
The following actions are not applicable to key tables:
- LINK_AND_UPDATE, LINK_AND_UPDATE_OR_CREATE, DELETE_LINK:
  - Since no relations exist, no LINK operations can be performed.
- UPDATE_OR_CREATE (ONE / N)
  - Since different preconditions must be checked for an UPDATE or CREATE action (see below) and searches must already be executed in the parser to check the correct syntax, these actions have been forbidden.
It is currently not possible to create a KeyRange in a single XML file and create new keys for this range directly afterwards. The newly created range cannot yet be used in the same transaction (will be processed in 9.2.50).

In addition to these basic restrictions, certain preconditions must be met for the remaining actions.

CREATE
- S_Keytab/KeyTabNum --- When creating new keys, the fields KeyName + KeyRange must be specified.

Example:

XML

 <Entry entity="KeytabNum" action="CREATE" found="ZERO">
    <Field name="Pk.KeytabNum" identifyingField="true">
        <FieldValue>
            <stringValue>TESTKEY1</stringValue>
        </FieldValue>
    </Field>
    <!-- Error: KeyName.KeytabNum muss bei dieser Aktion zwingend angegeben werden.-->
    <Field name="DisplayName.KeytabNum" identifyingField="false">
        <FieldValue>
            <stringValue>Testschlüssel</stringValue>
        </FieldValue>
    </Field>
    <!-- Error: KeyRange.KeytabNum muss bei dieser Aktion zwingend angegeben werden. -->
</Entry>

- KeyRange --- When creating new key ranges, the fields Pk + DataType must be specified.

Example:

XML

<Entry entity="KeyRange" action="CREATE" found="ZERO">
    <!-- Error: Pk.KeyRange muss bei dieser Aktion zwingend angegeben werden. -->
    <Field name="Description.KeyRange" identifyingField="true">
        <FieldValue>
            <stringValue>Testrange String 1</stringValue>
        </FieldValue>
    </Field>
    <Field name="DataType.KeyRange" identifyingField="false">
        <FieldValue>
            <stringValue>java.lang.String</stringValue>
        </FieldValue>
    </Field>
</Entry>

<Entry entity="KeyRange" action="CREATE" found="ZERO">
    <Field name="Pk.KeyRange" identifyingField="true">
        <FieldValue>
            <stringValue>TEST_RANGE_STRING2</stringValue>
        </FieldValue>
    </Field>
    <Field name="Description.KeyRange" identifyingField="false">
        <FieldValue>
            <stringValue>Testrange String 1</stringValue>
        </FieldValue>
    </Field>
    <!-- Error: DataType.KeyRange muss bei dieser Aktion zwingend angegeben werden. -->
</Entry>

UPDATE + N
- S_Keytab/KeyTabNum --- This action normally returns several datasets as the search result. The specified fields are then set to the same values in all datasets. Therefore, the fields Pk + KeyName must be defined as IdentifyingFields or omitted for this action. If they are defined as id fields, the search returns only a single result and the action is equivalent to UPDATE + ONE. It is not possible to set these fields to the same value for multiple datasets. The uniqueness of the keys would be lost.

Example:

CODE

<Entry entity="KeytabNum" action="UPDATE" found="N">
    <!-- Error: Pk kann nicht mit UPDATE + N verändert werden. Entweder identifyingField = true oder Feld entfernen. -->
    <Field name="Pk.KeytabNum" identifyingField="false">
        <FieldValue>
            <stringValue>TESTKEY1</stringValue>
        </FieldValue>
    </Field>
    <Field name="DisplayName.KeytabNum" identifyingField="true">
        <FieldValue>
            <stringValue>Testschlüssel</stringValue>
        </FieldValue>
    </Field>
    <!-- Error: KeyName kann nicht mit UPDATE + N verändert werden. Entweder identifyingField = true oder Feld entfernen. -->
    <Field name="KeyName.KeytabNum" identifyingField="false">
        <FieldValue>
            <intValue>212345</intValue>
        </FieldValue>
    </Field>
    <Field name="KeyRange.KeytabNum" identifyingField="false">
        <FieldValue>
            <stringValue>S_PRJSTA</stringValue>
        </FieldValue>
    </Field>
    <Field name="ParentPk.KeytabNum" identifyingField="false">
        <FieldValue>
            <stringValue>S_PRJSTA-100</stringValue>
        </FieldValue>
    </Field>
</Entry>

Special feature: Actions on quote items (QuoteItem)

Quote items must always be created below a quote and the item set must also contain the QuotePK.

CODE

<Entry entity="Quote" action="UPDATE" found="ONE">    
    <Field name="Quoteno.Quote" identifyingField="true">
        <FieldValue>
            <stringValue>ANG 0000002</stringValue>
        </FieldValue>
    </Field>
    <Entry entity="QuoteItem" action="CREATE" found="NO_SEARCH" relation="rQuotePK_QuoteItem">
        <Field name="QuotePK.QuoteItem" fieldType="PK">
            <FieldValue>
                <stringValue>fvvvvvv7hk88i1am8op7sgQu</stringValue>
            </FieldValue>
        </Field>
        ...
    </Entry>
</Entry>

Problems/Solutions

The following problems are known when using the interface:

Composed fields

The fields ComposedAddress, ComposedFax, ComposedMobilePhone and ComposedPhone on the different roles cannot be set. The XML import interface ignores these entries, since these fields are composed of several other fields and are read-only in the application. Please fill in the individual fields here (example ComposedPhone: PhoneNoCountry, PhoneNoCity, PhoneNoBase and PhoneNoExtension).

Deleted data

The return structure indicates that a corresponding dataset already exists, but none can be found in the application? The XML import interface also finds deleted datasets in order to be able to reactivate them if desired. It is highly likely that a corresponding entry already exists and is only deactivated.

Special characters

If the &, < or > characters are to be used, a CDATA block must be placed around the corresponding field, otherwise it would no longer give valid XML. Example:

XML

 <Entries>
    <Config transactionTime="36000" version="9.2" testRun="false"/>
    <Entry entity="Activity" action="CREATE" found="ZERO">
        <Field name="Subject.Activity" identifyingField="true">
            <FieldValue>
                <stringValue><![CDATA[Anruf Müller & Söhne]]></stringValue>
            </FieldValue>
        </Field>
    </Entry>
</Entries>

Lookup fields with validation fields

Lookup fields with entered validation fields cannot be handled correctly and generate the message "The validation of the lookup field failed". In the standard version, this only applies to the 'DefaultContactPerson.Activity' field. To avoid this problem the 'EntityLookupField' tag should be used here or instead the value of the Pk (fieldType="PK").

Too many datasets found

The XML import interface also finds inactive datasets.

If more datasets are found than expected for the criteria entered, these may be inactive datasets. To exclude them, the 'Active' field must be marked as identifying. Example on the activity:

CODE

<Field name="Active.Activity" identifyingField="true">
    <FieldValue>
        <stringValue>true</stringValue>
    </FieldValue>
</Field>

Incorrect encoding of the template file

If an error message of the following type occurs, the CURSOR importer was most likely used and its template file was incorrectly encoded. As a reminder: It must be encoded as "UTF-8 without BOM".

CODE

org.apache.axis2.AxisFault: de.cursor.util.xml.binding.XMLBindingException: javax.xml.bind.UnmarshalException
- with linked exception:
[org.xml.sax.SAXParseException: cvc-complex-type.2.3: Element 'Entries' cannot have character [children],
because the type's content type is element-only.]

Empty fields

If you try to "empty" a field, an error message of the following type appears for number, boolean or date fields:

CODE

[org.xml.sax.SAXParseException: cvc-datatype-valid.1.2.1: '' is not a valid value for 'double'.]

In this case, two changes to the XML structure are necessary:

XML

 <Entries xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">

The Entries tag requires a new attribute.

XML

<FieldValue>
	<dateTimeValue xs:nil="true"/>
</FieldValue>

The corresponding field must be declared as empty.

Space character at end of text

MSSQL, Informix, and Oracle behave differently when spaces are used at the end of the text. In the following XML code for creating activities:

XML

 <Entries>
    <Config transactionTime="300" version="9.2" testRun="false"/>
    <Entry entity="Activity" action="CREATE" found="ZERO">
        <Field name="Subject.Activity" identifyingField="true">
            <FieldValue>
                <stringValue>Mein Betreff</stringValue>
            </FieldValue>
        </Field>
    </Entry>
    <Entry entity="Activity" action="CREATE" found="ZERO">
        <Field name="Subject.Activity" identifyingField="true">
            <FieldValue>
                <stringValue>Mein Betreff </stringValue>
            </FieldValue>
        </Field>
    </Entry>
</Entries>

Under Oracle, this code would lead to two activities being created. The first would be created with the subject "My Subject", the second entry would not find any activity with the subject "My Subject " and still create another activity.

Under MSSQL, Informix and DB2 (under Windows), an activity with the subject "My Subject" would also be created first. However, the second entry would also find activities with the subject "My Subject " when searching for "My Subject", since MSSQL, Informix and DB2 (under Windows) perform automatic trimming here. The result is that only one activity is created here.

To get around these problems, you should only create data without spaces at the beginning and end of the text, or clean up the existing data.