Last Update: 27.12.2024

Einleitung

Dieser Artikel beschreibt, wie man mit Hilfe von Lobster Integration (Version > 4.6.11) über eine JDBC-Schnittstelle per SQL auf ein Salesforce-CRM-System zugreifen kann.

Hinweis: Im Artikel wird nicht beschrieben, wie der Zugriff auf die von Salesforce zur Verfügung gestellte HTTP/SOAP-Schnittstelle funktioniert.

Für die SQL-Zugriffe ist der Erwerb einer kostenpflichtigen Zusatz-Lizenz notwendig. Ebenso muss ein spezieller JDBC-Treiber der Firma CDATA, welcher im Rahmen der Lizenz zur Verfügung gestellt wird, dafür installiert sein.

Wichtiger Hinweis: Dieser JDBC-Treiber wandelt die von Lobster Integration kommenden SQL-Statements in Webservice-Aufrufe auf die Salesforce HTTP/SOAP-Schnittstelle um. Hier ist darauf zu achten, dass die SQL-Statements einfach gehalten werden ( z. B. keine komplizierten JOIN-Bedingungen, etc. ). Je komplexer die Statements, desto höher ist die Wahrscheinlichkeit, dass die Umwandlung in Webservice-Aufrufe nicht mehr zu 100% funktioniert.

Salesforce-Anbindung

Um mit Lobster Integration per SQL auf Salesforce zugreifen zu können, sind zwei Schritte notwendig:

1) JDBC-Treiber

Wenn die Lizenz aktiviert wurde, dann wird der JDBC-Treiber automatisch in Ihrem Update Center angezeigt.

Nach dem Herunterladen des Treibers, muss der Integration Server einmal neu gestartet werden. Danach kann mit dem nächsten Schritt fortgefahren werden.

Linux:
Integration Server neu starten.

Windows:
Hier muss einmal nach folgender Reihenfolge vorgegangen werden:

Integration Server beenden
Skript ./bin/hub.bat starten
Skript ./bin/hub.bat mit Strg+c beenden
Integration Server starten

Hinweis: Es ist ratsam, gelegentlich einen Blick in das Update Center zu werfen, da dort Aktualisierungen angezeigt und durchgeführt werden können.

2) Hinzufügen von Datenbank-Aliasen

Es sind zwei Aliase notwendig, weil der JDBC-Treiber nicht über einen Alias Bulk- und normale Operationen ausführen kann.

Der Bulk-Alias wird beim Zugriff auf Salesforce in Phase 5 (SQLBulkUnit) verwendet. Der Nicht-Bulk-Alias für alle anderen Zugriffe (Phasen 1,3 und 4). Durch diese Trennung kann verhindert werden, dass große Bulk-Operationen durch lange laufende Select-Statements blockiert werden.

Die Aliase werden erstellt unter Verwaltung → Datenbanken/Connectoren. Nachfolgend finden Sie zwei Vorlagen, die Sie importieren können. Ihre Werte können Sie dann anpassen. Alternativ kann ein Alias auch über die Vorlagen → Vorlagen(Presets) → Salesforce angelegt werden.

a) Bulk Alias

Import-Vorlage Bulk-Alias

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Lobster//DTD Configure 1.0//EN" "http://www.lobster.de/dtd/configure_1_1.dtd">
	<Configure class="com.ebd.hub.services.database.ConnectionService">
	<Call name="initPool">
		<Arg>
			<New class="com.ebd.hub.services.database.DatabaseSettings">
				<Set name="alias">salesforce</Set>
				<Set name="allowGrowing">True</Set>
				<Set name="database">jdbc:lobster:sforce2:</Set>
				<Set name="user">(your salesforce login username)</Set>
				<Set name="password">(your salesforce login password)</Set>
				<Call name="addNamedProperty">
					<Arg>Security Token</Arg>
					<Arg>(your security token)</Arg>
				</Call>
				<Call name="addNamedProperty">
					<Arg>Use Bulk API</Arg>
					<Arg>true</Arg>
				</Call>
				<Call name="addNamedProperty">
					<Arg>Bulk API Version</Arg>
					<Arg>v2</Arg>
				</Call>
 				<Call name="addNamedProperty">
					<Arg>Logfile</Arg>
					<Arg>"C:\Lobster\IS\logs\salesforce_jdbc\sf.log"</Arg>
				</Call> 
 				<Call name="addNamedProperty">
					<Arg>Verbosity</Arg>
					<Arg>0</Arg>
				</Call> 
  				<Call name="addNamedProperty">
					<Arg>Max Log File Size</Arg>
					<Arg>10MB</Arg>
				</Call>  
   	 	        <Set name="catalogName"></Set>
				<Set name="driver">de.lobster.jdbc.jdbc.sforce.SForceDriver</Set>
				<Set name="minSize">0</Set>
				<Set name="maxSize">0</Set>
				<Set name="idleTime">300000</Set>
				<Set name="sqlCommand"></Set>
				<Set name="rollback">True</Set>
				<Set name="caching">True</Set>
			</New>
		</Arg>
	</Call>
</Configure>

Parameter	Beschreibung	Beispiel
alias	Alias-Name.	<Set name="alias">salesforce</Set>
database	Hier wird der Connection-String für den JDBC-Treiber angegeben. Für die Übersicht werden alle Parameter in der database.xml als "addNamedProperty" angegeben, damit diese beim Import in der Oberfläche in der Registerkarte "JDBC Properties" angezeigt werden. Wenn weitere Properties dazu kommen, können diese in der Oberfläche in der Registerkarte "JDBC Properties" ergänzt werden. Deswegen ist der Eintrag an der Stelle sehr kurz und ist nur dafür da, um den richtigen Treiber zu identifizieren.	<Set name="database">jdbc:lobster:sforce2:</Set> ( "2" und Doppelpunkt am Ende beachten!)
user	User-Name des Salesforce-Logins.	<Set name="user">(your salesforce login username)</Set>
password	Passwort des Salesforce-Logins.	<Set name="password">(your salesforce login password)</Set>
Security Token	In Salesforce generierter, fester Security Token. Bei Anlegen des Tokens, Ändern des Passworts, etc. wird der Token per E-Mail an den User gesendet. In Salesforce kann über View Profile/Settings/Reset My Security Token ein neuer Token generiert werden. Dieser Token läuft nicht automatisch ab.	<Call name="addNamedProperty"> <Arg>Security Token</Arg> <Arg>(your security token)</Arg> </Call>
Use Bulk API	Aktiviert die Verwendung der Bulk API von Salesforce über den JDBC-Treiber. Muss im Bulk-Alias auf "true" gesetzt sein.	<Call name="addNamedProperty"> <Arg>Use Bulk API</Arg> <Arg>true</Arg> </Call>
Bulk API Version	Es gibt v1 und v2. Default ist v1. Wird v1 verwendet, werden auch Select-Queries beim Limit von max. 15000 Batches mitgezählt, sodass bei vielen Selects das Limit schnell überschritten sein kann. Damit dies nicht passiert, sollte hier v2 eingestellt sein. Diese Jobs werden dann zuallererst abgearbeitet, was dazu führen kann, dass ein "Langläufer"-Select-Statement andere, unter aktive Jobs eingeordnete, Jobs blockiert. Deshalb wird für Selects der zweite Alias (Nicht-Bulk-Alias) verwendet. Bei diesem ist "use Bulk API" auf "false" gesetzt. Somit werden keine Salesforce-Jobs angelegt, sondern es wird direkt auf die Objekte zugegriffen.	<Call name="addNamedProperty"> <Arg>Bulk API Version</Arg> <Arg>v2</Arg> </Call>
minSize, maxSize	Muss auf 0 gestellt sein, da sonst die Salesforce-Bulk-Jobs nicht geschlossen werden.	<Set name="minSize">0</Set> <Set name="maxSize">0</Set>
driver	Verwendete Java-Treiber-Klasse.	<Set name="driver">de.lobster.jdbc.jdbc.sforce.SForceDriver</Set>
Use Connection Pooling	Aktiviert "ConnectionPooling" des JDBC-Treibers. Dieser Parameter muss bei Bulk auf "false" stehen, was der Standardwert des Parameters ist und deshalb kann der Parameter weggelassen werden. Wenn dieser auf "true" steht, dann versucht der JDBC-Treiber von zwei unabhängigen Lobster-Integration-Jobs die erzeugen Bulks in einen Salesforce-Job zu hängen und das so lange, wie die Connection aufrecht erhalten wird. Da aber jedes Profil so lange läuft, bis der Salesforce-Job beendet ist, gibt es beim zweiten Profil-Lauf einen Fehler, dass an einen geschlossenen Salesforce-Job kein neuer Bulk hinzugefügt werden kann.
allowGrowing, catalogName, idleTime, sqlCommand, rollback, caching	Diese Parameter haben für die Salesforce-Aliase keine Bedeutung. Diese sind standardmäßig in jedem Datenbank-Alias.

b) Nicht-Bulk-Alias

Import Vorlage Nicht-Bulk-Alias

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Lobster//DTD Configure 1.0//EN" "http://www.lobster.de/dtd/configure_1_1.dtd">
    <Configure class="com.ebd.hub.services.database.ConnectionService">
		<Call name="initPool">
		    <Arg>
		        <New class="com.ebd.hub.services.database.DatabaseSettings">
		            <Set name="alias">salesforce_nobulk</Set>
		            <Set name="allowGrowing">True</Set>
		            <Set name="database">jdbc:lobster:sforce2:Logfile="C:\Lobster\IS\logs\salesforce_jdbc\sf.log";Verbosity="3";Max Log File Size="10MB"</Set>
		            <Set name="user">(your salesforce login username)</Set>
		            <Set name="password">(your salesforce login password)</Set>
		            <Call name="addNamedProperty">
		                <Arg>Security Token</Arg>
		                <Arg>(your security token)</Arg>
		            </Call>
		            <Call name="addNamedProperty">
		                <Arg>Use Bulk API</Arg>
		                <Arg>false</Arg>
		            </Call>
		            <Call name="addNamedProperty">
		                <Arg>Use Connection Pooling</Arg>
		                <Arg>true</Arg>
		            </Call>
		            <Set name="catalogName"></Set>
		            <Set name="driver">de.lobster.jdbc.jdbc.sforce.SForceDriver</Set>
		            <Set name="minSize">0</Set>
		            <Set name="maxSize">0</Set>
		            <Set name="idleTime">300000</Set>
		            <Set name="sqlCommand"></Set>
		            <Set name="rollback">True</Set>
		            <Set name="caching">True</Set>
		        </New>
		    </Arg>
		</Call>
</Configure>

Parameter	Beschreibung	Beispiel
alias, database, user, passwort, Security Token, minSize, maxSize, driver	Siehe oben.
Use Bulk API	Aktiviert die Verwendung der Bulk-API von Salesforce über den JDBC-Treiber. Muss im Nicht-Bulk-Alias auf "false" gesetzt sein.	<Call name="addNamedProperty"> <Arg>Use Bulk API</Arg> <Arg>false</Arg> </Call>
Use Connection Pooling	Aktiviert ConnectionPooling des JDBC-Treibers. Anders als bei dem Bulk-Alias, sollte dieser Parameter hier immer auf "true" gesetzt sein, da sonst schnell das Salesforce-Limit von 3000 Verbindungen/Tag überschritten sein kann.	<Call name="addNamedProperty"> <Arg>Use Connection Pooling</Arg> <Arg>true</Arg> </Call>
allowGrowing, catalogName, idleTime, sqlCommand, rollback, caching	Siehe oben.

c) Zugriff auf andere Salesforce-Instanzen

Produktive Instanzen werden über login.salesforce.com erreicht, Sandbox-Instanzen (= vom Prodsystem geklontes Testsystem) über test.salesforce.com.

Will man auf ein Testsystem (Sandbox) zugreifen, muss folgendes JDBC-Property im Alias ergänzt werden (Default für "Use Sandbox" ist "false"):

database.xml

<Call name="addNamedProperty">
    <Arg>Use Sandbox</Arg>
    <Arg>true</Arg>
</Call>

Es ist auch möglich, sich bei Salesforce eigene Subdomains zu kaufen, z. B. firmenname.my.salesforce.com

Um über diese URL auf die Salesforce-Instanz zugreifen zu können, muss der Parameter "LoginURL" ergänzt werden. Das gilt für die Sandbox und das Produktiv-System. Für die Sandbox muss zusätzlich der Parameter "Use Sandbox" auf "true" stehen.

database.xml

<Call name="addNamedProperty">
    <Arg>LoginURL</Arg>
    <Arg>https://<mysubdomain>.my.salesforce.com/services/Soap/c/60.0</Arg>
</Call>

Hinweis: 60.0 ist aktuell die Salesforce-API-Version, die vom JDBC-Treiber unterstützt wird (Stand: 04/2024).

d) Proxy-Konfiguration

Bitte alle Parameter per "addNamedProperty" in den Alias eintragen.

Parameter	Bedeutung	Default
Proxy Server	Hostname oder IP-Adresse des Proxies.	./.
Proxy Port	TCP-Port, auf dem der Proxy läuft.	80
Proxy User	User-Name für Authentifizierung.	./.
Proxy Password	Passwort für Authentifizierung.	./.
Proxy Auth Scheme	Autentifizierungstyp (BASIC, DIGEST, NEGOTIATE, PROPRIETARY).	BASIC
Proxy Auto Detect	System-Proxy-Einstellungen verwenden. Sollen die hier konfigurierten Proxyparameter verwendet werden, dann auf false setzen.	false
Proxy Exceptions	Semikolon-getrennte Liste von Hostnamen und IP-Adressen, bei denen die Verbindung nicht über den Proxy gehen soll.	./.
Proxy SSL Type	AUTO, ALWAYS, NEVER, TUNNEL (siehe Treiber-Doku).	AUTO

Weitere Details in der Treiber-Doku: https://cdn.cdata.com/help/RFK/jdbc/Connection.htm

OAuth2 konfigurieren (optional, falls erforderlich/gewünscht)

Voraussetzungen für die Verwendung von OAuth2 in Verbindung mit dem Salesforce-JDBC-Treiber:

a) Es muss auf Salesforce-Seite eine entsprechende App erstellt werden.

b) Die Werte für Client ID (Consumer Key) und Client Secret (Consumer Secret) müssen bekannt sein.

Bei Fragen hierzu ziehen Sie bitte die offizielle Salesforce-Dokumentation zu Rate oder wenden sich an ihren Salesforce-Berater.

Es sind verschiedene Schritte notwendig, um den Prozess zum automatischen Erneuern des Token zu ermöglichen. Auf jeden Fall wird ein Lobster Integration benötigt, der bereits Zugriff auf Salesforce hat - zunächst mit User/Passwort-Authentifizierung, wie es bereits in diesem Dokument beschrieben wurde.

Über die Admin-Konsole oder SQL Konsole in den Plugins, müssen verschiedene Prozeduren ausgeführt werden.

Im Folgenden wird nun Schritt für Schritt das Holen des Access Tokens und des Refresh Tokens beschrieben.

Hinweis: Es darf keiner der Schritte ausgelassen werden, da diese aufeinander aufbauen! Das Holen vom ersten Access und Refresh Token kann über einen Alias gemacht werden. Aber alle Aliase müssen am Schluss für Oauth2 konfiguriert sein.

Schritt 1 - Salesforce-Alias vorbereiten

Im Salesforce-Alias müssen unter JDBC Properties nachfolgende Properties ergänzt werden. Wichtig ist, dass die "CallbackURL" in Salesforce und in Lobster Integration http://localhost:33333 lautet. Dies ist die Standard-Callback-URL für Headless Machines.

Alle Platzhalter in eckigen Klammern müssen noch mit den realen Werten bestückt werden.

<Call name="addNamedProperty">
	<Arg>AuthScheme</Arg>
	<Arg>OAuth</Arg>
</Call>
<Call name="addNamedProperty">
    <Arg>OAuthClientId</Arg>
    <Arg>[Client Id(Consumer Key)]</Arg>
</Call>                
<Call name="addNamedProperty">
    <Arg>OAuthClientSecret</Arg>
    <Arg>[Client Secret(Consumer Secret)]</Arg>
</Call>
<Call name="addNamedProperty">
    <Arg>CallbackURL</Arg>
    <Arg>http://localhost:33333</Arg>
</Call>
<Call name="addNamedProperty">
    <Arg>InitiateOAuth</Arg>
    <Arg>OFF</Arg>
</Call>
<Call name="addNamedProperty">
    <Arg>OAuthSettingsLocation</Arg>
    <Arg>[<your_Lobster_home_directory>]/conf/Salesforce/OAuthSettings.txt</Arg>
</Call>
<Call name="addNamedProperty">
    <Arg>LoginURL</Arg>
    <Arg>[LoginURL]</Arg>
</Call>
<Call name="addNamedProperty">
    <Arg>OAuthAccessTokenURL</Arg>
    <Arg>[OAuthAccessTokenURL]</Arg>
</Call>

Parameter	Beschreibung	Beispiel
AuthScheme	Das Schema, mit dem sich der JDBC-Treiber gegen Salesfoce autorisieren soll. Für OAuth muss der Wert "OAuth" sein.
OAuthClientId	Hier wird der Consumer Key (siehe Salesforce-Beschreibung) eingetragen.	<Call name="addNamedProperty"> <Arg>OAuthClientId</Arg> <Arg>3MVG9Ve.2wqUVx_bR4rnWKR66zawe4q34aygrhQ1zCQ2LCVCj1JxSp.X_VyaCU4l1HjBLzvKzSAre.xK</Arg> </Call>
OAuthClientSecret	Hier wird das Consumer Secret (siehe Salesforce-Beschreibung) eingetragen.	<Call name="addNamedProperty"> <Arg>OAuthClientSecret</Arg> <Arg>32913EEE7324357WERZT849D54FEE3C85E43F6C32751AD79818BDE4D</Arg> </Call>
CallbackURL	Die Callback-URL ist für den OAuth2-Grant-Type Authorization Code erforderlich. An diese URL wird beim Erneuern des Tokens die Autorisierung für den Anwender zurück gegeben. Da Lobster Integration eine Server-Anwendung ist und keine Benutzeraktionen im Hintergrund ausgeführt werden können, wird hier der Standard als Dummy beibehalten.
InitiateOAuth	Der Parameter gibt an, welches Verfahren durchgeführt werden muss. Für die Einrichtung von OAuth2 wird "OFF" benötigt, da es noch keine gültigen Token für die Anbindung gibt. Nach der Einrichtung wird dieser Parameter in "REFRESH" umbenannt, weil dann nur noch der Refresh Token erneuert werden muss. Weiter unten in diesem Artikel wird erklärt, zu welchem Zeitpunkt die Änderung erfolgen muss.
OAuthSettingsLocation	Hier wird der Speicherort angegeben, an dem der JDBC-Treiber den aktuellsten Token ablegt. Es empfiehlt sich, dafür einen Speicherort im ./conf-Verzeichnis anzugeben.	<Call name="addNamedProperty"> <Arg>OAuthSettingsLocation</Arg> <Arg>/opt/Lobster/IS/conf/Salesforce/OAuthSettings.txt</Arg> </Call>
LoginURL	Die URL, mit der sich der Treiber in Salesforce anmeldet. Diese URL unterscheidet sich je nach Salesforce-Instanz: Für das Test-System: https://test.salesforce.com/ Für das Produktiv-System: https://login.salesforce.com/ Wenn eine Domain gekauft wurde: https://<myCompany>.sandbox.my.salesforce.com	<Call name="addNamedProperty"> <Arg>LoginURL</Arg> <Arg>https://lobster--test.sandbox.my.salesforce.com</Arg> </Call>
OAuthAccessTokenURL	Die URL, mit der sich der Treiber den Access Token von Salesforce abholt. Diese URL unterscheidet sich je nach Salesforce Instanz: Für das Test-System: https://test.salesforce.com/services/oauth2/token Für das Produktiv-System: https://login.salesforce.com/services/oauth2/token Wenn eine Domain gekauft wurde: https://<myCompany>.sandbox.my.salesforce.com/services/oauth2/token	<Call name="addNamedProperty"> <Arg>OAuthAccessTokenURL</Arg> <Arg>https://lobster--test.sandbox.my.salesforce.com/services/oauth2/token</Arg> </Call>

Schritt 2 - Verifier von Salesforce holen

Als Erstes wird die Authorization URL von Salesforce geholt. Dafür öffnet man die Admin-Konsole und navigiert dort zu Tools → SQL Monitor. Im Verlauf wird immer der SQL Monitor erwähnt, alternativ kann immer auch unter Plugins die SQL Konsole verwendet werden.

Als Datenbank-Alias wird der Salesforce-Alias verwendet, der im Schritt 1 angepasst wurde.

Dann muss folgender Befehl ausgeführt werden:

execute GetOAuthAuthorizationUrl

Als Ergebnis wird eine URL zurück gegeben. Diese muss in einem Browser aufgerufen werden. Der Browser muss sich dafür nicht auf dem Integration Server befinden.

Beispiel:

https://login.salesforce.com/services/oauth2/authorize?state=aHR0cDovL2xvY2FsaG9zdDozMzMzMw%3D%3D&client_id=3MVG99Oxasdfasdfasdf0_eLiYU4FC2.NRn9htUmh2uIfNM.13BM33aZClit&response_type=code&redirect_uri=https%3A%2F%2Foauth.cdata.com%2Foauth%2F

Die Antwort vom Server auf den Request ist ein Redirect. Es ist möglich, dass im Browser ein Fehler angezeigt wird, da die URL mit localhost:33333 nicht existiert, das ist aber korrekt so.

Die Redirect URL, die in der Adressleiste vom Browser erscheint, kann z. B. so aussehen:

http://localhost:33333/?code=YVByeDR5X0t6c2NXenl5easdfasdfkRmRyakxtNlNScEJNR2hFbG8wNTlJb2t2c1IzTVJ1UHU0Skg3aXdfYjMzYkRiM2NrZ1FZbWc9PQ==&state=YUhSMGNEb3ZMMnh2WTJGc2FHOXpkRG96TXpNek13PT0=&rssbus=true

Der Wert von Parameter "code" ist der Verifier. Dieser wird für den nächsten Schritt benötigt. Im Beispiel ist es der Wert YVByeDR5X0t6c2NXenl5easdfasdfkRmRyakxtNlNScEJNR2hFbG8wNTlJb2t2c1IzTVJ1UHU0Skg3aXdfYjMzYkRiM2NrZ1FZbWc9PQ==

Schritt 3 - Access Token und Refresh Token holen

Mit dem Wert aus Schritt 2 muss im SQL Monitor nun folgende Prozedur aufgerufen werden.

execute GetOAuthAccessToken Verifier='<ihr Verifier>'

Diese Prozedur gibt eine Tabelle mit einem Datensatz zurück. Benötigt werden aus diesem Datensatz die Werte für Access Token und Refresh Token.

Schritt 4 - Token im Alias hinterlegen

Nun muss der Salesforce-Alias unter Verwaltung → Datenbanken/Connectoren angepasst werden. Es muss einmal der Access Token und Refresh Token aus Schritt 3 ergänzt werden. Ebenso muss der Wert für Parameter "InitialteOAuth" in "REFESH" umbenannt werden.

<Call name="addNamedProperty">
    <Arg>InitiateOAuth</Arg>
    <Arg>REFRESH</Arg>
</Call>    
<Call name="addNamedProperty">
    <Arg>OAuthAccessToken</Arg>
    <Arg>[Access Token]</Arg>
<Call name="addNamedProperty">
    <Arg>OAuthRefreshToken</Arg>
    <Arg>[Refresh Token]</Arg>
</Call>   

Logging

Aktivierung

Um das Logging des JDBC-Treibers zu aktivieren, werden am Alias des JDBC-Treibers zusätzliche Parameter angegeben:

database.xml

<Call name="addNamedProperty">
    <Arg>Logfile</Arg>
    <Arg>"C:\Lobster\IS\logs\salesforce_jdbc\sf.log"</Arg>
</Call>    
<Call name="addNamedProperty">
    <Arg>Max Log File Size</Arg>
    <Arg>"10MB"</Arg>
</Call> 
<Call name="addNamedProperty">
    <Arg>Verbosity</Arg>
    <Arg>0</Arg>
</Call> 

Parameter	Beschreibung
Logfile	Der absolute Pfad zum Logfile. Alle Ordner müssen vorhanden sein.
Verbosity	Loglevel. Von 1 (gering) bis 5 (sehr hoch). Sollte standardmäßig auf 0 (= aus) stehen.
Max Log File Size	Maximale Größe der Logdatei. Wwird diese überschritten, wird ein neues Logfile aufgemacht.

Im Logfile steht im Klartext, was zwischen JDBC-Treiber und Salesforce ausgetauscht wurde (je nach "Verbosity" in unterschiedlichem Detaillierungsgrad).

Hier kann sowohl erzeugtes SQL als auch die zwischen JDBC-Treiber und Salesforce übertragenen HTTP-Requests/Responses einsehen.

In der Regel ist "Verbosity" = 3 auf einem Test-System ausreichend zur Fehlersuche. Wird das Logging nicht mehr benötigt, sollte man es auch wieder deaktivieren.

Wichtiger Hinweis: Auf einem Produktiv-System sollte das Logging nur mit äußerster Vorsicht aktiviert werden, weil hier gegebenenfalls sehr schnell sehr große Log-Dateien entstehen können!

Das Logfile entsteht nicht gleich beim Start des Integration Servers, sondern erst beim ersten Zugriff auf den jeweiligen Datenbank-Alias.

Logfile Rollover

Ist die "Max Log File Size" erreicht, findet ein Rollover statt. Die aktuelle Logdatei erhält einen Zeitstempel (yyyyMMddHH-mmss) im Dateinamen, und eine neue Logdatei (mit dem in "Logfile" angegebenen Namen) wird angelegt. Das weitere Logging findet dann in dieser neuen Datei statt.

Technische Besonderheiten in Salesforce

Nachfolgend werden ein paar technische Besonderheiten beschrieben, die für die Verwendung der JDBC-Schnittstelle zu Salesforce relevant sind.

Metadaten-Cache

Beim ersten Zugriff auf ein Salesforce-Objekt werden zunächst die Metadaten des Objekts angefordert und in einen internen Cache ("MetaCache") gelegt.

Dies erhöht zwar einerseits die Geschwindigkeit für zukünftige Zugriffe auf dieses Objekt, hat aber andererseits zur Folge, dass bei Änderungen am Objekt (z. B. Hinzufügen oder Entfernen eines Feldes am Salesforce Objekt) ein Neuaufbau des Caches erfolgen muss.

Um den Cache neu aufzubauen, ist es notwendig, den Integration Server einmal komplett neu zu starten.

Salesforce Bulk API

Bulk Jobs bieten den Vorteil, dass große Datenmengen wesentlich schneller per Insert oder Update verarbeitet werden können.

In Salesforce gibt es Limitierungen (abhängig von der lizenzierten Salesforce Edition) bezüglich Verbindungen pro Tag und Anzahl Batches pro Tag, deshalb ist es sinnvoll, große Datenmengen in einem Bulk zu übertragen.

Wichtiger Hinweis: Bulk Jobs in Salesforce entstehen nur, wenn der verwendete Datenbank-Alias "use Bulk API = true" gesetzt hat und in Phase 5 die SQLBulkUnit verwendet wird.

Es entsteht kein Bulk Job in Salesforce, wenn der verwendete Datenbank-Alias zwar "use Bulk API= true" gesetzt hat, aber das Insert/Update durch Phase 3 (Funktion) oder Phase 4 (Datenbankknoten) erzeugt wurde.

Wird die SQLBulkUnit mit einem Datenbank-Alias verwendet, der "use Bulk API= false" gesetzt hat, gibt es eine Fehlermeldung in Phase 5: "Got no salesforce job-ID".

In der Salesforce-GUI kann man sich über "Setup/Environments/Jobs/Bulk Data Load Jobs" eine Liste der gerade in Bearbeitung befindlichen bzw. fertiggestellten Bulk Jobs anzeigen lassen.

Ein Bulk Job besteht aus 1-n Batches, in jedem Batch können 1 - max. 9999 (Einstellung SqlBulkUnit - Max. sql statements in batch) Records enthalten sein.

	Attribut	Beschreibung
Kopfdaten	Job ID Object External ID Field Content Type ...	Kopfdaten des Bulk Jobs.
Batch 1	Record 1	Erster Datensatz in Batch 1.
	Record 2	Zweiter Datensatz in Batch 1.
	...	...
	Record 9999	Letzter Datensatz in Batch 1.
Batch 2	Record 1	Erster Datensatz in Batch 2.
	Record 2	Zweiter Datensatz in Batch 2.
	...	...

Pro Datenbank-Knoten in Lobster data entsteht ein Salesforce Bulk Job (auch bei mehreren Datenblättern/Records entsteht nur ein Bulk Job pro Knoten - die Daten aus den einzelnen Datenblättern werden zusammengefasst).

Die Salesforce Bulk Jobs werden seriell von Lobster Integration abgearbeitet.

Die einzelnen Batches eines Bulk Jobs werden in Salesforce parallel abgearbeitet.

Wichtiger Hinweis: "delete before insert" kann mit der SQLBulkUnit im Zusammenhang mit Salesforce nicht verwendet werden!

Objekte/Felder

In Salesforce gibt es Standardobjekte (Type = "Standard Object", wird von Salesforce so zur Verfügung gestellt, wie z. B. "Account") und selbst angelegte Objekte (Type = "Custom Object"). Jedes Objekt hat ein Label (zur Anzeige in der GUI), sowie einen API-Namen (mit diesem kann über die API auf das Objekt zugegriffen werden).

Am API-Namen kann erkannt werden, ob es sich um ein Custom Object handelt - dann endet dieser mit "__c".

Ein Objekt hat 1-n Felder. Felder haben ein Field Label (zur Anzeige in der GUI) sowie einen Field Name (für den API-Zugriff). Handelt es sich um ein customized Field, so endet der Field Name wiederum mit "__c".

Über den Object Manager (Setup/Object Manager) in der Salesforce-GUI können Details zum Aufbau der einzelnen Objekte und deren Felder angezeigt werden.

Standardobjekte können nicht gelöscht, jedoch neue Felder/Objekte hinzugefügt werden. Standardfelder können nicht gelöscht oder verändert werden.

Objekt-Beziehungen

In Salesforce können zwischen den Objekten Beziehungen gesetzt werden. Es gibt zwei Haupttypen von Beziehungen: Lookup- und Master-Detail. Wie diese verwendet werden können, ist in Abschnitt Salesforce per SQL - Tutorial beschrieben.

Lookup-Beziehung (Nachschlage-Beziehung)

Lookup-Beziehungen werden normalerweise verwendet, wenn Objekte miteinander in Beziehung stehen.

Beispiel aus den Salesforce-Standardobjekten: "Account" und "Contact". Hierbei handelt es sich um eine relativ "lockere" Beziehung. Ein Contact kann zu einem Account gehören, muss aber nicht. Er kann auch ganz für sich alleine stehen.

Um ein Contact-Objekt an ein Account-Objekt zu hängen, muss in Contact das Feld "AccountId" (welches vom Datentyp "Lookup(Account)" ist) mit der internen ID eines Account-Objekts gefühlt sein. Ist dieses Feld mit der internen ID des Accounts gefüllt, erscheint auf der Salesforce-Oberfläche auch ein Link am Contact zum Account,

Master-Detail-Beziehung

Bei einer Master-Detail-Beziehung ist das Detail-Objekt nicht eigenständig. Im Gegenteil, es hängt stark vom Master ab. Wenn ein Datensatz aus dem Master-Objekt gelöscht wird, werden auch alle zugehörigen Detaildatensätze gelöscht. Beim Erstellen von Master-Detail-Beziehungen wird das Beziehungsfeld immer im Detail-Objekt erstellt.

Ein Beispiel hierfür aus den Salesforce-Standardobjekten kann hier leider nicht angegeben werden, da ein Standard-Objekt niemals ein Detail-Objekt sein kann.