CRM und Inbound-Marketing Blog

Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll einsetzen

Bild_Blogartikel_Web API(Bildquelle: Canva)

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:

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.(Bildquelle: infinitas GmbH / bei allen nachfolgenden Darstellungen handelt es sich ebenfalls um Bildquellen der infinitas GmbH)

 

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:

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

 

Tipps & Tricks rund um Microsoft Dynamics 365: In unserem Self-Service-Bereich  erhältst Du weitere Informationen zum Thema CRM. »

 

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.

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

 

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:

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

 

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:

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

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.

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

 

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.

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

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:

So setzen Sie Web-API-Funktionen in Microsoft Dynamics 365 sinnvoll ein.

 

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.

 

Self-Service Microsoft Dynamics 365
 
Diese Blogartikel könnten Dich ebenfalls interessieren: 

Themen: Arbeiten mit Microsoft Dynamics 365 CRM