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>
<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>
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
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.
<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").
<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 (" " 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=" " 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=" " 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="
" 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.
<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>