Salesforce.com
This guide describes how to connect Salesforce (SFDC) with Koddi Ads using Koddi's metadata feature to map records between the two platforms.
The primary workflows are:
- An Account created in Salesforce creates a corresponding Advertiser in Koddi.
- An Opportunity reaching the agreed conversion milestone in SFDC creates the associated Media Plan, Campaigns, and IOs in Koddi.
- Delivery and performance data can flow from Koddi back to Salesforce through APIs or an agreed data lake integration.
Salesforce manages customer relationships and commercial commitments. Koddi manages media planning, campaign execution, and delivery. The integration connects these workflows through persistent record identifiers.
Object Relationships and Mapping
Koddi’s execution hierarchy is Advertiser → Media Plan → Campaign → Ad Group. IOs are associated separately with campaigns, and one IO can cover multiple campaigns.
Media plans organize campaigns around budgets, flight dates, and goals. Campaigns contain ad groups, which hold execution settings such as targeting, bids, and advertised entities.
The recommended Salesforce mapping is:
| Salesforce record | Koddi record | Mapping approach |
|---|---|---|
| Account | Advertiser | Store the Salesforce Account ID in advertiser metadata |
| Opportunity | Media Plan | Store the Salesforce Opportunity ID in media plan metadata |
| Opportunity Product, Order Product, or custom media line | Campaign | Store the corresponding Salesforce line ID in campaign metadata |
| Order or custom IO record | IO | Store the corresponding Salesforce record ID in IO metadata |
Your Salesforce configuration determines the final object mapping. For example, without Salesforce Orders, you may use an Opportunity or custom object as the commercial reference for an IO.
One Opportunity may produce multiple campaigns or IOs. Each resulting Koddi record should carry enough metadata to identify its Salesforce source.
Suggested Metadata Conventions
Use explicit metadata keys in Koddi to distinguish Salesforce object types.
| Proposed metadata key | Purpose |
|---|---|
salesforce_account_id | Identifies the Salesforce Account |
salesforce_opportunity_id | Identifies the originating Opportunity |
salesforce_opportunity_line_item_id | Identifies an Opportunity Product, when used |
salesforce_order_id | Identifies the Salesforce Order, when used |
salesforce_order_item_id | Identifies an Order Product, when used |
salesforce_io_id | Identifies a custom Salesforce IO record, when used |
These keys are integration conventions. Agree on their names and placement before development, and preserve existing conventions where already established.
Store Salesforce IDs as strings using their 18-character format. Scope mappings to the correct Salesforce organization, Koddi customer environment, and object type.
Metadata identifies the corresponding Salesforce records. Native Koddi IDs and relationships continue to connect advertisers, media plans, campaigns, ad groups, and IOs.
Account Creation Workflow
When an eligible Account is created in Salesforce, the integration creates its corresponding Advertiser in Koddi.
- Read the Salesforce Account and validate the required advertiser information.
- Check whether a Koddi advertiser is already mapped to that Account.
- If a mapping exists, update the existing advertiser as appropriate.
- If no mapping exists, create the advertiser using the agreed account fields.
- Store the Salesforce Account ID in advertiser metadata.
- Record the resulting Koddi advertiser ID and synchronization outcome.
The field mapping should identify the source for advertiser name, currency, time zone, required contact details, and any customer-specific configuration.
An Account name change should update the existing advertiser where appropriate. It should retain the same ID mapping.
The default relationship can be one Account to one Advertiser. If the customer needs separate advertisers for brands, regions, or business units, define an additional identifier to distinguish those advertisers.
Opportunity Conversion Workflow
For this integration, “converted” means the Opportunity has reached the agreed commercial milestone, typically Closed Won or a specific approved or booked status.
When that milestone is reached, the integration validates the Opportunity and creates or updates the required Koddi objects.
| Step | Integration action |
|---|---|
| Resolve advertiser | Find the advertiser mapped to the Opportunity’s Account |
| Create media plan | Translate the approved plan into the required budget, flight dates, goals, and experience configuration |
| Create campaigns | Translate the commercial lines into the required campaign executions |
| Create IOs | Create the commercial authorizations using the agreed Salesforce source records |
| Associate records | Connect campaigns to their media plan and applicable IOs |
| Save references | Write Salesforce IDs into Koddi metadata and record the resulting Koddi IDs |
A Salesforce Opportunity Product does not always need to produce exactly one campaign. For example, one commercial line may require multiple campaigns for different experiences or flight periods. Each campaign should retain the same source line reference and a distinct execution identifier.
Koddi’s media plan submission workflow can create child campaigns and ad groups. If that workflow is used, the integration should capture those generated records rather than creating a second set independently.
Creating the records and activating media should follow the agreed operational workflow. Opportunity conversion should trigger activation only when all required approvals and execution requirements have been satisfied.
Ad Group Handling
Ad groups generally do not require a Salesforce mapping.
They can be created through Koddi’s planning workflows, templates, APIs, or media operations processes. Targeting, bids, entities, and associated assets remain managed at this level within Koddi.
Reporting can roll ad group delivery into its parent campaign, then use campaign metadata to identify the appropriate Salesforce record. This supports commercial reporting without requiring Salesforce to mirror every execution detail.
IO Associations
IOs should be treated as commercial records associated with campaigns. One IO may cover several campaigns within the customer’s agreed structure.
For example, an Opportunity may produce a Holiday Media Plan containing a Sponsored Products campaign and a Display campaign. Both campaigns may be associated with the same Holiday IO.
The IO metadata identifies the Salesforce commercial record. The campaign associations identify which media delivery belongs to that IO.
The integration should validate that each campaign is associated with the intended IO and that commercial amounts reconcile with the approved allocation. An IO amount should not be copied as the full budget of every associated campaign.
Reporting from Koddi to Salesforce
Reporting writeback is optional and can be configured around the customer’s sales, account management, and reconciliation needs.
A typical reporting process is to retrieve delivery data, resolve the Salesforce references from Koddi metadata, aggregate to the required commercial level, and update the corresponding Salesforce fields or related reporting records.
Possible outputs include delivered spend, impressions, clicks, performance against booked budget, and the latest reporting timestamp. Attributed outcomes can be included where configured.
Keep delivered spend separate from booked Opportunity or Order value. Use stable reporting keys so refreshed data updates existing rows. Agree on currency, time zone, reporting latency, and the period over which historical results may be restated.
Campaign totals and their underlying ad group totals represent overlapping delivery. Select one reporting grain for each dataset to prevent double counting.
See our reporting API and secure data collaboration pages for more details.
Updates and Operational Handling
Define ownership for each synchronized field.
| Information | Recommended owner |
|---|---|
| Account identity and commercial records | Salesforce |
| Approved commercial budget and flight | Salesforce, with agreed translation into Koddi |
| Execution settings, bids, targeting, and optimization | Koddi |
| Delivery and performance metrics | Koddi |
| Synchronization status and errors | Integration service |
After conversion, approved commercial changes should update the mapped records. The integration should validate their effect on active media before applying them.
Preserve unrelated metadata during updates. Repeated events and retries should resolve the existing mapping before attempting another create. If a request times out, determine whether creation succeeded before resending it.
Track partial completion so a failed IO association or Salesforce writeback can resume without recreating the advertiser, media plan, or campaigns.
Cancellations, deletions, and Account merges should follow explicit rules that preserve delivery history and mapping records.
Implementation and Validation
Before development, agree on the Salesforce objects, conversion trigger, field mappings, metadata keys, campaign allocation rules, IO associations, reporting requirements, and synchronization schedule. Your Koddi team can help you.
Validate the integration in a test environment using these acceptance checks:
- Account creation produces the intended advertiser with the correct metadata.
- Opportunity conversion creates the expected media plan, campaigns, and IOs.
- Campaigns retain the correct media plan and IO associations.
- Ad groups are created and managed without requiring Salesforce records.
- Repeated events and interrupted runs create no duplicates.
- Approved changes update the existing mapped records.
- Reporting resolves to the correct Salesforce records and reconciles with Koddi.
- Missing mappings and failed operations produce visible, actionable exceptions.
FAQ
How does the Salesforce integration work?
The integration connects Salesforce commercial records to Koddi Ads through APIs and metadata. Typically, a Salesforce Account creates a Koddi Advertiser, and an approved or converted Opportunity creates the associated Media Plan, Campaigns, and IOs. Reporting can flow back to Salesforce as needed.
Does adding Salesforce IDs to metadata automatically synchronize the platforms?
Metadata provides the relationship between records. An integration service must read changes, call the appropriate APIs, and manage synchronization. This service can run in your existing middleware or another agreed integration environment.
Which Salesforce records map to Koddi objects?
The typical mapping is Account to Advertiser, Opportunity to Media Plan, and Opportunity Products or Order Products to Campaigns. Orders or custom IO records map to Koddi IOs. The final mapping depends on your Salesforce configuration and commercial workflow.
What triggers the creation of a Media Plan, Campaigns, and IOs?
Your implementation defines the trigger, typically when an Opportunity reaches Closed Won or another approved booking status. The integration validates the required account, budget, flight, and commercial information before creating the corresponding Koddi records.
How should Salesforce IDs be stored in Koddi metadata?
Use consistent, explicit keys such as salesforce_account_id, salesforce_opportunity_id, and salesforce_order_item_id. Store IDs as strings using Salesforce's 18-character format. Agree on the keys for each Koddi object before implementation, and preserve unrelated metadata during updates.
Can we link existing Koddi records to Salesforce?
Yes. Start with a mapping exercise to identify the corresponding Salesforce and Koddi records, then populate the agreed metadata fields. Review ambiguous matches before saving them. Use persistent IDs for ongoing synchronization rather than relying on record names.
Can one Salesforce Opportunity create multiple Koddi Campaigns?
Yes. One Opportunity can produce a Media Plan containing multiple Campaigns. A single commercial line may also require multiple Campaigns for different experiences or flight periods. Each Campaign should retain its Salesforce source reference and a distinct execution identifier.
Can one IO be associated with multiple Campaigns?
Yes. An IO can be associated with multiple Campaigns. Store the Salesforce commercial reference in IO metadata and maintain the applicable campaign associations in Koddi. Allocate campaign budgets according to the approved plan rather than copying the full IO amount into every Campaign.
Do we need to create or map Ad Groups in Salesforce?
Generally, no. Ad Groups remain part of Koddi's execution workflow and can be managed through planning workflows, templates, APIs, or media operations. Their delivery can roll up to the parent Campaign, which provides the Salesforce mapping.
Does converting an Opportunity automatically launch advertising?
Only if your integration is explicitly configured to do so. Record creation and media activation should follow the agreed approval workflow. Campaigns must satisfy the applicable creative, targeting, funding, and operational requirements before delivery begins.
How are changes to budgets, dates, or commercial records handled?
Define which system owns each field and which changes are eligible for synchronization. Approved Salesforce changes should update the existing mapped Koddi records. Changes affecting active media should follow the agreed validation and approval process.
How does the integration prevent duplicate records?
Before creating a record, the integration should resolve any existing mapping using the Salesforce ID and the intended execution identifier. Retried events should resume or update the existing records. If a create request times out, check whether it succeeded before submitting another create request.
Can Koddi reporting data flow back into Salesforce?
Yes. The integration can retrieve reporting through Koddi APIs or use an agreed data lake integration to prepare Salesforce updates. Typical outputs include delivered spend, impressions, clicks, and performance against booked budget. Available metrics, reporting detail, and refresh frequency are agreed during implementation.
How do we reconcile reporting and handle missing mappings?
Join delivery data to the Salesforce references stored in Koddi metadata, then aggregate it to the required Campaign, Media Plan, IO, or Account level. Use consistent dates, currencies, and metric definitions, and keep booked value separate from delivered spend.
Flag missing or conflicting mappings for review. Refresh existing reporting rows when results change, and avoid adding campaign totals to their underlying ad group totals, which would double count delivery.
Updated about 1 hour ago