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:

Using SOAP enterprise / partner service
Using REST service
Using BULK service

Each service has its advantages and disadvantages / limitations. For detailed information please refer following Salesforce documentations:

Following example Java code demonstrates how to use the SOAP partner service to create or update a data in object Adserver ID, Key and Value of ADvendio. To generate a Java library using Salesforce Partner WSDL, please refer Introduction to the Force.com Web Services Connector, there you can find example code how to login into ADvendio. The example code below just shows how to create or update data in ADvendio.

Before that, you must first know how the data model Adserver ID, Key and Value are defined in ADvendio.

The object Adserver ID, its API name is ADvendio__AdServer_ID__c, has following fields that will be set in the example:

Field API Name	Data Type
Name	Text(80)
RecordTypeId	Lookup(RecordType)
ADvendio__Active__c	Checkbox
ADvendio__AdServer_ID__c	Number(18, 0) (External ID)
ADvendio__AdServer_Login__c	Lookup(AdServer Login)
ADvendio__AdServer_Name__c	Text(255)
ADvendio__Category__c	Picklist
ADvendio__Status__c	Picklist
ADvendio__Type__c	Picklist
ADvendio__UniqueKey__c	Text(255) (External ID) (Unique Case Insensitive)

The object Key, its API name is ADvendio__Key__c, has following fields that will be set in the example:

Field API Name	Data Type
Name	Text(80)
ADvendio__Active__c	Checkbox
ADvendio__AdServerId__c	Master-Detail(AdServer ID)
ADvendio__Predefined__c	Checkbox
ADvendio__UniqueKey__c	Text(255) (External ID) (Unique Case Insensitive)

The object Value, its API name is ADvendio__Value__c, has following fields that will be set in the example:

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.

Assume you want to create or update a key and a value in ADvendio, the property of them are:

For Key:
- Name: "An Example-Key"
- ID: 12345
For Value of the Key:
- Name: "An Example-Value"
- ID: 54321

In addition, both key and value are assumed from an ad-server DFP defined as a record of "AdServer Login" in ADvendio, the Salesforce record ID of this "AdServer Login" is "a0AA000000yqsnX".

Furthermore, the ID of RecordType with name DFP of object AdServer ID is known, e.g. "012A00000012g4A".

The pseudo code to create or update the key and the value is as follows:

Java example code snippet to create or update a key an value

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):

<?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:

<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:

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:

{
   "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

8.1.5 How to create / update data in ADvendio using your integration application

Example: Create Key, Value and AdserverId records

Authentication / Login via API

How to create / Update Records?

Possible mapping as example at Dataplans Journal Designer: