In der WebAPI 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 Ihnen, wie Sie diese nutzen können.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 Sie z.B. durch einen Button in Ribbon einen Workflow ausführen möchten, einen Datensatz erstellen usw.. In diesem Blogartikel geht es um die Anwendung von Web-APIs im Kontext von Dynamics 365. Wir zeigen Ihnen 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);
Geben Sie den Entitätsnamen und die Felder, die Sie für den Datensatz festlegen möchten, 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 Sie den Code ausgeführt haben, zeigt Ihnen die Meldung, dass ein neuer Datensatz erstellt wurde:
updateRecord
Dies ist die Syntax, die Sie verwenden, um einen Datensatz zu aktualisieren:
Xrm.WebApi.updateRecord(entityLogicalName, id, data).then(successCallback, errorCallback);
Geben Sie den Entitätsnamen, die ID des Datensatzes und die Felder, die Sie bearbeiten möchten, 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 Sie den Code ausgeführt haben, zeigt Ihnen die Meldung, dass der Datensatz aktualisiert wurde:
deleteRecord
Verwenden Sie die folgende Syntax, um einen Datensatz mit der Web API zu löschen:
Xrm.WebApi.deleteRecord(entityLogicalName, id).then(successCallback, errorCallback);
Geben Sie 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 können Sie einen Datensatz abrufen:
Xrm.WebApi.retrieveRecord(entityLogicalName, id, options).then(successCallback, errorCallback);
- Geben Sie den Entitätsnamen und die ID an.
- Options:
$select: Mit select können Sie die Spalten, die Sie zurückgeben möchten, begrenzen. Wenn Sie diesen Befehl nicht verwenden, werden alle Spalten zurückgegeben.
$expand: Mit expand können Sie 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 Sie dies nicht angeben, 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
Sie können Workflows entweder basierend auf einem Trigger oder als bedarfsabhängigen Prozess ausführen.
Es gibt Fälle, in denen Sie einen Workflow aus dem Code direkt ausführen möchten, 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.
Denken Sie daran, den Workflow als bedarfsabhängigen Prozess auszuführen.
Für den Code brauchen Sie den Namen und die ID des Workflows. Kopieren Sie die ID aus der URL.
Nachfolgend finden Sie den Code, mit dem Sie den Workflow ausführen können. Fügen Sie ihn in Ihre JS-Webressource:
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 das CRM Web API erkunden, um zu erfahren, welche Funktionen zur Verfügung stehen und um die Funktionsweise des CRMs besser zu verstehen.
Je mehr Sie über das Dynamics Web API und die Dynamics-Funktionen wissen, desto besser können Sie die verschiedenen Anpassungen verstehen und vornehmen.
