Zugriff auf Microsoft Dynamics CRM 2011 mit Java – Teil II

In diesem Artikel erkläre ich, wie die im Artikel Zugriff auf Microsoft Dynamics CRM 2011 mit Java – Teil I generierten Klassen für den Zugriff auf das Microsoft Dynamics CRM über die REST-Schnittstelle genutzt werden können.

Die Serviceklasse

Der im Teil I generierte Code enthält zu jeder Entität im CRM eine entsprechende Klasse, welche den eindeutigen Name der Entität im CRM als Klassenname besitzt. Zudem wird eine Service-Klasse erzeugt, deren Methoden für die eigentlichen Rest-Abfragen genutzt werden können.

Die Service-Klasse kann wie im Codebeispiel mit dem Default-Konstruktor initialisiert werden.

Erstellung von Abfragen

Mit Hilfe der Serviceklasse lassen sich verschiedenste Abfragen erstellten:

In diesem Teil erläutere ich zunächst die Basisoperationen zum Abfragen, Hinzufügen, Aktualisieren und Löschen von Entitäten. Weitere speziellere Funktionalitäten werden im dritten Teil dieser Reihe vorgestellt.

Abfrage einer einzelnen Entität

Im folgenden Beispiel wird ein Kontakt (Entität „Contact“) anhand der Id abgefragt.

In Zeile 1 wird die Query erstellt. Für jede Entität existiert eine Methode service.create<Entity>Query() zur Erzeugung einer Query, die nach Ausführung Objekte des jeweiligen Entitätstyps zurückliefert. In diesem Beispiel liefert die Query als Ergebnis Objekte der Klasse Contact zurück.

Intern erstellt Restlet einen GET-Request auf  „/ContactSet“ relativ zur URI des Organisationsdatendienstes. Als Antwort erhält es ein Dokument im AtomXML Format, welches über die Query geparst wird, die schließlich die Ergebnisse bereitstellt.

In Zeile 2 wird die Query implizit über den Zugriff mittels eines Iterators ausgeführt. Alternativ kann die Ausführung auch über service.execute() angestoßen werden.

Würde im Beispiel die Id des Kontaktes bei der Erzeugung der Query weggelassen werden, so würde diese die Menge aller Kontakte zurückliefern:

Hinzufügen einer neuen Entität

Dieses Beispiel zeigt, wie eine neuer Kontakt erstellt und im CRM hinzugefügt werden kann.

Als erstes wird ein neues Contact Objekt erzeugt und die entsprechenden Werte für Id, Vor- und Nachname gesetzt. Anschließend kann mit Hilfe der service.addEntity() Methode der Kontakt im CRM hinzugefügt werden. Die Serviceklasse besitzt für jede vorhandene Entität eine solche addEntity() Methode.

Bei der Ausführung von addEntity() wird ein POST-Request auf die zugehörige Entitätsmenge gesendet, in diesem Fall auf „/ContactSet“.

Eine Besonderheit im Beispiel stellen die Zeilen 7-9 dar. Hier wird dem Kontakt ein Land hinzugefügt. Da Land aber eine eigenständige Entität ist, muss dieses über eine Beziehung zugeordnet werden. Dafür wird ein EntityReference-Objekt erzeugt und die Id des entsprechenden Landes zugewiesen. Schließlich wird das Reference-Objekt am Kontakt gesetzt. CountryId ist hierbei das Feld im CRM, welches die Beziehung zum Land speichert.

Aktualisieren einer Entität

Im folgenden Beispiel wird demonstriert, wie die Daten eines Kontaktes geändert werden können.

Zunächst wird ein Kontakt abgefragt (siehe Abfrage einer einzelnen Entität). Anschließend wird der Nachname des Kontaktes geändert. Mit service.updateEntity() wird der Kontakt schließlich im CRM aktualisiert.

Die Methode updateEntity() sendet einen PUT-Request an die entsprechende Entitätsmenge. Da im Request die Id in der gleichen Form wie bei der Query-Erstellung benötigt wird, muss sie um den Präfix „guid“ und einfache Anführungszeichen erweitert werden. Dies geschieht im Beispiel in Zeile 5, wobei die Id der Entität im CRM selbst davon unberührt bleibt.

Hinweis: Wird der Kontakt vorher nicht vollständig abgefragt (z.B. durch Projektion), werden mit updateEntity() die leeren Felder auch mit übertragen und damit deren Werte im CRM gelöscht. Dies kann mit Hilfe einer selbst erstellten Update-Methode, die einen MERGE-Request sendet, umgangen werden.

Löschen einer Entität

Das Beispiel zeigt, wie ein spezieller Kontakt gelöscht werden kann.

Zum Löschen wird die Methode service.deleteEntity() verwendet. Ihr wird die Entitätsmenge und die Id des zu entfernenden Kontaktes als String in der selben Form wie bei der Erstellung einer Query übergeben.

Alternativ kann der Methode auch der abgefragte Kontakt direkt übergeben werden. Hierbei muss jedoch darauf geachtet werden, dass die Id vorher wiederum um den Präfix „guid“ und einfache Anführungszeichen erweitert wird.

 

Eine Antwort zu “Zugriff auf Microsoft Dynamics CRM 2011 mit Java – Teil II”

  1. […] In diesem Artikel erläutere ich, wie mit Hilfe von RESTlet speziellere Abfragen an das Microsoft Dynamics CRM durchgeführt werden können. Dieser Teil dient als Fortsetzung zu Zugriff auf Microsoft Dynamics CRM 2011 mit Java – Teil II. […]

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.