Uživatelské nástroje

Nástroje pro tento web


crm:admin:xmlconn2

XML konektor (verze InTouch CRM 5.5 a vyšší)

Při implementaci podpory neomezeného počtu kontaktních údajů u záznamů v adresáři, muselo být odstraněno několik databázových sloupců a v důsledku toho zanikly i jim odpovídající pole při komunikaci přes rozhraní XML konektoru.

Zaniklá pole podle typu záznamu:

Kontakt - telWork, telWork2, telPrivate, mobile, fax, email, emailSec, web

Adresa - tel1, tel2, fax, email1, email2, web

Osoba - telWork, telWork2, telPrivate, mobile, fax, email, emailSec, emailPrivate

Nově zaváděná pole (pro všechny typy záznamů):

phone

email

web

Nově je nutné počítat s tím, že může být více polí pojmenováno těmito názvy.

Jak klient pozná, že v odpovědi serveru jsou názvy polí v novém formátu

V XML dokumentu odpovědi je v kořenovém elementu <ok> uveden atribut version s hodnotou 2.0 nebo vyšší:

<?xml version="1.0" encoding="UTF-8"?>
<ok version="2.0">...</ok>

Pokud má atribut version hodnotu nižší než 2.0 nebo pokud úplně chybí, je třeba očekávat názvy polí ve starém formátu. Kompatibilitu svého klienta zajistíte tedy jednoduše:

String version = okElement.getAttribute("version");
double versionNum = version == null ? 1.0 : parseDouble(version);
if (versionNum >= 2.0) {
    // nová verze serveru
} else {
    // stará verze serveru
}

Zpětná kompatibilita

V odpovědi XML konektoru verze 2.0 nejsou původní pole již obsažena. S ohledem na zachování zpětné kompatibility je možné se na ně ptát, nebo podle nich filtrovat, ale v odpovědi budou hodnoty reprezentovány novým způsobem.

Například dotaz tohoto typu (výběr kontaktů podle e-mailu) je stále funkční:

<?xml version="1.0" encoding="utf-8"?>
<touch>
   <actions>
      <list entity="contact">
         <fields>
            <field name="email" type="string">zakaznicky_email@seznam.cz</field>
         </fields>
      </list>
   </actions>
</touch>

Ale v XML odpovědi již neobdržíte pole telWork, ale stejný údaj v novém formátu (email + atribut „priority“), např.:

<?xml version="1.0" encoding="UTF-8"?>
<ok version="2.0">
   <fields primaryKey="XXXX">
      .
      <field name="phone" priority="1">+420XXXXXXXXX</field>
      <field name="email" priority="3">zakaznicky_email@anneca.cz</field>
      <field name="web" priority="2">http://www.anneca.cz</field>
      .
   </fields>
</ok>

Do samotné hlavičky odpovědi jsme přidali version=„2.0“, aby mohl klient detekovat, že v odpovědi už nelze očekávat původní názvy polí a je nutné kontaktní údaje načítat novým mechanismem.

V uvedeném příkladu odpovědi jsou vidět pole phone1, email2, web3.

Nové názvy polí kontaktních údajů

Na formuláři v CRM můžete libovolně měnit pořadí (prioritu) jednotlivých kontaktních údajů.

V XML konektoru je pro určení pořadí definován atribut „priority“ a pro jednotlivé typy kontaktních údajů byly zvoleny výrazy phone, email a web.

Na uvedeném příkladu (viz. výše) je vidět, že na formuláři je pořadí kontaktních údajů následující:

  1. telefonní kontakt
  2. web
  3. emailová adresa

Nový způsob zápisu/aktualizace kontaktních údajů

Díky konverzi polí při zpracování, na straně serveru je možné kontaktní údaje zapisovat starým způsobem, např.:

<?xml version="1.0" encoding="utf-8"?>
<touch>
   <actions>
      <create entity="customer">
         <fields>
            .
            <field name="telWork">+420XXXXXXXXX</field>
            <field name="emailSec">zakaznicky_email@anneca.cz</field>
            .
         </fields>
      </create>
   </actions>
</touch>

Při zpracování tohoto požadavku se z přijatých polí telWork a emailSec udělá seznam kontaktních údajů a po zápisu kontaktu do databáze se v dalším kroku zapíší i tyto kontaktní údaje (v pořadí, v jakém byly uvedeny v XML dávce). Pokud provedete dotaz „list“, či „lookup“ na takto vytvořený záznam, tak dostanete v XML odpovědi např. pole phone (s prioritou 1), a email (s prioritou 2).

Tímto způsobem lze ovšem „po staru“ zapsat jen omezený počet kontaktních údajů (počet klíčových výrazů je omezen a není nijak definováno pořadí těchto kontaktních údajů). Pro zapsání libovolného počtu je vhodné používat symbolické výrazy (stejné, jako ty, které vrací aplikace v odpovědi), např.:

<?xml version="1.0" encoding="utf-8"?>
<touch>
   <actions>
      <create entity="customer">
         <fields>
            .
            <field name="phone" priority="1">+420XXXXXXXXX</field>
            <field name="email" priority="2">zakaznicky_email@anneca.cz</field>
            .
         </fields>
      </create>
   </actions>
</touch>

Tímto zápisem můžete docílit zápisu neomezeného počtu kontaktních údajů (uvedením atributů „priority“ můžete navíc ovlivnit pořadí údajů na formuláři).

UPOZORNĚNÍ - Aktualizace (kontaktních údajů) funguje tak, že pokud je v obdržených datech detekován kontaktní údaj (podle jeho názvu, nebo je detekován klíčový symbolický výraz, viz. výše), tak se všechny již existující kontaktní údaje smažou a jsou kompletně nahrazeny vstupními daty.
Při aktualizaci kontaktních údajů je tedy nutné zasílat vždy celou kolekci kontaktních údajů, které mají být u záznamu evidovány (nelze zasílat např. jen nově zjištěný email).

UPOZORNĚNÍ k verzi 5.5.1 - předchozí nedostatek (nutno v XML zasílat všechny kontaktní údaje) byl ve verzi 5.5.1 odstraněn. Přijatý kontaktní údaj z XML konektoru je pomocí kontrolního mechanismu přidán jako nový (nebo vyhodnocen jako již duplicitní). Ve verzi 5.5.1 je snazší kontaktní údaj přidat. Smazání již existujícího kontaktního údaje je možné jen pomocí aktualizace (akce <update> v atributem mode=„replace“) - důrazně upozorňujeme, že v tomto módu je nutné v XML zasílat všechny kompletní údaje, které chcete, aby byly u kontaktu uloženy (údaje, které XML nebude obsahovat budou u již existujícího kontaktu smazány).

Zápis a čtení souhlasů se zpracováním osobních údajů

UPOZORNĚNÍ k verzi 5.7 - do XML konektoru přidána podpora čtení (akce <list>) a zápisu (akce <create>) souhlasů se zpracování osobních údajů kontaktů a osob, pomocí entity „consent“.

Zaniklá pole: newsletter, ourInfo, partnerInfo, acceptance, acceptanceAll

<?xml version="1.0" encoding="utf-8"?>
<touch>
   <actions>
       <create entity="consent">
           <fields>
               <field name="customer">1</field>
               <field name="consentType">1</field>
               <field name="description">Souhlas poskytnut ze zákaznické zóny</field>
               <field name="value">true</field>
           </fields>
       </create>
   </actions>
</touch>

V případě, že potřeba zapsat více, než jen jeden souhlas, tak je možné zapsat všechny souhlasy najednou v jednom zapisovacím XML a nemusí se posílat jednotlivé požadavky postupně.

<?xml version="1.0" encoding="utf-8"?>
<touch>
   <actions>
       <create entity="consent">
           <fields>
               <field name="customer">1</field>
               <field name="consentType">1</field>
               ...
           </fields>
       </create>
       <create entity="consent">
           <fields>
               <field name="customer">1</field>
               <field name="consentType">1</field>
               ...
           </fields>
       </create>
   </actions>
</touch>

Metoda <create> je implementována tak, že pokud je u záznamu nalezen již existující souhlas se stejnou hodnotou value a stejným popiskem description, tak se nový záznam nevytváří (neobsahuje žádnou novou „hodnotu“). V ostatních případech je souhlas zapsán jako nový záznam. Po aktualizaci/zápisu záznamu Kontaktu/Osoby vrátí XML konektor v odezvě primární klíč záznamu a ten je pak možné použít pro následující zápis souhlasů. Souhlasy je vhodné zapisovat, jen tehdy pokud je opravdu detekována změna (tj. pokud došlo ke změně daného souhlasu). V opačném případě (tj. po každém zápisu kontaktu zapisovat i jeho souhlasy) je nutné již existující souhlasy nejprve načíst (případně upravit ty, které se měnily) a poté provést zápis zpět do aplikace.

Pro čtení již existujících souhlasů je nutné použít akci <list>.

<?xml version="1.0" encoding="utf-8"?>
<touch>
   <actions>
      <list entity="consent">
         <fields>
            <field name="customer" operator="=">1</field>
         </fields>
      </list>
   </actions>
</touch>

Příklad odpovědi může být např.:

<?xml version="1.0" encoding="UTF-8"?>
<ok version="2.0">
   <fields primaryKey="5">
      <field name="customer">1</field>
      <field name="consentType">1</field>
      <field name="sourceType">3</field>
      <field name="description">Poznámka k souhlasu se zpracováním osobních údajů</field>
      <field name="entered">1524660762000</field>
      <field name="value">true</field>
   </fields>
   <fields primaryKey="8">
      <field name="customer">1</field>
      <field name="consentType">2</field>
      <field name="sourceType">3</field>
      <field name="description">Poznámka k souhlasu s poskytnutím os. údajů třetím stranám</field>
      <field name="entered">1524662354000</field>
      <field name="value">true</field>
   </fields>
   <fields primaryKey="7">
      <field name="customer">1</field>
      <field name="consentType">10</field>
      <field name="sourceType">3</field>
      <field name="description">Poznámka k nesouhlasu zasílání zpravodaje</field>
      <field name="entered">1524660922000</field>
      <field name="value">false</field>
   </fields>
</ok>

Význam jednotlivých atributů je popsán v referenční příručce souhlasů.

crm/admin/xmlconn2.txt · Poslední úprava: 10.10.2018 12:10 autor: herman