introduction - marketo developersdevelopers.marketo.com/support/marketo_crm_sync_reference... ·...
TRANSCRIPT
INTRODUCTION
This document aims to provide detailed information regarding implementation of a synchronization architecture between Marketo and an external CRM system. Entities are described as well as the specifics of performing initial synchronization, or “bootstrapping,” and maintaining synchronization of new and updated records.
TableofContentsMarketo-CRMSynchronizationArchitecture...............................................................................................1
Introduction.............................................................................................................................................1
Overview..................................................................................................................................................4
TypicalSynchronizedEntities...................................................................................................................4
Leads....................................................................................................................................................4
Companies............................................................................................................................................6
Opportunities.......................................................................................................................................7
OpportunityRoles................................................................................................................................8
SalesPersons........................................................................................................................................9
ExtendedSynchronizedEntities.............................................................................................................10
CustomObjects..................................................................................................................................10
Activities.............................................................................................................................................11
Programs............................................................................................................................................13
ProgramMembership........................................................................................................................14
StaticLists...........................................................................................................................................15
Synchronization..........................................................................................................................................16
Configuration..........................................................................................................................................16
SynchronizedFields............................................................................................................................16
SynchronizedCustomObjects............................................................................................................16
SynchronizedActivityTypes...............................................................................................................16
BootstrappingConfiguration..............................................................................................................16
SynchronizationInterval.....................................................................................................................16
BootstrappingfromMarketo.................................................................................................................17
Leads..................................................................................................................................................17
Companies..........................................................................................................................................17
OpportunitiesandRoles.....................................................................................................................17
SalesPersons......................................................................................................................................18
CustomObjects..................................................................................................................................18
ProgramsandMembership................................................................................................................18
Activities.............................................................................................................................................18
ListsandMembership........................................................................................................................19
RecommendedBootstrappingOrder.................................................................................................19
MaintainingSynchronization..................................................................................................................19
RecommendedSynchronizationOrder..............................................................................................19
LeadsandCompanies.........................................................................................................................20
SalesPersons......................................................................................................................................21
OpportunitiesandRoles.....................................................................................................................21
Activities.............................................................................................................................................22
CustomObjects..................................................................................................................................22
Program-OpportunityAttribution..........................................................................................................22
First-TouchAttribution(FT).................................................................................................................22
Multi-Touch(MT)................................................................................................................................23
OverviewMarketorecommendsimplementationofCRMsynchronizationapplicationsusingatwo-waypollingmodel,retrievingchangesandnewrecordsfromeithersystem,andpushingthosechangesasmappedintheapplicationconfigurationtotheothersystem.ThemiddlewaresystemshouldqueryforchangesofselectedrecordtypesperiodicallyandthenperformanynecessarytranslationandfiltrationbeforepushingtherecordupdatestoCRMorMarketorespectively.
TypicalSynchronizedEntitiesAminimallyfunctionalCRMintegrationwithMarketowillprovidetwo-waysynchronizationofLeads,andCompanies,andone-wayCRM-to-Marketointegrationofthefollowingentities:
• Opportunities• OpportunityRoles• SalesPersons
GlobalNotesforObjectModels
SomeobjectschemasinMarketoaredynamicanduser-editable,soitisextremelydesirabletoallowdynamicupdatestotheschema,andthisshouldbedoneasaroutinepartofasynchronizationcycle.Forthesetypesofobjects,aDescribe{Object}endpointismadeavailable,whichwillreturnallofthefieldsavailabletotheMarketoAPIs,alongwithdatatypeandlengthinformationwhereapplicable.Whereavailable,theDescribeendpointshouldbeusedastheexclusivesourceoftruthfortheobjectschema.Administrativeusersshouldbepermittedtoadd,removeandaltermappingfornon-IDfieldsatanytime.
LeadsPrimaryKey:id
TheintegeridofaMarketoleadrecordandtheprimarykeyaresystemmanagedbyMarketo,andmayonlybeassignedbyMarketo.Anyinsertoperationsattemptedbyaforeignsystemwhichincludeidwillberejected.
InMarketo,leadsrepresentanyperson-recordwhichisasalesormarketingtarget.Theyaredistinctfromsalespersonrecords,whichrepresentasalespersonwhohasresponsibilityoverleadrecords.AllSmartCampaigns,commonlyreferredtoasa“workflow”innon-Marketosystems,filter,trigger,andoperateonleadrecords,basedontheircharacteristicsandactions.UnlikemosttypicalCRMsystems,MarketodoesnothavetwoseparaterecordtypesforLeadandContactrecords,rather,eachperson-recordinMarketohasadditionalfieldswhichmatchthoseavailableforCompanies.ThesetofcompanytypefieldsonagivenrecordisnolongerupdateablewhentheexternalCompanyIdfieldissetforthatrecord,andisdeferredtothelinkedcompanyrecord.
Model
LeadsarehighlyextensibleinMarketoandmayincludeanunlimitednumberofcustomfields.Whensynchronizinganyparticularsubscription,asetofstandardfieldsshouldnotbereliedupon,andtheDescribeLeadfunctionoftheRESTAPIshouldbeusedastheexclusivesourceoftruthtodeterminefieldavailabilityandupdateabilityinaparticularsubscription.
Themodelforaleadisalsopotentiallydynamic,asfieldsmaybeaddedorhiddenbyend-usersatanytime,sotheschemaofleadrecordsshouldbemaintainedwheneverasynchronizationcycleisinitiated.
AcustomleadfieldshouldbecreatedinMarketotoholdtheprimarykeyoftheCRM,inordertopermitunambiguousupsertoperationsforleadrecords.
Mapping
LeadfieldmappingshouldbedeterminedbytheavailablepersontypesintheCRMsystem.AtypicalCRMimplementationwouldonlyincludeLeadsandContactsandwouldbemappedtothelogicalcorrespondingfieldforeachrecordtype.WhenpossibleasuggestedlistofmappingsshouldbegivenforfieldswhichareknowninbothMarketoandtheCRM,butusersshouldbeallowedtochangethesefieldmappingsfreelytoaccountfordifferentusages.Ifleadsaremappedtomultipleobjecttypes,thenmappingsforeachtypeshouldbeallowedtobemappedindependently.Itispossibleandsometimesdesiredtohaveleadsmappedtomultipletypesofrecords(e.g.LeadsandContactsintheCRM),differentiatingthetypeonthebasisofacustomCRMtypestringfield,referringeithertotheIDoftheparticularrecordtype,oraplaintextstringrepresentingthetype.
Relationships
LeadsarerelatedtonumerousaccessibleobjecttypesinMarketo:
Object RelationshipType LinkType LinkFieldCompany N:1 LeadField externalCompanyIdSalesPerson N:1 LeadField externalSalesPersonIdOpportunity N:N OpportunityRole
ObjectleadId
CustomObjects 1:N,N:1,orN:N SeeCustomObjectSection
SeeCustomObjectSection
Activities 1:N ActivityField leadIdProgram N:N ProgramMembership
ObjectSeeProgramMembership
Accessibility
LeadsmaybereadandwrittentoinMarketofreelyprovidedthattheRead-WriteLeadPermissionhasbeenawardedtotheAPIuserbeingused.Leadscanbereadthroughthefollowingendpoints:
• GetLeadbyID• GetMultipleLeadsbyFilterType• GetMultipleLeadsbyListId• GetMultipleLeadsbyProgramId
Leadscanbewrittentothroughthefollowingendpoints:
• Create/UpdateLeads• ImportLead
LeadRecordsmaybemergedthroughtheMergeLeadsendpoint.Adiscussionofthisendpoint’sbehaviormaybefoundhere.
LeadsmaybedeletedthroughtheDeleteLeadsendpoint.
LeadMetadataisreadthroughtheDescribeLeadendpoint.
CompaniesPrimaryKey:externalCompanyId,id
externalCompanyIdisanarbitrarystringfieldsetuponcreationbytheexternalsystem.Itisguaranteedtobeunique.Itisnotupdateable.Idisauniquesystem-generatedintegerid.
Companyobjectsrepresenttheorganizationtowhichleadrecordsbelong.LeadsareaddedtoaCompanybypopulatingtheircorrespondingexternalCompanyId.Leadslinkedtoacompanyrecordwilldirectlyinheritthevaluesfromacompanyrecordasthoughthevaluesexistedonthelead’sownrecord.Attributesavailableonthecompanyrecordareavailablefortriggeringandfilteringonleadrecordsfromwithintheapplication.
Companyrecordsmayonlybecreatedbyexternalsystems,andtheCRMshouldbetreatedasthesourceoftruth,exceptwhenchangestocompanyrecordsaredetectedinMarketo.
Model
• Companiesarefullyextensibleandmayhaveanynumberandtypeofcustomfields• Theschemashouldbedynamicandcapableofingestingorevictingfieldsfromthemodelatany
time.ItshouldberefreshedwithDescribeCompanyasaroutinepartofsynchronization.• DescribeCompanyshouldbeusedastheexclusivesourceoftruthfortheschemaofcompany
Mapping
CompanyrecordsinMarketoshouldbemappedtoanequivalentobjecttypeinCRM.ThesearetypicallyreferredtoasCompanies,Accounts,orOrganizations,butterminologymayvaryfordifferent
CRMs.UsersshouldbeallowedtoeditthemappingsofMarketoCompanyfieldstoCRMCompanyfields.
TheprimarykeyofcompanyrecordsinCRMshouldbemappedtotheexternalCompanyIdfieldwheneverpossible.
Relationships
Object RelationshipType LinkType LinkFieldLead 1:N LeadField externalCompanyIdOpportunity 1:N OpportunityField externalCompanyId
Accessibility
Inordertoreadandwritetocompanyrecords,anAPIusermusthavetheRead-WriteCompanypermission.
Companiesmaybereadthroughasingleendpoint,GetCompaniesByFilterType.Companiesmayonlybefilteredonalimitednumberoffields,whichareprovidedinthesearchableFieldsattributeoftheDescribeCompanyresult.
CompaniescanbewrittentousingtheCreate/UpdateCompaniesendpoint.
CompaniesmaybedeletedthroughtheDeleteCompaniesendpoint.
OpportunitiesPrimaryKey:externalOpportunityId,marketoGUID
externalOpportunityIdisanarbitrarystringfieldwhichissetuponcreationbytheexternalsystem.Itisguaranteedtobeuniqueandisnotupdateable.marketoGUIDisasystem-generatedGUIDstringwhichisguaranteedtobeunique.
OpportunityobjectslooselyrepresentsalesdealsinMarketo,andareresponsibleforattributingrevenuetoleads,companiesandprograms.OpportunityusagevariesbetweenbothCRMimplementationsandorganizationalimplementations,sotheymayencompassanywherefromasalesdealcompletewithindividuallineitemstobroaderrecordsofsalesefforts.Itmaynotbepossibletoaccommodateanorganization’susecasesfortrackingsalesdealsthroughtheimplementationopportunitiesalone,soadditionalextensionthroughCustomObjectsmayberequired.
ToperformproperRevenueAttribution,Opportunitiesmustbelinkedtoleadsviaroles,andlinkedtocompaniesviatheexternalCompanyIdfield.ForinformationonRevenueAttribution,pleaseseethe<Program-OpportunityAttribution>section.
Model
Likeleadsandcompanies,opportunitieshaveaflexibleanduser-extensibleschema,whichshouldberoutinelyupdatedthroughtheDescribeOpportunityendpoint.
Mapping
Ingeneral,thesamemappingstrategyshouldbeemployedforOpportunitiesasLeadsandCompanies,butOpportunitieshavesomespecial-casefieldswhichshouldbemappedwithcare:
• The“Amount”fieldinMarketoisthefieldfromwhichallrevenuecalculationsaremadeandshouldalwaysbemappedtotheOpportunityfieldwhichrepresentstheestimatedamountoftheproposeddealbeforeclose,andtherealizedamountofthedealafterclose.
• The“RevenueExpected”metricusestheMarketo“CloseProbability”fieldtoderivethemetricfromamount.TheCloseProbabilitypercentageismultipliedagainstAmounttoreturnRevenueExpected.
• Stagehasasetofcalculatedvaluesbasedonthe“closed”and“won”fieldsonopportunityrecords.Closedshouldbesettotrueifthesalesdealisnolongerbeingpursued,eitherbecausetheeffortfailed,orbecausethedealwaswon.Wonshouldbesettotrueonlyifclosedisalsotrueandthedealhasbeenwon.DifferentCRMsmaytreatthesecharacteristicdifferently,andsotheymayrequiretranslationfromthesystem.
externalOpportunityIdshouldbemappedtotheprimarykeyintheCRMwheneverpossible.
externalCreatedDateshouldbemappedtotheCRMsystem’scanonicalcreationdateforopportunities.
Relationships
Object RelationshipType LinkType LinkFieldCompany N:1 OpportunityField externalCompanyIdLead N:N OpportunityRole
ObjectleadId
Program N:N SeeProgram-OpportunityAttributionsection
SeeProgramOpportunityAttributionsection
Accessibility
Inordertoreadandwritetoopportunities,anAPIusermusthavetheRead-WriteOpportunitiespermission.
OpportunitiescanbereadviatheGetOpportunitiesbyFilterTypeendpoint.Likecompanies,theyhavealimitedsetofsearchablefieldswhichcanberetrievedviatheDescribeOpportunityendpoint.
OpportunitiesmaybecreatedorupdatedviatheCreate/UpdateOpportunitiesendpoint.
OpportunitiesmaybedeletedthroughtheDeleteOpportunitiesendpoint.
OpportunityRolesPrimaryKey:CompoundKey[leadId,role,externalOpportunityId],marketoGUID.
OpportunityroleshaveacompoundkeyofleadId,roleandexternalOpportunityId.leadIdandexternalOpportunityIdarerelationshipfieldstotheirrespectiveleadandopportunities.Toinsertarecord,orupdateitviaitsdedupeFieldskey,allthreefieldsmustbepassedintherecord.marketoGUIDisauniqueGUIDstring,whichissystem-managedandisgeneratedoncreationoftherecord.
Opportunityrolesarelinkobjectsfromleadrecordstoopportunityrecords.Withoutthisrelationship,leadswillnotbeassociatedtoOpportunitiesinanyway.Theyarealsorequiredrelationshipstoperformend-to-endProgramOpportunityAttribution.
Model
TheschemaforOpportunityRolesisnon-extensibleandshouldbederivedfromtheDescribeOpportunityRoleendpointonce.PrimarycontactsonanopportunityaredesignatedinMarketobytheisPrimaryflagontheopportunityrole.IftheprimarycontactconceptexistsintheCRMbeingintegrated,thisshouldbeimplementedaspartofthemodelandmapping.
Mapping
isPrimaryshouldbematchedifthereisaconceptofprimarycontactsintheCRMbeingintegrated.
externalCreatedDateshouldbemappedtothecanonicaldateintheCRMwhichcorrespondstothedatethatapersonbecameamemberoftheopportunity.
Relationships
Object RelationshipType LinkType LinkFieldLead N:1 OpportunityRoleField leadIdOpportunity N:1 OpportunityRoleField externalOpportunityId
Accessibility
Toreadandwriteopportunityroles,anAPIusermusthavetheRead-WriteOpportunitiespermission.
OpportunityRolescanbereadviatheGetOpportunityRolesbyFilterTypeendpoint.Likecompanies,theyhavealimitedsetofsearchablefieldswhichcanberetrievedviatheDescribeOpportunityendpoint.
OpportunityRolesmaybecreatedorupdatedviatheCreate/UpdateOpportunityRolesendpoint.
OpportunityRolesmaybedeletedthroughtheDeleteOpportunityRolesendpoint.
SalesPersonsPrimaryKey:externalSalesPersonId,marketoGUID
externalSalesPersonIdisanarbitrarystringfieldsetuponcreationbyanexternalsystem.marketoGUIDisauniquesystem-managedGUIDstringwhichissetuponcreationbyMarketo.
SalesPersonsrepresentaninternalentitywhichhasownershipofasetofpersonrecords,typicallyforsalespurposes.TheinformationpresentontheserecordsisusedtoderivecertainformulafieldsandtokensforleadrecordsinMarketo.
Model
TheschemaforSalesPersonsisnon-extensibleandshouldbereadoncefromtheDescribeSalesPersonendpoint.
Mapping
externalSalesPersonIdshouldbemappedtotheprimarykeyforthecorrespondinguserorownerobjecttypeintheintegratedCRM.
Relationships
Object RelationshipType LinkType LinkFieldLead 1:N LeadField externalSalesPersonId
Accessibility
InordertoreadandwritetoSalesPersons,anAPIusermusthavetheRead-WriteSalesPersonpermission.
SalesPersonscanbereadviatheGetSalesPersonsbyFilterTypeendpoint.Likecompanies,theyhavealimitedsetofsearchablefieldswhichcanberetrievedviatheDescribeSalesPersonsendpoint.
SalesPersonsmaybecreatedorupdatedviatheCreate/UpdateSalesPersonsendpoint.
SalesPersonsmaybedeletedthroughtheDeleteSalesPersonsendpoint.
ExtendedSynchronizedEntitiesCustomObjectsPrimaryKey:marketoGUID,AdditionalUserDefinedkeys
Customobjectsalwayshaveauniquesystem-generatedmarketoGUIDwhichissetuponcreation.Therewillbeatleastoneadditionalkey,andpossiblymore,whichareuser-definedinthecustomobjectdefinition.Keysmaybesinglefieldsfortypeswhicharelinkeddirectlytoleadsorcompanies,andmayhavecompoundkeysfortypeswhicharelinkedtoleadsoraccountsandanothercustomobjecttype.KeyscanbedeterminedbyusingDescribeCustomObjecttoretrievethelistofdedupeFields.
MarketoallowsthedefinitionofCustomObjecttypesbyuserstoextendtheMarketoschema.Marketocustomobjectsmayberelatedtoleadsorcompanies,ineitheraonerecordtomanycustomobjectconfiguration,oramany-to-manyconfigurationthroughtheusageofintermediatecustomobjects.
Model
TheschemaforCustomObjectsisdynamicandvariableacrossallsubscriptions.EachCustomObjectmayhaveanynumberoffieldswhichmayupdated
Mapping
CustomObjectmappingshouldbedrivenbycustomerrequirementsandcan’tberigidlydefinedingeneral.
Relationships
MarketoCustomObjectsmayonlyberelatedtoeitherleadsorcompanies,ineithera1:NorN:NconfigurationthroughtheusageofintermediateCustomObjects.RelationshipscanbederivedfromtherelationshipsparameteroftheresultofDescribeCustomObject.
Accessibility
Toreadandwritetocustomobjects,anAPIusermusthavetheRead-WriteCustomObjectpermission.CustomObjectshavethestandardsetofGet,Create/Update,andDeleteendpoints.AListCustomObjectsendpointisalsoprovidedtoagiveameansofdeterminingwhatCustomObjecttypesareavailableinagivensubscription.
ActivitiesPrimaryKey:id
ActivitieshaveauniqueintegeridthatissetuponcreationbyMarketo.
ActivitiesarerecordsofactivitiesassociatedtoleadrecordsinMarketo.Theymayrecordactivityofmanydifferenttypes,asindicatedbytheiractivityTypeId.Activitiesareread-onlyinMarketo.Certainactivitytypesareprunedafter90daysintheMarketosystem.PrunedActivities:
• DataValueChange• AddtoList• RemovefromList• VisitWebPage• ClickLink
Thetypesofactivitiesavailableinagivensubscriptionarevariabledependingonmanyfactors,includingtypeofsubscription.TheavailabletypesandtheirmetadatashouldalwaysbedeterminedbycallingGetActivityTypesfromthetargetsubscription.
Activitiesareread-only
Model
Activitieshaveasemi-strictschema.Thefollowingfieldsaredefined,butnotnecessarilyusedforallactivitytypes:
Name Datatype Descriptionid Integer UniqueidleadId Integer Idofthelinkedlead.MapstoidonleadrecordsactivityTypeId Integer IdofthetypeofactivitycorrespondingtoaresultofGet
ActivityTypesactivityDate Datetime DatethattheactivityoccurredprimaryAttributeValue String ValueoftheprimaryattributeprimaryAttributeValueId Integer Idoftheprimaryattributeattributes Array Arrayofname/valuepairsrepresentingtheattributesofthe
activity
Eachactivitytypehasaprimaryattributewhichcorrespondstoavalueofsomekind.TheattributemayberelatedtoanytypeofassetorobjecttypeinMarketo.Forexample,theprimaryAttributeValueoftheVisitsWebPagetypecorrespondstothenameorURLofthewebpagewhichwasvisited.TheMarketonamewillbepresentedifthepagewasalandingpage,andtheURLifitisnotaMarketopage.Attributesconsistsofanarrayofname/valuepairs,namingeachofthefieldsforanactivitytypeandthecorrespondingvalue.
Activitiesmaybemodeledaseitherasingleobjecttypewithanarrayofattributes,orasindividualobjecttypes,dependingontherequirementsorbestpracticesfortheexternalCRMsystem.
Relationships
ActivitiesinMarketoarealwaysrelatedtoleadrecordsthroughtheleadIdfield.SomeactivitytypesmayhavearelationshiptootherMarketoassetsthroughtheirprimaryAttributeValue.
Accessibility
Inordertoreadactivities,anAPIusermusthavetheRead-OnlyActivitypermission.TowritecustomactivitiestheRead-WriteCustomActivitiespermissionisrequired.
ActivitiescanbereadthroughtheGetLeadActivities,GetLeadChanges,andGetDeletedLeadsendpoints.CustomActivitiesmaybewrittenthroughtheWriteCustomActivitiesendpointifacustomobjecttypehasbeendefined.
ProgramsProgramsinMarketoarebothaprimaryorganizationalassetandakeyattributioncomponent.Programsrepresentmarketingcampaigns,individualmarketingtacticsandassets,andoperationalworkflows.Eachprogrammayencapsulatemarketingassets,SmartLists(i.e.dynamicsegmentationlists)andSmartCampaigns(i.e.workflows).Opportunity-relatedrevenueisattributedtoprogramsbasedonalead’srelationshiptoaprogram,representedeitherbytheAcquisitionProgramleadfield,orbyalead’sprogrammembershipinthatprogram.
ItisacommonpracticeinCRMintegrationforaprogramnottobedirectlyrepresentedinCRMbuttobetranslatedtoanothertypeofobject.Forexample,inMarketo’snativeSFDCsync,theProgramismappedtotheCampaigntype,andtheProgram’smembershipismappedtotheCampaignMembershiptype.
Model
Theschemaforprogramsismostlystatic.Thenumberoffieldsavailableforprogramrecordswillnotchange,buttheChannelsandTagshaveusercustomizablevalues,whichshouldbemodeledifchoosingtoallowcreationofnewprogramsfromCRMtoMarketo.Aprogramwillhavethefollowingfields:
Name Datatype DescriptionId Integer Uniqueidoftheprogramname String User-definednamedescription String User-defineddescriptioncreatedAt Datetime DateofcreationupdatedAt Datetime Dateoflastupdateurl url Urloftheprograminthesubscriptiontype String Typeoftheprogram,oneof:Default,Event,EventwithWebinar,
Nurture,orEmailchannel String Channeloftheprogram.Definesacceptablestatusesforprogram
membershipfolder Object Parentfolderoftheprogram.status String Statusoftheprogram.workspace String Parentworkspaceoftheprogramtags Array Arrayofuser-definedtags.Tagsprovidecustomizable
informationforprograms.costs Array Arrayofcosts.Usedtodefinecostsrelatedtorunningaprogram.
MappingTheCRMtobeintegratedmayhaveanobjecttypewhichmapstotheMarketoprogramnaturally.Programsbroadlyrepresentmarketingcampaigns,andarelinkedtoleadsthroughtheProgramMembershipobjectwhichdefinesthelead’sstatus,andsuccessinthemarketingeffort.
RelationshipsProgramsarerelatedtoleadsthroughtheProgramMembershipobject.ProgramsalsohaveotherrelationshipstoassetswhicharenotpertinenttothediscussionofCRMintegration.
Accessibility
Toreadprograms,theRead-OnlyAssetpermissionisrequired.ProgramscanbereadthroughBrowsePrograms,GetProgrambyId,GetProgrambyName,andGetProgrambyTagType.
Towriteprograms,theRead-WriteAssetpermissionsisrequired.ProgramscanbecreatedthroughCreateProgram,canbeupdatedthroughUpdateProgram,clonedthroughCloneProgram,andDeletedthroughDeleteProgram.
ProgramMembershipPrimaryKey:Compound[IdofProgram,IdofLead]
Theprimarykeyforprogrammembershipisauniquecompoundkeyoftheidofthelinkedprogramandtheidofthelinkedlead.Theremayonlybeoneprogrammembershiprecordforeachuniquepair.
ProgramMembershiprepresentsalead’srelationshiptoaprogramandtheirstatusinthatprogram.
Model
ProgramMembershiphasastrictschema.InrelationtoCRMsomefieldsmaybeconsideredoptionaldependingoncustomerrequirements.Stream,isExhaustedandnurtureCadencewillonlybepopulatedwhenthemembershiprecordisrelatedtoaNurtureProgram,andmaynothaveexternalrelevance.
Name Datatype DescriptionprogressionStatus String StatusoftheleadintheparentprogramStream String NameofthestreamthattheleadisamemberofnurtureCadence String Cadenceoftheleadinanurtureprogram.EitherNormalor
PausedisExhausted Boolean WhethertheleadisexhaustedinitscurrentNurtureStreamacquiredBy Boolean WhethertheleadwasacquiredbytheparentprogramreachedSuccess Boolean WhethertheleadisinasuccessstatusintheparentprogramreachedSuccessDate Datetime ThedatethattheleadbecamesuccessfulintheprogrammembershipDate Datetime Thedatetheleadbecameamemberoftheprogram
TheidoftheparentprogramandisoftheparentleadarenotexplicitlyreturnedbyGetLeadsbyProgramId,butareinferredbythegivenprogramid,andthereturnedparentlead.
Mapping
Likeprograms,programmembershipmayhaveanaturalmappingtoanexistingobjecttype,butmayalsoneedtoberepresentedbyacustomobjecttypeintheintegratedCRM.
Relationships
Programmembershipisrelatedtoprogramsandleadsbytheirrespectiveids.
Accessibility
ReadingandwritingprogrammembershiprequirestheRead-WriteLeadpermission.ProgrammembershipmaybereadthroughGetLeadsbyProgramId,andwrittenthroughChangeLeadProgramStatus.
StaticListsPrimaryKey:id
StaticListshaveauniquesystem-managedintegeridwhichissetatcreation.
StaticListsrepresentnon-dynamicgroupingsofleadrecordsinMarketo(opposedtoSmartLists,whicharedynamicandupdateautomaticallyasnewleadsmeetthecriteriaorexistingleadsceasetomeetthecriteria).StaticListsareonlycreatedbyusersfromtheUIformarketingpurposes.StaticListsmayormaynotbeimportantinexternalsystemsdependingoncustomerrequirements,andhaveanextremelybroadsetofusecases.StaticListsareusedtoflexiblyrepresentgroupsofpeople.
Model
StaticListshaveastrictschemadefinedbelow.
Name Datatype DescriptionId Integer UniqueIdName String User-definednameDescription String User-defineddescriptionprogramName String NameoftheparentprogramifapplicablecreatedAt Datetime DatethelistwascreatedupdatedAt Datetime Datethelistwaslastupdated
ListMembershipisdefinedasasimplerecordcontainingtheidoftheparentlistandtheidoftheparentlead.
Mapping
StaticListsandtheirmembershipmayhaveanaturalcorollaryinthetargetedCRM.
Relationships
StaticListsarerelatedtoleadsthroughthelistmembershipobjectcontainingtheidofboththeleadandthelist.
Accessibility
TheRead-OnlyLeadspermissionisrequiredtoreadStaticLists.TheRead-OnlyLeadpermissionisrequiredtoreadmembership,andtheRead-WriteLeadpermissionisrequiredtoaddorremovelistmembership.
ListsmaybereadthroughGetListByIdandGetMultipleLists.
MembershipmaybereadthroughGetLeadsbyListIdandwrittenthroughAddLeadstoList,ImportLeadandRemoveLeadsfromList.
Synchronization
ConfigurationTomaintainthebestpossibleperformance,asetofconfigurationoptionsshouldbepresentedtoadministrativeusers.
SynchronizedFieldsNotallfieldsarenecessarytobemappedandsynchronizedbetweenMarketoandanassociatedCRMsystem.Adminusersshouldbepresentedwiththeoptiontoenableordisablesynchronizationofspecificfieldsforeachentitytypewherethisisappropriate(Leads,Companies,Opportunities,CustomObjects).Onlyspecialtyfieldsasdiscussedintheentitiessectionshouldbemandatoryforsynchronization,whileallothersshouldbeoptional.Reducingthenumberofsynchronizedfieldswillimprovesynchronizationperformanceinallcases.
SynchronizedCustomObjectsNotallCustomObjectsarenecessarytoincludeinanassociatedCRMsystem.AdminusersshouldbepresentedwiththeoptiontoenableordisablesynchronizationofCustomObjectsandbemadeawareofanymanualdataextensionwhichneedstooccurintheCRMpriortoenablementofsynchronization.Wherepossible,yourservershouldperformautomaticprovisioningofassociatedCustomObjectsintheCRMforobjectswherebootstrappingfromMarketotoCRMisbeingperformed.Inthecasethatthisisnotavailable,manualandflexiblemappingshouldbepermittedtoavailabletypesandfields.ForCRM-to-Marketosynchronization,thedefinitionshouldbederivedfromthetypeinCRM.
SynchronizedActivityTypesManyactivitytypesdonothaveanyrelevanceinaCRMsystemandshouldnotbesynchronizedever,whileothersmayormaynotbeneededonaclient-by-clientbasis.AdminusersshouldbeabletoselectwhichtypesareandarenotsynchronizedtolimitAPIcallusageandimprovesynchronizationperformance.
BootstrappingConfigurationAnadminuserorimplementeruponinitialconfigurationshouldbeabletoconfigurewhichsetoffieldsandrecordtypesneedtoberetrievedfromMarketo.Anoptionshouldalsobegiventotheseusersallowingthemtoconfiguretheearliestdatefromwhichtosynchronizeforeachparticularrecordtype.Initialsynchronizationtimecanbereduceddramaticallywhentheearliesttimeismorerecent.
SynchronizationIntervalMarketo’snativesynchronizationconnectorsqueueanewbatchofpushesandpullsfiveminutesafterthecompletionofthepreviousbatch.Thiscoversagreatdealofcasesandstrikesanacceptablecompromisebetweenrelativelylowsynchronizationlatency,andutilizationofAPIcalls.Foryoursolution,youshouldbasethesynchronizationintervalbasedonhowmanyAPIcallsatypicalsynchronizationcyclewilltake.ForaccountsprovisionedorrenewedafterMarch2016,thedefaultnumberofAPIcallsperdayis50,000withoptionaladditionalAPIcallspurchasedingroupsof10,000/day.
ThenumberofchangesthataclientexpectstooccurfortheirleadrecordsandtheirsynchronizedactivitieswillbethegreatestinfluenceonthecumulativenumberofAPIcallswhichwillbeusedinagivenday,andthisshouldinfluenceyourdesign.Yourbaselineforcontinuoussynchronizationwherenochangesareretrievedinanygivencycleshouldnotexceed7,500callsperday.
BootstrappingfromMarketoIfthereisexistingdatainaMarketosubscriptionwhichwillberequiredforfutureuseinthecorrespondingCRMsystem,thenthisdatashouldberetrievedfromMarketofortheprimaryobjectsLeads,Companies,Opportunities,Roles,andSalesPersons.
Thebootstrappercodeshouldbeseparatefromthecontinuoussynchronizationcode,assometimesbootstrappingwillnotbenecessaryatall.BootstrappingfromMarketoshouldonlybeperformediftheclientindicatesthatthereisexistingdataforagiventypeinMarketo.Whereverpossible,theretrievalshouldalsobefocusedtothesmallestpossiblesetofdatarequired.
LeadsThemosteffectivewaytobootstrapallleadrecordsisbyretrievingallNewLeadactivitiesfromthetargetinstance,andthenretrievingallofthecorrespondingleadsbyId.Thetypicalprocessisasfollows:
• CallGetPagingTokenwithasufficientlyearlytimestamp.Thisinformationshouldbeprovidedbytheclient.
• CallGetLeadActivitiesfortheNewLeadactivity,andpagethroughthesetofresults,storingthecorrespondingvaluesofleadIdintheactivity.
• CallGetLeadsbyFilterTypeusingidasthefilterType,with300ofthestoredIdsforeachcall.ThismaybedoneinparallelwiththeretrievaloftheNewLeadactivities.
• Theresultingleadrecordsmaythenbestoredasmapped.
CompaniesThenecessitytobootstrapcompanyrecordsfromMarketowillberareasofthiswritinginApril2016.
CompaniesshouldbebootstrappedonthebasisofthepresenceofexternalCompanyIdonbootstrappedleads.Thetypicalprocessisasfollows:CallGetCompanieswithfilterTypeofidField.filterValuesshouldbesetsofupto300valuestakenfromtheexternalCompanyIdfieldsoftheLeadsalreadyobtained.
OpportunitiesandRolesItshouldbenotedthatitisnotatallidealtobootstrapopportunitiesfromMarketo.Ifthereisanotheravailabledatasourcetoretrievethisdata,itislikelythesourcethatshouldbeused,asMarketodoesnotoriginateOpportunitydatafromwithintheapplication.
BootstrappingOpportunitiesandrolesshouldbedonebasedonthedatapresentintheAddtoOpportunityactivitytype.Thetypicalprocesstobootstrapopportunitiesandrolesisasfollows:
• CallGetPagingTokenwithasufficientlyearlytimestamp• CallGetLeadActivitiesfortheAddtoOpportunityActivityandpagethroughthesetofresults• IftheexternalCreatedDateandupdatedAtfieldsarenotrequired,theRolerecordsmaybe
inferred.
• ThelistofopportunitiesshouldberetrievedwithGetOpportunitiesbasedontheavailableOpptyIDintheactivityresults,usingidFieldasthefilterType.
• IfrequiredtherolerecordsshouldberetrievedwithGetOpportunityRoles,basedontheleadId,role,andOpptyIdfields,usingdedupeFieldsasthefilterType.
SalesPersonsThenecessitytobootstrapsalespersonrecordsfromMarketowillberareasofthiswritinginApril2016.
SalespersonsshouldbebootstrappedonthebasisofthepresenceofexternalSalesPersonIdonbootstrappedleads.Thetypicalprocessisasfollows:CallGetSalespersonswithfilterTypeofidField.filterValuesshouldbesetsofupto300valuestakenfromtheexternalSalesPersonIdfieldsoftheLeadsalreadyobtained.
CustomObjectsBootstrappingcustomobjectsfromMarketoshouldbecarefullyconsidered.MarketocurrentlydoesnotexposetheabilitytopullincrementalupdatesfromMarketocustomobjectrecords,sotheoptionmaypresentlimitedusefulness.
ThemethodofbootstrappingfromMarketowilldependonthedefinitionoftheobject.For1:Nrelationshipswithleadsoraccounts,therewillonlybeoneobjecttypetoretrieve.ForN:Nrelationshipstherewillbetwotypes.RefertotheEntitiessectionformorespecificinformationonCustomObjectdefinitions.
Thetypicalprocessforretrievingcustomobjectsisasfollows:
• Retrievetheactivitytypeforthecustomobject.Itwillfollowthenamingpattern“Addto{CustomObjectName}”
• CallGetPagingTokenwithasufficientlyearlytimestamp• CallGetLeadActivitiesfortheAddtoCustomObjectactivitytyperetrievedearlier• CallGetCustomObjectsbasedonthekeysretrievedfromtheactivities.Thiswillneedtobe
cross-referencedtothecorrespondingDescribeCustomObjectresult.
ProgramsandMembershipNote:Ifimplemented,itisrecommendedthatmembershipforprogramsonlybesynchronizedonanon-demandbasis.
ToretrieveallprogramsfromMarketo,theclientsimplyneedstocallBrowseProgramsandpagethroughtheresultsbyincrementingtheoffsetparameter.
ToretrieveallmembershipfromMarketo,theclientneedstocallGetLeadsbyProgramIdforeachsynchronizedprogramandpagethrougheachresultset,retrievingtheinformationinthechildmembershipobject
ActivitiesActivitiesmayonlyberetrievedforuptotenactivitytypesatatime,soitisbesttomaintainseparatesynchronizationqueuesforeachsetofuptotentypeswhichhavebeenindicatedforsynchronization.Thetypicalprocessisthis:
• CallGetPagingTokenwiththeearliestdesiredtime
• CallGetLeadActivitieswithasetofuptotenactivityTypeIdsandpagethroughtheresultsetuntilmoreResultisfalse
• Initiatethepreviousstepforthenextsetoftenactivitytypesifnecessary
ListsandMembershipToretrieveallListsfromMarketo,theclientneedstocallGetMultipleListsandpagethroughtheresultsetuntiltheend.
Toretrievealllistmembership,theclientneedstocallGetMultipleListsbyListIdforeachsynchronizedlist,andpagethroughtheresultset.
RecommendedBootstrappingOrder1. NewLeadActivitiessinceinstancecreation2. LeadRecordsbyleadIdforNewLeadActivities3. CompanyrecordsbyexternalCompanyIdfromLeads4. AddtoOpportunityactivities5. OpportunitiesbyOpportunityIDfromactivities6. OpportunityRolesbyleadId,externalOpportunityID,androlefromactivities7. SalesPersonsbyexternalSalesPersonIdfromLeads8. Otherrecordtypesasrequired
MaintainingSynchronizationThesimplestandmostconsistentwaytomaintaincontinuoussynchronizationistoimplementapollerwhichretrieveschangestorecordsinMarketoandpushesthemtoCRMandthenfromCRMandpushesthemtoMarketo,andthenrepeatsthecycleafterapredeterminedperiodeachtime.
ToretrievechangesfromMarketo,twohighwatermarksmustbemaintained,thefirstforchangestolead/companyfieldswhichhaveoccurredsincethemostrecentlyretrievedchange,andforthesynchronizationcase,andthesecondfortheactivitieswhichhaveoccurredsincethemostrecentlyretrievedleadactivity.Thesearedatetimevalues.Whenretrievingchangesoractivitiesinasubsequentsynchronizationcycle,theexactdatetimeofthemostrecentlycreatedrecordshouldbeused.SinceMarketomaintainsonlyper-secondandnotper-millisecondresolutionfordatetimes,itispossiblethatactivitiesmayoccurwiththesamedatetimeasthehigh-watermark.Thiswillresultinretrievalofduplicateactivitieswhichmaybesafelyignoredbasedontheidoftheactivity.
RecommendedSynchronizationOrder1. CreateandUpdateCompanies2. GetCompanies3. CreateandUpdateSalespersons4. CreateandUpdateLeads5. GetLeads6. GetLeadMergesandDeletions7. GetLeadActivities8. DeleteLeads9. CreateandUpdateOpportunities
10. CreateandUpdateRoles11. DeleteRoles12. DeleteOpportunities13. DeleteCompanies14. DeleteSalespersons15. CreateandUpdateCustomObjects
LeadsandCompaniesSynchronizationforLeadsandCompaniesismaintainedprimarilyusingtheGetLeadChangesendpointwhichretrievesdatavaluechangerecordswhichoccurafteratimestampgivenbyapagingtokenwhichisretrievedviatheGetPagingtokenendpoint.ThisendpointwillreturnbothNewLeadactivities,whichindicatesthecreationofanewknownleadinMarketo,anddatavaluechangeactivitiesforasetoffieldsgivenintheparametersofthecall.
ThechangeactivitiesshouldbeappliedintheorderofthecreatedDate,fromearliesttolatest,givenintheactivitytotherecordsinCRMwhichcorrespondtotherecordgivenbyleadIdintheactivity.NewLeadactivitiesshouldbeaddedtoaqueueofnewleadrecordswhichneedtoberetrievedbyid,“leadId”intheactivity,usingtheGetLeadsbyFilterTypeendpoint,withidasthefilterType.Thesemayberetrievedupto300atatime.Itisrecommendedtowaituntilthereare300recordstoretrieve,andthentomakethecalltoretrievetheserecords,insteadofcallingwheneverthesebecomeavailable.If,uponreachingtheendofthesetofchanges,therearelessthan300records,thenthesetshouldberetrieved.
Inadditiontochangesandnewleads,inordertomaintainsynchronizationtheMergeLeadandDeleteLeadactivitymustberetrievedinorderaccountforleadrecordswhicharemergedtogether.Themergeactivityindicatesthattworecordshavebeenmergedintoasinglerecord.TheCRMmayormaynotchoosetohonorthemerge/delete,deletethelosingrecordandretrievethechangesfromthewinninglead,oritmaybeignoredandhavea“DeletedinMarketo”flagsettoindicatethattheMarketoLeadIDforthatrecordisnolongervalid.
Forimplementationdetailsonretrievingactivities,seetheactivitiessection.
Aspartofastandardsynchronizationcycle,changesfromtheCRMshouldalsoberetrieved.Ideallyonlyfieldswhichhavebeenupdatedsincethemostrecentsynccycleshouldberetrieved,butthismaynotbepossiblegiventheconstraintsofthesystem.Ifthisisavailable,allthechangesforagivenrecordshouldbeaggregatedintoaleadrecordtobesubmittedtoMarketo.Ifachanges-onlyoptionisnotavailable,thenitisviabletoretrievethewholerecordwithalloftheMarketo-mappedfieldsforsubmissiontoMarketo.
Topushchangesforleadrecords,therearetwooptions,thebulkImportLeadAPIandtheCreate/UpdateLeadsendpoint.ImportLeadallowsaspreadsheetofleadsasrowstobesubmittedintoMarketoforcreationorupdate,whichmaybeupto10MBinsize.Create/Updateleadallowsfortheinputofupto300leadrecordsasJSON.Thereareadvantagestoeitherone.ImportLeadisasynchronousandhasahighertotalthroughput,butrequiresanindividualpollingimplementationtocheckonthestatusoftheimport,anditsharesaqueuewithMarketolistimports,soitispossibleforthecalltoremainenqueuedforasignificantperiodoftime,resultinginagreatdealoflatency.
Create/UpdateLeadoffersmuchfasterfeedback,butwillconsumesignificantlygreaternumbersofAPIcallstoimportlargenumbersofleadsperbatchasitmayonlysubmitupto300recordspercall.
Ineithercase,forincrementalsyncingofupdatesfromCRM,thelookupFieldshouldbespecifiedastheprimarykeyselectedfromtheCRMsystem,andthecreateOrUpdatemodeshouldbeusedwhenusingCreate/Updatelead.ThisallowssharingofthesamequeuebynetnewleadsandleadupdateswhichneedtobepushedintoMarketo.
InthecasethataMarketoLeadislinkedtoacompanyrecordviaexternalCompanyId,commonlyconceptualizedasacontact,thecompanytypefieldsthatwerepartoftheleadrecordarenolongerwriteablethroughtheleadrecordandaredeferredtothelinkedcompanyrecord
CompaniesItisimportanttodeterminewhichfieldsareCompany-typefields,andwhichfieldsareLead-typefields.ThiscanbedonewiththeDescribeCompanyendpoint.AllfieldslistedthereareCompany-typefields,ofwhichmostaremirroredasleadfieldsforunlinkedleads.IfaCompany-typefieldisreflectedinaChangeDataValueoperation,thenthechangeshouldbereflectedagainstthecompanyrecordinCRMifthechangewasmadeagainstaleadwhichislinkedtoacompanyrecordviaexternalCompanyId.Ifnot,thechangeshouldjustbereflectedagainsttheleadrecord.
SalesPersonsNote:Inasingle-CRMcaseSalesPersonrecordsshouldbemanagedbytheCRMitself,sotheserecordsshouldnotbepulledfromMarketoafterthebootstrappingprocess.
SalesPersonrecordsshouldbecreatedordeletedinMarketowheneveracorrespondingeventoccursintheCRMsystem.Thischeckshouldbeperformedbytheintegrationsoftwareuponeverysynccycletoseeifchangesarerequired.Intheeventthatasalespersonrecordrequiresdeletion,allleadswhichhavethatsalesperson’sexternalSalesPersonIdmusthavethatvaluechangedtoanewvalue,orhavethevaluesettonullbeforetherecordcanbedeleted.
SynchronizationofleadownershipshouldbeperformedaspartofleadsynchronizationviatheexternalSalesPersonIdfield.
OpportunitiesandRolesNote:Inasingle-CRMcaseitisexceedinglyrareforOpportunitiesandRolestobecreatedbynon-CRMsources.ItisunlikelytobearequirementtopullthesetypesofrecordsfromMarketo.
OpportunityandrolesrecordsshouldbecreatedordeletedwheneveracorrespondingeventoccursintheCRMsystem.Thisshouldbeperformedaspartofaroutinesynccycle.Ifanopportunityrequiresdeletion,allofitschildrolerecordsmustbedeletedpriortoitsdeletion.Theorderofoperationsforopportunitiesshouldbeassuch:
1. CreateandUpdateOpportunities2. CreateandUpdateOpportunityroles3. DeleteOpportunityRoles4. DeleteOpportunities
ActivitiesLeadactivitiesareread-onlyaftercreation,andsodonotrequireatwo-wayimplementation.TheyarereadfromMarketoviatheGetLeadActivitiesendpoint,ingroupsofupto10activitytypes.TheendpointacceptsanearliestcreationdateviaapagingtokenwhichisretrievedviatheGetPagingTokenendpoint.ThesetofresultsshouldbepagedthroughuntilthemoreResultparameterintheresponseisreturnedasfalse,andthecorrespondingactivitieswrittentoCRM.Themostrecentdatetimefromtheactivitiesretrievedshouldbestoredasthehighwatermarktobeginthenextsynccyclewith.
Activitiesareusedtoretrieveincrementaldataregardingcustomobjects.
CustomObjectsToperformMarketotoCRMsynchronizationofcustomobjects,the“Addto{CustomObjectName}”activitymustberetrieved,andthecorrespondingrecordsretrievedwiththeGetCustomObjectsendpoint.CustomObjectsmayhavedifferentrelationshiptypeswhichneedtobemodeled.Formoreinformation,pleaseseetheCustomObjectsectioninEntities.
Creation,updates,anddeletionofCustomObjectsshouldbehandledexactlyasopportunitiesorsalespersonsare.
Program-OpportunityAttributionMarketo’smostimportantattributionmodelisbasedontherelationshipbetweenLeads,ProgramsandOpportunities,whereprogramsrepresentsomelevelofunifiedmarketingeffort,andopportunitiesrepresentsalesdeals.Theserelationshipsareinferred,andtheamountofmoneyearnedintheclosureofanopportunityisattributedtotheassociatedmarketingeffort,oneormoreprograms,throughtheassociatedleads’programmembershiprecord.Marketohastwoformsofattribution,First-Touch(FT),andMulti-Touch(MT),whichhaverelatedbutdistinctmethodsofcalculation.Careshouldbetakentoensurethattherelevantfieldsforopportunitiesandleadsaremappedcorrectlytoprovideforproperrevenueattributionofopportunities.
First-TouchAttribution(FT)FirstTouchattributionidentifiestheprogramsthataremosteffectiveatacquiringtherightleads(i.e.newleadsthateventuallyconverttosalesopportunities,pipeline,wonopportunitiesorrevenue).Itdoesbyassigningfullmarketingcreditforthedeal/revenuetotheprogramthatfirstbroughttheleadintothedatabase.ThisisdonebydesignatingAcquisitionProgramandacquisitiondateforaleadrecordandafewotherrequirements:
• TheleadmusthaveanAcquisitionProgram• Thelead'sacquisitiondatemustoccurbeforetheCreatedDateoftheOpportunity• TheleadmustreachProgramSuccessintheProgram
Meetingtheseprerequisiteswillgivefirst-touchattributiontotheprogramforOpportunitiesassociatedtothelead.TheserequirementsaloneshouldpopulatetheCostofOpportunity(basedonProgramCost),PipelineCreated,PipelineCreated(StillOpen),andRevenueExpectedmeasureinaProgramOpportunityAnalysisreport.
TopopulatetheRevenueWonandRevenuetoInvestmentmetrics,theOpportunitymustbeinStage“ClosedWon.”
Multi-Touch(MT)Multi-TouchAttributionisusedtoindicatetheusefulnessofaprograminmovingknownleadstowardapurchase(i.e.closed-wonopportunities)byspreadingcreditfortherevenueacrossalltheprogramsthatsuccessfullytouchedtheleadsonclosed-wonopportunities.WhereasFTattributionisusedtooptimizetheleadsyou’rebringingintoyourdatabase,MTattributionisusedtooptimizethemovementofthoseleadsthroughthemarketingfunnel.
AnopportunitywillhaveitsPipelineandOpportunitiesCreatedmeasuresattributedviaMTtoaprogramwhenaleadreachessuccessinthatprogrampriortotheCreateddateoftheopportunity.Thisisusedtodeterminetheefficacyofaprogramforgeneratingpotentialdealsfromexistingleads.
AnopportunitywillhaveitsRevenueWon,OpportunitiesWon,andRevenuetoInvestmentattributedtoaprogramviaMTwhenaleadreachessuccessinaprogrambetweentheCreatedDateandtheCloseDateofanOpportunity.Thisisusedtodeterminetheefficacyofaprograminclosingdeals.