Uživatelské nástroje

Nástroje pro tento web


crm:admin:xmlconn5_7

Vzdálená komunikace s InTouch CRM přes XML Connector (do verze 5.7)

Změny verze 5.7

Úvod

InTouch CRM umožňuje přijímat a zpracovávat data z jiných informačních systémů. Typickým příkladem je požadavek na vytvoření záznamu v InTouch CRM na základě údajů získaných prostřednictvím webového formuláře.

Adresa pro komunikaci s XML Connectorem

Předpokládajme, že máte k dispozici nainstalovaný a běžící InTouch CRM na adrese http://my.server.com/intouch. URL adresa pro komunikaci s XML Connectorem je vždy ve tvaru ADRESA_CRM/connector.do. XML Connector bude mít v našem případě adresu http://my.server.com/intouch/connector.do. V případě CRM Online verze, musíte do URL adresy zadat i Váš kód ONLINE verze. Např.http://my.server.com/intouch/connector.do?crmID=KOD123

Jinými slovy, na výše uvedené URL bude třeba posílat XML zprávy protokolem HTTP, aby byla navázána žádaná komunikace.

Požadavky lze zasílat v kódování windows-1250, nebo v UTF-8. Aplikace toto kódování respektuje z definice hlavičky XML (např. encoding=„windows-1250“). Ovšem odpovědi aplikace na dotazy jsou standartně v kódování UTF-8.

Způsob předání XML zprávy

Připravená XML zpráva (formát je popsán níže) musí být předána v parametru data. To také znamená, že je třeba poslat html požadavek jako typ application/x-www-form-urlencoded.

Příklad navázání komunikace (JAVA)

Na příkladu níže je vidět ukázka JAVA kódu pro navázání komunikace s XML Connectorem.

// připravená data
String XML = "<?xml version="1.0" encoding="windows-1250"?> ...";
// navázání spojení a předání dat
URL url = new URL("http://my.server.com/connector.do");
URLConnection   con = url.openConnection();
con.setRequestProperty("Content-Type",
			"application/x-www-form-urlencoded");
con.setDoOutput(true);
OutputStream os = con.getOutputStream();
// je třeba překódovat XML do formátu x-www-form-urlencoded
String encodedXml = "data="+encode(xml,"windows-1250");
os.write(encodedXml.getBytes("iso-8859-1"));
os.flush();
os.close();
// získání výsledků
InputStream is = con.getInputStream();
Document    doc = Xml.createDocument(is);
is.close();

Ukázka přenášených dat

Na příkladu níže je vidět jak může vypadá dotaz na XML Connector. Jedná se o vytvoření kontaktu v adresáři s hodnotami jméno=John a příjmení=Brown.

<?xml version="1.0" encoding="UTF-8"?>
<touch>
	<actions>
		<create entity="contact">
			<fields>
			<field name="firstname" type="string">John</field>
			<field name="surname" type="string">Brown</field>
			</fields>
		</create>
	</actions>
</touch>

Podstatná je část uvnitř tagu <actions>. Je to seznam akcí, které je možné od InTouch CRM požadovat k provedení. V tomto případě se jedná o vytvoření kontaktu, a proto je zasílána jedna akce <create>.

Příslušná odpověď by pak mohla vypadat takto:

<?xml version="1.0">
<ok primaryKey="235"></ok>

Její význam je, že se podařilo úspěšně založit nový kontakt v adresáři a jeho přidělený kód je 235.

Popis formátu XML

Podporované akce

Jak je vidět z DTD, klientský program může po InTouch CRM požadovat provedení tzv. akcí, které jsou obsaženy v elementu <actions>. Stávající implementaci connectoru podporuje těchto pět akcí.

create Vytvoření nového záznamu v databázi
update Aktualizace stávajícího záznamu
lookup Nalezení exitujícího záznamu
getId Získání kódů existujících záznamů podle požadavku
list Získání informací o více záznamech současně (např. kompletní ceník produktů)
factsheet Získání faktů ke kontaktu s určitým kódem
getSql Získání dat pomocí libovolného SQL SELECT dotazu

Každá z uvedených akcí (kromě factsheet) musí obsahovat povinný atribut entity, který určuje, na jakém typu záznamů se operace provádí (kontakt, komunikace, produkt, apod.).

Prvek field

Akce musí obsahovat seznam polí, jejichž hodnoty určují, co se vytváří, hledá a nebo aktualizuje. Všechny podstatné informace jsou obsaženy v elementu <field>.

<field name="XXX" type="string">...</field>

Atribut name určuje název pole (platný seznam názvů je uveden níže), type určuje typ dat (např. řetězec=string) a obsah elementu jsou vlastní data pole.

Prvek xfield

Některé objekty v CRM mají tzv. atributy (např. atributy kontaktu, atributy nabídky, atd - neplést s atributy XML souboru). Tyto atributy jsou uloženy v jiných databázových tabulkách a pro jejich zápis je nutné je nějakým způsobem oddělit od standartních polí. K tomu slouží právě tag <xfield>.

<xfield name="XXX" type="string">...</xfield>

Podporované entity

Aby bylo možné posílat požadavky na akce systému InTouch CRM, je třeba znát seznam entit, se kterými je možné pracovat.

Název Význam
customer Kontakt v adresáři
contact Kontakt v adresáři
person Osoba u kontaktu
branch Pobočka nebo adresa kontaktu
address Pobočka nebo adresa kontaktu
opportunity Příležitost
order Objednávka
orderitem Položka objednávky
invoice Vydaná faktura
communication Komunikace (telefon, fax, apod.)
task Úkol
event Událost
file Soubor nebo dokument
document Soubor nebo dokument
product Produkt
pcategory Kategorie produktu<
image Obrázek, který je připojen k produktu
content Záznam ze správce obsahu (viz. Znalosti)
note Poznámky
store Sklady
storeitem Položky na skladě
problem Problém
problemcomment Komentář k problému
fact Fakt (informace) ke kontaktu

Příklad vytvoření kontaktu (akce create)

Požadavek na vytvoření kontaktu je níže. V seznamu polí musí být při vytváření záznamu ty pole, které jsou povinné. Informaci o tom, které pole je povinné zjistíte z přehledu polí pro jednotlivé entity (uvedeno níže).

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<create entity="contact">
		<fields>
			<field name="company" type="string">Hurnbach s.r.o.</field>
			<field name="fileAs" type="string">Dobrota</field>
			<field name="email" type="string">dobrota@hurnbach.cz</field>
			<field name="enteredFrom" type="string">webf</field>
			<field name="surname" type="string">Dobrota</field>
			<field name="firstname" type="string">František</field>
			<field name="language" type="string">cz</field>
			<field name="comment" type="string">Zaregistroval se na webu</field>
		</fields>
	</create>
</actions>
</touch>

Odpověď při úspěšném provedení:

<?xml version="1.0" encoding="utf-8"?>
<ok primaryKey="17"></ok>

Uvedená odpověď znamená, že byl záznam vytvořen a byl mu přidělen kód 17 (primární klíč).

Příklad vyhledání kontaktu (akce lookup)

Požadavek je opět uveden níže. Pro vyhledání kontaktu použijeme akci s názvem lookup a entitu contact. Pokud chceme vyhledat záznam, musíme uvést pole, podle kterých chceme vyhledávat v databázi. V tomto případě hledáme záznam, který má kód (primární klíč) roven číslu 17.

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<lookup entity="contact">
		<fields>
			<field name="id" type="string">17</field>
		</fields>
	</lookup>
</actions>
</touch>

Odpověď bude vypadat takto:

<?xml version="1.0" encoding="UTF-8"?>
<ok primaryKey="17">
<fields>
	<field name="company" type="string">Hurnbach s.r.o.</field>
	<field name="fileAs" type="string">Dobrota</field>
	<field name="email" type="string">dobrota@hurnbach.cz</field>
	... (výpis zjednodušen vynecháním polí) ...
	<field name="enteredFrom" type="string">webf</field>
	<field name="surname" type="string">Dobrota</field>
	<field name="firstname" type="string">František</field>
	<field name="language" type="string">cz</field>
	<field name="comment" type="string">Zaregistroval se na webu</field>
</fields>
</ok>

Některé tagy <field> mohou obsahovat atribut junk=„true“, který znamená, že údaj je neplatný a nepůjde jej zapsat zpět. Většinou se to týká kontaktních údajů, ale i u ostatních kontrolovaných hodnot (rodné číslo, příjmení, IČO, …). Ve výstupu to může vypadat následovně:

	...
	<field name="surname" junk="true">Samec1980</field>
	<field name="ico" junk="true">2222</field>
	...

V příkladu je vidět neplatné příjmení osoby (obsahuje číslice) a neplatné IČO (špatný počet číslic, neplatný formát). Pokud z CRM přijdou údaje označené jako junk je ideální nejdříve požádat uživatele o opravu (např. webový profil).

Příklad aktualizace kontaktu (akce update)

V následujícím příkladě chceme zaslat do InTouch CRM změněná pole, tj. aktualizovat existující záznam. Je důležité vědět, že v seznamu polí se musí vyskytovat primární klíč záznamu, což je pro kontakt pole id. Požadavek bude vypadat takto:

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<update entity="contact">
		<fields>
			<field name="company" type="string">Hurnbach s.r.o.</field>
			<field name="email" type="string">dobrota@hurnbach.cz</field>
			<field name="surname" type="string">Dobrota</field>
			<field name="firstname" type="string">František</field>
			<field name="id" type="string">17</field>
		</fields>
	</update>
</actions>
</touch>

Odpověď:

<?xml version="1.0" encoding="UTF-8"?>
<ok primaryKey="17"></ok>

Přepis celého záznamu (pouze pro adresář)

Pokud nechcete u záznamů v adresáři CRM aktualizovat jen některá pole, ale chcete celý záznam kompletně přepsat novými údaji, můžete do tagu <update> přidat atribut mode=„replace“. Pole, pro která nebyl v dávce korespondující tag <field>, budou po aktualizaci prázdná.

Vynechání validace (pouze pro adresář)

Díky postupnému zpřísnění kontroly platnosti zapisovaných dat může nastat situace, že v databázi CRM jsou neplatné údaje kontaktu (čísla v příjmení, špatná telefonní čísla, apod.). Takové záznamy je možné aktualizovat jen tehdy, pokud aktualizujete pouze vybraná pole uvedená níže. Při pokusu o aktualizaci jiného pole, než která zde uvádíme, je prováděna plná kontrola zapisovaných dat a <update> může skončit chybou.

Pole, u kterých není prováděna plná kontrola platnosti dat jsou: id, comment, newsletter, ourInfo, partnerInfo, vip, categories, acceptance, acceptanceAll, password, canShopping, globalStatus, form.

(pole id je ve výčtu jen proto, že je nutné ho uvádět kvůli nalezení záznamu, který se má aktualizovat)

Příklad vyhledání kódů - primárních klíčů (akce getId)

Akci getId můžeme s úspěchem využít tehdy, když potřebujeme zjistit kódy záznamů, které vyhovují nějaké podmínce. V následujícím příkladě se dotazujeme na kódy produktů, které byly upraveny po 11.5.2006 12:34.

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<getId entity="product">
		<fields>
			<field name="modified" type="string" operator="&gt;">2006-05-11 12:34:00</field>
		</fields>
	</getId>
</actions>
</touch>

Odpověď:

<?xml version="1.0" encoding="UTF-8"?>
<ok primaryKey="5">
<fields>
	<field name="id2" type="string">5</field>
	<field name="id1" type="string">4</field>
	<field name="id0" type="string">1</field>
</fields>
</ok>

V odpovědi je vidět seznam kódů, které systém vrátí, a které vyhovují dotazu. Jsou pojmenovány id0 - id2. Toto pojmenování však nemá žádný význam. Klientská aplikace může názvy ignorovat a používat pouze hodnoty uvnitř elementu pro další dotazy.

Příklad získání seznamu záznamů (akce list)

V následujícím příkladě se dotazujeme na seznam produktů, které byly upraveny po 11.5.2006 12:34.

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<list entity="product">
		<fields>
			<field name="modified" type="string" operator="&gt;">2006-05-11 12:34:00</field>
		</fields>
	</list>
</actions>
</touch>

Odpověď bude vypadat takto:

<?xml version="1.0" encoding="UTF-8"?>
<ok>
<fields primaryKey="20">
	<field name="id" type="string">20</field>
	<field name="name" type="string">Apple MacBook Pro</field>
	...údaje o produktu s kódem 20
</fields>
<fields primaryKey="21">
	<field name="id" type="string">21</field>
	<field name="name" type="string">Apple iPod Nano 4GB (red)</field>
	...údaje o produktu s kódem 21
</fields>
... další produkty
</ok>

Z důvodu výkonostních je odpověď limitována na max. 1000 záznamů. To znamená, že pokud máte v InTouch CRM více než 1000 záznamů, budete nuceni provést více dotazů. Akce vrací seznamy seřazené podle primárního klíče (id). Pokud tedy nejvyšší id v prvním dotazu bylo 1350, tak v následujícím dotazu provedete volání takto:

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<list entity="product">
		<fields>
			<field name="modified" type="string" operator="&gt;">2006-05-11 12:34:00</field>
			<field name="id" operator="&gt;">1350</field>
		</fields>
	</list>
</actions>
</touch>

Atribut operator, který použijete v dotazu, může nabývat následujících hodnot: <, >, ⇐, >=, !=, starts, ends, contains. Je samozřejmé, že místo znaků < a > musíte psát &lt; resp. &gt;, aby dotaz vyhověl syntaxi XML.

Příklad získání seznamu faktů ke kontaktu (factsheet)

Následující dotaz vrátí seznam všech faktů ke kontaktu s kódem 123.

<?xml version="1.0" encoding="UTF-8"?>
<touch>
<actions>
	<factsheet type="customer" id="123"/>
</actions>
</touch>

Odpověď bude vypadat takto:

<?xml version="1.0" encoding="UTF-8"?>
<ok>
	<fields primaryKey="clickBanner|123">
		<field name="title" type="string">Kliknul na banner na webu</field>
		<field name="created" type="string">1336125307000</field>
		<field name="priority" type="string">70</field>
		<field name="kindGroup" type="string">clicks</field>
		<field name="value" type="string">25.3.2012</field>
		<field name="closed" type="string">false</field>
		<field name="display" type="string">3</field>
		<field name="customer" type="string">123</field>
		<field name="type" type="string">0</field>
		<field name="kind" type="string">clickBanner</field>
		<field name="modified" type="string">1336125521000</field>
		<field name="info" type="string">Přišel na web díky Google AdWords</field>
	</fields>
	<fields primaryKey="surveyForm|123">
		<field name="title" type="string">Vyplnil dotazník</field>
		...
	</fields>
	...
</ok>

Příklad získání dat (akce getSql)

Akci getSql lze použít na libovolné získání dat z CRM. Povinný je atribut table - název tabulky v SQL databázi a seznam elementů fields - seznam SQL sloupců, jejichž data chcete získat. Nepovinné jsou elementy where - SQL podmínka a limit - SQL limit vrácených výsledků.

<?xml version="1.0"?>
      <touch>
      <actions>
        <getSql table="special_note">
          <where>type=1</where>
          <limit>2</limit>
          <fields>
            <field name="id" />
          </fields>
        </getSql>
      </actions>
      </touch>

Odpověď:

      <ok>
        <fields primaryKey="row1">
          <field name="id" type="string">2734</field>
        </fields>
        <fields primaryKey="row2">
          <field name="id" type="string">2737</field>
        </fields>
      </ok>

V odpovědi je vidět seznam vyhovujícíh záznamů v SQL databázi a zobrazeny jsou u nich pouze hodnoty definované přes element fields.

Chyby

V případě, že se požadovaná akce nepodaří uskutečnit, výsledkem bude odpověď v následujícím tvaru.

<?xml version="1.0" encoding="UTF-8"?>
<errors>
	<error>Column not found,  message from server: "Unknown column 
	'type' in 'where clause'"</error>
</errors>

Chyb, které jsou obsaženy v elementu error může být v odpovědi více.

Popis jednotlivých entit

Pro každou podporovanou entitu potřebujete znát význam a pojmenování polí. Podívejte se prosím do referenční příručky tvůrce předloh, kde naleznete požadovanou dokumentaci.

file (document)

Entita file reprezentuje v CRM soubor sekce Dokumenty. Přes tuto entitu nelze vytvářet adresář. Obsah souboru se přenáší v elementu content a je interpretován jako bytové pole, zakódované do datového formátu Base64.

crm/admin/xmlconn5_7.txt · Poslední úprava: 11.10.2018 11:10 autor: herman