Integrace Ecomail s eWay-CRM

Integrace Ecomail s eWay-CRM slouží k automatické synchronizaci kontaktů mezi eWay-CRM a marketingovým nástrojem Ecomail.

Obsah

K čemu integrace slouží

Integrace je navržená tak, aby se nové nebo upravené kontakty z eWay-CRM automaticky přenášely do vybraných seznamů v Ecomailu.

Synchronizace podporuje vytvoření i aktualizaci kontaktu, přiřazení kontaktu do jednoho nebo více seznamů, práci se štítky (kategoriemi), uživatelskými poli a stavem odběru newsletteru.

Kontakt může být v Ecomailu zařazený do více seznamů současně. V každém seznamu může mít vlastní stav, například v jednom seznamu může být přihlášený a v jiném odhlášený.

Jaká data se synchronizují

Do Ecomailu se dá kontakt vytvořit nebo aktualizovat ve chvíli, kdy má v eWay-CRM vyplněnou e-mailovou adresu a je u něj zvolený alespoň jeden cílový seznam, který je identifikovaný pomocí ID.

Ve výchozím rozsahu se synchronizují především tyto údaje:

Pole v eWay-CRM Pole v Ecomailu Poznámka
E-mail E-mail Povinné pole a hlavní identifikátor kontaktu
Jméno Jméno
Příjmení Příjmení
Datum narození (je třeba vlastní pole) Narozeniny Volitelné datumové pole
Adresa Adresa
Společnost Firma
Zaměstnání Telefon
Nezasílat newsletter Přihlášen / Odhlášen Řídí stav odběru
Seznamy Ecomailu list_id Hodnoty se vybírají v multiselect poli v eWay-CRM
Kategorie Štítky Štítky se přenáší jako seznam textových hodnot
Uživatelská pole Vlastní pole Pole musí být v Ecomailu vytvořená předem

Vlastní pole

Pokud chcete synchronizovat další údaje z eWay-CRM, je potřeba je namapovat na vlastní pole v Ecomailu.

Vlastní pole musí být v Ecomailu vytvořená ručně před zahájením synchronizace. Konektor je neumí v Ecomailu automaticky zakládat.

Typ pole v eWay-CRM Typ pole v Ecomailu Poznámka
Text Text Standardní textová hodnota
Víceřádkový text Text  Bude upraveno na jednořádkový text
Číslo Celé číslo nebo Desetinné číslo Podporuje celá i desetinná čísla
Odkaz Text nebo URL Podle typu pole v Ecomailu
Datum Datum Hodnota se přenáší jako datum
Zaškrtávací pole Text Hodnota se vypíše jako ANO, nebo NE
Seznam Text
Zaškrtávací seznam Text
Relace Nepodporuje

Co připravit před spuštěním

Před prvním spuštěním doporučujeme zkontrolovat a připravit:

  • API klíč z Ecomailu.
  • Přístupové údaje k eWay-CRM, ideálně pro API uživatele.
  • Seznamy v Ecomailu, do kterých se mají kontakty synchronizovat.
  • Multiselect pole v eWay-CRM pro výběr seznamů.
  • Pole v eWay-CRM pro uložení Ecomail ID kontaktu.
  • Vlastní pole v Ecomailu, pokud chcete synchronizovat další údaje.
  • Mapování vlastních polí v konfiguračním souboru.
  • Triggery, které budou konektor spouštět.

Před prvním spuštěním integrace doporučujeme také provést export kontaktů z Ecomailu a uložit si zálohu.

API klíč

API klíč získáte přímo v administraci Ecomailu.

Postup:

  1. Přihlaste se do svého účtu v Ecomailu.
  2. Přejděte do části Správa účtu.
  3. Otevřete sekci Pro vývojáře.
  4. Zde najdete svůj API klíč, který musíte zkopírovat do konfiguračního souboru - viz dále.

API klíč má přístup k datům v účtu, proto s ním zacházejte stejně opatrně jako s heslem.

Seznamy v Ecomailu

Každý seznam v Ecomailu má vlastní list_id. Toto ID je potřeba uložit do eWay-CRM, aby konektor věděl, do kterého seznamu má kontakt synchronizovat.

V eWay-CRM je potřeba vytvořit v modulu Kontakty uživatelské pole typu Zaškrtávací seznam.

Do tohoto pole přidejte položky odpovídající seznamům v Ecomailu. U každé položky je třeba do technické hodnoty, tedy do pole FileAs, vložit příslušné list_id z Ecomailu.

list_id najdete v Ecomailu například v URL adrese prohlížeče po otevření konkrétního seznamu. URL seznamu může vypadat takto:

https://vyse_domena.ecomailapp.cz/contacts/1?status=active

V takovém pžípadě je tedy list_id rovno 1.

Díky multiselect poli může být jeden kontakt přiřazený do více seznamů současně.

Pole pro Ecomail ID

Konektor si k jednotlivým kontaktům ukládá číselné ID kontaktu z Ecomailu. Díky tomu může kontakty při dalších změnách správně párovat a aktualizovat.

V eWay-CRM je proto potřeba vytvořit v modulu Kontakty pole pro uložení Ecomail ID.

Toto pole musí splňovat následující:

  • je vytvořené v modulu Kontakty,
  • jeho typ je Odkaz,
  • název pole je volitelný,
  • databázový název pole se následně uvede v konfiguraci konektoru.

Synchronizace uživatelských polí

Pokud chcete synchronizovat další vlastní údaje, ujistěte se, že v Ecomailu existují odpovídající vlastní pole.

To znamená:

  • máte vytvořené pole v eWay-CRM,
  • máte vytvořené odpovídající pole v Ecomailu,
  • znáte databázový název pole v eWay-CRM - viz článek Jak zjistit databázové jméno výchozího nebo vlastního pole,
  • znáte klíč vlastního pole v Ecomailu (naleznete v Ecomailu v sekci Kontakty > Vlastní pole a ve sloupci Merge Tag - tedy v tomto případě například multi),
  • obě pole mají kompatibilní datový typ - viz tabulka výše.

Každé propojení vlastního pole je třeba nastavit v konfiguračním souboru.

Příklad mapování:

<customFields>
  <field customFieldName="af_82" emFieldKey="MY_FIELD" />
</customFields>

Kde:

  • customFieldName je databázový název pole v eWay-CRM,
  • emFieldKey je klíč vlastního pole v Ecomailu.

Konfigurační soubor

Aplikace Ecomail Connector obsahuje konfigurační soubor, ve kterém je potřeba nastavit připojení k eWay-CRM, připojení k Ecomailu a mapování polí.

Příklad konfigurace:

<ecomailConnector>
  <crmConnection
    url="https://ADRESA_VAŠÍ_EWAY_CRM"
    userName="UŽIVATELSKÉ_JMÉNO_API_UŽIVATELE"
    password="" />
  <ecomailConfig
    baseUrl="https://api2.ecomailapp.cz"
    apiKey="YOUR-API-KEY" />
  <fields>
    <contactModule
      ecomailContactIdField="af_81"
      ecomailGroupFieldName="af_80"
      birthdayFieldName="af_20">
      <customFields>
        <field customFieldName="af_82" emFieldKey="MY_FIELD" /> - těchto záznamů se vloží tolik, kolik 
      </customFields>
    </contactModule>
  </fields>

</ecomailConnector>

Význam jednotlivých hodnot:

Hodnota Popis
url Adresa webové služby eWay-CRM
userName Uživatelské jméno API uživatele
password Heslo API uživatele; zůstává prázdné
baseUrl URL adresa Ecomail API, standardně https://api2.ecomailapp.cz
apiKey API klíč z administrace Ecomailu
ecomailContactIdField Databázový název pole v eWay-CRM, kam se ukládá Ecomail ID kontaktu
ecomailGroupFieldName Databázový název multiselect pole v eWay-CRM, kde se vybírají seznamy Ecomailu
birthdayFieldName Volitelné pole s datem narození
<field customFieldName="af_82" emFieldKey="MY_FIELD" /> Záznamů se vkládá tolik, kolik vlastních polí synchronizujete
customFieldName Databázový název vlastního pole v eWay-CRM
emFieldKey Klíč vlastního pole v Ecomailu

Na základě této konfigurace je třeba upravit také triggery, které konektor spouštějí.

Triggery

Spouštění konektoru zajišťují eWay-CRM triggery definované v souboru:

EcomailTriggers.xml

Některé názvy polí je nutné v triggeru ručně upravit. Triggery totiž nemohou načítat hodnoty z konfiguračního souboru konektoru.

Místa, která je potřeba upravit, jsou v souboru EcomailTriggers.xml označena komentáři. Hodnoty v triggeru musí odpovídat databázovým názvům polí nastaveným v konfiguraci konektoru.

Typicky se jedná zejména o:

  • pole s přiřazenými seznamy Ecomailu,
  • pole s Ecomail ID kontaktu,
  • případná další uživatelská pole použitá v synchronizaci.

Instalace konektoru

Konektor je umístěný na webové službě eWay-CRM ve složce :

Apps\EcomailConnector

Při nasazení je potřeba:

  1. Nahrát celou složku EcomailConnector do adresáře Apps na FTP serveru.
  2. Zkontrolovat, že složka obsahuje EcomailConnector.exe, konfigurační soubor a všechny potřebné závislosti.
  3. Nahrát soubor EcomailTriggers.xml do adresáře s triggery.
  4. Upravit konfigurační soubor konektoru.
  5. Upravit názvy polí v souboru triggerů.
  6. Zkontrolovat logování konektoru.

Logy se ukládají do složky s logy na webové službě.

První spárování existujících kontaktů

Po prvotním nasazení konektoru je potřeba jednorázově spustit proces párování existujících kontaktů.

Tento krok zajistí, že kontakty, které už existují v Ecomailu i v eWay-CRM, budou správně propojené. Bez prvotního spárování by se tyto kontakty při dalších změnách nemusely synchronizovat a docházelo by k duplicitám.

Párování probíhá ve dvou fázích.

1. Párování kontaktů

Konektor načte členy ze všech seznamů v Ecomailu a porovná je s kontakty v eWay-CRM podle e-mailové adresy.

Pro každý spárovaný kontakt uloží do eWay-CRM potřebné identifikátory a informaci o přiřazených seznamech.

2. Aktualizace dat v Ecomailu

Po spárování konektor provede aktualizaci dat v Ecomailu, například jména, příjmení, data narození nebo vlastních polí.

Kontakty, které mají v eWay-CRM aktivní příznak Nezasílat newsletter, jsou v této fázi přeskočeny, protože se do Ecomailu nemají aktivně synchronizovat jako přihlášené kontakty.

Spuštění prvního párování

Před prvním spuštěním doporučujeme vyexportovat kontakty z Ecomailu a vytvořit si tak zálohu.

Pro první párování slouží samostatný trigger:

EcomailPairContactsTrigger.xml

Ve výchozím stavu je vypnutý:

Active="false"

Postup aktivace:

  1. Otevřete soubor EcomailPairContactsTrigger.xml.
  2. Nastavte čas triggeru na aktuální čas serveru + 2 minuty.
  3. Přesný čas serveru lze ověřit v logu.
  4. Nastavte trigger jako aktivní: Active="true"
  5. Uložte soubor.
  6. Počkejte na jednorázové spuštění triggeru.
  7. Po úspěšném proběhnutí párování můžete trigger opět deaktivovat úpravou na Active="false".

Trigger pro první párování se spouští pouze jednou.

Pozor: Hodnota Time musí být nastavena podle lokálního času serveru, ne podle lokálního času uživatele. Čas serveru je možné ověřit v časových značkách v logu.

Jak funguje synchronizace v provozu

Synchronizace se spouští zejména při těchto událostech:

  • vytvoření kontaktu,
  • úprava kontaktu,
  • změna přiřazení kontaktu k seznamu Ecomailu,
  • změna marketingového souhlasu,
  • odebrání kontaktu ze seznamu,
  • smazání kontaktu.

Při vytvoření nebo úpravě kontaktu používá konektor režim vytvoření nebo aktualizace. Pokud kontakt v daném seznamu ještě neexistuje, vytvoří se. Pokud už existuje, aktualizuje se.

Odhlášení, odebrání ze seznamu, mazání

U Ecomailu je důležité rozlišovat mezi odhlášením kontaktu a odebráním kontaktu z konkrétního seznamu:

Odebrání kontaktu z konkrétního seznamu

Pokud v eWay-CRM odeberete kontaktu hodnotu z pole se seznamy Ecomailu, kontakt zmizí z daného konkrétního seznamu.

Pokud je kontakt přiřazený i do jiných seznamů, z těchto seznamů nezmizí a zůstane v nich přihlášený.

Odhlášení kontaktu ze všech seznamů

Pokud v eWay-CRM nastavíte u kontaktu pole Nezasílat newsletter na ANO, kontakt se odhlásí ze všech přiřazených seznamů najednou. Kontakt zmizí ze všech konkrétních seznamů a v seznamu Všechny bude označený jako odhlášený.

Pokud v Ecomailu nastavíte kontakt jako odhlášený, tato změna se projeví i v eWay-CRM.

Opětovné přihlášení kontaktu

Pokud kontakt znovu přiřadíte do seznamu v eWay-CRM, konektor jej v Ecomailu znovu přihlásí do daného seznamu.

Pokud v eWay-CRM nastavíte u kontaktu pole Nezasílat newsletter na NE, kontakt se v Ecomailu znovu přihlásí do svých původních seznamů.

Smazání kontaktu

Ecomail kontakt fyzicky nesmaže pouze při jeho odebrání ze seznamu. V takovém případě zůstává kontakt zachovaný v seznamu Všechny jako odhlášený.

K úplnému a trvalému smazání kontaktu z Ecomailu dojde pouze při smazání kontaktu v eWay-CRM.

Omezení a doporučení

Před používáním integrace doporučujeme věnovat pozornost těmto omezením:

  1. Vlastní pole musí existovat předem
    Konektor neumí vytvářet vlastní pole v Ecomailu automaticky. Pokud pole v Ecomailu neexistuje, hodnota se nemusí uložit.
  2. Štítky se mohou v našeptávači objevit se zpožděním
    Přes API jsou funkční hned, ale jejich zobrazení v rozhraní Ecomailu může chvíli trvat.
  3. Smazání a odebrání ze seznamu nejsou totéž
    Odebrání ze seznamu kontakt v Ecomailu fyzicky nesmaže. Úplné smazání nastane pouze při smazání kontaktu v eWay-CRM.
  4. Jedna e-mailová adresa by měla odpovídat jednomu kontaktu
    Aby nedocházelo k nejasnostem při párování, doporučujeme nepoužívat více různých kontaktů se stejnou e-mailovou adresou.

Doporučený postup před spuštěním

Před ostrým spuštěním integrace doporučujeme:

  1. Zálohovat kontakty z Ecomailu.
  2. Zkontrolovat seznamy v Ecomailu.
  3. Připravit multiselect pole v eWay-CRM.
  4. Doplnit list_id do hodnot v poli FileAs.
  5. Připravit pole pro Ecomail ID kontaktu.
  6. Vytvořit vlastní pole v Ecomailu.
  7. Nastavit konfigurační soubor.
  8. Upravit EcomailTriggers.xml.
  9. Spustit první párování kontaktů.
  10. Ověřit synchronizaci na několika testovacích kontaktech.
  11. Teprve poté zapnout běžný provoz integrace.