16 Jan 2020

Wenn Sie den Wert eines Microsoft Dynamics 365 JavaScript-Felds auslesen wollen, würden Sie eine Web API verwenden, nicht wahr? Ich habe das auf jeden Fall so gemacht, nicht wissend, dass sich die Aktivitätsparteifelder nicht direkt in einer Web API ablesen lassen.

Anders als die meisten Entitäten im Microsoft Dynamics 365 haben Aktivitätsentitäten viele ungewöhnliche Beziehungen und Feldtypen. Aber keine Sorge, ich lasse Sie nicht in die gleiche Falle tappen. In diesem Blogbeitrag will ich Ihnen zeigen, wie Parteilistenfelder mit einer Web API ausgelesen werden können.


Was ist eine Aktivität?

Zuvor sollten wir allerdings klären, was Aktivitäten sind. Aktivitäten sind Vorgänge, die Nutzer in Microsoft Dynamics CRM ausführen. Oft werden sie verwendet, um den Kontaktverlauf mit Kunden nachverfolgen zu können.

In Dynamics CRM gibt es viele verschiedene Aktivitäten:

  • Telefonanruf
  • Aufgabe
  • Brief
  • E-Mail
  • Besprechung
  • Fax

Bei der Erstellung einer Aktivität wird ein entsprechender Eintrag für einen Aktivitätszeiger generiert.

Aktivitätsentitäten fungieren sozusagen als Schnittstelle zwischen primären Entitäten und benutzerdefinierten Aktivitäten.


Was ist eine Aktivitätspartei?

Nachdem wir nun wissen, was eine Aktivität ist, schauen wir uns an, wie eine Aktivitätspartei definiert wird.

Eine Aktivität kann mehrere Aktivitätsparteien haben. Es ist eine spezielle Entität, die die verschiedenen Parteien speichert, die jedem Aktivitätstyp zugeordnet sind. Vielleicht haben Sie schon ein spezielles Feld mit dem Typ „Parteiliste“ in allen Aktivitätsentitäten gesehen.

Das Dynamics-365-Feld Aktivitätspartei-Liste ist ein spezielles Auswahlfeld, das auf mehrere Entitäten verweist.

Dieses Feld ist in der Web API für die Entität nicht direkt sichtbar. Um diese Menge an Entitätsverweisen zu speichern, hat Microsoft einen speziellen Entitäten-Typ namens Aktivitätspartei eingerichtet.

Zur Aktivitätspartei gehört das spezielle Feld Party Id., das mehrere Entitätsreferenzen, wie Nutzer, Kontakt, Account, Lead usw., speichern kann.

Microsoft definiert eine Aktivitätspartei wie folgt: „Eine Aktivitätspartei stellt eine Person oder Gruppe dar, die einer Aktivität zugeordnet ist”.

Wo werden diese Parteilisten verwendet? Aktivitätsparteien werden in Microsoft Dynamics 365 am häufigsten bei An und Von in einer Aktivität verwendet, z.B. bei E-Mails oder Briefen.

Hier werden Aktivitätsparteien verwendet, weil eine E-Mail mehrere E-Mail-Adressen im Empfänger-Feld haben kann, etwa im CC.

Beispiele für Parteilistenfelder sind An, Cc, Bcc, Teilnehmer usw.


Wie man Werte aus einer Web API/JavaScript ausliest

Nun kommen wir dazu, wie diese Werte mit einer Web API/JavaScript ausgelesen werden können.

Es gibt 11 Arten von Aktivitätsparteien im Microsoft Dynamics 365. Der Aktivitätsparteientyp ist als Integer-Wert in ActivityParty.ParticipationTypeMask angelegt.

Die folgende Tabelle listet die unterschiedlichen Aktivitätsparteitypen und den korrespondierenden Integer-Wert für das Attribut ActivityParty.ParticipationTypeMask auf:

Aktivitätsparteityp Wert Beschreibung
Sender (Absender)1Gibt den Absender an.
Empfänger (ToRecipient)2Gibt den Empfänger im Feld An an.
Cc-Empfänger (CCRecipient3Gibt den Empfänger im Feld Cc an.
Bcc-Empfänger (BccRecipient)4Gibt den Empfänger im Feld Bcc an.
Erforderlicher Teilnehmer (RequiredAttendee)5Gibt einen erforderlichen Teilnehmer an.
Optionaler Teilnehmer (OptionalAttendee)6Gibt einen optionalen Teilnehmer an.
Organisator (Organizer)7Gibt den Aktivitätsorganisator an.
Betreff (Regarding)8Gibt das entsprechende Element an.
Besitzer (Owner)9Gibt den Aktivitätsbesitzer an.
Ressource (Resource)10Gibt eine Ressource an.
Kunde (Customer)11Gibt einen Kunden an.

Eine eigene Web API-Suche erstellen

Eine eigene Web API-Suche zu erstellen ist ganz einfach.

  • Zunächst benötigen Sie Zugriff auf die Entität Aktivitätspartei.
  • Geben Sie activityId an. Dieses ist der Globally Unique Identifier (GUID) für Ihre Aktivität (Brief, E-Mail, Aufgabe, usw.).
  • Geben Sie participationtypemask an. Dies ist aus der Tabelle oben ersichtlich, abhängig vom jeweiligen Wert (z.B. Empfänger, Absender, CCEmpfänger, usw.)
  • Außerdem benötigen Sie das Feld PartyId., das GUID für Account/Kontakt/Lead ist. Mit PartyId. kann auch der Entitätstyp bestimmt werden.

Hier sehen Sie den JavaScript-Code, den ich verwendet habe, um die Entitätsdetails für den Empfänger einer Aktivität im Feld An auszulesen:


(async (entityId)=>{
       const activityEntity=await Xrm.Web API.retrieveMultipleRecords("activityparty", "?$filter=_activityid_value eq " + 
       entityId + " and participationtypemask eq 2&$select=_partyid_value,_activityid_value");
       activityEntity.entities
        .map(x => ({
            id: x._partyid_value, 
            entityLogicalName: x['_partyid_value@Microsoft.Dynamics.CRM.lookuplogicalname'], 
            Name: x['_partyid_value@OData.Community.Display.V1.FormattedValue']}))
        .forEach(console.log);  
    }
)('Your entity ID');

Output:

1.	0: {id: "fa8c729e-31b4-e911-a99d-000d3ab34f97", entityLogicalName: "account", Name: "proMX AG"}
2.	1: {id: "0f2ba5cd-34b4-e911-a996-000d3ab311f1", entityLogicalName: "contact", Name: "John Adam"}
3.	2: {id: "7ca6600e-2cb4-e911-a99d-000d3ab31f17", entityLogicalName: "contact", Name: "Manali Kapoor"}

Einfacher als gedacht, oder?

Hoffentlich hilft Ihnen dieser Beitrag beim nächsten Mal, wenn Sie Schwierigkeiten mit Aktivitäten haben.

Answering