Versions Compared

Version Old Version 26 New Version Current
Changes made by

Nicole Jünger

Nicole Jünger

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note

In order to use the Forecast API, your Salesforce Org needs to have API usage activated through having an API usage License. 

We also recommend you to automate the OAuth access to avoid authorization issues: 1.6 How to authenticate / authorize ADvendio Gateway for the use of our Third Party System integrations? - Authorize ADvendio message / OAuth#Setup:


Numberedheadings
start-numbering-with1

The Forecast API function is implemented as Apex class and is exposed as REST web service by using Salesforce standard functionality (see Apex Developer Guide for more information). For general information about the Forecast API feature, see

REST web service

URL

https://<my-domain-name>.my.salesforce.com/services/apexrest/ADvendio/ADvendio__Campaign_Item__c/CheckAvailability/

https://<my-domain-name>.my.salesforce.com/services/apexrest/ADvendio/ADvendio__Campaign_Item__c/JobUpdates/


Method

PATCH

URL Params

-

Data Params

A JSON object with the attribute campaignItems, containing a JSON serialized list of Campaign Items.

Example: { "campaignItems":[{<Campaign Item>}, ...]}

See for detailed information about the internal data structure of the Campaign Item.

Success Response

Code: 200

Content: A JSON serialized list of the Campaign Items from the request body, but now with updated availability and status fields.

Example: [{<Campaign Item>}, ...]

Error Response

See Salesforce Apex REST Documentation

Logic

The CheckAvailability web service function returns the availabilities for all Campaign Items not connected to an Ad Server and starts the availability check for the Campaign Items that are connected to an Ad Server. If an availability check job was started the job information will be saved to the field ADvendio__MostRecentGatewayJobInformation__c. The returned Campaign Item can now be used to get the job results by using the JobUpdates function.


The following fields are updated by the CheckAvailability or JobUpdates function.

Campaign Item FieldData formatNote
ADvendio__AvailabilityRunning__cNumber

Campaign Item start time < NOW()

AND

Already submitted to the Ad Server

ADvendio__ReservedImpressionsRunning__cNumber
ADvendio__MatchedImpressionsRunning__cNumber
ADvendio__Availability__cNumber

Campaign Item start time > NOW()

OR

Not yet submitted to the Ad Server

ADvendio__ReservedImpressionsPlanned__cNumber
ADvendio__MatchedImpressionsPlanned__cNumber
ADvendio__Share_of_Voice__cPercent100 * Matched / BookingQuantity
ADvendio__LastAvailabilityForecast__cDate/TimeNOW()
ADvendio__MostRecentGatewayJobInformation__c

JSON String:

{"jobId":123456,
  "campaignItemId":"a0Y000000000001EAA"
  "status":{
    "progress":1,
    "message":"Finish Job",
    "status":2,
    "start":"2019-09-02T07:34:37.000+0000",
    "operation":"Forecast",
    "orgId":"00D1x0000008bZ9EAI"
}}

If an Ad Server is connected the availability will be asynchonously checked by the Ad Server Gateway.

This field is used to store information about the asynchronous job.

campaignItemId: If there is no Campaign Item id, we need an identifier to map back the results, so a fake id is automatically generated.

progress: A value between 0 and 1 to show the progress of the job. Starts with 0 and is finished when it reatches 1.

message: Message about the job status

status: Queued = 0, In progress = 1, completed = 2, failed = 3

start: The the time stamp when the job was started.

operation: For Check Availability always "Forecast".

orgId: The Salesforce org id.

ADvendio__SelectedContent__r.ADvendio__Availability__c

JSON:

{ "version":1,
  "availabilityPerTime": {
    "2020-01-01":123,
    "2020-02-01":565
  }
}

If there is Content linked to the Campaign Item at it is no AdServer connected, the availability will be checked per content per time frame. Time frames are days for CPD, weeks for CPW, months for CPMo, years for CPY and the Campaign Item run time for Fixed Price billing category.

version: A version number for the JSON format in case we need to change it.

availabilityPerTime: Map of the first date of a time frame to the availability number for that time frame.

Examples

Get a Session-ID

bashGet a Session ID


Connected App

Get CLIENT_ID and CLIENT_SECRET from any connected app or create a new app in your org: App Manager -> New Connected App

Enable Enable OAuth Settings to see the consumer key (CLIENT_ID) and Consumer Secret (CLIENT_SECRET)


Minimal request

A simple request for a Campaign Item connected to an Ad Server (Google Ad Manager, other Ad Server may need additional information).

bashCall Check Availability web service

For CheckAvailability the following fields are required per Campaign Item: ADvendio__from_Date__c, ADvendio__until_Date__c, ADvendio__Ad_Price__c

jsrequestBody.txt


jsResponse


Second call to get the job results some time later:

bashCall Job Updates web service

For the JobUpdates request the field ADvendio__MostRecentGatewayJobInformation__c is required. This contains the jobId and dummy campaignItemId to map the results back to each Campaign Item.

jsrequestBody1.txt


jsResponse




Request with some targeting

A request for a Campaign Item connected to an Ad Server including some targeting information. To simplify this, we're using Targeting Sets, which contain all Targeting Criteria. You will need to create those in advance in Salesforce. See  for more information on that.

bashCall Check Availability web service


jsrequestBody.txt


jsResponse


Second call to get the job results some time later:

bashCall Job Updates web service


jsrequestBody1.txt


jsResponse



Request for non adserver Campaign Items with Content

A request for a Campaign Item not connected to an Ad Server with selected Content. This will start the Exclusivity Check process inside of ADvendio instead of the Check Availability against the AdServer Gateway.

bashCall Check Availability web service


jsrequestBody.txt


jsResponse

Request for non adserver Campaign Items with Content (Inventory Forecast)

A request for a Campaign Item not connected to an Ad Server with selected Content. This will start the Exclusivity Check process inside of ADvendio instead of the Check Availability against the AdServer Gateway.

jsrequestBody.txt


responseBody

Usage in Apex

java


...