Commands

List of action XML syntax reference.

<request>

The <request> element contains the definition of an interface XML request. It is the root element of the document, and the whole document is defined to be namespace-neutral. (Example, see How to remove namespaces).

<request/>

Appearance

<request> </request>

Attributes

ixslt log logmode noerrorlog oxslt

any Session Attribute

any Custom Attribute

Contents

(Any command element)+

May occur in

(No parent elements - defines the top-level element)

Remarks

Attributes on the <response> element that are not processed by CRM.interface (i.e. that are not in the attributes list above) are plainly copied to the <response> element of the XML response. This allows for easy pass-through of key-value pairs that can for example be used to connect the request to its corresponding response via a unique id.

<break>

The <break> command stops processing the request if the break condition is fulfilled. Commands not already executed are left unprocessed.

<break/>

Appearance

<break> </break>

Attributes

if transaction

any Custom Attribute

Contents

(No child elements)

May occur in

< request >

Remarks

none

  <?xml version="1.0"?>
      <request xmlns:mp="http://www.update.com/xml/core/mp">
        <import>
          <fields>
            <Company>
              <Company matchup="true">break-dance</Company>
              <UndefinedField>undefined field</UndefinedField>
            </Company>
          </fields>
        </import>
        <!-- break on error -->
        <break if="/root/response/*[last()]//return[@type='error']"/>
        <!-- otherwise, do further processing -->
        <nop/>
      </request>

In the example above the execution of the request is stopped if an error occurs (<UndefinedField> doesn’t exist in Aurea CRM; therefore the <nop> command following the import command is not executed, see response below).

If you would resolve the error in the request, the break condition is no longer fulfilled and the <nop> command would be executed.

 <response xmlns:mp="http://www.update.com/xml/core/mp" xmlns="">
        <import>
          <return table="FI" id="0" type="error" func="C_Portal::ProcessImportNode">
            <ecode>-10027</ecode>
            <etext>Dictionary: Field not found</etext>
            <table table="FI" tablename="Company"/>
            <field>UndefinedField</field>
          </return>
        </import>
      </response>

<debug>

The <debug> command is for internal purposes only. Do not use except when explicitly instructed to do so.

<delete>

The <delete> command allows for deletion of multiple records from a single table (like in the Aurea CRM win service module).

<delete/>

Appearance

<delete> </delete>

Attributes

any Command Attribute

if

any Custom Attribute

Contents

tables links? fields? condition? sortlist? custom_sortlist?

May occur in

< request >

Remarks

The <delete> command is executed as a <query> and the resulting records are deleted.

Be sure that the set of records to be deleted are properly limited by conditions and/or links, otherwise you might delete too many or even all records in a table (including all its child records).

<?xml version="1.0"?>
      <request>
        <delete>
          <tables>
            <table tablename="Company"/>
          </tables>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="delete-test*"/>
          </condition>
        </delete>
      </request>

In the example above all company records that match the condition (Company starts with "delete-test") is deleted. The response returns the record id of each deleted record.

  <response>
        <delete>
          <return table="FI" tablename="Company" id="4294979919" type="delete"/>
          <return table="FI" tablename="Company" id="4294979937" type="delete"/>
          <!-- … -->
        </delete>
      </response>

In the example below person records that match the condition (LastName = "Maier") within the linked company record (Company = "delete-test") is deleted.

The response is similar to the example before.

  <?xml version="1.0"?>
      <request>
        <delete>
          <tables>
            <table tablename="Person"/>
          </tables>
          <condition>
            <cond tablename="Person" fieldname="LastName" op="=" value="Maier"/>
          </condition>
          <links>
            <Company>
              <Company>delete-test</Company>
            </Company>
          </links>
        </delete>
      </request>

<dictionary>

Note: The dictionary is no longer used in Aurea CRM; instead the XML names are read from the Aurea CRM data model (field "XML field name"). Therefore the <dictionary /> command serves for informational purposes, only.

The <dictionary> command generates a new dictionary.xml in the \xml subfolder of the installation directory - an existing file is renamed to dictionary_YYYYMMDDhhmmss.xml.

<dictionary/>

Appearance

<dictionary> </dictionary>

Attributes

complete if transaction

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

Note: Deprecated. The dictionary is no longer used in Aurea CRM.

Attribute

Meaning

text_class = CustomTexts

custom text is defined in the dictionary

text_class = CoreTexts

text is defined in data model

text_class = MissingTexts

neither in the data model, nor in the dictionary a custom text is defined, text is generated automatically based on the field number

<getcat>

The <getcat> command exports all values for a catalog. If the catalog is dependent, the parent values are also generated.

<getcat/>

Appearance

<getcat> </getcat>

Attributes

extkey id include_locked_values if transaction

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

The <getcat> command returns the language-dependent catalog texts. Furthermore, sort number and tenant are also included in the response. If extkey='true', external keys are also returned.

The catalog can be given by number/name, catalog number or the core catalog number.

      <?xml version="1.0"?>
      <request>
        <getcat tablename="Company" fieldname="Country"/>
      </request>
      <response>
        <getcat tablename="Company" fieldname="Country">
          <catalog index="2" ucatindex="-1">
            <cat index="1" locked="false">Österreich</cat>
            <cat index="2" locked="false">Deutschland</cat>
            <cat index="3" locked="false">Schweiz</cat>
          </catalog>
        </getcat>
      </response>

In this example the catalog texts of a dependent catalog is returned. Additionally its respective parent catalog text is returned.

      <?xml version="1.0"?>
      <request>
        <getcat tablename="ProblemResolution" fieldname="Product"/>
      </request>
      <response>
        <getcat tablename="ProblemResolution" fieldname="Product">
          <catalog index="28" ucatindex="29">
            <ucat index="0" locked="false">
              <cat1>Product Group 1</cat1>
              <cat index="0" locked="false">Product 1-1</cat>
            </ucat>
            <ucat index="1" locked="false">
              <cat1>Product Group 2</cat1>
              <cat index="0" locked="false">Product 2-1</cat>
              <cat index="1" locked="false">Product 2-2</cat>
              <cat index="2" locked="false">Product 2-3</cat>
            </ucat>
          </catalog>
        </getcat>
      </response>

The example below illustrates request and response using extkey and id attribute.

<?xml version='1.0'?>
      <request>
        <getcat id='2' extkey='true' include_locked_values='true'/>
        <getcat name='Firma-Frei 3'/>
        <getcat table='IT' fieldname='Interest'/>
      </request>
      <?xml version='1.0'?>
      <response>
        <getcat id="2" extkey="true" include_locked_values="true">
          <catalog id="2" cid="20000" name="Land">
            <cat code="2" extkey="GER" value="Deutschland"/>
            <cat code="1" extkey="AUT" value="Österreich"/>
            <cat code="4" locked="true" mnr="69" sort="666" value="test"/>
            <cat code="3" extkey="THA" value="Thailand"/>
          </catalog>
        </getcat>
        <getcat name="Firma-Frei 3">
          <catalog id="61" cid="20021" name="Firma-Frei 3">
            <cat code="1" sort="1001" value="FI free3 1001"/>
          </catalog>
        </getcat>
        <getcat table="IT" fieldname="Interest">
          <catalog id="46" pid="45" cid="20035" name="Interesse">
            <cat code="2" value="leer"/>
            <cat code="1" value="test">
              <cat code="1" value="test1"/>
              <cat code="2" value="test2"/>
              <cat code="3" value="test3"/>
            </cat>
          </catalog>
        </getcat>
      </response>

<getdoc>

The <getdoc> command reads documents from the D1 or D2 document tables and embeds them base64-encoded in the response. XML documents can optionally be embedded as inline XML.

<getdoc />

Appearance

<getdoc> </getdoc>

Attributes

decipher decrypt forceBase64 verify

any Command Attribute

if

any Custom Attribute

Contents

tables links? fields? condition? sortlist? custom_sortlist?

May occur in

<request>

Remarks

The <getdoc> command is executed as a <query> and the resulting records are then processed as follows. If it is a document record (D1 or D2), its document is used. Otherwise, all fields read are interpreted as a document reference and the corresponding document is used.

In this example all records from D1 document table that match the condition are read and the document itself is returned as base64-encoded string in the response. The contents of the fields declared in the <fields> section is also returned.

To read documents from the D2 table use tablename="CustomerDocuments" instead of "Documents".

<?xml version="1.0"?>
      <request>
        <getdoc>
          <tables>
            <table tablename="Documents"/>
          </tables>
          <fields>
            <!-- Declare any additional fields to be read from D1 record -->
            <field tablename="Documents" fieldname="Keyword"/>
          </fields>
          <condition>
            <cond tablename="Documents" fieldname="Name" op="=" value="test*"/>
          </condition>
        </getdoc>
      </request>
      <response>
        <document table="D1" id="4294967495">
          <docid>A1-199</docid>
          <Name>test.txt</Name>
          <ContentType>text/plain</ContentType>
          <Size>4</Size>
          <Keyword>example</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </document>
        <document table="D1" id="4294967497">
          <docid>A1-201</docid>
          <Name>test2.txt</Name>
          <ContentType>text/plain</ContentType>
          <Size>4</Size>
          <Keyword>example</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </document>
      </response>

The base64-encoded document is within the rawdata element. The elements <docid>, <Name>, <Size> and <ContentType> are returned by default.

In the next example below all contact records that match the condition (current date) are read. The fields declared in the <fields> section are interpreted as a document reference (e.g.: "A1-200", "K100-5") and the corresponding document is returned as base64-encoded string in the response.

<?xml version="1.0"?>
      <request>
        <getdoc>
          <tables>
            <table tablename="Contact"/>
          </tables>
          <fields>
            <field tablename="Contact" fieldname="Document1"/>
          </fields>
          <condition>
            <cond tablename="Contact" fieldname="Date" op="=" value="$curDay"/>
          </condition>
        </getdoc>
      </request>
      If the field is empty the following error will be returned:
      <response>
        <getdoc>
          <return table="MA" id="4295006414" type="error" func="C_Portal::XmlProcessGetDocument">
            <ecode>-10054</ecode>
            <etext>Field is empty</etext>
            <table>MA</table>
            <field>Document1</field>
          </return>
        </getdoc>
      </response>
      If the field contains a wrong or not existing document reference the following error will be returned:
      <response>
        <getdoc>
          <return type="error" func="C_Portal::XmlProcessGetDocumentEx">
            <ecode>-10055</ecode>
            <etext>Document not found</etext>
            <code>0</code>
            <docid>wrongref</docid>
          </return>
        </getdoc>
      </response>

<history>

The <history> command exports the record history (that is stored in the H0 table).

<history />

Appearance

<history> </history>

Attributes

any Command Attribute

any Custom Attribute

Contents

tables links? fields? condition? sortlist? custom_sortlist? history_condition?

May occur in

<request>

Remarks

The <history> command is executed as a <query> with the resulting records being output with their history added.

The record history can also be output by reading the H0 table as a dependent table.

<request>
        <query>
          <tables>
            <table tablename="Company">
              <table tablename="History"/>
            </table>
          </tables>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="update software AG"/>
          </condition>
          <fields tablename="Company" fields="Company"/>
          <fields tablename="History" fields="1"/>
        </query>
        <history>
          <tables>
            <table tablename="Company"/>
          </tables>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="update software AG"/>
          </condition>
        </history>
      </request>

In the query response detailed information is returned, whereas in the history response the history information is generated in a "query result"-structure.

<response>
        <query>
          <Company table="FI" id="296352743952" recId="x0000004500000210">
            <Company>update software AG</Company>
            <history>
              <revisions>
                <revision id="1">
                  <header version="7060" dm="67">
                    <date_time>2009-09-17T12:46:11.241</date_time>
                    <module id="11">XML</module>
                    <StatNo>69</StatNo>
                    <Flags name="ModuleFlags"/>
                    <UserId>6900002</UserId>
                    <mode value="2">update</mode>
                    <function value="0"/>
                    <Flags name="NulFlags">Mapping</Flags>
                    <Flags name="Flags">fields</Flags>
                    <internal len="122"/>
                  </header>
                  <fields>
                    <field id="0" fid="60" type="string" hdb_type="2" hdb_len="8">prev</field>
                    <field id="1" fid="4011" type="date" hdb_type="15" hdb_len="4">2009-09-17</field>
                    <field id="2" fid="4016" type="time_msec" hdb_type="19" hdb_len="4">12:46:11.209</field>
                    <field id="3" fid="4203" type="unsigned_short" hdb_type="9" hdb_len="2">69</field>
                    <field id="4" fid="4204" type="rep" hdb_type="21" hdb_len="4">WWW</field>
            <field id="5" fid="4205" type="static_catalog" hdb_type="6" hdb_len="1">XML</field>
                    <field id="6" fid="4206" type="unsigned_int" hdb_type="11" hdb_len="4">67108864</field>
                  </fields>
                </revision>
                <revision id="2">
                  <header version="7060" dm="67">
                    <date_time>2009-09-17T13:08:32.213</date_time>
                    <module id="11">XML</module>
                    <StatNo>69</StatNo>
                    <Flags name="ModuleFlags"/>
                    <UserId>6900002</UserId>
                    <mode value="2">update</mode>
                    <function value="0"/>
                    <Flags name="NulFlags">Mapping</Flags>
                    <Flags name="Flags">fields</Flags>
                    <internal len="92"/>
                  </header>
                  <fields>
                    <field id="0" fid="61" type="string" hdb_type="2" hdb_len="8">prev</field>
                    <field id="1" fid="4016" type="time_msec" hdb_type="19" hdb_len="4">13:08:32.198</field>
                  </fields>
                </revision>
              </revisions>
            </history>
          </Company>
        </query>
        <history>
          <Company table="FI" id="296352743952" recId="x0000004500000210">
            <FreeC1>prev</FreeC1>
            <Upd>2009-09-17</Upd>
            <UpdTime>12:46:11.209</UpdTime>
            <x-UpdStatNo>69</x-UpdStatNo>
            <x-UpdUserId>WWW</x-UpdUserId>
            <x-UpdModule>XML</x-UpdModule>
            <x-UpdFlag>67108864</x-UpdFlag>
          </Company>
          <Company table="FI" id="296352743952" recId="x0000004500000210">
            <FreeC2>prev</FreeC2>
            <UpdTime>13:08:32.198</UpdTime>
          </Company>
        </history>
      </response>

<import>

The <import> command defines a write operation (insert/update/match) over one or more tables.

<import/>

Appearance

<import> </import>

Attributes

allow_deleted catnew force_update mode no_insert write_cursor_flags

any Command Attribute

if

any Custom Attribute

Contents

links? fields

May occur in

<request>

Remarks

See Matchup and especially the note in the topic internal/external matchup.

In this example two company records are imported into the database. The <import> command considers the matchup logic (similar to the import module, see Matchup). In case of the first company record in this example:

if matchup finds a company record with the imported external key, the record is updated.

if no company with this key exists, the company is inserted as a new record.

<?xml version="1.0"?>
      <request>
        <import>
          <fields>
            <Company>
              <ExtSystem>External</ExtSystem>
              <ExtKey>1508</ExtKey>
              <Company>My Company 1</Company>
              <Synonym>external</Synonym>
              <!— any other fields from company -->
            </Company>
            <Company>
              <Company>My Company 2</Company>
              <Synonym>internal</Synonym>
              <!— any other fields from company -->
            </Company>
            <!— any other company records-->
          </fields>
        </import>
      </request>

The response returns the id of each imported record and the type of the write operation (insert/update/match)

<response>
        <import>
          <return table="FI" tablename="Company" id="4294979917" type="update"/>
          <return table="FI" tablename="Company" id="4294979924" type="insert"/>
        </import>
      </response>

In the next example records from more tables is imported. One company with tow Persons and one contact for the second person.

<request xml:lang="de">
        <import>
          <fields>
            <Company>
              <ExtSystem>SAP</ExtSystem>
              <ExtKey>1508</ExtKey>
              <Company>My Company</Company>
              <Synonym>external</Synonym>
              <!-- any other fields from company -->
              <Person>
                <FirstName>John</FirstName>
                <LastName>Doe</LastName>
                <!-- any other fields from person-->
              </Person>
              <Person>
                <FirstName>Jane</FirstName>
                <LastName>Doe</LastName>
                <!-- any other fields from person-->
                <Contact>
                  <Contact>Telefon</Contact>
                  <Subject>Imported via CRM.interface</Subject>
                  <!-- any other fields from contact-->
                </Contact>
                <!-- any other contact records-->
              </Person>
              <!-- any other person records -->
            </Company>
            <!-- any other company records -->
          </fields>
        </import>
      </request>
      <response>
        <import>
          <return table="FI" tablename="Company" id="4294979917" type="update"/>
          <return table="KP" tablename="Person" id="4294977462" type="insert">
            <links>
              <link table="FI" tablename="Company" id="4294979923" linkId="-1"/>
            </links>
          </return>
          <return table="KP" tablename="Person" id="4294977463" type="insert">
            <links>
              <link table="FI" tablename="Company" id="4294979923" linkId="-1"/>
            </links>
          </return>
          <return table="MA" tablename="Contact" id="4295044743" type="insert">
            <links>
              <link table="KP" tablename="Person" id="4294977463" linkId="-1"/>
            </links>
          </return>
        </import>
      </response>

In this example the company record declared in the <links> section is read and – if found - set as the link record of the imported contact. The structure of the response is the same shown as in the examples above.

<request xml:lang="de">
        <import>
          <fields>
            <Contact>
              <links>
                <Company>
                  <ExtSystem>SAP</ExtSystem>
                  <ExtKey>1508</ExtKey>
                </Company>
              </links>
              <Contact>Brief</Contact>
              <Subject>Imported via CRM.interface</Subject>
            </Contact>
          </fields>
        </import>
      </request>

If the link record does not exist, the following error is returned:

<response>
        <import>
          <return type="error" func="C_Portal::ReadLinks">
            <ecode>-10041</ecode>
            <etext>Link record not found</etext>
            <link>
              <Company>
                <ExtSystem>External</ExtSystem>
                <ExtKey>1508</ExtKey>
              </Company>
            </link>
            <code>0</code>
          </return>
        </import>
      </response>

If more than one link record is found, the following error is returned:

<response>
        <import>
          <return type="error" func="C_Portal::ReadLinks">
            <ecode>-10042</ecode>
            <etext>Link record not unique</etext>
            <link>
              <Company>
                <Company>Test</Company>
              </Company>
            </link>
            <code>-2</code>
          </return>
        </import>
      </response>

In order to be independent from default xml names within an <import/> request you can also reference a field by its unique field id (attribute fid) and a table by its abbreviation (attribute table).

<import>
        <fields>
          <call table="KM">
            <links>
              <businesspartner table="FI">
                <name fid="2">update software AG</name>
              </businesspartner>
            </links>
            <key fid="88">ABC10000</key>
            <parentcat fid="4">Software</parentcat>
            <childcat fid="5">Call</childcat>
            <owner fid="50">Alexander Jüttner</owner>
            <owner2 fid="51">Christoph Macheiner</owner2>
          </call>
        </fields>
      </import>

The above example is the equivalent to the following one (using the default syntax):

<import>
        <fields>
          <ProblemResolution>
            <links>
              <Company>
                <Company>update software AG</Company>
                </ Company>
              </links>
            <No>ABC10000</No>
            <ProblemGroup>
              Software</ ProblemGroup>
              <Problem>Call</Problem>
              <ProcessedBy>Alexander Jüttner</ProcessedBy>
              <CompletedBy>Christoph Macheiner</CompletedBy>
            </ProblemResolution>
        </fields>
      </import>

<insert>

The <insert> command defines a write operation over one or more tables where only insert is permitted.

<insert/>

Appearance

<insert> </ insert >

Attributes

allow_deleted catnew force_update mode no_insert write_cursor_flags

any Command Attribute

if

any Custom Attribute

Contents

links? fields

May occur in

<request>

Remarks

The <insert> command is executed as an <import> with matchup disabled.


      <request>
        <insert>
          <fields>
            <Company>
              <Company>My Company 1</Company>
              <Synonym>internal</Synonym>
              <!— any other fields from company -->
            </Company>
            <Company>
              <Company>My Company 2</Company>
              <Synonym>internal</Synonym>
              <!— any other fields from company -->
            </Company>
            <!— any other company records-->
          </fields>
          </ insert>
        </request>

The only difference to the <import> command is that there is no matchup logic considered. All records are inserted as new records.

<response>
        <insert>
          <return table="FI" tablename="Company" id="4294979923" type="insert"/>
          <return table="FI" tablename="Company" id="4294979924" type="insert"/>
          </ insert >
      </response>

<login>

The <login> command changes the current login user and/or language.

<login/>

Appearance

<login> </login>

Attributes

any Session Attribute

if transaction

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

The <login> command changes the current active login user and/or language for the remainder of the request. In contrast, when credentials and/or language are specified on any other command, they are only used for that single command. See also Shadow User.

CRM.interface uses a technical user – by default the WWW user – to access Aurea CRM if no login context is provided. Use update.Users.exe – which is installed in the installation of interface - to create or modify the users.xml file. Because users.xml contains the usernames and passwords of a CRM user, it is highly recommend to encrypt the contents of the file via the option "Use Xml Encryption".

See also, Authentication and Impersonation.

      <request>
        <login user="MyUser" pwd="secret_password"/>
      </request>
      If the login is successful the response returns information about the user, the corresponding rep user and the login language.
      <response>
        <!-- … -->
        <login user="MyUser">
          <login userId="2">
            <user>MyUser</user>
            <rep repId="103944" grpId="105473">My Rep Name</rep>
            <language>de</language>
          </login>
          <language>ger (de/German) 0,1,deu</language>
        </login>
      </response>
      If the password is incorrect, the following error is returned (code -17):
      <response>
        <login user="MyUser">
          <return type="error" func="C_Portal::XmlDoLogin">
            <ecode>-10043</ecode>
            <etext>Login error</etext>
            <code>-17</code>
            <user>MyUser</user>
            <language>0</language>
          </return>
        </login>
      </response>
Note: If the user does not exist the code = -13 is returned. For other error codes, see the

list of errors

in the Appendix.

In this example the first <query> command is executed in the context of user "MyUser" (declared at request element). The first <login> command changes the context to user "User1". The next two <query> commands are executed in this user’s context.

The two <query> commands after the second <login> command are then executed in the context of user "User2".

<request user="MyUser" pwd="my_secret_password">
        <query>
          <!-- query 1 -->
        </query>
        <login user="User1" pwd="password1"/>
        <query>
          <!-- query 2 -->
        </query>
        <query>
          <!-- query 3 -->
        </query>
        <login user="User2" pwd="password2"/>
        <query>
          <!-- query 4 -->
        </query>
        <query>
          <!-- query 5 -->
        </query>
      </request>

<matchup>

The <matchup> command executes the internal or external matchup for the specified record data.

<matchup/>

Appearance

<matchup> </matchup>

Attributes

any Command Attribute

if

any Custom Attribute

Contents

match query ?

May occur in

<request>

Remarks

see also Matchup.

For each matching record one <MatchupRecord> element is returned within the <match> element, containing score, text and description.

When the internal matchup is used, score is always 100, text and description are empty - in this case the record ID is returned as well.

When the external matchup is used, the information returned depends on the implementation.

In this example no explicit <query> command is specified in the request, so only the Default-Reference of the matching records are returned.

<request>
        <matchup>
          <match>
            <fields>
              <Company>
                <Company>update software</Company>
                <Country>Österreich</Country>
                <Street>Operngasse 17-21</Street>
                <ZipCode>1040</ZipCode>
              </Company>
            </fields>
          </match>
        </matchup>
      </request>
      <response>
        <matchup>
          <match>
            <MatchupRecord table="FI" tablename="Company" id="4294967300">
              <Score>100.00</Score>
              <Text1/>
              <Text2/>
            </MatchupRecord>
            <MatchupRecord table="FI" tablename="Company" id="4294975546">
              <Score>100.00</Score>
              <Text1/>
              <Text2/>
            </MatchupRecord>
            <MatchupRecord table="FI" tablename="Company" id="4294975547">
              <Score>100.00</Score>
              <Text1/>
              <Text2/>
            </MatchupRecord>
          </match>
          <query>
            <Company tableshort="FI" id="4294967300">
              <x-mmDefaultReference>update software AG</x-mmDefaultReference>
            </Company>
            <Company tableshort="FI" id="4294975546">
              <x-mmDefaultReference>update software Germany GmbH</x-mmDefaultReference>
            </Company>
            <Company tableshort="FI" id="4294975547">
              <x-mmDefaultReference>update software (Switzerland) GmbH</x-mmDefaultReference>
            </Company>
          </query>
        </matchup>
      </response>
      To read additional fields, specify a <query> after the <match>.
      <request hello="world">
        <matchup>
          <match>
            <fields>
              <Company>
                <Company>update software</Company>
                <Country>Österreich</Country>
                <Street>Operngasse 17-21</Street>
                <ZipCode>1040</ZipCode>
              </Company>
            </fields>
          </match>
          <query>
            <tables>
              <table tablename="Company"/>
            </tables>
            <fields tablename="Company" fields="Company,Synonym,Country"/>
          </query>
        </matchup>
      </request>
      <response hello="world">
        <matchup>
          <match>
            <MatchupRecord table="FI" tablename="Company" id="4294967300">
              <Score>100.00</Score>
              <Text1/>
              <Text2/>
            </MatchupRecord>
            <MatchupRecord table="FI" tablename="Company" id="4294975546">
              <Score>100.00</Score>
              <Text1/>
              <Text2/>
            </MatchupRecord>
            <MatchupRecord table="FI" tablename="Company" id="4294975547">
              <Score>100.00</Score>
              <Text1/>
              <Text2/>
            </MatchupRecord>
          </match>
          <query>
            <Company tableshort="FI" id="4294967300">
              <Company>update software AG</Company>
              <Synonym>update</Synonym>
              <Country>Österreich</Country>
            </Company>
            <Company tableshort="FI" id="4294975546">
              <Company>update software Germany GmbH</Company>
              <Synonym> update</Synonym>
              <Country>Deutschland</Country>
            </Company>
            <Company tableshort="FI" id="4294975547">
              <Company>update software (Switzerland) GmbH</Company>
              <Synonym>update</Synonym>
              <Country>Schweiz</Country>
            </Company>
          </query>
        </matchup>
      </response>

<merge>

The <merge> request allows the merging of Company and Person records via CRM.interface.

The merge mode defines what approach is taken to field-level conflict resolution (meaning which record "wins" when individual field values are conflicting). In source and target modes, the respective record’s field values always win. In timestamps mode, the most up-to-date field value wins.

<merge/>

Appearance

<merge> </merge>

Attributes

table tablename mode verbose no_exec flag_ignore transaction

if

any Custom Attribute

Contents

destination_record source_record

May occur in

<request>

Remarks

The information needed to perform a merge is:

The type of record to be merged: Company or Person

The merge mode: source, destination or timestamps

A key identifying the source record (Record ID and External Keys are supported)

A key identifying the destination* record

After the merge operation, the source record is deleted. The "surviving" record is always identified as the destination record, independently of the merge mode.

In this example the source company record is identified via the external key (1234) and is merged into the destination record (extkey=5678). The remaining company contains the field values of the original source company. Existing child records of the source company are moved to the destination company.

<request>
        <merge tablename="Company" mode="source">
          <source_record extsystem="External" extkey="1234"/>
          <destination_record extsystem= "External" extkey="5678"/>
        </merge>
      </request>
      <response>
        <merge tablename="Company" mode="source"/>
      </response>

To obtain more information about conflicts during the merge process, use the attribute verbose = "true":

<request>
        <merge tablename="Company" mode="source" verbose="true">
          <source_record extsystem="External" extkey="1234"/>
          <destination_record extsystem= "External" extkey="5678"/>
        </merge>
      </request>
      <response>
        <merge tablename="Company" mode="source" verbose="true">
          <conflicts>
            <conflict>
              <link linkId="0" srcId="FI" srcName="Company" destId="FI" destName="Company"/>
              <record source="4294979927" destination="4294979928" duplicate="0"/>
              <source_record>
                <Company table="FI" recId="x0000000100003157">
                  <CoGrp>1</CoGrp>
                  <CoNo>12631</CoNo>
                  <Company>Source</Company>
                  <!-- … -->
                </Company>
              </source_record>
              <destination_record>
                <Company table="FI" recId="x0000000100003158">
                  <CoGrp>1</CoGrp>
                  <CoNo>12632</CoNo>
                  <Company>Destination</Company>
                  <!-- … -->
                </Company>
              </destination_record>
            </conflict>
            <conflict>
              <link linkId="0" srcId="FI" srcName="Company" destId="PI" destName="LeadStatus"/>
              <record source="4017" destination="4018" duplicate="0"/>
              <source_record>
                <LeadStatus table="PI" recId="x0000000000000fb1">
                  <Date>2009-09-15</Date>
                  <RepID>000100002</RepID>
                  <CoGrp>1</CoGrp>
                  <CoNo>12631</CoNo>
                  <!-- … -->
                </LeadStatus>
              </source_record>
              <destination_record>
                <LeadStatus table="PI" recId="x0000000000000fb2">
                  <Date>2009-09-15</Date>
                  <RepID>000100002</RepID>
                  <CoGrp>1</CoGrp>
                  <CoNo>12632</CoNo>
                  <!-- … -->
                </LeadStatus>
              </destination_record>
            </conflict>
          </conflicts>
          <results>
            <result>
              <FI typ="" src="4294979927" dst="4294979928" result="source"/>
            </result>
            <result>
              <XF typ="child" src="454" result="relink"/>
            </result>
            <result>
              <PI typ="child" src="4017" dst="4018" result="source"/>
            </result>
          </results>
        </merge>
      </response>

In this example the source person record is identified via the unique record ID (4294967297) and is merged into the destination record (ID=4294967285). The remaining person contains the field values of the original destination person. Existing child records of the source person are moved to the destination person.

<request>
        <merge tablename="Person" mode="destination">
          <source_record recId="4294967297"/>
          <destination_record recId="4294967285"/>
        </merge>
      </request>
      <response>
        <merge tablename="Person" mode="destination"/>
      </response>

<metainfo>

The <metainfo> command returns the Meta information of a table, such as the fields of a table and their attributes and the indices of the table.

The response nodes <Flags name="FieldAttributes"> and <Flags name="FieldFormat"> are primarily intended for the update support for error analysis.

<metainfo/>

Appearance

<metainfo> </metainfo>

Attributes

table tablename flags include fields mode transaction

if

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

none

<request>
        <metainfo tablename="Company"/>
      </request>
      <response>
        <metainfo tablename="Company">
          <Flags name="FieldAttributes">
            <Flag name="InputHook" value="x00000001"/>
            [...]
          </Flags>
          <Flags name="FieldFormat">
            <Flag name="DigitGrouping" value="x00000001"/>
            [...]
          </Flags>
          <Company index="4" id="FI" name="Firma" customname="" basename="" dbname="FI" count="168">
            <fields>
              <CoGrp fid="0" fnr="0" name="FiGr." dbname="ID" type="S" len="4" ilen="2" cat="0" ucat="-1" attr="x20000000" ofmt="x0" field_class="x1000" text_class="x2000000"/>
              <CoNo fid="1" fnr="1" name="FiNr." dbname="ID" type="L" len="9" ilen="4" cat="0" ucat="-1" attr="x40000020" ofmt="x0" field_class="x1000" text_class="x2000000"/>
              <Company fid="2" fnr="2" name="Firma" dbname="Firma" type="C" len="120" ilen="240" cat="0" ucat="-1" attr="x1" ofmt="x0" field_class="x1000" text_class="x2000000"/>
              <Synonym fid="3" fnr="3" name="Synonym" dbname="Syno" type="C" len="30" ilen="60" cat="0" ucat="-1" attr="x0" ofmt="x0" field_class="x1000" text_class="x2000000"/>
              <Division fid="4" fnr="4" name="Division" dbname="Division" type="C" len="40" ilen="80" cat="0" ucat="-1" attr="x0" ofmt="x0" field_class="x1000" text_class="x2000000"/>
              <Country fid="5" fnr="5" name="Land" dbname="Land" type="K" len="80" ilen="2" cat="2" ucat="-1" attr="x1" ofmt="x0" field_class="x1000" text_class="x2000000"/>
            </fields>
            [...]
            <indexes>
              <index id="1" type="p" autonumbered="1">
                <field fid="0" fnr="0" name="CoGrp" type="S" len="4" ilen="2" cat="0" ucat="-1" attr="x20000000" ofmt="x0" field_class="x1000" text_class="x2000000"/>
                <field fid="1" fnr="1" name="CoNo" type="L" len="9" ilen="4" cat="0" ucat="-1" attr="x40000020" ofmt="x0" field_class="x1000" text_class="x2000000"/>
              </index>
              [...]
            </indexes>
          </Company>
        </metainfo>
      </response>

Attribute

Meaning

fid

Unique ID of field in Aurea CRM

fnr

Zero based index of field in data base

name

Field name (output in current language)

dbname

Column name of database table

type

See Field types.

len

Maximum input / output length

ilen

Internal length in bytes, e.g. if type = L and ilen = 8 then it is a 64Bit integer, if ilen=4 then it is a 32 bit integer

cat

Catalog number

ucat

Parent catalog number, if catalog is a dependent catalog

attr

Field attributes, see list in appendix Field Attributes.

ofmt

Field output format attributes, see list in appendix Field output formats.

Text_class

Origin of language dependent fieldname, see list in appendix FieldTypes and Categories.

cid

IDs for tables and fields

ccat

IDs for catalog fields

core

IDs for core fields. If core=all, the values for all verticals are returned, if core='bb,bc', only the values for the BTB and OTC verticals are returned.

<mp>

The <mp> command facilitates generation of arbitrary XML content.

<mp/>

Appearance

<mp> </mp>

Attributes

if output test transaction

any Custom Attribute

Contents

(Any Content)

May occur in

<request>

Remarks

See Message Processing.

<nop>

The <nop> command allows testing if interface is "up and running" – in case of success the request does not return any data and therefore it is the easiest method of testing.

<nop/>

Appearance

<nop> </nop>

Attributes

if transaction

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

none

<request>
        <nop/>
      </request>
      <response>
        <nop/>
      </response>
      In principle, no command is needed for the "up and running" test. However, then the following error is returned:
      <request/>
      <response>
        <return type="error" func="C_Portal::ProcessXml">
          <ecode>-10049</ecode>
          <etext>No command found in document</etext>
        </return>
      </response>

<putdoc>

The <putdoc> command imports documents into the document tables D1 or D2.

<putdoc/>

Appearance

<putdoc> </ putdoc >

Attributes

if transaction

any Custom Attribute

Contents

links? rawdata? xmldata? filedata?

May occur in

<request>

Remarks

The document itself can either be specified as BASE64 encoded blob or read from a file (based on file name).

In this example a text file is imported into the D1 table.

The document itself is provided as a base64-encoded string within the <rawdata> element. The fields <Name> and <Keyword> are mandatory.

The response returns the document reference (A…for Documents from D1).

      <request>
        <putdoc>
          <Name>Testdatei.txt</Name>
          <Keyword>Putdoc_Test</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
      </request>
      <response>
        <!-- -->
        <putdoc>
          <docid>A1-333</docid>
        </putdoc>
      </response>

In order to import additional field values into the document record as well, you have to add an <import> command after the <putdoc> command to update the record created by the <putdoc> command.

      <request>
        <putdoc>
          <Name>Testdatei.txt</Name>
          <Keyword>Putdoc_Test</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
        <import>
          <fields>
            <Documents>
              <links>
                <link tablename="Documents" id="$lastRecId"/>
              </links>
              <Private>false</Private>
              <DocClass>Textfile</DocClass>
              <Owner>Own RepName</Owner>
              <FreeC1>Test</FreeC1>
              <!-- … -->
            </Documents>
          </fields>
        </import>
      </request>

In this example a text file is imported into the D1 table (<putdoc>). The following <import> command creates a document link record (D3) linked to this D1 record and to the company declared in the <links> section (if the company record exists and is unique).

      <request>
        <putdoc>
          <Name>Testdatei.txt</Name>
          <Keyword>Putdoc_Test</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
        <import>
          <fields>
            <DocumentLink>
              <links>
                <Company>
                  <Company>My PutDoc Company</Company>
                </Company>
                <link tablename="Documents" id="$lastRecId"/>
              </links>
            </DocumentLink>
          </fields>
        </import>
      </request>
      <response>
        <putdoc>
          <docid>A1-335</docid>
        </putdoc>
        <import>
          <return table="D3" tablename="DocumentLink" id="4294967737" type="insert">
            <links>
              <link table="FI" id="4294979928" linkId="-1"/>
              <link table="D1" tablename="Documents" id="4294967631" linkId="-1"/>
            </links>
          </return>
        </import>
      </response>

XML documents need not be base64-encoded, they can be embedded as inline XML (element <xmldata>).

      <request>
        <putdoc>
          <Name>HelloWorld.xml</Name>
          <Keyword>Putdoc_Test</Keyword>
          <xmldata>
            <root>
              <hello attr="true">world</hello>
            </root>
          </xmldata>
        </putdoc>
      </request>
      <response>
        <putdoc>
          <docid>A1-336</docid>
        </putdoc>
      </response>

In order to import documents directly from file system, use <filedata>. In this case no other elements are needed in the request:

      <request>
        <putdoc>
          <filedata>C:\MyFiles\Textfile.txt</filedata>
        </putdoc>
      </request>
      <response>
        <putdoc>
          <docid>A1-338</docid>
        </putdoc>
      </response>

This request combines elements of the <query> and the <putdoc> commands:

With the definitions provided in the <tables> and <condition> elements a query for companies is executed. Afterwards the document is imported into the D2 table as a child record of the company record found by the query.

The document itself is provided as a base64-encoded string within the <rawdata> element. The fields <Name> and <Keyword> are mandatory.

The response returns the document reference (K…for CustomerDocuments)

      <request>
        <putdoc>
          <tables>
            <table tablename="Company"/>
          </tables>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="My Putdoc Company"/>
          </condition>
          <Name>Testdatei.txt</Name>
          <Keyword>Putdoc_Test</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
      </request>
      <response>
        <putdoc>
          <docid>K1-131</docid>
        </putdoc>
      </response>

Example <putdoc> - Import documents into the D2 document table

Note: The result of the query has to be just one unique record.

If no record is found, this request is equivalent to the request from the example in Error! Reference source not found. and only the document is imported into the D1 table.

If more than one record is found, the following error is returned:

      <response>
        <putdoc>
          <return type="error" func="C_Portal::XmlProcessPutDocument">
            <ecode>-10042</ecode>
            <etext>Link record not unique</etext>
            <table>FI</table>
          </return>
        </putdoc>
      </response>

Example <putdoc> - Response, if link record is not unique

In addition to the example before, this request contains the <doclinks> element:

      <request>
        <putdoc>
          <tables>
            <table tablename="Company"/>
          </tables>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="My Putdoc Company"/>
          </condition>
          <doclinks>
            <field tablename="Contact" fieldname="Document1" id="4294967631"/>
          </doclinks>
          <Name>Testdatei.txt</Name>
          <Keyword>Putdoc_Test</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
      </request>
      <response>
        <!-- … -->
        <putdoc>
          <docid>K1-133</docid>
          <doclinks>
            <doclink tablename="Contact" fieldname="Document1" id="4295044745"/>
          </doclinks>
        </putdoc>
      </response>

A record from a declared table (@tablename) is referenced by its record ID (@id). The document reference of the imported document is written into the declared field (@fieldname) of this record.

In this example: The text file is imported to the D2 table as a child of the company "My Putdoc Company". The contact record with record ID 4294967631 is read and the document reference (K1-133) is written into the field Document1 of this contact.

Note: Normally the record ID is specified by a variable ($lastRecId). e.g.: from a preceding <query> command.

If the record declared in the <doclinks> element does not exist, the following error is returned:

      <response>
        <!-- … -->
        <putdoc>
          <docid>K1-134</docid>
          <doclinks>
            <return table="MA" id="4295044746" type="error" func="C_Portal::WriteRecord">
              <ecode>-10004</ecode>
              <etext>Cannot create cursor</etext>
              <cursorid>-30</cursorid>
              <recordid>4295044746</recordid>
              <type>write</type>
            </return>
          </doclinks>
        </putdoc>
      </response>

In order to update an existing D1 document via <putdoc> you explicitly have to read the document via <links>, since <putdoc> doesn’t provide a matchup-mechanism.

      <request hello="world">
        <putdoc>
          <links>
            <Documents>
              <StatNo>10</StatNo>
              <SeqNo>19262</SeqNo>
            </Documents>
          </links>
          <Name>test3.txt</Name>
          <Keyword>D1_Update_12484</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
      </request>

In order to update an existing D2 document via <putdoc> you explicitly have to read the document via <links>, since <putdoc> doesn’t provide a matchup-mechanism. Additionally you have to specify the company/person context, because without this context a new D1 document would be created instead updating the existing D2 document.

      <request>
        <putdoc>
          <tables>
            <table tablename="Person"/>
          </tables>
          <condition>
            <cond tablename="Person" fieldname="LastName" op="=" value="Hofmann"/>
          </condition>
          <links>
            <CustomerDocuments>
              <StatNo>1</StatNo>
              <SeqNo>128</SeqNo>
            </CustomerDocuments>
          </links>
          <Name>test3.txt</Name>
          <Keyword>D2_Update_12485</Keyword>
          <rawdata xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">dGVzdA==</rawdata>
        </putdoc>
      </request>

<query>

The <query> command defines a read operation over one or more tables.

<query/>

Appearance

<query> </query>

Attributes

labels maxrecords reverse select skiprecords lenient_filter chunked

The following attributes are solely valid, if chunked = "true".

back chunk_size clear hardcache navigable

offset page qid

any Command Attribute

if

any Custom Attribute

Contents

tables links? fields? condition? sortlist? custom_sortlist?

May occur in

<request>

Remarks

none

In this example all company records are returned that match the declared condition (field Company starts with "My Company"). The values of the fields declared are returned in the response.

      <request>
        <query>
          <tables>
            <table tablename="Company"/>
          </tables>
          <fields tablename="Company" fields="Company,Synonym"/>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="My Company*"/>
          </condition>
        </query>
      </request>
      <response>
        <query>
          <Company tableshort="FI" id="4294967394">
            <Company>My Company 1</Company>
            <Synonym/>
          </Company>
          <Company tableshort="FI" id="4294967399">
            <Company>My Company 2</Company>
            <Synonym>my</Synonym>
          </Company>
          <!-- any other company records -->
        </query>
      </response>

In this example all company records are returned that match the declared condition for company table (Company starts with "My Company") and within each Company all person records that match the condition for person table (LastName starts with "M").

Note: Normally in the <tables> section the dependency of the tables is declared. Only one root table is possible.

It is not possible to mix conditions from different tables within one <condition> section. If desired for each table a separate condition section has to be declared.

      <request>
        <query>
          <tables>
            <table tablename="Company">
              <table tablename="Person"/>
            </table>
          </tables>
          <fields>
            <field tablename="Company" fieldname="CoGrp"/>
            <field tablename="Company" fieldname="CoNo"/>
            <field tablename="Company" fieldname="Company"/>
            <field tablename="Person" fieldname="LastName"/>
            <field tablename="Person" fieldname="FirstName"/>
          </fields>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="My Company*"/>
          </condition>
          <condition>
            <cond tablename="Person" fieldname="LastName" op="=" value="M*"/>
          </condition>
        </query>
      </request>
      <response>
        <query>
          <Company tableshort="FI" id="4294975508">
            <CoGrp>1</CoGrp>
            <CoNo>8212</CoNo>
            <Company>My Company 1</Company>
          </Company>
          <Company tableshort="FI" id="4294979923">
            <CoGrp>1</CoGrp>
            <CoNo>12627</CoNo>
            <Company>My Company 2</Company>
            <Person tableshort="KP" id="4294977464">
              <LastName>Maier</LastName>
              <FirstName>Sabine</FirstName>
            </Person>
            <Person tableshort="KP" id="4294977464">
              <LastName>Mader</LastName>
              <FirstName>Georg</FirstName>
            </Person>
            <!— any other person records within this company -->
          </Company>
          <!— any other company records -->
        </query>
      </response>

In the example below we have a filter condition which causes a conversion error (<etext>Conversion error</etext>) because the condition compares a numeric field fieldname="FreeN1" with an alphanumeric value (value="update").

      <request>
        <query maxrecords="5">
          <tables>
            <table tablename="Company"/>
          </tables>
          <fields tablename="Company" fields="1,2,3,4,5,6,7"/>
          <condition>
            <cond tablename="Company" fieldname="FreeN1" op="!=" value="update"/>
          </condition>
        </query>
      </request>
      <response>
        <query maxrecords="5">
          <return type="error" func="C_Portal::CheckField">
            <ecode>-10023</ecode>
            <etext>Conversion error</etext>
            <field table="FI" tablename="Company" fid="63" fnr="63" type="L" fieldname="FreeN1"/>
            <description>parse error</description>
            <value/>
          </return>
        </query>
      </response>

In the example below we use lenient_filter="true" and therefore the incorrect condition fieldname="FreeN1" is ignored and only the condition on fieldname="Company" is executed.

      <request>
        <query maxrecords="5" lenient_filter="true">
          <tables>
            <table tablename="Company" />
          </tables>
          <fields tablename="Company" fields="2"/>
          <condition>
            <cond tablename="Company" fieldname="FreeN1" op="!=" value="update"/>
            <lop op="and"/>
            <cond tablename="Company" fieldname="Company" op="()" value="update"/>
          </condition>
        </query>
      </request>

Chunked read

Reading in chunks allows for more efficient retrieving of (possible) huge data sets and navigating in these data sets. First only the record-IDs are read (up to maxrecords). Subsequent queries return the next "page" (determined by chunk_size) of records by referencing the original query via a query-ID (qid).

In the example below the data two chunks of 10 records are read.

      <request>
        <query maxrecords="50" qid="query_chunked_FI.xml" chunked="true" chunk_size="10">
          <tables>
            <table tablename="Company"/>
          </tables>
          <fields tablename="Company" fields="CoGrp,CoNo,Company,Country"/>
        </query>
      </request>
      <request>
        <query qid="query_chunked_FI.xml"/>
      </request>

If you don’t specify a qid in the requests, interface generates a unique qid to be used in the following queries.

      <request>
        <query maxrecords="50" chunked="true" chunk_size="10">
          <tables>
            <table tablename="Company"/>
          </tables>
          <fields tablename="Company" fields="CoGrp,CoNo,Company,Country"/>
        </query>
      </request>
      <response>
        <query maxrecords="50" chunked="true" chunk_size="10" qid="QVRQQzI1ODJfdXBkYXRlLndlYi5zZXJ2aWNlcy50ZXN0LmV4ZV9fMjAxMi 0xMC0xNiAxMzowNjoxMS44NzNfNjkwMTg5MDMwX1A3Njg4X1Q4NzYwXykjPmFsVi5SSXE=" count="50">
      …
      </response>

In order to read the next page you have to do something like in the request shown below.

      <request>
        <query qid="QVRQQzI1ODJfdXBkYXRlLndlYi5zZXJ2aWNlcy50ZXN0LmV4ZV9fMjAxM i0xMC0xNiAxMzowNjoxMS44NzNfNjkwMTg5MDMwX1A3Njg4X1Q4NzYwXykjPmFsVi5SSXE="/>
      </request>

chunk_size can be set on every query; if not set explicitly on the "following" queries, the last value of is chunk_size used.

If navigable = true is not specified the initial list of record-IDs is reduced by the records returned by each query. The last chunk of data is marked with last_chunk="true". If all records have been read "Query already completed" is returned.

      <response>
        <query qid="query_chunked_FI.xml" chunk_size="10" count="50" last_chunk="true">
          <query qid="query_chunked_FI.xml">
            <return type="error" func="C_Portal::XmlExecuteQueryChunked">
              <ecode>-10090</ecode>
              <etext>Chunked read error</etext>
              <description>Query already completed</description>
            </return>
          </query>
        </response>

If navigable = true the record-IDs are kept at the server until the timeout is reached (timeout = 60 minutes after last use); by default navigation direction is forward, unless back=true. The starting point of the navigation can be set via the offset or page attribute.

count returns the total number of records (≤ maxrecords) from the initial query; if navigable = true the current offset is returned in the pos attribute.

<refresh>

The <refresh> command refreshes the Aurea CRM internal caches (e.g. format cache, catalogue cache, rep cache). Please note, that the refresh request requires SU user privileges.

<refresh/>

Appearance

<refresh> </refresh>

Attributes

catalogs configuration formats protocols reps transaction

if

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

none

      <request user="SU" pwd="__SUPWD">
        <refresh/>
      </request>
      <response user="SU">
        <refresh/>
      </response>

<row_export>

The <row_export> command allows for exporting data through the use of an export format, its functionality is equivalent to the Aurea CRM export module. Currently, the exported data cannot be returned in the XML response (it can only be written to the export file).

<row_export/>

Appearance

<row_export> </row_export>

Attributes

debug format_name output_file

Contents

(No child elements)

May occur in

<request>

Remarks

 

<row_import>

The <row_import> command allows for importing data through the use of an import format, its functionality is equivalent to the Aurea CRM import module. Import data can be specified using a file, or as XML using a single <data> block or split into multiple "lines" using <rows> with <row> sub-nodes.

<row_import />

Appearance

<row_import> </row_import>

Attributes

debug format_name input_file record_separator field_separator boundary_separator

Contents

rows/row data

May occur in

<request>

Remarks

The response <r> of the <row_import> command includes information about what happened with the data record.

<r ipos=[integer] irelpos=[integer] status=[integer] table=[string] id=[long integer]/>

iposhierarchical position,

0 = root table,

1=child table first level,

2=child table second level

irelpos hierarchical position of the table if imported multiple times

status0 = not processed, e.g. if no data record for this table is included in the import data

1 = record is matched

2 = record is inserted

4 = record is changed

8 = record is deleted

16 = record is rejected due to an error

32 = similar records are found

64 = matchup logic has been aborted with no success (example: primary key is specified, and the record is not found)

128 = record went through manual matchup (not possible in non-interactive scenarios like u7.interface)

256 = match via external key

The response <e> of the <row_import> command includes detailed information about import errors for each row, the concerned field is further detailed in the <field> element.

<e rc=[integer]> where rc references the row in which the error occurred

<field table=[string] tablename=[string] fid=[integer] fnr=[integer] type=[string] fieldname==[string]/>

The response <msg> provides an error message.

In the example below all attribute definitions (fields, separator, data …) are taken from the Aurea CRM import format.

      <request>
        <row_import format_name=" Import format Company"/>
      </request>

In the example below the input file definition of the Aurea CRM import format is overwritten by the request. Path can be absolute or – as defined in this example via using the $ syntax – relative to the installation directory of CRM.interface.

      <request>
        <row_import format_name=" Import format Company" input_file="$\Documents\import_companies.txt"/>
      </request>

The example below illustrates how to override the separators defined in the Aurea CRM import format via the <row_import> request. Please note that you have to escape the separators according to the XML language definition ("&#10;" is equivalent to Lf). The separator settings are equivalent to the definition in the Aurea CRM format as depictured below.

      <request>
        <row_import format_name=" Importformat Firmen" input_file="$\Documents\import_firmen.txt" record_separator="&#10;" field_separator=";" boundary_separator=","/>
      </request>

The example below illustrates how data can be passed to the <row_import> request directly. In this case you have to overwrite the data source defined in the Aurea.CRM format via input_file="".

If data is defined in a CDATA section you can send un-escaped data (e.g. you do not need to escape special characters with "&"). Otherwise you have to ensure that the data is in valid XML format.

      <request>
        <row_import format_name="Importformat CompanyPerson" input_file="" record_separator="&#10;" field_separator=";">
          <!-- empty @input_file because we have one in the format-->
          <rows>
            <row>Test AG;1020;Wien;Hauptstrasse 68;782612;Joe;Doe</row>
            <row>Test AG;1020;Wien;Hauptstrasse 68;782612;Tom;Tester</row>
            <row><![CDATA[ Test & Co GmbH;2340;Mödling;Einbahnstrasse 77;32145]]></row>
          </rows>
        </row_import>
      </request>

The next example executes basically the same import request as in example for <row_import> - import data in request, but now all data is wrapped into one <data> element.

      <request>
        <row_import format_name=" Importformat CompanyPerson" input_file="" record_separator=";" field_separator=",">
          <!-- empty @input_file because we have one in the format-->
          <data>Test AG,1020,Wien,Hauptstrasse 68,782612,Joe,Doe;Test AG,1020,Wien,Hauptstrasse 68,782612,Tom,Tester;Test GmbH,2340,Mödling,Einbahnstrasse 77,32145</data>
        </row_import>
      </request>

In the next example all data is wrapped into one CDATA section.

      <request>
        <row_import format_name="Importformat CompanyPerson" input_file="" record_separator=";" field_separator=",">
          <!-- empty @input_file because we have one in the format-->
          <data><![CDATA[Test AG,1020,Wien,Hauptstrasse 68,782612,Joe,Doe;Test AG,1020,Wien,Hauptstrasse 68,782612,Tom,Tester;Test & Co GmbH,2340,Mödling,Einbahnstrasse 77,32145]]></data>
        </row_import>
      </request>

The ipos attribute means the hierarchical position of the table, where 0 is the root table, 1 is a child table, 2 is a grandchild table etc. irelpos is an index of the table if imported multiple times.

The status attribute says, if the record is updated or newly created (status = 2) etc. status 0 is returned for the last data set, because in this data set only a company (and no person) is specified. The id attribute represents the id of the record in the Aurea CRM data base. For further details see the remarks in the description of the <row_import> command.

      <response>
        <!-- … -->
        <row_import format_name="pvcs_67776_row_import" record_separator="&#xA;"  field_separator=";">
          <r row="1" ipos="0" irelpos="0" status="261" table="FI" id="296352743515"></r>
          <r row="2" ipos="0" irelpos="0" status="261" table="FI" id="296352743515"></r>
          <r row="3" ipos="0" irelpos="0" status="16" table="FI" id="0">
            <e rc="3">
      <field table="FI" tablename="Company" fid="63" fnr="63" type="L" fieldname="FreeN1"></field>
              <msg>negative value</msg>
            </e>
          </r>
          <r row="4" ipos="0" irelpos="0" status="16" table="FI" id="0">
            <e rc="4">
      <field table="FI" tablename="Company" fid="123" fnr="123" type="D" fieldname="MatchupDate"></field>
              <msg>invalid month</msg>
            </e>
          </r>
          <r row="5" ipos="0" irelpos="0" status="261" table="FI" id="296352743515"></r>
        </row_import>
      </response>
      <request>
        <row_export format_name="Importformat CompanyPerson" output_file="$\Documents\ Export_Firmen_und_Personen.txt "/>
      </request>
      <response>
        <!-- … -->
        <row_export format_name=" Importformat CompanyPerson" output_file="$\ Documents\Export_Firmen_und_Personen.txt"/>
      </response>

The example above illustrates a <row_export> command, where the resulting file is written to the "\documents" subfolder of the CRM.interface installation directory.

Note: Currently there is no possibility to specify separators in the <row_export> directly, this may only be done in the Aurea CRM export format.

<sleep>

The <sleep> command causes interface to sleep for a given number of milliseconds. This request might be useful in testing scenarios.

<sleep>

Appearance

<sleep> </sleep>

Attributes

msec transaction

if

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

Use with caution and consider that time-outs may occur on endpoints.

      <request>
        <sleep msec="1000"/>
      </request >
      <response>
        <sleep msec="1000"/>
      </response>

<status>

The <status> command allows for testing, if interface is up and running – it returns various data (Operating System etc.) where interface is running and internal status data about CRM.interface.

<status/>

Appearance

<status> </status>

Attributes

datamodel profiling_snapshot

if transaction

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

Content of the response may be changed without notice in further versions.

      <request>
        <status/>
      </request>

<test>

The <test> command is for internal purpose only. Do not use except when explicitly instructed to do so.

<transaction>

The <transaction> command is used to begin and end transactions explicitly.

<transaction/>

Appearance

<transaction> </transaction>

Attributes

cmd

if

any Custom Attribute

Contents

(No child elements)

May occur in

<request>

Remarks

For further details see Working with transactions.

<update>

The <update> command allows updating multiple records from a single table (like in the CRMwin service module).

<update/>

Appearance

<update> </update>

Attributes

any Command Attribute

if

any Custom Attribute

Contents

tables links? fields? condition? sortlist? custom_sortlist?

May occur in

<request>

Remarks

The <update> command is executed as a <query> and the resulting records are updated with the specified fields.

Be sure that the set of records to be updated are properly limited by conditions or links, otherwise you might update too many or even all records in a table.

      <request>
        <update>
          <tables>
            <table tablename="Company"/>
          </tables>
          <condition>
            <cond tablename="Company" fieldname="Company" op="=" value="Test interface 1"/>
          </condition>
          <fields>
            <Company>
              <Synonym>update</Synonym>
              <FreeN1>10</FreeN1>
            </Company>
          </fields>
        </update>
      </request>
      <response>
        <update>
          <return table="FI" tablename="Company" id="4294979929" type="update"/>
          <return table="FI" tablename="Company" id="4294979937" type="update"/>
        </update>
      </response>

In the example above all company records that match the condition (Company starts with "update-test") is updated with the fields Synonym and FreeN1.

The response returns the record id of each updated record.

<xquery>

The <xquery> command executes a "Query" or "Read Engine" format.

<xquery />

Appearance

<xquery> </xquery>

Attributes

name type

any Command Attribute

if

any Custom Attribute

Contents

par*

May occur in

<request>

Remarks

Regarding par* see example below.

In the example the format with type "Query" (defined in CRMweb) and the declared name ("My Web Query") is read and executed. The response does not return the format definition but the records which are the result of executing the query.

      <request>
        <xquery name="My Web Query" type="32"/>
      </request>
      <response>
        <xquery name="My Web Query" type="32">
          <Company tableshort="FI" id="4294967332">
            <Company>My Company 1</Company>
            <Synonym>internal</Synonym>
            <Country>Österreich</Country>
            <Person tableshort="KP" id="4294968027">
              <LastName>Maier</LastName>
              <FirstName>Sabine</FirstName>
            </Person>
            <Person tableshort="KP" id="4294968028">
              <LastName>Müller</LastName>
              <FirstName>Stefan</FirstName>
            </Person>
            <!-- … -->
          </Company>
          <Company tableshort="FI" id="4294975524">
            <!-- … -->
          </Company>
        </xquery>
      </response>

In this case the format with type "Read Engine" is executed and the response also returns the resulting records. The structure of the response is similar to the example before.

      <request>
        <xquery name="My Read Engine" type="34"/>
      </request>

If the "Query" or "Read Engine" format contains parameters, they need to be specified in <par> elements. Each parameter is referenced with fieldname and its respective table prefix.

      <request>
        <xquery name="Test Read Engine with parameter" type="34">
          <par prefix="FI" fieldname="Country">Österreich</par>
        </xquery>
      </request>

If parameters are unresolved, the following error is returned:

      <response>
        <!--... -->
        <xquery name="Test" type="34">
          <return type="error" func="C_CursorMD::ResolveFilterParameters">
            <ecode>-10081</ecode>
            <etext>Unresolved parameter</etext>
            <prefix>FI</prefix>
            <fieldname>Country</fieldname>
            <index>0</index>
          </return>
        </xquery>
      </response>