Sometimes you may want to build your own integration application to create or update data in ADvendio. The ADvendio itself is an application based on Salesforce platform, there are number of ways that your application can use to communicate with ADvendio. They are:
...
| Field API Name | Data Type |
|---|---|
| Name | Text(80) |
| ADvendio__Active__c | Checkbox |
| ADvendio__AdServerId__c | Lookup(AdServer ID) |
| ADvendio__Key__c | Master-Detail(Key) |
| ADvendio__UniqueKey__c | Text(255) (External ID) (Unique Case Insensitive) |
According to the data model, a record of type Key requires a record of type AdServer ID. A record of type Value requires a record of type Key, and it has a field pointing to a record of type AdServer ID too.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
public void createOrUpdateKey() {
try {
// Create an sObject of type ADvendio__AdServer_ID__c
SObject anAdServerId = new SObject();
anAdServerId.setType("ADvendio__AdServer_ID__c");
// Set the Name to key name. In our example it is given in assumption.
anAdServerId.setField("Name", "An Example-Key");
// Set the RecordTypeId to ID of RecordType with name DFP of object AdServer ID. In our example it is given in assumption.
anAdServerId.setField("Name", "012A00000012g4A");
// Set the ADvendio__Active__c to true.
anAdServerId.setField("ADvendio__Active__c", true);
// Set the ADvendio__AdServer_ID__c to key ID. In our example it is given in assumption.
anAdServerId.setField("ADvendio__AdServer_ID__c", 12345);
// Set the ADvendio__AdServer_Login__c to the ID of record of ad-server DFP. In our example it is given in assumption.
anAdServerId.setField("ADvendio__AdServer_Login__c", "a0AA000000yqsnX");
// Set the ADvendio__AdServer_Name__c to key name. In our example it is given in assumption.
anAdServerId.setField("ADvendio__AdServer_Name__c", "An Example-Key");
// Set the ADvendio__Category__c to "Key-values" which is fix definition of ADvendio.
anAdServerId.setField("ADvendio__Category__c", "Key-values");
// Set the ADvendio__Status__c to the correspond value assigned to the key in ad-server if there is.
// Allowed is one of "Active", "Inactive", "Archived" or "Deleted".
anAdServerId.setField("ADvendio__Status__c", "Active");
// Set the ADvendio__Type__c to the "Key" which is fix definition of ADvendio.
anAdServerId.setField("ADvendio__Type__c", "Key");
// Set the ADvendio__UniqueKey__c to a fixed format defined in ADvendio.
// It is a string concatenation: ID of record of ad-server + "|" + "Key" + "|" + key ID
anAdServerId.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|Key|12345");
// Create or update the ADvendio__AdServer_ID__c, using the upsert method.
// The unique key for upsert is ADvendio__UniqueKey__c.
UpsertResult[] upsertResults = partnerConnection.upsert(
"ADvendio__UniqueKey__c"
new SObject[] {anAdServerId}
);
// Iterate through the results, check the possible error
for (int j = 0; j < upsertResults.length; j++) {
System.out.println("\nItem: " + j);
if (upsertResults[j].isSuccess()) {
System.out.println("ADvendio__AdServer_ID__c with an ID of " + upsertResults[j].getId() + " was created/updated.");
}
else {
// There were errors during the upset call,
// go through the errors array and write
// them to the console.
for (int i = 0; i < upsertResults[j].getErrors().length; i++) {
Error err = upsertResults[j].getErrors()[i];
System.out.println("Errors were found on item " + j);
System.out.println("Error code: " + err.getStatusCode().toString());
System.out.println("Error message: " + err.getMessage());
}
}
}
// Your additional error handler here.
// Create an sObject of type ADvendio__Key__c
SObject aKey = new SObject();
aKey.setType("ADvendio__Key__c");
// Set the Name to key name. In our example it is given in assumption.
aKey.setField("Name", "An Example-Key");
// Set the ADvendio__Active__c to true.
aKey.setField("ADvendio__Active__c", true);
// Set the ADvendio__Predefined__c to the correspond value assigned to the key in ad-server if there is.
aKey.setField("ADvendio__Predefined__c", false);
// Set the ADvendio__UniqueKey__c to a fixed format defined in ADvendio.
// It is a string concatenation: ID of record of ad-server + "|" + key ID
aKey.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|12345");
// Set the ADvendio__AdServerId__c to the one created/updated above. Here we use the unique key of that record.
anAdServerId = new SObject();
anAdServerId.setType("ADvendio__AdServer_ID__c");
anAdServerId.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|Key|12345");
aKey.setField("ADvendio__AdServerId__r", anAdServerId); // Attention: the first parameter is ADvendio__AdServerId__r, not ADvendio__AdServerId__c.
// Create or update the ADvendio__Key__c, using the upsert method.
// The unique key for upsert is ADvendio__UniqueKey__c.
upsertResults = partnerConnection.upsert(
"ADvendio__UniqueKey__c"
new SObject[] {aKey}
);
// Iterate through the results, check the possible error
for (int j = 0; j < upsertResults.length; j++) {
System.out.println("\nItem: " + j);
if (upsertResults[j].isSuccess()) {
System.out.println("ADvendio__Key__c with an ID of " + upsertResults[j].getId() + " was created/updated.");
}
else {
// There were errors during the upset call,
// go through the errors array and write
// them to the console.
for (int i = 0; i < upsertResults[j].getErrors().length; i++) {
Error err = upsertResults[j].getErrors()[i];
System.out.println("Errors were found on item " + j);
System.out.println("Error code: " + err.getStatusCode().toString());
System.out.println("Error message: " + err.getMessage());
}
}
}
// Your additional error handler here.
} catch (ConnectionException ce) {
ce.printStackTrace();
}
}
public void createOrUpdateValue() {
try {
// Create an sObject of type ADvendio__AdServer_ID__c
SObject anAdServerId = new SObject();
anAdServerId.setType("ADvendio__AdServer_ID__c");
// Set the Name to value name. In our example it is given in assumption.
anAdServerId.setField("Name", "An Example-Value");
// Set the RecordTypeId to ID of RecordType with name DFP of object AdServer ID. In our example it is given in assumption.
anAdServerId.setField("Name", "012A00000012g4A");
// Set the ADvendio__Active__c to true.
anAdServerId.setField("ADvendio__Active__c", true);
// Set the ADvendio__AdServer_ID__c to key ID. In our example it is given in assumption.
anAdServerId.setField("ADvendio__AdServer_ID__c", 54321);
// Set the ADvendio__AdServer_Login__c to the ID of record of ad-server DFP. In our example it is given in assumption.
anAdServerId.setField("ADvendio__AdServer_Login__c", "a0AA000000yqsnX");
// Set the ADvendio__AdServer_Name__c to key name. In our example it is given in assumption.
anAdServerId.setField("ADvendio__AdServer_Name__c", "An Example-Value");
// Set the ADvendio__Category__c to "Key-values" which is fix definition of ADvendio.
anAdServerId.setField("ADvendio__Category__c", "Key-values");
// Set the ADvendio__Status__c to the correspond value assigned to the key in ad-server if there is.
// Allowed is one of "Active", "Inactive", "Archived" or "Deleted".
anAdServerId.setField("ADvendio__Status__c", "Active");
// Set the ADvendio__Type__c to the "Value" which is fix definition of ADvendio.
anAdServerId.setField("ADvendio__Type__c", "Value");
// Set the ADvendio__UniqueKey__c to a fixed format defined in ADvendio.
// It is a string concatenation: ID of record of ad-server + "|" + "Value" + "|" + value ID
anAdServerId.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|Value|54321");
// Create or update the ADvendio__AdServer_ID__c, using the upsert method.
// The unique key for upsert is ADvendio__UniqueKey__c.
UpsertResult[] upsertResults = partnerConnection.upsert(
"ADvendio__UniqueKey__c"
new SObject[] {anAdServerId}
);
// Iterate through the results, check the possible error
for (int j = 0; j < upsertResults.length; j++) {
System.out.println("\nItem: " + j);
if (upsertResults[j].isSuccess()) {
System.out.println("ADvendio__AdServer_ID__c with an ID of " + upsertResults[j].getId() + " was created/updated.");
}
else {
// There were errors during the upset call,
// go through the errors array and write
// them to the console.
for (int i = 0; i < upsertResults[j].getErrors().length; i++) {
Error err = upsertResults[j].getErrors()[i];
System.out.println("Errors were found on item " + j);
System.out.println("Error code: " + err.getStatusCode().toString());
System.out.println("Error message: " + err.getMessage());
}
}
}
// Your additional error handler here.
// Create an sObject of type ADvendio__Value__c
SObject aValue = new SObject();
aValue.setType("ADvendio__Value__c");
// Set the Name to value name. In our example it is given in assumption.
aValue.setField("Name", "An Example-Value");
// Set the ADvendio__Active__c to true.
aValue.setField("ADvendio__Active__c", true);
// Set the ADvendio__UniqueKey__c to a fixed format defined in ADvendio.
// It is a string concatenation: ID of record of ad-server + "|" + value ID
aValue.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|54321");
// Set the ADvendio__Key__c to the Key created/updated above. Here we use the unique key of that record.
SObject aKey = new SObject();
aKey.setType("ADvendio__Key__c");
aKey.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|Key|12345");
aValue.setField("ADvendio__Key__r", aKey); // Attention: the first parameter is ADvendio__Key__r, not ADvendio__Key__c.
// Set the ADvendio__AdServerId__c to the one created/updated above. Here we use the unique key of that record.
anAdServerId = new SObject();
anAdServerId.setType("ADvendio__AdServer_ID__c");
anAdServer.setField("ADvendio__UniqueKey__c", "a0AA000000yqsnX|Value|54321");
aValue.setField("ADvendio__AdServerId__r", anAdServerId); // Attention: the first parameter is ADvendio__AdServerId__r, not ADvendio__AdServerId__c.
// Create or update the ADvendio__Value__c, using the upsert method.
// The unique key for upsert is ADvendio__UniqueKey__c.
upsertResults = partnerConnection.upsert(
"ADvendio__UniqueKey__c"
new SObject[] {aValue}
);
// Iterate through the results, check the possible error
for (int j = 0; j < upsertResults.length; j++) {
System.out.println("\nItem: " + j);
if (upsertResults[j].isSuccess()) {
System.out.println("ADvendio__Key__c with an ID of " + upsertResults[j].getId() + " was created/updated.");
}
else {
// There were errors during the upset call,
// go through the errors array and write
// them to the console.
for (int i = 0; i < upsertResults[j].getErrors().length; i++) {
Error err = upsertResults[j].getErrors()[i];
System.out.println("Errors were found on item " + j);
System.out.println("Error code: " + err.getStatusCode().toString());
System.out.println("Error message: " + err.getMessage());
}
}
}
// Your additional error handler here.
} catch (ConnectionException ce) {
ce.printStackTrace();
}
} |
Example: Create Key, Value and AdserverId records
Authentication / Login via API
You can send the following XML per POST-Method with "Content-Type: text/xml; charset=utf-8” in RequestHead to the service URL (which you got at your login):
| Code Block |
|---|
<?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>THE-SESSION-ID</ns1:sessionId>
</ns1:SessionHeader>
</soapenv:Header>
<soapenv:Body>
<invalidateSessions xmlns="urn:enterprise.soap.sforce.com">
<sessionIds>THE-SESSION-ID</sessionIds>
</invalidateSessions>
</soapenv:Body>
</soapenv:Envelope> |
The result should be the following:
| Code Block |
|---|
<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> |
You will find more details here: https://developer.salesforce.com/page/Salesforce_APIs
How to create / Update Records?
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:
| Code Block |
|---|
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.
When you send for example the request with curl to the Salesforce REST Service:
curl -H 'Authorization: Bearer YOUR-SESSIONID' https://eu11.salesforce.com/services/data/v37.0/query/?q=URL_ENCODED_QUERY
Then you will receive the JSON-Response:
| Code Block |
|---|
{
"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
...