Skip to main content
Skip table of contents

XML import interface

XML import interface v. 1.0

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, WFInstanceId, RightPk, ClientNo, MassData, OfflineData)
VALUES ('SYSTEM.XMLImporter.ImportPeriod', '/de/cursor/jevi/client/swingclient/importer/SchemaXMLImporter$!!$ImportPeriod', '' ,'SYSTEM', '', '30000', 'CN' 1,
GETDATE(), 'TECH_USER', GETDATE(), 'TECH_USER', NULL, '#EMPTY-KEY#', NULL, NULL, 0, 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>

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.

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.

XML import interface v. 0.5

The XML import can create and link data from an XML file in CURSOR-CRM/EVI.

Process description

  • An XML file containing the datasets to be imported is stored in a defined directory.

  • A client monitors the directory in an interval of 10 seconds. 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, WFInstanceId, RightPk, ClientNo, MassData, OfflineData)
VALUES ('SYSTEM.XMLImporterOld.ImportPeriod', '/de/cursor/jevi/client/swingclient/controller/InitController$!!$ImportPeriod', '' ,'SYSTEM', '', '30000', 'CN', 1,
GETDATE(), 'TECH_USER', GETDATE(), 'TECH_USER', NULL, '#EMPTY-KEY#', NULL, NULL, 0, 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.XMLImporterOld.ImportPeriod'

  • If a file is found, the client tries to import the file. To do this, the datasets of the XML structure are transferred to the application server. After the transfer is complete, the XML file is moved to another directory to prevent it being imported again after 10 seconds.

  • The server uses specific criteria to check whether a dataset exists and generates INSERT or UPDATE statements from the XML structure. In doing so, it attempts to deduct these in a single transaction.

  • A log file logs how many datasets were created and whether there were any problems.

  • The import takes place without further prompting or information to the user.

Activate directory monitoring

  • Create the directory that is to be monitored for the data import. You can choose any place and description.

  • Open the file ...\EVI\Client\jboss\bin\runjboss.bat.

  • In the batch file, find the line

POWERSHELL 
@start "EVI Client" "%~dp0..\jre1.6.0_01\bin\javaw" -  DDEBUG.MODE=%DEBUG_MODE% -cp %CP% %START_OPTIONS% %START_CLASS%


and add the entry

POWERSHELL 
-Dde.cursor.importer.dir=Pfad

to get

POWERSHELL 
@start "EVIJET Client" "%~dp0..\jre1.6.0_01\bin\javaw"
-Dde.cursor.importer.dir=Pfad -DDEBUG.MODE=%DEBUG_MODE% -cp %CP% %START_OPTIONS% %START_CLASS%

where path specifies the path leading to the directory to be monitored.

  • Save the change in the runjboss.bat file.

Structure of the XML files

The XML files should always be UTF-8 encoded. For example, the Notepad++ tool can convert to UTF-8.

The header and footer of the document are always the same:

XML 
<Entries testRun="false" logFile="C:\temp\Import.log">
 
</Entries>

First, the basic element is defined. It must always be called "Entries". The Entries element has two attributes:

  1. "testRun" is optional and determines whether the import is actually performed (false) or only checks whether the import would work correctly (true). The default value here is 'true'.

  2. "logFile" is optional and specifies the path where the log file should be stored. If no file is specified, the standard output is logged.

XML 
<Entry entity="Customer" createIfNotFound="true">
 
</Entry>

For each entity to be imported or updated, an Entry named element is defined within the basic element. Entry also has four attributes, three are explained here, the fourth, relation, is explained further below:

  1. "entity" is mandatory and specifies the entity to be imported.

  2. "createIfNotFound" is optional and determines whether only existing data is updated (false) or whether new data is also created (true). The default value is false.

    Hinweis

    If false is set here, a field within the data set must be marked with identifyingField="true". See below for more details.

  3. In "rightTemplate" you can store a Pk of a rights template that is to be used for this dataset.

    Hinweis

    This only works if the corresponding entity has rights assigned to it.

XML 
 <Field name="MatchCode.Customer" value="TEST GMBH DATENSATZ 1 35390" identifyingField="true"/>

Finally, the fields to be set are specified within a dataset. All fields not specified are populated with default values. Each field is represented by a "Field" element. At least one "Field" element must be specified. The "Field" element has three attributes:

  1. The mandatory attribute "name" specifies the name of the field.

  2. Also mandatory is the attribute "value", which specifies the value to be set.

  3. "identifyingField" is set to "false" by default and is optional. It should be set to "true" for each field to be used to find the dataset to be updated. For CLOB fields, this attribute must NOT be set to "true".

Note

If several datasets or no datasets are found, there are two possibilities:

  1. If "createIfNotFound" of the "Entry" element is set to "true", the dataset is created again.

  2. If on the other hand "createIfNotFound" of the "Entry" element is set to "false", the import will be aborted.

Therefore, a sufficient number of fields should always be marked with "identifyingField ="true"". Since a unique dataset can never be determined without the identifyingField attribute, in the case of "createIfNotFound="false"" it is mandatory to flag at least one field with in this way.

Simple example

A complete example of importing a business partner would look like this:

XML 
<?xml version="1.0" encoding="ISO-8859-1"?>
<Entries testRun="false" logFile="C:\temp\Import.log">
    <Entry entity="Customer" createIfNotFound="true" rightTemplate="Feldberechtigungen Users">
        <Field name="MatchCode.Customer" value="TEST GMBH DATENSATZ 1 35390" identifyingField="true"/>
        <Field name="CustomerNo1.Customer" value="1020304050" identifyingField="true"/>
        <Field name="PeCountryKey.Customer" value="D"/>
        <Field name="PeZIP.Customer" value="35390"/>
    </Entry>
</Entries>

A business partner would be created here if it could not be found using the "MatchCode" and "CustomerNo1" fields. The fields "MatchCode", "CustomerNo1", "PeCountryKey" and "PeZIP" are set. All other fields would be populated with default values. The dataset would be assigned a rights template. The log file Import.log would be created in the directory C:\temp.

Nested elements

In order to link datasets with each other, they can be nested. This means that any number of nested "Entry" elements can be placed within an "Entry" element. The nested "Entry" element must contain the "relation" attribute mentioned earlier, which specifies the relation type.

XML 
<Entry entity="Customer" createIfNotFound="true">
    <Field name="MatchCode.Customer" value="TEST GMBH DATENSATZ 1 35390" identifyingField="true"/>
    <Field name="Name1.Customer" value="TEST GmbH Datensatz 1" identifyingField="false"/>
    <Field name="CustomerNo1.Customer" value="1020304050" identifyingField="true"/>
    <Field name="PeCountryKey.Customer" value="D" identifyingField="false"/>
    <Entry entity="ContactPerson" createIfNotFound="true" relation="rCustomerKey_ContactPerson">
        <Field name="MatchCode.ContactPerson" value="MÜLLER 1, ERWIN 1" identifyingField="true"/>
        <Field name="Sex.ContactPerson" value="H" identifyingField="false"/>
    </Entry>
</Entry>

In this example, a business partner and a contact person assigned to this business partner are created. You can nest as deep as you like.

XML 
<?xml version="1.0" encoding="ISO-8859-1"?>
<Entries testRun="false" logFile="C:\temp\Import.log">
    <Entry entity="Activity" createIfNotFound="true">
        <Field name="Subject.Activity" value="Wichtiger Anruf" />
        <Field name="Text.Activity" value="Derundder hat angerufen" />
        <Field name="ActTypeKey.Activity" value="TELEIN" />
        <Field name="ActStatusKey.Activity" value="O" />
        <EntityLookupField name="DefaultContactPerson.Activity">
            <Field name="LastName.ContactPerson" value="Altenhain" identifyingField="true"/>
            <Field name="FirstName.ContactPerson" value="Cornelia" identifyingField="true"/>
            <Field name="CustomerKey.ContactPerson" value="CURSOR GIESSEN" identifyingField="true"/>
        </EntityLookupField>
    </Entry>
</Entries>

In order to populate lookup fields where the value is not known, use the "EntityLookupField" element. This is only available from version 9.2.x and later. The name of the field to be populated is specified in the "name" attribute. "Field" elements are then used within the element to identify a unique dataset. If no or several datasets are found, the import terminates. This is why at least one "Field" element must be specified.

XML 
<?xml version="1.0" encoding="ISO-8859-1"?>
<Entries testRun="false" logFile="C:\temp\Import.log">
    <Entry entity="ContactPerson" createIfNotFound="true">
        <Field name="MatchCode.ContactPerson" value="OTBA" identifyingField="true"/>
        <Field name="LastName.ContactPerson" value="Baeuscher" identifyingField="true"/>
        <Field name="FunctionKey.ContactPerson" value="EKL" identifyingField="true"/>
        <Link pk="ged-activitypkToepper4" entity="Activity" relation="rCoPeAc"/>
    </Entry>
</Entries>

The "Link" element can be used to link the dataset with existing entries. In the example, the contact person is linked to an existing activity. To do this, set the following three attributes:

  1. "pk" The primary key of the existing dataset is specified here.

  2. "entity" must contain the entity of the existing dataset.

  3. "relation" specifies the relation type between the entities to be linked.

Complete example

In conclusion, here is an example containing all the above elements:

XML 
<?xml version="1.0" encoding="ISO-8859-1"?>
<Entries testRun="false" logFile="C:\temp\Import.log">
    <Entry entity="Activity" createIfNotFound="true">
        <Field name="Subject.Activity" value="Wichtiger Anruf" identifyingField="true"/>
        <Field name="Text.Activity" value="Derundder hat angerufen" identifyingField="true"/>
        <Field name="ActTypeKey.Activity" value="TELEIN" identifyingField="true"/>
        <Field name="ActStatusKey.Activity" value="O" identifyingField="true"/>
        <EntityLookupField name="DefaultContactPerson.Activity">
            <Field name="LastName.ContactPerson" value="Altenhain" identifyingField="true"/>
            <Field name="FirstName.ContactPerson" value="Cornelia" identifyingField="true"/>
            <Field name="CustomerKey.ContactPerson" value="CURSOR GIESSEN" identifyingField="true"/>
        </EntityLookupField>
    </Entry>
    <Entry entity="ContactPerson" createIfNotFound="true">
        <Field name="MatchCode.ContactPerson" value="OTBA" identifyingField="true"/>
        <Field name="LastName.ContactPerson" value="Baeuscher" identifyingField="true"/>
        <Field name="FunctionKey.ContactPerson" value="EKL" identifyingField="true"/>
        <Link pk="ged-activitypkToepper4" entity="Activity" relation="rCoPeAc"/>
    </Entry>
    <Entry entity="Customer" createIfNotFound="true">
        <Field name="MatchCode.Customer" value="TEST GMBH DATENSATZ 1 35390" identifyingField="true"/>
        <Field name="Name1.Customer" value="TEST GmbH Datensatz 1" identifyingField="false"/>
        <Field name="CustomerNo1.Customer" value="1020304050" identifyingField="true"/>
        <Field name="PeCountryKey.Customer" value="D" identifyingField="false"/>
        <Entry entity="ContactPerson" createIfNotFound="true" relation="rCustomerKey_ContactPerson">
            <Field name="MatchCode.ContactPerson" value="MÜLLER 1, ERWIN 1" identifyingField="true"/>
            <Field name="Sex.ContactPerson" value="H" identifyingField="false"/>
        </Entry>
    </Entry>
</Entries>

Example for importing addresses

XML 
<?xml version="1.0" encoding="ISO-8859-1"?>
<Entries logFile="c:/temp/file1.txt" testRun="false">
    <Entry entity="Customer" createIfNotFound="true">
        <Field name="MatchCode.Customer" value="MeinGeschäftspartner" identifyingField="false"/>
        <Field name="CustomerNo1.Customer" value="MeinGeschäftspartner" identifyingField="true"/>
        <Field name="Name1.Customer" value="Name1" identifyingField="false"/>
        <Field name="PersontypeKey.Customer" value="U" identifyingField="false"/>
        <Field name="PeCity.Customer" value="München" identifyingField="false"/>
        <Field name="PeStreetNumber.Customer" value="2" identifyingField="false"/>
        <Field name="PeCountryKey.Customer" value="D" identifyingField="false"/>
        <Field name="PeZIP.Customer" value="81373" identifyingField="false"/>
        <Field name="PeStreet.Customer" value="Leonhard-Moll-Bogen" identifyingField="false"/>
        <Field name="PeStreetNumberAddition.Customer" value="" identifyingField="false"/>
        <Entry entity="Address" createIfNotFound="true" relation="rCuAd">
            <Field name="LetterCuAd.Address" value="true" identifyingField="false"/>
            <Field name="DefaultCuAd.Address" value="true" identifyingField="false"/>
            <Field name="City.Address" value="Giessen" identifyingField="false"/>
            <Field name="StreetNumber.Address" value="33" identifyingField="false"/>
            <Field name="CountryKey.Address" value="D" identifyingField="false"/>
            <Field name="ZIPKey.Address" value="47328" identifyingField="false"/>
            <Field name="Street.Address" value="Floriansgasse" identifyingField="false"/>
            <Field name="NameKey.Address" value="BÜRO" identifyingField="false"/>
        </Entry>
    </Entry>
</Entries>

A business partner with an address is imported. In addition, an additional address is assigned to it, which is declared as a postal and display address via the flags LetterCuAd.Address and DefaultCuAd.Address. If several such addresses were declared, the last one to indicate this would be marked as the postal or display address.

Generate an XML file (Example "GP Import.xls")

The file (GP Import.xls) is a simple example of what an Excel template could look like that creates XML files that can be used for XML import. However, it does not create business partner entries with nested elements or links. The XML import must always be used with due care. This also applies to the use of this template. It consists of a CONFIG spreadsheet for configuration and a spreadsheet with the import data (called Business Partners in the template).

CONFIG spreadsheet

Entity

Table name of the entity, e.g. Customer or ContactPerson.

Create if it doesn't exist

If true, the datasets are transferred. If a dataset already exists in the database, it is not created again. If false, no datasets are transferred.

Import path

Here you specify the path monitored by the EVI Client into which the XML file is to be written. This folder must exist, otherwise an error message will appear when you click on "transfer".

LogPath

The log file of the import process is stored in this directory.

TempPath

The XML file is stored in this directory during the EXCEL XML export. This prevents duplicate access by the EXCEL that is still writing and by the client that is already reading it in. After the EXCEL XML export is completed, the created file is moved from the Temp folder to the Import folder.

tmpFileName

Enter the name of the temporary XML file here.

xmlFile

Enter the name of the final XML file here.

logFile

Enter the name of the log file here

Datasheet

Specify on which spreadsheet the data to be imported is located.

Test run?

If 'true', the import is performed, the log file is written and a rollback is then performed on the database. No changes are made to the database. If 'false', the data is written to the database.


Spreadsheet with the import data

Row 5 (named cell START ff.)

Enter the column name of the CURSOR-CRM / EVI Jet entity in the respective cell. Pay attention to spelling (upper and lower case, as well as the entity name separated by a dot, also in upper and lower case). Currently, a maximum of 100 columns can be transferred.

Row 6

If all entries are set to 'false', all datasets are created in the database without checks. If one or more columns are marked with a 'true', the system searches the database for the corresponding fields. If a dataset is found, e.g. with the corresponding match code and telephone number, the dataset in the database is overwritten with the entries of the XML file and no new dataset is created.


Clicking the Transfer button writes the XML file to the defined directory. VBA macros must be enabled in EXCEL.

The export runs until an empty cell is found in column A.

Problems/Solutions

The following problems are known when using the interface:

Person

No operations can be performed on the Person entity object using the XML import. The roles (business partner, contact person, employee) should be used in this case.

Lookup fields with validation fields

Lookup fields with entered validation fields cannot be handled correctly and generate the message "Could not transform [...] into a LookupVO for field [...]". In the standard version, this only applies to the "DefaultContactPerson.Activity" field. To get around this problem you should use the "EntityLookupField" tag here.

If two entities are linked several times, the Pk of the corresponding relation must also be specified. Example:

XML 
 <Entry entity="Project" createIfNotFound="true" >
    <Field name="Projectno.Project" value="PRJ 0000001" identifyingField="false"/>
    <Field name="Pk.Project" value="myProjectPk" identifyingField="true"/>
    <Field name="RelationPKrPjCoPe.Project" value="DER PASSENDE RELATION PK" identifyingField="true"/>
    <Entry entity="ContactPerson" createIfNotFound="true" relation="rPjCoPe">
        <Field name="CustomerKey.ContactPerson" value="MyCustomer" identifyingField="true"/>
        <Field name="Sex.ContactPerson" value="H" identifyingField="false"/>
        <Field name="LastName.ContactPerson" value="Lastname" identifyingField="true"/>
        <Field name="FirstName.ContactPerson" value="Firstname" identifyingField="true"/>
    </Entry>
</Entry>

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close