In der Web-API von Microsoft Dynamics 365 stehen vordefinierte Funktionen zur Verfügung, die den Entwicklern helfen, mit wenigen Codezeilen verschiedene Aktionen im CRM auszuführen und dadurch zeitaufwendiges und komplexes Coding zu sparen. In diesem Blogartikel gehen wir auf die vordefinierten Funktionen in der Web-API von Microsoft Dynamics 365 ein und zeigen Dir, wie Du diese nutzen kannst.API steht für „Application Programming Interface” und bildet sozusagen die Schnittstelle zwischen zwei Anwendungen, sodass diese beiden miteinander kommunizieren können.
Beispiele für die Verwendung von Dynamics 365 Web-APIs
Es kann vorkommen, dass Du z.B. durch einen Button in Ribbon einen Workflow ausführen möchtest, einen Datensatz erstellen usw.. In diesem Blogartikel geht es um die Anwendung von Web-APIs im Kontext von Dynamics 365. Wir zeigen Dir verschiedene Beispiele für die Verwendung von Dynamics-365-Web-APIs wie z.B. Erstellen, Aktualisieren, Löschen und Abrufen von Datensätzen und Ausführen eines Workflows:
createRecord
Die nachfolgende Funktion erstellt einen neuen Datensatz im CRM:
Xrm.WebApi.createRecord(entityLogicalName, data).then(successCallback, errorCallback);
Gib den Entitätsnamen und die Felder, die Du für den Datensatz festlegen möchtest, in einem JSON-Objekt namens data an:
var data = {
"subject": "createRecord",
"firstname": "Jalal",
"lastname": "Heidari"
}
Xrm.WebApi.createRecord("lead", data).then(
function success(result) {
alert ("Das neue Lead mit der ID: " + result.id + "wurde angelegt.");
},
function(error){
alert("Error: " + error.message);
}
)
Nachdem Du den Code ausgeführt hast, zeigt Dir die Meldung, dass ein neuer Datensatz erstellt wurde:
updateRecord
Dies ist die Syntax, die Du verwendest, um einen Datensatz zu aktualisieren:
Xrm.WebApi.updateRecord(entityLogicalName, id, data).then(successCallback, errorCallback);
Gib den Entitätsnamen, die ID des Datensatzes und die Felder, die Du bearbeiten möchtest, in data an:
var data =
{
"subject": "updateRecord"
}
Xrm.WebApi.updateRecord("lead", "989d606f-d4ed-eb11-bacb-000d3ade7f5f", data).then(
function success(result) {
alert("Das Lead wurde aktualisiert.");
},
function (error) {
console.log(error.message);
}
)
Nachdem Du den Code ausgeführt hast, zeigt Dir die Meldung, dass der Datensatz aktualisiert wurde:
deleteRecord
Verwende die folgende Syntax, um einen Datensatz mit der Web API zu löschen:
Xrm.WebApi.deleteRecord(entityLogicalName, id).then(successCallback, errorCallback);
Gib den Entitätsnamen und die ID des Datensatzes an:
Xrm.WebApi.deleteRecord("lead", "989d606f-d4ed-eb11-bacb-000d3ade7f5f").then(
function success(result) {
alert("Das Lead wurde gelöscht.");
},
function (error) {
alert(error.message);
}
)
Nach dem Ausführen wird der Datensatz gelöscht.
retrieveRecord
Mit folgender Syntax kannst Du einen Datensatz abrufen:
Xrm.WebApi.retrieveRecord(entityLogicalName, id, options).then(successCallback, errorCallback);
Gib den Entitätsnamen und die ID an, für options gibt es folgende Möglichkeiten:
- $select: Mit select kannst Du die Spalten, die Du zurückgeben möchtest, begrenzen. Wenn Du diesen Befehl nicht verwendest, werden alle Spalten zurückgegeben.
- $expand: Mit expand kannst Du steuern, welche Daten von verwandten Entitäten zurückgegeben werden.
In diesem Beispiel soll die Website der verknüpften Firma mit dem Kontakt (eeeccfa3-d9ed-eb11-bacb-000d3ade7f5f) und dem Namen des Kontaktes abgerufen werden.
Xrm.WebApi.retrieveRecord("contact", "eeeccfa3-d9ed-eb11-bacb-000d3ade7f5f", "?$select=lastname&$expand=parentcustomerid_account($select=websiteurl)").then(
function success(result) {
alert("Nachname: " + result.lastname + ", Website: " + result.parentcustomerid_account.websiteurl);
},
function (error) {
alert(error.message);
}
)
Wenn wir dies ausführen, sehen wir:
retrieveMultipleRecords
Diese Methode gibt eine Sammlung von Datensätzen aus dem CRM zurück:
Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback)
- Options: Hier werden folgende Optionen unterstützt: $select, $top, $filter, $expand, $orderby.
- MaxPageSize: Das ist die Anzahl der zurückgegebenen Datensätze. Wenn Du dies nicht angibst, wird der Wert auf 5.000 Datensätze gesetzt.
In einem Beispiel rufen wir alle Firmen, die in Hannover sind, ab:
Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$filter=address1_city eq 'Hannover'").then(
function success(result) {
for (var i = 0; i < result.entities.length; i++) {
alert(result.entities[i].name);
}
},
function(error) {
alert("Error: " + error.message);
}
)
Nach dem Ausführen wird das Ergebnis als ein Array dargestellt:
In allen Beispielen ist die Angabe der „entityLogicalName“ und „Options notwendig“ und der Rest ist optional.
executeWorkflow - Ausführen eines Workflows mit Web-API
Du kannst Workflows entweder basierend auf einem Trigger oder als bedarfsabhängigen Prozess ausführen.
Es gibt Fälle, in denen Du einen Workflow aus dem Code direkt ausführen möchtest, z.B. mit einem Klick auf einen benutzerdefinierten Button. Dazu kann der Workflow über Web-API bzw. die ExecuteWorkflow ausgeführt werden.
Bis Dynamics CRM 2016 (8.1) war ExecuteWorkflow nicht über Web-API verfügbar. Aber mit Dynamics 365 steht jetzt die ExecuteWorkflow zur Verfügung.
In unserem Beispiel erstellen wir eine Anfrage, wodurch ein benutzerdefinierter Workflow, der einen Termin für den Kontakt erstellt, ausgeführt wird.
Denke daran, den Workflow als bedarfsabhängigen Prozess auszuführen.
Für den Code brauchst Du den Namen und die ID des Workflows. Kopiere die ID aus der URL.
Nachfolgend findest Du den Code, mit dem Du den Workflow ausführen kannst. Füge ihn in Deine JS-Webressource ein:
function executeWorkflow(executionContext){
var formContext = executionContext.getFormContext();
var entityID = formContext.data.entity.getId().replace("{", "").replace("}", "");
var workflowId = "{d2192498-56a2-4918-bb9a-e3f361c3e40a}"; // Workflow-ID
var functionName = ""; // Funktionsname
var query = "";
try {
// Abfrage zum Ausführen des Workflows definieren
query = "workflows(" + workflowId.replace("}", "").replace("{", "") + ")/Microsoft.Dynamics.CRM.ExecuteWorkflow";
var data = {
"EntityId": entityID
};
// Anfrage erstellen
var req = new XMLHttpRequest();
req.open("POST", Xrm.Page.context.getClientUrl() + "/api/data/v9.0/" + query, false);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.onreadystatechange = function () {
if (this.readyState == 4) {
req.onreadystatechange = null;
if (this.status == 200) {
//success callback
var result = JSON.parse(this.response);
formContext.ui.setFormNotification("Der Workflow '"+ functionName +"' wurde erfolgreich ausgeführt.", "INFORMATION")
} else {
//error callback
var error = JSON.parse(this.response).error;
}
}
};
req.send(JSON.stringify(data));
} catch (e) {
alert("Ein Fehler ist aufgetreten - Funktionsname: :" + functionName + "Error:" + e)
}
}
Nach dem Ausführen wurde der Termin erstellt und mit dem Kontakt verknüpft:
Zusammenfassung
Die Web-API ist der unterstützte Weg, um mit der Microsoft Dynamics Datenbank zu interagieren.
Wir empfehlen, dass die CRM-Entwickler zunächst die CRM Web-API erkunden, um zu erfahren, welche Funktionen zur Verfügung stehen und um die Funktionsweise des CRMs besser zu verstehen.
Je mehr Du über die Dynamics Web-API und die Dynamics-Funktionen weißt, desto besser kannst Du die verschiedenen Anpassungen verstehen und vornehmen.
