07/25/2016 Magentoplugin2.0manual1

07/25/2016 Magentoplugin2.0manual2

1 Contents 1 Contents 2

2 Introduction 3

3 ConnecttheplugintoaTripolisDialogueclient 43.1 Pluginsettings 43.2 ConnectionwithTripolisDialogue 4

4 Databasesmappingsandcontactsynchronization 54.1 ContactSynchronization 54.1.1 Enabling/disablingofcontactsynchronizing 54.1.2 Statuspage 5

4.2 Mapping 54.2.1 Databasemapping 54.2.2 Contactgroupmapping 64.2.3 Contactfieldmapping 6

4.3 InitialSynchronization 74.3.1 Subscribingandunsubscribingofcontacts 7

5 Transactionalemails 85.1 Transactionalfieldmapping 85.2 EmailMapping 9

6 Useproductfeedsinemails 116.1 Security 116.1.1 IPrestrictionoffeeds 116.1.2 Feeduserrestriction 11

6.2 URLGenerator/Feedtypes 116.2.1 Customerfeed 126.2.2 Productfeed 126.2.3 Quotefeed 13

6.3 Singleorderfeed 146.3.1 Invoicefeed 146.3.2 Shipmentfeed 146.3.3 Creditmemofeed 146.3.4 Sendtoafriendfeed 156.3.5 Sendwishlistfeed 156.3.6 Abandonedcart 15

7 Appendix 177.1 Loglevel 177.2 EmailObjectEncryptionsettings 17

07/25/2016 Magentoplugin2.0manual 3

2 Introduction InthisdocumentwedescribeindetailhowtousetheMagentoPluginforTripolisDialoguetosynchronizecontactsandsendemailstoMagentocustomers.Themainstepsinthisprocessare:

1. ConnecttheplugintoaTripolisDialogueclient(Section3).2. CreatemappingsforContactSynchronization(Section4).3. Setuptransactionalemails(Section5).4. Useproductfeedsinemails(Section6).

ForcontactsynchronisationyoucanconnectaMagentostoreviewtoaTripolisDialoguedatabase.Thisdatabasewillcontaincontactrecordsandasauseryoucanmapanystorefieldwithcustomerdata,toadatabasefieldinTripolisDialogue.Youcanalsosetuponegroupforsubscribersandoneforunsubscribersthatthepluginwillusebasedonthecustomerprofilesettings.ContactswillbeupdatedautomaticallyinTripolisDialoguewhenchangesoccurinthewebshop.Inthissynchronizationthewebshopisalwaysleading.Whenfirsttakingtheplugininproductionitisnecessarytodoaninitialsynchronization.ForsendingtransactionalemailsthepluginusesaseparatedatabaseinTripolisDialogue(ormultipledatabasesiftherearemultiplestoreviews).Thisdatabasewillnotcontaincontacts,buttransactionalrecords.Fortheserecordsyoucancreateadatabasemappingoftype"transactions"alongwiththenecessaryfieldmappingsforthisdatabasemap.IntheWorkspaceconnectedtothisdatabaseyoucanmaptransactionalemailstothedefaultmailsinMagento.Foreachtransactionalevent,thepluginwillcreateatransactionalrecordandwillsendouttheemailmappedtothisevent.Detailsforeachtransactioncanbefoundinthevarioustransactionfeeds(Section6.2).Forcommercialemailstoyourcontactsthepluginprovidesanumberofproductfeeds.TherearevariousfeedtypessuchasLatestAdditions,Bestsellers,etc.andtheURLforeachfeedcanbegeneratedbasedontype,numberofproductsandproductcategory.ThesefeedscanbeusedinNewslettersorDirectEmailsinTripolisDialogue.ThefeedURL'shaveaclearstructurethatmakesthemeasytouseincombinationwithplaceholdersforarticlefieldsinnewsletters.

07/25/2016 Magentoplugin2.0manual 4

3 Connect the plugin to a Tripolis Dialogue client TosynchronizecustomersinMagentotocontactsinTripolisDialogueyouneedtoconfiguretheplugin.

3.1 Plugin settings Afterinstallingtheplugin(seemagento_installation_manual)makesurethatyouenableditandthatyouprovidedan(administrator)email-addressfornotifications.Leavedisabledduringsetup.Enablerightbeforeinitialsynchronization.Thesesettingscanbefoundunder:Maintab:Tripolis>Configuration>Settings

IfyouhavemultiplestoresrunningonyourMagentoinstallation,keepinmindthatthisconfiguration,bydefault,issetupforallstoreviews,orforeachstoreviewindividually.ConfigurationofthescopeDefaultConfigmeansthatyoursettingswillapplyforallstoreviewsforwhichnoconfigurationhasbeenset.ToconfigureaspecificstoreviewselectthatstoreviewinthedropdownoftheCurrentConfigurationScopeselectionbox.

3.2 Connection with Tripolis Dialogue ToestablishaconnectionwithTripolisDialogueyouprovideyourcredentialsintheDialogueInstancesection(makesuretouseadedicatedAPIaccountwithadvancedAPIrights).YoucantesttheconnectionbyusingRunTest.Maintab:Tripolis>Configuration>Settings

LoggingThepluginprovidesextensiveloggingoptions;pleasechecktheappendixformoredetails.URLObjectEncryptionInformationusedinURL’scanbeencryptedwithAESencryption,seeappendixforfurtherdetails.

07/25/2016 Magentoplugin2.0manual 5

4 Databases mappings and contact synchronization 4.1 Contact Synchronization Inthissynchronizationthewebshopisalwaysleading.EmailiskeyinDialogueforcontactsynchronization(tohandlebothsubscribersandcustomers)Guesttransactionsareexcludedfromsynchronization.

4.1.1 Enabling / disabling of contact synchronizing ThecontactsynchronizationbetweenMagentoandTripolisDialoguecanbeenabledordisabledatalltimes.ThisismanagedintheContactsynchronizationsection.Maintab:Tripolis>Configuration>Settings

4.1.2 Status page Beforeinitialmapping,checktheConnectionstatusonthestatuspage.Maintab:Tripolis>Status

4.2 Mapping ForMagentotocommunicatewithTripolisDialogue,itisnecessarytocreatemappingsforcontact-databases,contact-groupsandcontact-fields.

4.2.1 Database mapping StartwithcreatingadatabasemapbyclickingAddDatabaseMapinthetoprightcorner.Maintab:Tripolis>Mapping>Databasemapping Thiswillopenfollowingpage:

1. Magentostore:selectthestoreviewforthismapping,donotuseAdmin2. Mapname:chooseadescriptivenameforthismapping,e.g.“Englishshopcontactdatabasemap”3. TripolisContactDatabase:selectacontactdatabase(ifdropdownisempty,checkconnectionstatus)4. TripolisWorkspace:selectaWorkspace,necessaryformappingemails5. Usedfor:2types,contactsortransactions

07/25/2016 Magentoplugin2.0manual 6

Databasemappingscanbeusedforeithercontactsortransactions.Inthissectionwefocusonthecontactsmapping.Fortransactions,pleaselookatsection5.AmappingforcontactswillcreatecontactrecordsinamappedTripolisDialoguedatabase,thiscontactdatabasecanbeusedfore-mailscampaigns.Eachstoreviewcanbemappedtoit’sowncontactdatabase.

4.2.2 Contact group mapping GroupmappingisnecessarytomapMagento’snewslettersubscribersandunsubscriberstoTripolisDialogue,It’scurrentlytheonlysupportedgrouptype.Thismappingallowsyoutomanageyournewslettersubscribersandunsubscribers,makesuretomapbothgroupsbeforestartinganinitialsync.

Maintab:Tripolis>Mapping>Groupmapping:

1. Magentosourcetype:SelectNewsletter(whichistheonlyoption).2. Magentosource:skipthisoption.3. Databasemap:selectdatabasemapping.4. TripolisGroup:selectagroupinTripolisDialogue.5. Usedfor:eithernewslettersubscribersornewsletterunsubscribers.

4.2.3 Contact field mapping ContactfieldmappingsareusedtomapfieldsinMagentowithcontactfieldsinTripolisDialogue.YoucanmapallstandardcustomerfieldsinMagento.Theonlymandatoryfieldforcontactsmappingisemailbutwerecommendtoalsomap:firstname,lastname.Maintab:Tripolis>Mapping>Fieldmapping

1. DatabaseMap:selectdatabasemapping.2. TripolisField:afterselectingadatabasemapping,thelistofavailableTripolisfieldswillrefresh.Makesurethat

theDialoguecontactdoesnothaveaminimumlength(Min.lengthshouldbe0orempty).3. MagentoSourceType:selectaMagentofieldcategory.

4. Magentosource:selectasourcefieldtomatchtheselectedTripolisfield.

07/25/2016 Magentoplugin2.0manual 7

4.3 Initial Synchronization MagentocustomersaresynchronizedtotheTripolisDialoguecontactdatabaseinreal-timeaftercreationorupdateinMagento.Beforetakingthepluginintoproduction,youneedtorunaninitialsynchronization.Aftersettingupyourmappings(=database,group,contactfields)youcanclickSynchronizecontactstostartyourinitialsynchronization.Maintab:Tripolis>Status

Asimilarpromptappears:

MakesureNOTtoclosethispromptuntilyouarenotifiedthatthesyncisdone.Ifforsomereasonanewinitialsyncisrequired,thiscaneasilybedonebyclearingtheclientdataResetallclientdata(mappingswillremainintact).

Andinitiating/clickingSynchronizecontactsagain.

4.3.1 Subscribing and unsubscribing of contacts Magentoisleadinginthesubscriptionandunsubscriptionofyournewslettersubscribers.NewslettersubscriptionsaredoneviatheMagentofrontend.Whenunsubscribingthroughnewsletters,yourunsubscribelinkshouldlooksimilarto(withoutaesEncrypt):http://MYMAGENTOHOST.COM/index.php/tripolis/subscriber/unsubscribe/?email=${contact.email}.WewouldrecommendyouhowevertoencryptyourcontactdetailswithaesEncrypt(Section7.2),similarto:http://MYMAGENTOHOST.COM/index.php/tripolis/subscriber/unsubscribe/?email=${contact.email?aesEncrypt(%278KNamWenYUeXpNOj%27,%27ziHV1baRH9ooTOCw%27)}.

07/25/2016 Magentoplugin2.0manual 8

5 Transactional emails ForsendingtransactionalemailsthepluginusesaseparatedatabaseinTripolisDialogue(ormultipledatabasesiftherearemultiplestoreviews).Thisdatabasewillnotcontaincontacts,buttransactionalrecords.Forthisyoucanmakeadatabasemappingoftype"transactions"(Section4.2.1)andthedesiredfieldmappingsforthisdatabasemap(Section5.1).Touseallsortsoftransactionalinformationinyouremails,youcancreatefeedsfromMagento(Section6.2)InaWorkspaceconnectedtothisdatabaseyoucancreatetransactionalemailsandmapthesetoexistingemailsinthewebshop(Section5.2).Foreachtransactionalevent,thepluginwillcreateatransactionalrecordandsendtheemailmappedtothisevent.

5.1 Transactional field mapping Makesureyouhaveacreatedatransactionaldatabasemappingbeforecreatingtransactionalfieldmappings. Tripolis>Mapping>Transactionalmapping

Ifyouuseatransactionaldatabase,thefollowingMagentoSourceattributesarerequiredtoenablethesynchronizationoftransactionalrecords:

- TransactionId(type:String).- Transaction(type:String).- MagentoObjectId(type:String).- Email(type:Email).

Ifyouaremakinguseofupdateemails(e.g.OrderUpdate,ShipmentUpdate,InvoiceUpdate)youshouldalsomaptheCommentattribute(toaStringfieldInTripolisDialogue),thisfieldisforcomment(s)thatwilltriggerupdateemails.TimestampattributeshouldbemappedwithadatetimetypefieldinTripolisDialogueforadditionalloggingoftransactionalrecords.

07/25/2016 Magentoplugin2.0manual 9

5.2 Email Mapping TohaveTripolisDialoguesendemailsinsteadofMagentoyouneedtomapMagento’sdefaultemailswith(direct)emaileditionsinDialogue.Amappingfortransactionswillcreatetransactionalrecordsinamappeddatabase.Theserecordscanbeusedforallsortsoftransactionalemails.Atransactionrecordcanbeaninvoice,aconfirmation,anordermail,etc.Itisonlypossibletocreateonemappingfortransactionsforeachstoreview.Defaultmail-templates:

1. AbandonedCart2. CreditMemoupdate3. CreditMemoupdateforGuest4. Invoiceupdate5. InvoiceupdateforGuest6. NewCreditMemo7. NewCreditMemoforGuest8. Newinvoice9. NewinvoiceforGuest10. NewShipment11. NewShipmentforGuest12. Newaccount13. Newaccountconfirmationkey14. Newaccountconfirmed15. Newslettersubscriptionconfirmation16. Newslettersubscriptionsuccess17. Newsletterunsubscriptionsuccess18. Orderupdate19. OrderupdateforGuest20. Sendproducttoafriend21. ShareWishlist22. Shipmentupdate23. ShipmentupdateforGuest

Likegroupandfieldmappings,emailmappingsarealsobasedonadatabasemapping,aworkspaceneedstobedefinedhowever,inordertomapdirectemaileditions(newslettersarenotmappable).Passwordreset,notificationandreportemailsforinternalusecannotbesentthroughTripolisDialogue.

07/25/2016 Magentoplugin2.0manual 10

Maintab:Tripolis>Mapping>Emailmapping

1. Magentostore:selectastoreviewforwhichyouwanttomapatransactionalemail.2. MagentoEmailTemplate:selecttheMagentoemailtemplateyouwouldliketomap.3. DatabaseMap:selectthedatabasemap,whichcontainstheworkspacewithyourdirectemailtemplates4. DirectEmailType:selecttheTripolisDialoguedirectemailtypeofthedirectemailedition.5. DirectEmail:selecttheTripolisDialoguedirectemailedition6. EnableTripolisEmail:bydefaultsetto‘Yes’.7. DisableMagentoEmail:bydefaultsetto‘Yes’

07/25/2016 Magentoplugin2.0manual 11

6 Use of feeds and configuration settings Thepluginisabletocreatexmlfeedsofcustomer,productandtransactionalinformation.WiththesefeedsTripolisDialoguecancreatepersonalizedemailswithreal-timeinformationfromtheMagentowebshop.KeepinmindthatusingfeedsforlargemailingsresultsinanincreasedloadforyourMagentoserver.

6.1 Security Thepluginofferstwolevelsofsecuritytopreventunauthorizedaccesstothefeed’scontent.

6.1.1 IP restriction of feeds Inyourconfigurationsettingsyoucanenteracomma-separatedlistofIPaddressesthatwillhaveexclusiveaccesstothefeeds.TripolisSupportcanprovidetheIPaddressesusedbyyourTripolisDialogueinstance.AdditionallyyoucouldaddyourownIPaddressfortestingpurposes.Maintab:Configuration>Tripolis(leftmenuitem:Symfony|Modules)>Feedsettings

UsingtheIPrestrictionisnotrequired,howeverwestronglyrecommenddoingso.

6.1.2 Feed user restriction FeedscanonlybeaccessediftheURLofthefeedcontainsavalidsecuritykey.Tocreateakeyyouneedtoregisteratleastonefeeduser.Maintab:Tripolis>Feeds>Users Opens:

6.2 URL Generator / Feed types TheplugincontainsaURLGeneratorthatcreatesaURLforacertainfeedtype.Whenselectingdetailsforthefeed,theURLwillbuildupaccordingly.AvailableFeeds:

1. Customer2. Product(Singleproduct,Lastaddedproducts,Specialprice,Bestsellingproducts,Mostviewedproducts,Related

tocustomerpurchases,Randomproducts)3. Quote4. Singleorder5. Invoice6. Shipment7. Creditmemo8. Sendtofriend9. Sendwishlist

07/25/2016 Magentoplugin2.0manual 12

TouseanxmlURLinaTripolisDialogueemailitispossibletoreplacecertainelementswithcontactmergefields,articlefieldsorotherFreeMarkervariablescomingfromcontactfieldsinyourdatabase.Tripolis>Feeds>URLGeneratorFirst,selectaFeeduser.Ifyouhaven’tcreatedoneyouwillbedirectedtotheNewFeedUserpage.Next,selectaFeedtype:

Whileselectingoptionsandenteringvalues,theExampleURLwillinstantbuildupaccordingly.

6.2.1 Customer feed WiththisfeedyoucanaccessMagentocustomerdetails.

Thesesettingswillcreateafeedforcustomer139,like:http://MYMAGENTOHOST.COM/index.php/tripolis/feed/create/key/7e455b42794996a03c164df9039b4b50/type/customer/customerid/139/Customerid’scanbefoundintwolocations:

- Customers>ManageCustomers:inthecolumnIDyoucanfindyourMagentocustomerid- InDialogueinthetransactionaldatabase,thefieldthathasbeenmatchedwithMagentoObjectId

AURLexampleforusingfeedinTripolisDialogue:http://MYMAGENTOHOST.COM/index.php/tripolis/feed/create/key/1691ddbcaf5b877545c485cff63d513b/type/customer/customerid/${contact.customer_id}

07/25/2016 Magentoplugin2.0manual 13

6.2.2 Product feed TheproductfeedcanbeusedtoloadproductsfromtheMagentodatabase.Thereareafewlimitationshowever:

- OnlyproductswithvisibilitysettoCatalog,Search,orCatalog&Searchcanbeloaded.- OnlyproductsthataresettoEnabledandareinstockcanbeloaded.

Genericsettings:Theproductfeedisawrapperforalltheproductrelatedfeeds.

- Storeview:foreachfeedyouwillneedtoselectastoreview,asproductnamesanddescriptionsmayvary.- Specifyamaximumnumberofproductstobeincluded,setthevalueof‘Howmanyproducts?’.- Allproductfeedscanbefilteredbycategory.

Productselection:

- Singleproduct:feedofonesingleproduct,youcanuseeitherSKUorproductIdtospecifywhichproduct.- Lastaddedproducts:thisfeedwillprovidethemostrecentaddedproducts.- Bestsellingproducts:thisfeedwillcontainthebestsellingproducts.Currentlythisselectionisbasedonalltime

sales.- Mostviewedproducts:thisfeedwillcontainthemostviewedproducts.Currentlythisselectionisbasedonall

timeviews.- Relatedtocustomerpurchases:thisfeedalsorequiresacustomerId.Productsrelatedtoproductswhichthe

customerhasboughtwillbeincludedinthisfeed.- Randomproducts:asthenamesuggests,thisfeedwillcontainrandomproductsfortheselectedstoreviewand

ifspecifiedtheselectedcategory.

6.2.3 Quote feed

Thisfeedcanbeusedtofetchtheitemsofanabandonedshoppingcart.QuoteidcanbefoundinthecontactfieldthatismappedwithMagento’sMagentoObjectId.

07/25/2016 Magentoplugin2.0manual 14

6.2.4 Single order feed

Theorderfeedrequireseithertheorder’sMagentoIdortheorder’sincrementid.TheincrementidistheiddisplayedontheorderoverviewpageinMagento.However,theorderidistheidintheDialoguefield(inthetransactionaldatabase)thathasbeenmatchedwithMagentoObjectId.Itisalsopossibletomaptheincrementidtoyourtransactionalcontactdatabase,thereforetheorderfeedhasbeenconfiguredtoacceptboth.

6.2.5 Invoice feed

TheInvoicefeedonlyrequiresaninvoiceid.ThisIdcanbefetchedfromDialogueinthetransactionaldatabase:thesamefieldthathasbeenmatchedwithMagentoObjectId.

6.2.6 Shipment feed

Theshipmentfeedonlyrequiresashipmentid.ThisIdcanbefetchedfromDialogueinthetransactionaldatabase:thesamefieldthathasbeenmatchedwithMagentoObjectId.

6.2.7 Credit memo feed

TheCreditmemofeedonlyrequiresacreditmemoId.ThisIdcanbefetchedfromDialogueinthetransactionaldatabase:thesamefieldthathasbeenmatchedwithMagentoObjectId.

07/25/2016 Magentoplugin2.0manual 15

6.2.8 Send to a friend feed

UsuallywhenMagentosendsasendtofriendemailthecontentforthatemailisdirectlywrittenintotheemailtemplate.Sincewearenotabletodosowestorethiscontentintoadatabase.Thisfeedcanbeusedtoaccessthatcontent.ThesendtofriendidcanbefetchedfromDialogueinthetransactionaldatabase:thesamefieldthathasbeenmatchedwithMagentoObjectId.

6.2.9 Send wish list feed

TheSendwishlistfeedissimilartothesendtofriendfeedtypeandmakesuseofthesametypeofid.Thedifferenceisthatinsteadofsendingaproductacustomerissendinghisorherwishlisttoafriend.

6.3 Abandoned cart feed / functionality Theabandonedcartfeatureenablesyoutosendareminderemailtocustomerswhohaveaddeditemstotheirshoppingcartbuthaven’tcompletedtheorderprocess.ThisfunctionalitycanbeenabledthroughtheAbandonedcartsettings:System>Configuration>Tripolis(leftmenuitem:Symfony|Modules)>Abandonedcart

SetSendabandonedcartmailingstoYestoenabletheAbandonedcartfeature.Schedulestandsfortheexpirationtimeofashoppingcart(consideredas‘abandoned’)Cronspeed:frequency/speedofyourcronjob(ScheduledTask),oftheserverMagentorunson.

07/25/2016 Magentoplugin2.0manual 16

MappingofAbandonedcartemailtemplate:Tripolis>Mapping>Emailmapping

YouwillneedtomapthiscustomtemplatetoaTripolisDirectEmailtemplate.

07/25/2016 Magentoplugin2.0manual 17

7 Appendix 7.1 Log level ChoosebetweenErrorsonly,Errorsandnoticesonly,andEverything.Errorsonlyiscustom.

7.2 Email Object Encryption settings AllvaluesinURL’scanbeencryptedwith?aesEncrypt('<16characters/key>',<16characters/salt>’)Anunsubscribeexample:http://MYMAGENTOHOST.COM/index.php/subscriber/unsubscribe/?email=${contact.email?aesEncrypt('8KNamWenYUeXpNOj','ziHV1baRH9ooTOCw')}EnterthesamevaluesyouusedaskeyandsaltinTripolisDialoguetoencryptanemailaddressheresothatthemodulecandecryptthevalue.TheRunTestbuttonwillcheckifbothvalueshavealengthofexactly16characters.Tripolis>Configuration>Settings