How to connect to ADvendio - Using SOAP service to login into ADvendio, Using REST service to query data

Sometime you need to connect third-party systems with ADvendio to access Salesforce Data. Here you can find the basic as an example that is used by Dataplan's Journal Designer.

Example:

Booking Data by Publication Dates

Login into ADvendio, Get the Session-ID

To login into ADvendio thus to get a session-ID, you can send a XML per POST-Method to the ADvendio using e.g. curl like follows:

curl --header "Content-Type: text/xml; charset=UTF-8" --header "SOAPAction: login" -d XML_DATA https://login.salesforce.com/services/Soap/u/42"

The XML data to send looks like follows:

<?xml version="1.0" encoding="utf-8" ?>
<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <n1:login xmlns:n1="urn:partner.soap.sforce.com">
      <n1:username>YOUR_USERNAME</n1:username>
      <n1:password>YOUR_PASSWORD_AND_TOKEN_TOGETHER</n1:password>
    </n1:login>
  </env:Body>
</env:Envelope>

The result should be the following:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:partner.soap.sforce.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <loginResponse>
      <result>
        ...
        <serverUrl>https://na7.salesforce.com/services/Soap/u/42.0/00DA0000000ck3y</serverUrl>
        <sessionId>SESSION_ID</sessionId>
        ...
      </result>
    </loginResponse>
  </soapenv:Body>
</soapenv:Envelope>

In the result, there is serverUrl and sessionId you should use for subsequent calls to ADvendio.

Logout from ADvendio, Release the Session-ID

Assume the serverUrl you got from the login result is https://na7.salesforce.com/services/Soap/u/28.0/00DA0000000ck3y, to logout from ADvendio thus to release a session-ID, you can send a XML per POST-Method to the ADvendio using e.g. curl like follows:

curl --header "Content-Type: text/xml; charset=UTF-8" --header 'Authorization: Bearer SESSION_ID'-d https://na7.salesforce.com/services/Soap/u/42.0/

The XML data to send looks like follows:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Header>
        <ns1:SessionHeader soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="urn:enterprise.soap.sforce.com">
            <ns1:sessionId>SESSION_ID</ns1:sessionId>
        </ns1:SessionHeader>
    </soapenv:Header>
    <soapenv:Body>
        <invalidateSessions xmlns="urn:enterprise.soap.sforce.com">
            <sessionIds>SESSION_ID</sessionIds>
        </invalidateSessions>
    </soapenv:Body>
</soapenv:Envelope>

The result should be the following:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:enterprise.soap.sforce.com">
    <soapenv:Body>
        <invalidateSessionsResponse>
            <result>
                <success>true</success>
            </result>
        </invalidateSessionsResponse>
    </soapenv:Body>
</soapenv:Envelope>

Query Data by Publication-Dates

Short Explanation to mapping:

In most cases you need just one ADvendio field to be mapped to each Dataplan field. For the Dataplan fields “ID” and “Issue/Date” there are various ADvendio fields needed. You can connect the ADvendio fields with an "&".

We presume that the Gateway looks for all data with a Publish Date since December, 24th 2016.

The Query will look like this:

SELECT ADvendio__CampaignItem__r.Id, ADvendio__CampaignItem__r.ADvendio__Ad_Price__r.ADvendio__Ad_Spec__r.ADvendio__Ad_Type__r.
Name, ADvendio__CampaignItem__r.ADvendio__Ad_Price__r.ADvendio__Ad_Spec__r.ADvendio__Placement__r.ADvendio__Site__r.Name, 
ADvendio__CampaignItem__r.ADvendio__Media_Campaign__r.ADvendio__Account__r.Name, ADvendio__CampaignItem__r.
ADvendio__Media_Campaign__r.ADvendio__external_Media_Campaign_Name__c, ADvendio__CampaignItem__r.ADvendio__Media_Campaign__r.Owner.Name, 
ADvendio__CampaignItem__r.ADvendio__Height__c, ADvendio__CampaignItem__r.ADvendio__Width__c, 
ADvendio__CampaignItem__r.ADvendio__NumberOfColumns__c, ADvendio__CampaignItem__r.ADvendio__BusinessType__c, 
ADvendio__CampaignItem__r.ADvendio__PreferredPlacement__c, ADvendio__CampaignItem__r.ADvendio__SelectedBrandProductInformation__c, 
ADvendio__PublicationDate__r.Id, ADvendio__PublicationDate__r.Name, ADvendio__PublicationDate__r.ADvendio__PublicationDate__c 
FROM ADVendio__SelectedPublicationDate__c WHERE ADvendio__PublicationDate__r.ADvendio__PublicationDate__c=2016-12-24

Please take note of the "WHERE"-Clause for the data.

Assume the serverUrl you got from the login result is https://na7.salesforce.com/services/Soap/u/42.0/00DA0000000ck3y, when you send for example the request with curl to the Salesforce REST Service:

curl -H 'Authorization: Bearer SESSION-ID' https://na7.salesforce.com/services/Soap/u/42.0/query?q=URL_ENCODED_QUERY

Then you will receive the JSON-Response like follows:

{
   "totalSize" : 1,
   "done" : true,
   "records" : [
      {
         "ADvendio__CampaignItem__r" : {
            "ADvendio__Height__c" : 350,
            "attributes" : {
               "url" : "/services/data/v37.0/sobjects/ADvendio__Campaign_Item__c/a0G0Y000000YzacUAC",
               "type" : "ADvendio__Campaign_Item__c"
            },
            "ADvendio__BusinessType__c" : "Paid",
            "ADvendio__Media_Campaign__r" : {
               "ADvendio__external_Media_Campaign_Name__c" : "General Advertising Campaign Winter 2016",
               "Owner" : {
                  "attributes" : {
                     "type" : "Name",
                     "url" : "/services/data/v37.0/sobjects/User/0050Y0000017mIiQAI"
                  },
                  "Name" : "Stefan Ropte"
               },
               "attributes" : {
                  "type" : "ADvendio__MediaCampaign__c",
                  "url" : "/services/data/v37.0/sobjects/ADvendio__MediaCampaign__c/a0M0Y000000ZGdmUAG"
               },
               "ADvendio__Account__r" : {
                  "attributes" : {
                     "url" : "/services/data/v37.0/sobjects/Account/0010Y00000BUTVeQAP",
                     "type" : "Account"
                  },
                  "Name" : "GameCompany Ltd."
               }
            },
            "ADvendio__Width__c" : 210,
            "ADvendio__SelectedBrandProductInformation__c" : null,
            "Id" : "a0G0Y000000YzacUAC",
            "ADvendio__Ad_Price__r" : {
               "ADvendio__Ad_Spec__r" : {
                  "attributes" : {
                     "url" : "/services/data/v37.0/sobjects/ADvendio__Ad_Specs__c/a090Y000000OJA2QAO",
                     "type" : "ADvendio__Ad_Specs__c"
                  },
                  "ADvendio__Placement__r" : {
                     "attributes" : {
                        "type" : "ADvendio__Placement__c",
                        "url" : "/services/data/v37.0/sobjects/ADvendio__Placement__c/a0O0Y000000I7o3UAC"
                     },
                     "ADvendio__Site__r" : {
                        "Name" : "Seattle News",
                        "attributes" : {
                           "type" : "ADvendio__Site__c",
                           "url" : "/services/data/v37.0/sobjects/ADvendio__Site__c/a0W0Y000000Hso9UAC"
                        }
                     }
                  },
                  "ADvendio__Ad_Type__r" : {
                     "attributes" : {
                        "type" : "ADvendio__Ad_Type__c",
                        "url" : "/services/data/v37.0/sobjects/ADvendio__Ad_Type__c/a0A0Y000000xs3UUAQ"
                     },
                     "Name" : "Fullpage"
                  }
               },
               "attributes" : {
                  "url" : "/services/data/v37.0/sobjects/ADvendio__Ad_price__c/a0B0Y000000IIbaUAG",
                  "type" : "ADvendio__Ad_price__c"
               }
            },
            "ADvendio__NumberOfColumns__c" : "1",
            "ADvendio__PreferredPlacement__c" : "Page 2 als Beispiel"
         },
         "attributes" : {
            "type" : "ADvendio__SelectedPublicationDate__c",
            "url" : "/services/data/v37.0/sobjects/ADvendio__SelectedPublicationDate__c/a1F0Y000000cPkbUAE"
         },
         "ADvendio__PublicationDate__r" : {
            "Id" : "a1C0Y0000000nYCUAY",
            "ADvendio__PublicationDate__c" : "2016-12-24",
            "Name" : "No. 356",
            "attributes" : {
               "url" : "/services/data/v37.0/sobjects/ADvendio__PublicationDate__c/a1C0Y0000000nYCUAY",
               "type" : "ADvendio__PublicationDate__c"
            }
         }
      }
   ]
}

To get information about the authentification of a client towards Salesforce, which resources you can request how via REST-API, how the data-structure of the response will be please take a look at the SF REST API documentation.

You can find more details here: https://developer.salesforce.com/page/A_Deeper_look_at_SOQL_and_Relationship_Queries_on_Force.com

Possible mapping as example at Dataplans Journal Designer:

No.	Field	Required Field	Note	Example	ADvendio API
1	ID	Yes	Global unique Advert ID	AD9w87	ADvendio__CampaignItem__r.Id & ADvendio__PublicationDate__r.Id
2	Publication	Yes	Name, ID of the Title	Seattle News	ADvendio__CampaignItem__r.ADvendio__Ad_Price__r.ADvendio__Ad_Spec__r.ADvendio__Placement__r.ADvendio__Site__r.Name
3	Issue/Date	Yes	Issue Number/Year and/or Publish Date	1/2015 01-12-2015	ADvendio__PublicationDate__r.Name & "/" & ADvendio__PublicationDate__r.ADvendio__PublicationDate__c
4	Customer	Yes	Name of the Advertiser	BMW	ADvendio__CampaignItem__r.ADvendio__Media_Campaign__r.ADvendio__Account__r.Name
5	Product	No	Product Key Word	X5	ADvendio__CampaignItem__r.ADvendio__SelectedBrandProductInformation__c
6	Size	Yes	Advert Size or Format in Width/Height or Columns	FullPage	ADvendio__CampaignItem__r.ADvendio__Height__c & ADvendio__CampaignItem__r.ADvendio__Width__c & ADvendio__CampaignItem__r.ADvendio__NumberOfColumns__c
7	Bleed	No	Bleed	TRUE	ADvendio__CampaignItem__r.ADvendio__SetBleed__c
8	PlacementNote	No	Free Text information	Campaign 2015	ADvendio__CampaignItem__r.ADvendio__Media_Campaign__r.ADvendio__external_Media_Campaign_Name__c
9	PlacementCode	No	Placement Requirement	IFC (inside front cover)	ADvendio__CampaignItem__r.ADvendio__PreferredPlacement__c
10	BookingStatus	No	Status of the Contract	FULLPAID	ADvendio__CampaignItem__r.ADvendio__BusinessType__c
11	SalesRep	No	Contact person	Michael Miller	ADvendio__CampaignItem__r.ADvendio__Media_Campaign__r.Owner.Name
12	Features	No	Additional Info Coupon, Glue Card, Post Card, etc.	None	ADvendio__CampaignItem__r.ADvendio__Ad_Price__r.ADvendio__Ad_Spec__r.ADvendio__Ad_Type__r.Name
20	Acknowledgment	Yes	Once Ad is placed JD writes back the page no. plus additional information.	Page 3 top of the Page right	ADvendio__Campaign_Item__r.ADvendio__FlatPlanStatus__c

ADvendio Knowledge Base

8.1.3 Connect third-party systems