Versions Compared

Old Version 10

changes.mady.by.user Pascal Clausen

Saved on

compared with

New Version Current

changes.mady.by.user Nicole Jünger

Saved on

Key

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

...

Note

In order to use the Submit to Ad Server 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:

Note

Attention Breaking Changes:

With version 2.142 we introduced breaking changes in the way the requests to the submit API are structured.

We are doing these changes to allow the feature to work in a more flexible way. In the past it was required to send a single request for each separate Media Campaign of which you want to submit Campaign Items, now this can be combined. Also these changes allow our product additional features like a scheduled automatic submit of Campaign Items to an AdServer.

Please see the section “Minimal request - For versions 2.142 and up” in this article below, for more details and the required actions to take.

...

Numberedheadings
start-numbering-with1

REST web service

URL

https://<my-domain-name>.my.salesforce.com/services/apexrest/ADvendio/ADvendio__Campaign_Item__c/SubmitToAdServer/
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>}, ...]}

The Submit to AdServer web service requires an existing Campaign Item in the database, so the Id field is required. All other fields are ignored right now and should not be set. The AdServerGateway will query all information from the Salesforce database.

Success Response

Code: 200

Content: A JSON serialized list of the Campaign Items from the request body, with the ADvendio__MostRecentGatewayJobInformation__c field updated.

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

Error Response

See Salesforce Apex REST Documentation

Logic

The Submit to AdServer webservice starts the job to submit Campaign Items to the Ad Servers. When the 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 Submit to AdServer or JobUpdates function.

Campaign Item Field

Data format

Note

ADvendio__AdServerProposalId__c

Text

Populated if the Media Campaign type is Proposal

ADvendio__AdServerProposalLineItemId__c

Text

ADvendio__Adserver_ID_Order_ID__c

Text

Populated if the Media Campaign type is Order

ADvendio__Ad_Id__c

Text

ADvendio__Additional_Ad_Ids__c

Text

ADvendio__Submit_to_AdServer__c

Boolean

Set to false if the booking was successful

ADvendio__StatusSubmittedToAdServer__c

Text

The status of the booking process: "Created", "Updated" or "Error"

ADvendio__StatusMessageSubmittedToAdServer__c

Text

Error or warning messages

ADvendio__LastBookingProcess__c

Date/Time

NOW()

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":"Booking",
    "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 "Booking".

orgId: The Salesforce org id.

Examples

Get a Session-ID

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 - For versions 2.141 and older

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

For the Submit to AdServer function a real Campaign Item is required, so the record id is the only required field for each Campaign Item

The following response is received:


Second call to get the job results some time later:

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.

The following response is received:

Minimal request - For versions 2.142 and up

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

With release 2.142 we enhanced our API capabilities, so that it’s possible to submit multiple Campaign Items from many different Media Campaigns in a single request. This enhancement however requires also to provide the connected Media Campaign.

The following response is received:

When using multiple Campaign Items, the request looks like this:

The following response is received:

If the request does not contain a valid Media Campaign ID, the following error message will be returned by the process:

"{\"status\":{\"progress\":null,\"message\":\"No Campaign Id has been set for Booking operation\",\"status\":3,\"end\":\"2021-06-03T11:20:33.000+0000\",\"start\":\"2021-06-03T11:20:33.000+0000\",\"operation\":\"Booking\",\"orgId\":\"00DA0000000clAiMAI\",\"jobId\":8113},\"campaignItemId\":\"a0Y2K00000FPriyUAD\",\"jobId\":8113}"

How to check the status of the submit request:

To see whether the request was successful or not, it’s required to send a JobUpdates request, after some time has passed. First authenticate again:

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.

Usage in Apex


...