Integrace Emailkampane.cz s eWay-CRM

Integrace Emailkampane.cz s eWay-CRM slouží k automatické synchronizaci kontaktů mezi eWay-CRM a systémem Emailkampane.cz.

Obsah

K čemu integrace slouží

Integrace je navržená tak, aby se kontakty z eWay-CRM automaticky přenášely do systému Emailkampane.cz.

Synchronizace podporuje vytvoření a aktualizaci kontaktu, přiřazení kontaktu do jedné nebo více skupin, odebrání kontaktu ze skupiny, smazání kontaktu a práci se stavem odběru newsletteru.

Běžná synchronizace kontaktů probíhá primárně směrem z eWay-CRM do Emailkampane.cz. Výjimkou je synchronizace marketingových souhlasů, při které se stav aktivních a neaktivních kontaktů pravidelně přenáší z Emailkampane.cz zpět do eWay-CRM.

Kontakt se do Emailkampane.cz synchronizuje pouze tehdy, pokud má v eWay-CRM vyplněnou e-mailovou adresu a je přiřazený alespoň do jedné Emailkampane.cz skupiny.

Jaká data se synchronizují

Do Emailkampane.cz 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ň jedna cílová skupina.

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

Pole v eWay-CRM Pole v Emailkampane.cz Poznámka
E-mail E-mail Povinné pole a hlavní identifikátor kontaktu
Jméno Jméno
Příjmení Příjmení
Nezasílat newsletter Stav odběru (Aktivní / Neaktivní) Řídí odhlášení nebo opětovné přihlášení kontaktu
Skupiny Emailkampane.cz List / skupina Hodnoty se vybírají v multiselect poli v eWay-CRM
Emailkampane.cz Contact GUID Ukládá se po vytvoření nebo spárování kontaktu
Emailkampane.cz Contact ID Ukládá se po vytvoření nebo spárování kontaktu
Uživatelská pole Atributy kontaktu v Emailkampane.cz Pole musí být namapovaná v konfiguraci

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 Emailkampane.cz.
  • Uživatelské jméno k Emailkampane.cz účtu.
  • Přístupové údaje k eWay-CRM, ideálně pro API uživatele.
  • Skupiny v Emailkampane.cz, do kterých se mají kontakty synchronizovat.
  • Multiselect pole v eWay-CRM pro výběr Emailkampane.cz skupin.
  • Pole v eWay-CRM pro uložení Emailkampane.cz Contact GUID.
  • Pole v eWay-CRM pro uložení Emailkampane.cz Contact ID.
  • Vlastní pole v Emailkampane.cz, 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 Emailkampane.cz a uložit si zálohu.

API klíč

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

Postup:

  1. Přihlaste se do svého účtu v Emailkampane.cz.
  2. V pravém horním rohu klikněte na ikonu účtu a vyberte možnost Spravovat účet.
  3. V levém menu otevřete sekci Vývojář a přejděte do části API.
  4. Vygenerujte a zkopírujte API klíč.
  5. API klíč vložte do konfiguračního souboru konektoru.

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

Skupiny kontaktů v Emailkampane.cz

Pro správnou synchronizaci skupin je potřeba v eWay-CRM vytvořit multiselect uživatelské pole v modulu Kontakty. Toto pole reprezentuje přiřazení kontaktu do skupin v Emailkampane.cz.

Postup:

  1. V eWay-CRM vytvořte v modulu Kontakty uživatelské pole typu zaškrtávací seznam.
  2. Do tohoto pole založte jednotlivé položky odpovídající skupinám v Emailkampane.cz. Jako hodnoty pole tedy zadáváte přesné jméno skupiny tak, jak ho vidíte v sezamu v sekci Kontakty ve vašem účtu Emailkampane.cz (příklad: podle obrázku tedy jako hodnoty polí zadáte VIP a Klienti).
  3. Ke každé položce doplňte do pole FileAs skutečné jméno dané skupiny z Emailkampane.cz.
  4. Databázový název tohoto pole následně uveďte v konfiguraci souboru.

Pokud FileAs neobsahuje správně jméno skupiny, přiřazování kontaktů do Emailkampane.cz nebude fungovat.

Pole pro Emailkampane.cz ID

Konektor si k jednotlivým kontaktům ukládá identifikátory vrácené systémem Emailkampane.cz. 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 dvě pole:

  • pole pro Emailkampane.cz Contact GUID,
  • pole pro Emailkampane.cz Contact ID.

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

  • jsou vytvořená v modulu Kontakty,
  • jejich typ je Odkaz,
  • databázové názvy polí se uvedou v konfiguraci konektoru,
  • doporučuje se, aby byla pro běžné uživatele skrytá nebo pouze pro čtení.

Synchronizace uživatelských polí

Emailkampane.cz vlastní pole označuje jako atributy a nerozlišuje typ polí, všechny hodnoty se ukládají jako textové.

Pokud chcete synchronizovat další údaje z eWay-CRM, je potřeba je namapovat na atributy kontaktu v Emailkampane.cz.

To znamená:

  • máte vytvořené pole v eWay-CRM,
  • máte vytvořený odpovídající atribut kontaktu v Emailkampane.cz,
  • znáte databázový název pole v eWay-CRM,
  • znáte ID atributu v Emailkampane.cz,
  • obě hodnoty jsou uvedené v konfiguračním souboru.

Konfigurační soubor

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

Příklad konfigurace:

<emailkampaneConnector>

  <crmConnection
    url="https://ADRESA_VAŠÍ_EWAY_CRM"
    userName="UŽIVATELSKÉ_JMÉNO_API_UŽIVATELE"
    password="" />

  <emailkampaneConfig
    baseUrl="https://api.emailkampane.cz/"
    username="VÁŠ_EMAILKAMPANE_LOGIN"
    apiKey="YOUR-API-KEY" />

  <fields>
    <contactModule
      emailkampaneContactGuidField="af_77"
      emailkampaneContactIdField="af_78"
      emailkampaneGroupFieldName="_af_76">

      <customFields>
        <field customFieldName="af_53" ekAttributeId="12345" />
      </customFields>

      <multiSelectCustomFields>
        <field customFieldName="_af_84" ekAttributeId="12345" />
      </multiSelectCustomFields>

    </contactModule>
  </fields>

</emailkampaneConnector>

Význam jednotlivých hodnot:

Hodnota Popis
url Adresa webové služby eWay-CRM
userName Uživatelské jméno API uživatele eWay-CRM
password Heslo API uživatele; zůstává prázdné
baseUrl URL adresa Emailkampane.cz API, obvykle https://api.emailkampane.cz/
username Přihlašovací e-mail do Emailkampane.cz
apiKey API klíč vygenerovaný v administraci Emailkampane.cz
emailkampaneContactGuidField Databázový název pole v eWay-CRM, kam se ukládá Emailkampane.cz Contact GUID
emailkampaneContactIdField Databázový název pole v eWay-CRM, kam se ukládá Emailkampane.cz Contact ID
emailkampaneGroupFieldName Databázový název multiselect pole v eWay-CRM, kde se vybírají Emailkampane.cz skupiny
<field customFieldName="af_53" ekAttributeId="12345" /> Záznamů se vkládá tolik, kolik vlastních polí synchronizujete
customFieldName Databázový název vlastního pole v eWay-CRM
ekAttributeId Číselné ID atributu kontaktu v Emailkampane.cz
<multiSelectCustomFields> Pokud synchronizujete pole typu zaškrtávací seznam, je třeba je nastavit v této sekci.

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

Podrobný popis konfiguračních sekcí je uveden také v souboru README.md, který je součástí složky konektoru.

Triggery

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

EmailkampaneTriggers.xml

Triggery reagují zejména na tyto události:

  • změnu přiřazení kontaktu ke skupině,
  • změnu údajů kontaktu,
  • smazání kontaktu,
  • změnu marketingového souhlasu.

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 EmailkampaneTriggers.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 skupinami Emailkampane.cz,
  • pole s Emailkampane.cz Contact GUID,
  • pole s Emailkampane.cz Contact ID,
  • další uživatelská pole použitá v synchronizaci,
  • multiselect pole doplněná do sekce multiSelectCustomFields.

Při přidání nového multiselect pole do konfigurace je nutné doplnit odpovídající ActionCriteria do triggerů 7 a 8 v souboru EmailkampaneTriggers.xml.

Instalace konektoru

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

Apps\EmailkampaneConnector

Při nasazení je potřeba:

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

Logy jsou generovány do adresáře s logy.

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 Emailkampane.cz 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 správně.

Pokud kontakt existuje pouze v Emailkampane.cz a v eWay-CRM vůbec není, je potřeba jej nejdříve ručně importovat do eWay-CRM. Teprve poté ho párovací proces propojí s odpovídajícím kontaktem v Emailkampane.cz.

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

1. Párování kontaktů

Konektor načte všechny členy ze všech Emailkampane.cz skupin a porovná je s kontakty v eWay-CRM podle e-mailové adresy.

Pro každý spárovaný kontakt uloží do eWay-CRM:

  • Emailkampane.cz Contact GUID,
  • Emailkampane.cz Contact ID,
  • informaci o přiřazených skupinách.

Kontakty, které už byly spárované dříve, se přeskočí.

2. Aktualizace dat v Emailkampane.cz

Po spárování konektor provede aktualizaci dat v Emailkampane.cz, například jména, příjmení nebo dalších namapovaných vlastních polí.

Kontakty, které jsou v eWay-CRM odhlášeny od odběru newsletteru, jsou v této fázi přeskočeny, protože se do Emailkampane.cz 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 Emailkampane.cz a vytvořit si tak zálohu.

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

EmailkampanePairContactsTrigger.xml

Ve výchozím stavu je vypnutý:

Active="false"

Postup aktivace:

  1. Nahrajte soubor EmailkampanePairContactsTrigger.xml do adresáře s triggery na FTP serveru.
  2. Otevřete soubor EmailkampanePairContactsTrigger.xml.
  3. Nastavte čas triggeru na aktuální čas serveru + 2 minuty.
  4. Přesný čas serveru ověřte podle časových údajů v logu.
  5. Nastavte trigger jako aktivní: Active="true".
  6. Uložte soubor.
  7. Počkejte na jednorázové spuštění triggeru.
  8. Sledujte log a ověřte, že párování úspěšně doběhlo.
  9. Po úspěšném proběhnutí párování nastavte trigger zpět 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 ke skupině Emailkampane.cz,
  • odebrání kontaktu ze skupiny Emailkampane.cz,
  • změna marketingového souhlasu,
  • smazání kontaktu.

Kontakt se do Emailkampane.cz synchronizuje pouze tehdy, pokud:

  • má vyplněnou e-mailovou adresu,
  • je přiřazený alespoň do jedné Emailkampane.cz skupiny,
  • nemá nastaveno DoNotSendNewsletter = true.

Při změně údajů kontaktu v eWay-CRM se kontakt aktualizuje v Emailkampane.cz. Při přidání hodnoty do skupinového pole se kontakt přidá do odpovídající skupiny. Při odebrání hodnoty ze skupinového pole se kontakt z dané skupiny odebere.

Pokud Emailkampane.cz API odmítne e-mailovou adresu jako neplatnou nebo falešnou, konektor kontakt přeskočí, zaloguje varování a synchronizace ostatních kontaktů pokračuje bez přerušení.

Odhlášení, opětovné přihlášení, odebrání ze skupiny a mazání

U Emailkampane.cz je důležité rozlišovat mezi odhlášením kontaktu, odebráním ze skupiny a smazáním kontaktu:

  • Pokud v eWay-CRM odeberete kontaktu hodnotu z pole se skupinami Emailkampane.cz, kontakt se odebere z dané skupiny v Emailkampane.cz. Kontakt ale není nutně smazán jako celý kontakt. Pouze se odstraní jeho přiřazení ke konkrétní skupině.
  • Pokud v eWay-CRM nastavíte u kontaktu odhlášení z odběru, kontakt se v Emailkampane.cz odhlásí z odběru (nastaví se jako Neaktivní). Takový kontakt se do Emailkampane.cz nesynchronizuje.
  • Pokud v eWay-CRM nastavíte kontakt znovu přihlásíte, kontakt se v Emailkampane.cz znovu přihlásí k odběru (nastaví se jako Aktivní).
  • Pokud v Emailkampane.cz odhlásíte kontakt z odběru (nastavíte ho jako Neaktivní), odhlásí se také v eWay-CRM. Tato změna se neprovede hned, ale pravidelně podle nastavení v triggeru.
  • Při smazání kontaktu v eWay-CRM konektor odstraní kontakt také z Emailkampane.cz.

Omezení a doporučení

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

  • Kontakt se do Emailkampane.cz odešle pouze tehdy, pokud má v eWay-CRM e-mailovou adresu a je přiřazený alespoň do jedné Emailkampane.cz skupiny.
  • Při nesouladu databázových názvů polí mezi konfiguračním souborem a trigger XML nebude synchronizace fungovat správně.
  • Pokud chcete synchronizovat změny dalších polí, je nutné je ručně doplnit do trigger criteria, například pomocí IsChanged. Jinak se změna pole nemusí do Emailkampane.cz propsat.
  • Pokud do sekce multiSelectCustomFields v konfiguraci přidáte nové multiselect pole, je nutné přidat také odpovídající ActionCriteria do triggerů 7 a 8 v souboru EmailkampaneTriggers.xml.
  • 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 Emailkampane.cz.
  2. Zkontrolovat skupiny v Emailkampane.cz.
  3. Připravit multiselect pole v eWay-CRM.
  4. Doplnit ID skupin do hodnot v poli FileAs.
  5. Připravit pole pro Emailkampane.cz Contact GUID.
  6. Připravit pole pro Emailkampane.cz Contact ID.
  7. Připravit vlastní pole a atributy, které se mají synchronizovat.
  8. Nastavit konfigurační soubor.
  9. Upravit EmailkampaneTriggers.xml.
  10. Pokud používáte multiselect vlastní pole, doplnit odpovídající ActionCriteria do triggerů 7 a 8.
  11. Nahrát složku EmailkampaneConnector do adresáře Apps.
  12. Nahrát trigger soubory do adresáře s triggery.
  13. Spustit první párování kontaktů pomocí EmailkampanePairContactsTrigger.xml.
  14. Ověřit výsledek v logu.
  15. Otestovat synchronizaci na několika testovacích kontaktech.
  16. Teprve poté zapnout běžný provoz integrace.