Uživatelské nástroje

Nástroje pro tento web


crm:admin:xmlconn

Vzdálená komunikace s InTouch CRM přes XML Connector

Změny verze 4.0

  • Od této verze je interně upraven formát datumů na tzv. timestamp (počet ms od 1.1.1970, tj. např. 1.1.2011 12:25:00 → 1293881100000, POZOR v PHP je timestamp jen počet sekund - pak je nutné pro zápis přidat „000“ a při čtení číst jen prvních 10znaků). Pro dotazy a zápis hodnot můžete i nadále používat „starý“ běžný formát, ale aplikace bude datum vracet vždy v tomto novém formátu.

Změny verze 5.5

  • Spolu se změnou zapisování kontaktních údajů se změnil i jejich způsob čtení/zápisu. Ve verzi 5.5 byla zrušena standardní kontaktní políčka (u Kontaktů, Adres a Osob) jako Telefon, Telefon 2, Mobil, E-mail, E-mail 2 a Web.

Změny verze 5.5.1

  • Nové možnosti při aktualizaci v adresáři - akce <update> (aktualizace bez validace, přepsání celého záznamu).
  • Akce <list> a <lookup> informuje o neplatných hodnotách.

Změny verze 5.7

Změny verze 6.0

  • Se změnou formuláře kontaktu (osob a adres) došlo i ke změně v XML konektoru (InTouch 6.0). Přidali jsme podporu entity „party“ (obecná náhrada za „customer“, „person“ a „branch“) a dále pak novou akci „import“ (při které nemusíte řešit, zda provádět prvotní zápis „create“, nebo aktualizaci „update“).

Ú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.

Nejběžnější scénář komunikace mezi webem a InTouch CRM může vypadat takto: zákazník vyplní na webu objednávku, web zašle požadavek na registraci zákazníka do InTouch CRM a v odpovědi dostane přidělený kód zákazníka - web zašle data objednávky do InTouch CRM a dostane zpět kód vytvořené objednávky - web oba kódy zobrazí zákazníkovi s oznámením o potvrzení objednávky.

Jak napovídá název kapitoly, veškerá komunikace mezi druhým informačním systémem a InTouch CRM probíhá pomocí XML zpráv. Pro přenos těchto zpráv je použit protokol HTTP, metoda POST. Modul, který komunikaci zajišťuje, se jmenuje XML Connector a je standardní součástí InTouch CRM.

Z předchozího odstavce vyplývá, že pro správnou funkčnost XML Connectoru je třeba mít na firewallu povolenou komunikaci mezi serverem s InTouch CRM a serverem s druhým informačním systémem. Standardní port HTTP je 80. Pokud jste při instalaci zvolili jiný port, musíte příslušně změnit nastavení firewallu.

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>
		<import entity="party">
			<fields>
			<field name="type">ORGANIZATION</field>
			<field name="company">ANNECA s.r.o.</field>
			<field name="fileAs">ANNECA s.r.o.</field>
			</fields>
		</import>
	</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 <import>.

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 (nebo aktualizovat nalezený) 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
import Zajistí zápis záznamu do databáze (buďto vytvoří nový, nebo aktualizuje nalezený)
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.

Od verze 6.0 je type nepovinný, pokud se vyloženě nejedná o nějaké bytové pole (např. pro content u obrázků), tak není nutné type uvádět.

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

Pro zápis číselných, nebo datumových hodnot (které se stejně parsují z textového zápisu) se používá type=„string“, tudíž od verze 6.0 není nutné ho uvádět.

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">...</xfield>

Podporované entity (InTouch CRM verze 6.0)

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
party Kontakt, osoba či pobočka v adresáři
membership Vztah mezi „kontakty“
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
customer Kontakt (zpětně kompatibilní)
person Osoba (zpětně kompatibilní)
branch Adresa (zpětně kompatibilní)

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.

Příklad vytvoření firmy (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>
	<import entity="party">
		<fields>
			<field name="type">ORGANIZATION</field>
			<field name="company">Hurnbach s.r.o.</field>
			<field name="fileAs">Hurnbach s.r.o.</field>
			<field name="email">info@hurnbach.cz</field>
			<field name="enteredFrom">webf</field>
			<field name="ico">12345678</field>
			<field name="dic">CZ12345678</field>
			<field name="language">cs</field>
			<field name="comment">Zaregistroval se na webu</field>
		</fields>
	</import>
</actions>
</touch>

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

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

Uvedená odpověď znamená, že byl vytvořen (nebo aktualizován) záznam s kódem 17 (primární klíč).

Použitá akce import zajistí zápis importovaných dat do databáze a vrátí kód záznamu. Při importu mohou nastat dvě situace:

  • importovaný záznam je unikátní a dojde k zápisu nového záznamu do databáze
  • importovaný záznam už v databázi je a import provede jeho aktualizaci a vrátí kód již existujícího/nalezeného záznamu

To, jestli systém vyhodnotí importovaná data jako duplicitu, nebo nový záznam, se provádí vyhledáním duplicity podle následujících polí:

  • kontaktní údaje
  • IČO
  • Společnost
  • Rodné číslo
  • Symbol

Samozřejmě je možné, že podle importovaných dat se může najít duplicit víc a v tom případě algoritmus nijak nedefinuje, který z nich pro aktualizaci použije. Pokud tedy víte, že ve Vaší databázi je mnoho duplicit, a chcete mít pod kontrolou to, jaký konkrétní záznam se použije pro aktualizaci, tak musíte použít vlastní sekvenci dotazů (akce list, či getId) pro ověření, zda kontakt už v databázi není a případně nalezený použít pro akci update.

Pro „neduplicitní“ databázi kontaktů je vhodnější a především jednodušší používat akci import.

Příklad vyhledání firmy (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="party">
		<fields>
			<field name="id">17</field>
		</fields>
	</lookup>
</actions>
</touch>

Odpověď bude vypadat takto:

<?xml version="1.0" encoding="UTF-8"?>
<ok primaryKey="17">
<fields>
	<field name="id">17</field>
	<field name="type">ORGANIZATION</field>
	<field name="company">Hurnbach s.r.o.</field>
	<field name="fileAs">Hurnbach s.r.o.</field>
	... (výpis zjednodušen vynecháním polí) ...
	<field name="enteredFrom">webf</field>
	<field name="ico">12345678</field>
	<field name="dic">CZ12345678</field>
	<field name="language"cz</field>
	<field name="comment">Zaregistroval se na webu</field>
	<field name="email" priority="1">info@hurnbach.cz</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 firmy (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="party">
		<fields>
			<field name="id">17</field>
			<field name="company">Hurnbach s.r.o.</field>
			<field name="email">zakaznicke_centrum@hurnbach.cz</field>
			<field name="street">Koníčková 16</field>
			<field name="city">Sekačkovice</field>
			<field name="zip">11150</field>
			<field name="country">CZ</field>
		</fields>
	</update>
</actions>
</touch>

Odpověď:

<?xml version="1.0" encoding="UTF-8"?>
<ok primaryKey="17" version="2.0"></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, vip, categories, 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" 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">5</field>
	<field name="id1">4</field>
	<field name="id0">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" 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">20</field>
	<field name="name">Apple MacBook Pro</field>
	...údaje o produktu s kódem 20
</fields>
<fields primaryKey="21">
	<field name="id">21</field>
	<field name="name">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" 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">Kliknul na banner na webu</field>
		<field name="created">1336125307000</field>
		<field name="priority">70</field>
		<field name="kindGroup">clicks</field>
		<field name="value">25.3.2012</field>
		<field name="closed">false</field>
		<field name="display">3</field>
		<field name="customer">123</field>
		<field name="type">0</field>
		<field name="kind">clickBanner</field>
		<field name="modified">1336125521000</field>
		<field name="info">Přišel na web díky Google AdWords</field>
	</fields>
	<fields primaryKey="surveyForm|123">
		<field name="title">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ů. UPOZORNĚNÍ - použití této akce je na vlastní nebezpečí a je to striktně závislé na databázové struktuře dat, která se může v dalších verzích měnit

<?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">2734</field>
</fields>
<fields primaryKey="row2">
	<field name="id">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.

crm/admin/xmlconn.txt · Poslední úprava: 15.10.2018 12:10 autor: herman