Magento - Clang Extensie versie 1.1.0 Administrator Instructie
2
Inhoudsopgave 2.1 Voorbereidingen installatie van de Magento extensie...5 2.2 Extensie installeren...5 3.1 Configuratie systeeminstellingen in Magento...6 3.3 Magento Storeviews...10 3.4 Configuratie Clang-instellingen in Magento...10 3.4.1 Attribuutkopelingen...11 3.4.2 Campagnekoppelingen...12 3.4.3 Synchroniseren...14 3
1. Inleiding Deze handleiding betreft het gebruik van de extensie vanaf versie 1.1.0. Voor oudere versies van de extensie verwijzen wij graag naar de daarbij behorende handleiding. Met de Magento-Xtension van Clang wordt het mogelijk om uw webshop naadloos met Clang te integreren. Niet alleen nieuwe registraties en nieuwsbriefleden worden real-time gesynchroniseerd met Clang, ook informatie over bestellingen worden automatisch doorgestuurd naar de database van Clang. Bij de eerste keer synchroniseren wordt ook de bestelhistorie (van 3 maanden voorafgaand aan het moment van eerste synchronisatie) in Clang opgenomen. Daarnaast kan Clang alle e-mail vanuit de webshop voor zijn rekening nemen. Registratiebevestigingen, reminders, reviewmails, orderbevestigingen, wachtwoord vergeten, al deze e-mails kunnen worden opgemaakt in Clang, waarbij u gebruik kan maken van alle mogelijkheden die Clang al biedt op het gebied van dynamische content. Bovendien geniet u automatisch van de uitstekende deliverability en heldere rapportages van Clang. Gebruik productgegevens in de transactiemails, toon de beschikbare cross- en upsell-mogelijkheden en richt volledige customer lifecyclecampagnes in op basis van aankoopgedrag. Wilt u een reactivatiecampagne uitvoeren op klanten die al enige tijd niet meer in uw shop zijn geweest? Heeft u een fantastische aanbieding voor klanten die recent een product uit een bepaalde categorie hebben aangeschaft? Het wordt allemaal mogelijk met de uitgebreide segmentatiemogelijkheden de Magento-Xtension biedt. Naast alle informatie over uw klant en zijn gedrag in de e-mailing kan nu ook aankoopgedrag worden gebruikt voor nog betere segmentatie. Met behulp van de Magento-Xtension wordt het ook mogelijk om aanvullende campagnes in te richten die tot voor kort niet of moeilijk realiseerbaar waren met Magento. Denk hierbij aan een ReviewMail, waarbij de klant wordt verzocht om een review te plaatsen over een recent aangekocht product, of een Abandoned Cart-campagne, waarbij klanten die een product op het laatste moment toch niet hebben gekocht benaderd kunnen worden. De Magento-Xtension is beschikbaar voor zowel de Community (vanaf versie 1.6) als de Enterprise editie (vanaf versie 1.11) van Magento. Deze handleiding geeft u uitleg over hoe u de synchronisatie tussen uw Magentoen Clang-omgeving moet configureren. 4
2. Installatie Magento Clang extensie Om de integratie tussen Magento en Clang te realiseren, dient u in Magento een extensie te installeren die de koppeling activeert. Nadat u bij ons heeft aangegeven gebruik te willen maken van de integratie tussen Magento en Clang, zullen wij deze activeren en kunt u vanuit de brandmanager van Clang de laatste versie van de Magento extensie downloaden. Onderstaand leest u wat u moet doen om de extensie te installeren en te configureren. Alle wijzigingen in Magento worden direct in Clang verwerkt (SOAP). Vanuit Clang worden alleen de uitschrijvingen van nieuwsbrieven naar Magento doorgegeven. 2.1 Voorbereidingen installatie van de Magento extensie Voor de installatie is het volgende nodig: 1. Een werkende Magento-installatie met: Het Magento cron script dat periodiek draait. Raadpleeg, indien nodig, hiervoor de Magento-documentatie. Eventuele extra vertalingen als Magento moet gaan werken met andere talen en landinstellingen (anders dan VS, Engels). Als het een testomgeving betreft, dan moet deze benaderbaar zijn vanaf iedere locatie. 2. De Clang-extensie: Nadat de Magento extensie is geactiveerd in Clang, kunt u vanuit de brandmanager van Clang de laatste versie van de extensie downloaden. Voor het koppelen van de Magento aan de Clang omgeving ontvangt u van ons een API-sleutel / -token. Voor het invoeren van het Clang token verwijzen wij u naar hoofdstuk 3 van dit document. 3. Voor de instellingen in Clang dient u te beschikken over: Zie voor verdere uitleg hoofdstuk 3 van dit document. Een Magento SOAP/XML-RPC-gebruiker met bijbehorende API-sleutel. Deze gebruiker moet voldoende rechten hebben om product- en ordergerelateerde informatie op te halen. De WSDL van de Magento-API (waarschijnlijk http://domain.tld/index.php/api/soap/?wsdl) De URL van de Magento-webshop 2.2 Extensie installeren De extensie is onder andere verkrijgbaar: in de brand manager bij elke brand waarvoor de Magento koppeling is aangezet via http://download.myclang.com/magento/latest 5
Installatie en update De extensie wordt geleverd in de vorm van een zip bestand. Als dit wordt uitgepakt levert dat onder andere een directory app/ op. De Magento installatie bevat eveneens een directory app/. De inhoud van de directory met de extensie moet inclusief alle subdirectorypen naar de app/ directory van Magento worden gekopieerd. Dit overschrijft geen bestanden in Magento zelf. Hooguit wordt een reeds geïnstalleerde extensie bijgewerkt. Als de extensie wordt geïnstalleerd of vernieuwd worden alle relevante SQL build scripts in de extensie uitgevoerd. Log in in het Magento Admin Panel en ga naar het onderdeel Cache-beheer in uw Systeem tab. Klik rechtsboven op Flush Magento Cache. Ga dan naar onderdeel Configuratie in uw Systeem tab en kies Geavanceerd > Ontwikkelaar in het linkermenu. Zet onder het kopje Loginstellingen de logging aan. Deze logging zorgt ervoor dat de SOAP-requests (en andere informatie) wordt opgeslagen in /magento-install-dir/var/log. NB: de logbestanden kunnen na enige tijd omvangrijk worden. Voor productiesystemen wordt dan ook aangeraden om de logging uit te zetten of de logbestanden periodiek te roteren. 3. Magento en Clang configuratie Als u de extensie succesvol heeft geïnstalleerd zult u bij het inloggen in Magento de volgende melding zien (afb. 1) afb. 1 Ook in uw Systeem-mededelingen (zie voor verdere uitleg hoofdstuk 5) wordt de succesvolle installatie gemeld. (afb. 2) 3.1 Configuratie systeeminstellingen in Magento afb. 2 Om de synchronisatie tussen Magento en Clang te configureren gaat u naar de optie Configuratie onder de menutab Systeem (afb. 3). Hier kunt u onder andere het API-sleutel/token invoeren om de koppeling actief te maken. 6
afb. 3 Vervolgens klikt u in de linker menubalk, op de link Algemene instellingen van Clang om de specifieke Clang-gegevens te kunnen invullen. (afb. 4) afb. 4 Nadat u het menu Algemene instellingen opent, krijgt u de volgende mogelijkheden (afb. 5): afb. 5 Versie: Algemene informatie over de extensie. Wij verzoeken u deze gegevens bij de hand te houden indien u contact opneemt met onze supportafdeling. Token: Hier moet het token worden ingevuld dat door E-Village is aangeleverd. Een token / API-key is de unieke code waarmee twee of meerdere datasystemen aan elkaar gekoppeld kunnen worden. Heeft u nog geen token ontvangen, vraag deze dan op bij support@myclang.com. 7
3.2 Instellingen in Clang Zodra u bij ons heeft aangegeven de Magento - Clang koppeling te willen gaan gebruiken, zullen wij, in de Brandmanager van Clang, u de mogelijkheid geven de synchronisatie tussen Magento en Clang te activeren. U ziet dan in uw Brandmanager de checkbox Activeer Magento verschijnen. Voor het activeren van de Magento-synchronisatie dient u, in de Brandmanager van Clang, op het tabblad voorkeuren de Activeer Magento checkbox aan te vinken. (afb. 6) afb. 6 Vervolgens verschijnt het tabblad Magento instellingen in uw Brandmanager, waar u de volgende gegevens dient in te vullen (afb. 7). Gebruikersnaam van Magento (SOAP/XML-RPC gebruiker) De bijbehorende API-sleutel uit Magento De WSDL van de Magento API (waarschijnlijk http://domain/index.php/api/soap/?wsdl, waarbij 'domein' uiteraard moet worden vervangen) De URL van de webshop 8
afb. 7 Met behulp van de button Connectie testen is het mogelijk om te controleren of de instellingen voor de synchronisatie tussen Clang en Magento goed zijn geconfigureerd. 9
3.3 Magento Storeviews Binnen uw Magento-omgeving heeft u de mogelijkheid om gebruik te maken van meerdere websites, stores en storeviews. Per storeview heeft u bijvoorbeeld een andere online winkel, landinstelling (Valuta, Btw tarieven, verzendkosten etc.) of taalkeuze. Indien u uw Scope huidige configuratie (afb. 8) op Standaard configuratie heeft ingesteld, zorgt dit ervoor dat de instellingen van de Magento extensie voor alle websites stores en storeviews in uw Magento omgeving wordt gebruikt, ongeacht de talen en landinstellingen. afb. 8 Als uw Magento configuratie meerdere websites bevat is het mogelijk om per website een ander token in te stellen. Hiermee is het mogelijk om verschillende websites binnen Magento aan verschillende brands in Clang te koppelen. Let op: Al uw storeviews binnen websites in Magento die hetzelfde token gebruiken worden altijd als één brand in Clang opgeslagen. 3.4 Configuratie Clang-instellingen in Magento In uw Magento-omgeving, onder het tabblad Clang, krijgt u de drie volgende mogelijkheden (afb. 9): Attribuutkoppelingen Hier kunt u aangeven welk Magento-attribuutveld aan welk Clang klant- of klantoptieveld gekoppeld moet worden. (N.B.: in Magento worden de door de organisatie zelf aangemaakte klantvelden attribuutvelden genoemd. In Clang heten deze klantoptievelden) Zie hoofdstuk 3.4.1 voor verdere uitleg over de attribuutkoppelingen. Campagnekoppelingen Hier ziet een overzicht van de transactionele e-mails die vanuit Magento worden verzonden middels een gekoppelde campagne in Clang. Zie hoofdstuk 3.4.2 voor verdere uitleg over het koppelen van Clang campagnes. Synchroniseren Hier ziet u een overzicht van alle (handmatige en automatische) gegevens uitwisselingen tussen Magento en Clang. Daarnaast kunt u hier ook de synchronisatie handmatig starten. Zie hoofdstuk 3.4.3 voor verdere uitleg over het synchroniseren van de instellingen. 10
afb. 9 3.4.1 Attribuutkopelingen Standaard worden de basisvelden voor de synchronisatie tussen Magento en Clang door extensie gekoppeld. Zie het onderstaand overzicht van deze standaard velden: Clang veldnaam firstname lastname emailaddress externalid prefix title companyname optin Magento veldnaam firstname lastname email entity_id middlename prefix Company is_subscribed Onder de optie Attribuutkoppelingen kunt u aangeven, welk Magentoattribuutveld aan welk Clang klantoptieveld gekoppeld moet worden. Deze instellingen moeten per website worden gedaan. Het is dus ook mogelijk om de attributen verschillend te koppelen. In het overzicht (afb. 10) ziet u de reeds gekoppelde velden, standaard is dit overzicht leeg. Indien een bestaande attribuut koppeling wenst aan te passen of te verwijderen klikt u op de regel en krijgt u de mogelijkheid deze aan te passen of te verwijderen. afb. 10 11
Met de button Nieuwe attribuutrelatie (afb. 11) kunt een nieuwe koppeling tussen de twee velden aanmaken. afb. 11 Vervolgens selecteert u onder het dropdown menu Magento Attribuut Code het gewenste Magentoveld en onder Clang Code, het reeds in Clang aangemaakte, klant- of klantoptieveld. (afb. 12). De mogelijk koppelbare Clang velden worden gefilterd op basis van het geselecteerde attribuut veld. ( Een attribuutveld van het type Boolean of INT, dan worden alleen Clang klant- of klantoptieveld van hetzelfde type getoond. afb. 12 Nadat u de twee gewenste velden geselecteerd heeft, klikt u op de button Attribuutrelatie opslaan. Als de keuzelijst Clang code niet de gewenste opties aanbiedt, dan zijn de klantoptievelden binnen Clang nog niet aangemaakt of het Clang token is nog niet (correct) ingevoerd. 3.4.2 Campagnekoppelingen Onder de optie Campagnekoppelingen kunt u aangeven welke transactionele e- mails uit Magento via Clang moeten worden verzonden. Dit gebeurt door de e- mail aan een Clang campagne te koppelen. Elke keer dat Magento een transactionele e-mail gaat versturen wordt eerst gecontroleerd of er een gekoppelde Clang campagne bestaat. Is dit het geval, dan wordt deze campagne met de juiste data aangeroepen, en deze draagt dan zorg voor het versturen van de e-mail. Als er geen gekoppelde campagne wordt gevonden zal Magento de e- mail op de reguliere manier verzenden. De bestaande koppelingen in een website worden in een overzicht getoond, zie afb. 13. 12
Afb. 13 Het koppelen van Clang campagnes gebeurt in enkele stappen. 1. Voordat een campagne kan worden gekoppeld moet deze in Clang op de juiste manier worden opgebouwd. Dit is vanuit Magento te bereiken door de knop Nieuwe Campagne Maken (afb. 14) te gebruiken. afb. 14 Er kan dan een Magento transactionele e-mail worden gekozen en een naam voor de bijbehorende Clang campagne worden ingevoerd, zie afb. 15. afb. 15 De campagne die in Clang wordt gemaakt is eenvoudig, maar voldoende om de e-mail te kunnen versturen. Er wordt ook een e-mail content in Clang opgebouwd die vergelijkbaar is met de template die in Magento wordt gebruikt, maar waarin de variabelen zijn vervangen. 2. Via de knop Nieuwe Campagne Koppeling (afb. 16) worden de koppelingen gelegd. Hierbij is het mogelijk om meerdere e-mails aan dezelfde campagne te koppelen. Uiteraard moet de campagne geschikt worden gemaakt voor alle te versturen e-mails. afb. 16 Bij het koppelen is het mogelijk om een campagne aan een e-mail te koppelen voor een enkele storeview, of voor alle storeviews in een website, zie afb. 17. Bij het verzenden van e-mail zal de extensie eerst zoeken naar een koppeling voor de storeview van waaruit de mail wordt verstuurd, en pas dan naar een koppeling voor de gehele website. 13
afb. 17 Een speciale koppeling is te leggen voor onvoltooide bestellingen, zogenaamde 'abandoned carts'. Hiervoor is een campagne te koppelen die wordt aangeroepen als de extensie heeft vastgesteld dat een onvoltooide bestelling langer dan een uur geen activiteit heeft vertoond. In dit geval wordt de gekoppelde campagne eenmalig voor de bestelling aangeroepen. 3.4.3 Synchroniseren Onder de tab Synchroniseren staat per website de wachtrij met Magentoinformatie die met Clang uitgewisseld moet worden of reeds uitgewisseld is. (afb. 18) De meeste gegevens en acties worden real-time vanuit Magento naar Clang gecommuniceerd, zodat het versturen van transactionele mails vlot verloopt. Deze wachtrij wordt ingezet in de volgende gevallen: Tijdens de initiële synchronisatie van klant- en ordergegevens; Wanneer er geen real-time communicatie mogelijk is met Clang, bijvoorbeeld tijdens een tijdelijke netwerkstoring. In dat geval wordt de wachtrij gebruikt om de actie op een later moment nogmaals te proberen. afb. 18 Alle berichten met de status 'pending' moeten nog verzonden worden. Indien er berichten voor langere tijd met status pending in de wachtrij blijven staan, kan het zijn dat de Magento cron niet geactiveerd is. Raadpleeg de Magento handleiding voor meer informatie over de cron. 14
In deze omgeving is het ook mogelijk om een mislukte bericht opnieuw te starten, een bericht te verwijderen of te filteren en zoeken op bepaalde activiteiten. Afb. 19 Indien u voor de eerste keer de Clang synchronisatie (afb. 19) gebruikt, zullen de onderstaande gegevens standaard worden gesynchroniseerd. 1. Alle klanten uit Magento 2. De Magento-nieuwsbriefabonnees worden in Clang aan de groep Magento toegevoegd, en aan een subgroep van de 'Magento' groep met de naam van de website. Deze groepen worden automatisch gemaakt. 3. De data van alle bestellingen van de drie maanden voorafgaand aan het moment van synchroniseren. Deze gegevens worden in Clang opgeslagen, maar er wordt geen mail verstuurd. 15
4. Magento-relaties vs. Clang-relaties In de praktijk kan het voorkomen dat de gegevens in uw database van Magento niet gelijk zijn aan die van Clang. In Magento kunnen klanten staan die (nog) niet in Clang staan. Ook kan het zo zijn dat er klanten al wel in beide databases voorkomen, maar waarbij de afgegeven inschrijving voor uw nieuwsbrief niet overeenkomt. De ontdubbeling vindt plaats op basis van het e-mailadres. Volgens het onderstaande schema worden de gegevens uit Magento in Clang verwerkt. Situati e Relatie in Clang Opt-in in Clang Opt-in in Magento Opt-in in Clang na synchronisatie 1 Ja Ja Nee Ja Nee 2 Ja Nee Nee Nee Nee 3 Ja Ja Ja Ja Ja 4 Ja Nee Ja Ja Ja 5 Nee - Nee Nee Nee 6 Nee - Ja Ja Ja Toevoegen aan groep Magento in Clang Uitleg situatie 1: Kolom 1 Relatie in Clang : De klant staat al in de Clang database (kolom 1=Ja) Kolom 2 Opt-in in Clang : De Opt-in in Clang staat op Ja (kolom 2 = Ja) Kolom 3 Opt-in in Magento : De Opt-in in Magento staat op Nee (kolom 3 = Nee) Kolom 4 Opt-in in Clang na synchronisatie : Na de synchronisatie van de data gegevens staat de opt-in in Clang op Ja (kolom 4 = Ja) Kolom 5 Toevoegen aan de groep Magento in Clang : De klant wordt niet toegevoegd aan de groep Magento in Clang (klom 5 = Nee) Elke relatie die in Magento ingeschreven staat voor de nieuwsbrief wordt in Clang automatisch opgenomen in de groep Magento. (afb. 20) 16
afb. 20 Zodra u iemand uit de groep Magento of de subgroep van de website haalt, wordt ook in Magento de inschrijving voor de nieuwsbrief ingetrokken. Let op: Bij het opmaken van uw afmeldcampagne in Clang, raden wij u aan het campagneobject Verwijder uit groep (afb. 21) op te nemen in uw campagne. afb. 21 Aan orderdata word de onderstaande data gesynchroniseerd, welke vervolgens gebruikt kan worden in het maken van profielen of als variabelen in de e-mail content. Aantal bestellingen Beloningspunten Bestelling ID Betaalmethode BTW-bedrag Kortingsbedrag Product ID Product SKU Productnaam Som beloningspunten Subtotaal Totaal Totaal besteld bedrag per klant Verzendkosten Verzendwijze In het geval van 'abandoned cart' campagnes zijn enkele van deze velden niet relevant, en is er geen bestelling id, maar een id van de niet afgemaakte bestelling. 17
5. Magento Systeemmeldingen Als de status van de extensie verandert, bijvoorbeeld de SOAP-koppeling tussen Magento en Clang werkt niet meer, krijgt u hierover bericht op het moment dat u inlogt in Magento. (afb. 22) afb. 22 Ook boven in uw interface krijgt u een statusmelding te zien. (afb. 23) afb. 23 Onder de tab Systeem > Meldingen kunt u de status van de extensie terugvinden. Hier wordt dan ook aangegeven dat de SOAP-verbinding weer is hersteld. (afb. 24) afb. 24 NB: voor Magento Enterprise Edition ouder dan versie 1.11 en Magento Community Edition ouder dan versie 1.6 schrijft de extensie statusveranderingen niet als notificaties, maar naar de Magento-systeemlog. 18
6. Troubleshooting Als de synchronisatie voor langere tijd niet wordt afgerond, controleer dan of: Controleer of de extensie geactiveerd is onder System / Configuration/ Advanced. de API-sleutel / token goed is ingesteld (test de connectie in de Brandmanager in Clang) Of er geen foutmeldingen staan bij de Magento Systeemmeldingen het Magento cron script draait. er foutmeldingen staan in '/magento-install-dir/var/log'. Indien de SOAP calls mislukken met een foutcode 202, foutstring Session expired verzoeken wij u contact op te nemen met Clang support (support@evillage.nl). Logging Als er problemen zijn opgetreden zullen de logs die Magento beheert nuttige informatie bevatten. Deze zijn te vinden in var/log binnen de installatie directory van Magento. De volgende logs zijn hier beschikbaar, deels afhankelijk van de problemen die zijn opgetreden: exception.log: algemene Magento exceptie log system.log: algemene Magento systeemlog clang_queue_errors.log: fouten die in de verwerking van de synchronisatie queue zijn opgetreden clang_soap_client.log: alle requests en responses die door de extensie via SOAP naar Clang zijn gestuurd clang_soap_client_errors.log: fouten die zijn opgetreden in de SOAP uitwisseling met Clang. Deze bestanden zijn niet inzichtelijk vanuit de beheersinterface. NB: deze bestanden worden alleen geschreven als in Magento de instelling 'Ingeschakeld' onder Systeem > Configuratie > Geavanceerd > Ontwikkelaar > Log-instellingen op 'Ja' staan. Database tabellen De extensie heeft enkele eigen tabellen in de database van een Magento installatie: clang_attributes_assignment: koppeling van Magento velden aan Clang klantvelden en klantoptievelden. o Sleutelvelden: magento_attribute_code (dob, gender,...) clang_attribute_code (customer.birthday, customer_option.e12,...) website_id (integer) clang_campaign_template_relation: de koppeling tussen Magento templates van transactionele emails en Clang campagnes o Sleutelvelden: 19
template_id (sales_email_order_template, 1) store_id (integer) website_id (integer) campaign_id (integer) clang_customer_newsletters: de koppeling tussen Magento gebruikers en Clang groepen (niet in gebruik). clang_newsletters: de Clang groepen corresponderend met nieuwsbrieven (niet in gebruik). clang_customers: de koppeling tussen Magento gebruikers en Clang customers. o Sleutelvelden: clang_customer_id (integer) magento_customer_id (integer, leeg voor Clang customers die via guest checkout zijn binnengekomen) website_id (integer) email (e-mail adres) clang_queue: de synchronisatie queue. Deze gegevens in deze tabel zijn inzichtelijk in de administratieve interface. 20
7. Extensie (tijdelijk) uitschakelen Het is mogelijk om de Magento - Clang extensie tijdelijk uit te schakelen voor bijvoorbeeld systeemonderhoud of omdat u tijdelijk de mail toch via de Magento systeemmail wilt versturen, etc. De extensie kan uitgeschakeld worden door: In de map /magento-installdir/app/etc/modules het bestand 'EVillage_Clang.xml' te hernoemen naar 'EVillage_Clang.bak' Daarna In Magento onder het tabmenu Systeem > Cache-beheer de knop Flush Magento cache te klikken. Om de extensie vervolgens weer in te schakelen kunnen dezelfde acties uitgevoerd worden, waarbij de bestandsnaam weer naar 'EVillage_Clang.xml' wordt teruggezet. 21