Microsoft Dynamics CRM Connector

Installation und Konfiguration

Installation

Bevor der Microsoft Dynamics CRM Connector installiert wird, muss sichergestellt werden, dass der Mindbreeze Server bereits installiert ist und dieser Connector auch in der Mindbreeze Lizenz inkludiert ist.

Konfiguration von Mindbreeze

Index

Klicken Sie auf den Reiter “Indices” und dann auf das Symbol “Add new index”, um einen neuen Index zu erstellen (optional).

Geben sie den Indexpfad (“Index Path”) ein. Falls nötig, passen Sie den Anzeigenamen („Display Name“) vom Index Service und dem zugehörigen Filter Service an.

Anschließend die „Advanced Settings“ aktiviert werden.

Folgende „Dynamic Constraints“ müssen konfiguriert werden:

Datenquelle

Setup

Fügen Sie eine neue Datenquelle mit dem Symbol „Add new custom source” (zu finden unten rechts) hinzu.

Connection Settings

Legende:

• Mit * markierte Properties: Pflichtfeld, diese müssen explizit konfiguriert werden
• Nicht speziell markierte Properties: optionale Felder
• Mit (Advanced Settings) markierte Felder werden nur angezeigt, wenn die „Advanced Settings“ Ansicht in der Konfiguration aktiviert ist. Dies ist nur in speziellen Anwendungsfällen notwendig.

Sources

Im letzten Schritt geben Sie an, welche Teiles aus Ihrem CRM in Mindbreeze InSpire indiziert werden sollen.

Gehen Sie zunächst in den Entitätseinstellungen Ihres CRMs. Um alle Entitäten eines bestimmten Entitättyps aus Microsoft Dynamics CRM in Mindbreeze InSpire indizieren zu können, wird der Entitätsname der betreffenden Entität aus Microft Dynamics CRM benötigt.

Der folgende Screenshot zeigt die Konfiguration des Entitättyps „Opportunity“ (im deutschen CRM „Verkaufschance“) in Microsoft Dynamics CRM. In diesem Beispiel sollen alle Verkaufschancen (im Screenshot blau umrandet) indiziert werden, wobei der Microsoft Dynamics CRM Connector den internen Namen des Entitättyps benötigt (Name „opportunity“, im Screenshot rot umrandet).

Zusätzlich wird der interne Names des Hauptfeld für die Konfiguration des Connectors benötigt (im folgenden Screenshot rot umrandet).

Welchseln Sie wieder zu den Datenquellen-Einstellungen in Mindbreeze InSpire und geben Sie alle Entitättypen im Feld „Entity Types“ – getrennt mit einem Zeilenumbruch – ein , die sie indizieren wollen. Wollen Sie alle Verkaufschancen indizieren, so geben Sie in eine neue Zeile im Feld „Entity Types“ den Wert „opportunity“ ein.

Zu jedem eingetragenen Entity Type muss das Hauptfeld im Feld „Primary Name Attributes“ eingetargen werden. Die erste Zeile von „Entity Types“ ist also verknüpft mit der ersten Zeile von „Primary Name Attributes“; die zweite Zeile von „Entity Types“ ist verknüpft mit der zweiten Zeile von „Primary Name Attributes“ und so weiter. Da in diesem Beispiel „opportunity“ in der letzten Zeile vom Feld „Entity Types“ steht, muss das dazugehörende Hauptfeld „name“ in der letzten Zeile vom Feld „Primary Name Attributes“ stehen.

Mit dem Advanced Setting „Skip Downloading ACL Information” kann man das Herunterladen von ACL-Informationen deaktivieren. Dies führt dazu, dass keine Berechtigungs-Informationen heruntergeladen werden. Diese Option sollte nur in Kombination mit der Index-Einstellung „Unrestricted Public Access“ verwendet werden und nur, wenn öffentlicher Zugriff aller Dokumente explizit gewünscht ist.

Mit dem Advanced Setting „Add Entity Prefix to Key“ werden die Keys aller Dokumente mit dem Entitytyp prefixiert. Damit können eventuelle Keykonflikte vermieden werden.

Mit dem Advanced Setting „Entity Relation Resolution“ kann man zusätzlich noch Datenbankbeziehungen auflösen und die Metadaten der verbundenen Entity in dem Dokument mitindizieren.

Dazu sind folgende Einstellungen notwendig:

Entity Name: Der Name der Entity, von dem die Beziehung ausgeht. Dieser Name muss im Konfigurationsfeld „Entity Types“ enthalten sein.

Foreign Key Column Name: Der Name des Attributes, welche die Referenz auf die andere Entity beinhaltet.

Referenced Entity Name: Der Name der Entity, auf die die Referenz zeigt.

Referenced Column Name: Der Name des Attributes, auf den der Foreign Key der ursprünglichen Entity zeigt, normalerweise eine unique ID der Entity.

Mit dem Setting „Foreign Metadata Prefix“ können die Metadaten der verbunden Entity geprefixt werden.

In CRM finden Sie alle diese Paramter in den Entitätseinstellungen.
In diesem Beispiel wird die Beziehung zwischen Account und Currency aufgelöst:

Die Namen der Entites lassen sich wie oben für das Setting „Entity Types“ finden.
Für die Column Names, suchen Sie zuerst bei den Relationships der Entität nach der Relationship die aufgelöst werden soll:

Wenn Sie die Beziehung öffnen, sehen Sie bei „Lookup Field“ das Feld „Name“. Setzen Sie diesen als „Foreign Key Column Name“.

Der „Referenced Column Name“ ist normalerweise der Primary Key der referenzierten Entity. Meistens ist der Name dieser Column einfach der Name der Entity + „id“. Dies können sie bei den „Fields“ der Entity überprüfen:

Die vollständige Konfiguration von diesem Beispiel sieht dann folgendermaßen aus:

Mit diesem Feature können Sie auch ohne Probleme mehrer Beziehungen pro Entity auflösen.

Falls Sie dieses Feature verwenden, sollten Sie die folgenden Dinge beachten:

Die ACLs der verbundenen Entity werden nicht beachtet, das indizierte Dokument verwendet nur die ACLs der ursprünglichen Entity. Daher sollten sie mit diesem Feature keine Verbindungen zu Entities mit sensiblen Daten auflösen.

Diese Feature unterstützt 1:1 und N:1 Beziehungen. Wenn die Verbindung mit einer anderen Entity mehr als ein Ergebnis pro Eintrag zurückbringt, kann das zu unerwarteten Ergebnissen führen.
Bei 1:N Beziehungen können Sie stattdessen die N Seite indizieren und mit der 1 Seite verbinden, um dieses Problem zu umgehen.

Falls Sie das Setting „Foreign Table Metadata Prefix“ ändern oder eine konfigurierte Entity Relation Resolution entfernen, sollten Sie einen vollständigen Re-index durchführen, ansonsten kann es zu unerwarteten Ergebnissen kommen.

Error Handling (Advanced Settings)

Die folgenden Optionen betreffen die Fehlerbehandlung und Troubleshooting. Konfigurieren Sie diese Settings nur, wenn Sie Probleme beim Indizieren haben.

Performance Settings (Advanced Settings)

Die folgenden Optionen betreffen die Verarbeitungsgeschwindigkeit des Crawlers. Ändern Sie diese Settings nur, falls Sie Probleme mit dem Crawl-Run haben.

Principal Resolution Service

Um feststellen zu können, welche Benutzer welche Entitäten in Mindbreeze sehen dürfen, muss ein PrincipalResolutionService unter Services hinzugefügt werden.

In der Drop-Down-Liste Service muss „Microsoft Dynamics CRM Principal Resolution“ ausgewählt werden.

Im Feld Bind port muss ein freier Port angegeben werden.

Mit der Option „ACL Cache Expires Minutes“ kann definiert werden, nach wie vielen Minuten die gecasheden Rechteinformationen ablaufen und wieder vom CRM heruntergeladen werden müssen.

Mit der Option „Resolve msDS-PrincipalNames“ wird ein LDAP Server verwendet, um die E-Mail-Adressen von den angemeldeten Benutzern im Mindbreeze Inspire Search Client in msDS-PrincipalNames umzuwandeln. Das ist notwendig, wenn die Usernames im Microsoft Dynamics CRM auch msDS-PrincipalNames sind. Bei manchen Microsoft Dynamics CRM Instanzen (z.B. in der Online Version) kann es vorkommen, dass E-Mail-Adressen als Usernames verwendet werden. In diesem Fall müssen Sie diese Option deaktivieren.

Die Optionen „CRM URL“, „Organization Service URL“, „Is Microsoft Dynamics CRM Online“ und „Ignore Proxy“ müssen, wie in Abschnitt „Connection Settings“ beschrieben, konfiguriert werden.

Im nächsten Schritt muss der „Microsoft CRM Principal Service“ zur konfigurierten Datenquelle hinzugefügt werden. Wählen Sie dazu in der Drop-Down-Liste Caching Principal Resolution Service den gerade konfigurierten Service aus.

Wenn die Option „Resolve msDS-PrincipalNames“ aktiviert ist, müssen Sie noch die Konfiguration für den benötigten LDAP Server vornehmen. Wechseln Sie dazu zum Reiter Network und geben Sie bei den LDAP Settings zumindest den Domain Name an.

Im nächsten Schritt muss ein Benutzer unter Credentials konfiguriert werden, der zumindest die Rechte hat, dass er die UPN-Namen aller Benutzer auslesen kann.

Zusätzlich muss unter Endpoints eine Verknüpfung zwischen den LDAP Settings und den hinzugefügten Credentials hergestellt werden. Das Feld Location muss folgendermaßen konfiguriert werden:

dns://<LDAP Server Domain Name>   (z.B. dns://mycompany.com)

Anmeldeinformationen

Wechseln Sie im Mindbreeze Management Center zum Reiter Plugins und fügen Sie unter Credentials die Anmeldeinformationen hinzu:

Nun haben Sie 2 Möglichkeiten, um das angelegte Credential mit dem Crawler und dem Principal Resolution Service zu verknüpfen:

1. Wählen sie das Credential mit der Option „Credential“ in der Crawler und in der Principal Resolution Service Konfiguration aus oder
   
2. fügen Sie unter Endpoints einen neuen Endpunkt hinzu. Im Feld Location geben Sie die CRM URL an. Im Drop-Down-Feld Credential wählen Sie die gerade konfigurierten Anmeldeinformationen aus.
   

Achtung: Je nachdem, ob Sie eine On Premises Installation oder Microsoft Online verwenden, müssen die Anmeldeinformationen (Credentials) unterschiedlich konfiguriert werden (Username/Passwort oder OAuth 2). Die Art der Authentifizierung wird automatisch vom Connector erkannt, je nachdem, wie Sie den Connector konfiguriert haben. In der folgenden Tabelle finden Sie in der ersten Spalte die verschiedenen Arten der Authetifizierung und in den Spalten rechts daneben, welche Felder in der Credentials Konfiguration ausgefüllt werden müssen (X ist Pfilchtfeld, geklammertes (X) ist ein optionales Feld). Es ist unbedingt erfolderlich, dass die mit X merkierten Felder konfiguriert werden, damit die Authentifizierungsart erkannt werden kann. Bitte lesen Sie dazu auch die folgenden Abschnitte.

Authentifizierung: On Premises

Wenn Sie eine On Premises Installation verwendet und die Option „Is Microsoft Dynamics CRM Online” deaktiviert haben, eignet sich diese Authentifizierungsmethode.

Legen Sie einen neuen Account für Microsoft Dynamics CRM an oder verwenden Sie einen bestehenden. Dieser Account muss für alle für das Crawling relevanten Daten im CRM die benötigten Leserechte haben. Am besten eignet sich dazu ein Read-Only-Administrator-Account.

Credentials:

Nun können Sie das Credential im Mindbreeze Management Center im Network Tab konfigurieren, wie im Abschnitt „Anmeldeinformationen“ beschrieben. Wichtig ist, dass Sie folgende Felder konfigurieren:

• Type: Username/Password
• Username
• Domain (optional)
• Password

Authentifizierung: Kerberos on Premises

Wenn Sie eine On Premises Installation verwendet haben und die Option „Is Microsoft Dynamics CRM Online” deaktiviert haben, ist diese Authentifizierungsmethode möglich.

Erstellen Sie ein neues Konto für Microsoft Dynamics CRM oder verwenden Sie ein bestehendes Konto. Dieses Konto muss über die erforderlichen Leserechte für alle Daten in CRM verfügen, die für das Crawling relevant sind. Am besten eignet sich hierfür ein Read-Only-Administrator-Account.

Um die Kerberos-Authentifizierung auf der Mindbreeze Appliance zu konfigurieren, befolgen Sie zunächst die Anweisungen in der Kerberos-Authentifizierung Dokumentation, um die Connector Keytab-Datei zu erstellen, und laden Sie diese im MMC im Menüpunkt „Configuration“ unter der Registerkarte „Authentication“ hoch.

Aktivieren Sie danach im Bereich „Global Kerberos Settings“ die Option „SNEGO based Kerberos“ und legen Sie die hochgeladene keytab-Datei und das Principal für den Microsoft Dynamics CRM Connector und den Microsoft Dynamics CRM Principal Resolution Service fest. Achten Sie beim Festlegen des Principals auf die Groß- und Kleinschreibung.

Authentifizierung: Microsoft Online OAuth 2 Client Credentials (empfohlen für Microsoft Online)

Wenn Sie eine Microsoft Online Dynamics Instanz haben und die Option „Is Microsoft Dynamics CRM Online” aktiviert haben, wird diese Authentifizierungsmethode empfohlen. Diese Authentifizierungsmethode eignet sich auch, wenn Sie einen föderierten IDP (z.B. Okta) im Einsatz haben, über den sich die Benutzer normalerweise anmelden.

Bei dieser Authentifizierungsmethode wird kein echter Benutzer benötigt, sondern eine Azure App und ein Service-Benutzer in Dynamics. Zum Einrichten gehen Sie bitte wie folgt vor:

Azure App einrichten

Loggen Sie sich bei https://portal.azure.com ein und erstellen Sie im „Azure Active Directory“ eine App, indem Sie unter „App registrations“ auf „New registration“ klicken. Eine Redirect URI wird nicht benötigt.

Erstellen Sie anschließend ein Client Secret im Menü „Certificates & secrets“ und notieren Sie sich das erstellte Client Secret.

Wechseln Sie anschließend zur „Overview“ und notieren Sie sich die „Application (client) ID“ (= Client ID) und den OAuth2 Token Endpoint (v1) oder (v2).

Application User einrichten

Legen Sie nun einen Application User in Dynamics ein, der mit der Azure App verknüpft wird. Gehen Sie dazu in den Dynamics Settings auf „Security“ „Users“ und wechseln Sie zur „Application Users“ Ansicht. Klicken Sie anschließend auf „New“ und fügen Sie „Application ID“ der Azure App ein. Weisen Sie anschließend eine „security role“ zu, um alle für das Crawling relevanten Zugriffe zu bekommen. Am besten eignet sich dafür eine Read-Only Administrator Rolle.

Credentials im Mindbreeze Management Center

Nun können Sie das Credential im Mindbreeze Management Center im Network Tab konfigurieren, wie im Abschnitt „Anmeldeinformationen“ beschrieben. Wichtig ist, dass Sie folgende Felder konfigurieren:

• Type: OAuth 2
• Access Token URL
• Client ID
• Client Secret

Authentifizierung: Microsoft Online WS-Trust mit Username/Passwort (deprecated)

Wenn Sie eine Microsoft Online Dynamics Instanz haben und die Option „Is Microsoft Dynamics CRM Online” aktiviert haben, kann diese Authentifizierungsmethode verwendet werden.

Achtung: Diese Authentifizierungsmethode ist von Microsoft deprecated und wird von neuen Instanzen nicht mehr unterstützt. Verwenden Sie stattdessen OAuth 2 Client Credentials (siehe oben).

Wenn Sie aus irgendeinem Grund trotzdem diese Authentifizierungsart verwenden möchten, gehen Sie bitte wie folgt vor: Legen Sie einen neuen Account für Microsoft Dynamics an oder verwenden Sie einen bestehenden. Dieser Account muss für alle für das Crawling relevanten Daten im Dynamics die benötigten Leserechte haben. Am besten eignet sich dazu ein Read-Only-Administrator-Account.

Testen Sie anschließen den Account, indem Sie sich in Ihr Microsoft Dynamics einloggen und prüfen Sie, ob sie alle für das Crawling relevanten Daten sehen können.

Credentials:

Nun können Sie das Credential im Mindbreeze Management Center im Network Tab konfigurieren, wie im Abschnitt „Anmeldeinformationen“ beschrieben. Wichtig ist, dass Sie folgende Felder konfigurieren:

• Type: Username/Password
• Username (Email)
• Password

Synthesized Metadata

In Microsoft Dynamics CRM stehen Entitäten oft in Bezug zu anderen Entitäten (oft auch zu Entitäten eines anderen Entität-Typs). Um Attribute der verknüpften Entität im Suchclient anzeigen zu können, müssen „Synthesized Metadata“ konfiguriert werden. Dazu müssen zuerst die „Advanced Settings“ aktiviert werden.

Klicken Sie auf das Symbol „Add Composite Property“ und vergeben Sie einen Namen für das referenzierte Attribut im Feld „Name“.

Die Verknüpfung wird im Feld „Property Expression“ mit folgendem Muster hergestellt: mscrm_<Fremdschlüssel-Attribut>/mscrm_<Attribut im Referenzierten Dokument>.

Im „categoryDescriptor.xml“ kann der Name (im Screenshot „mscrm_parentcustomer_name“) dann als Metadatadatums-ID verwendet werden.

Must-Have Synthesized Metadata

Folgende Synthesized Metadata Definitions müssen konfiguriert werden, da diese im standardmäßig mitgelieferten „categoryDescriptor.xml“ verwendet werden:

1. Name: mscrm_parentaccount_name
   Property Expression: mscrm_parentaccountid/mscrm_name
   
2. Name: mscrm_owninguser_fullname
   Property Expression: mscrm_owninguser/mscrm_fullname
   
3. Name: mscrm_parentcontact_fullname
   Property Expression: mscrm_parentcontactid/mscrm_fullname

Appendix

Troubleshooting

Wenn Sie Probleme bei der Indizierung haben, können folgende Tipps hilfreich sein:

• Überprüfen Sie die Anmeldeinformationen. Sind diese korrekt? Verwenden Sie die richte Art der Anmeldung (On Premises versus Microsoft Online)?
• Sind die konfigurierten URLs korrekt?
• Möglicherweise soll der konfigurierte Proxy vom „Network“-Tab nicht verwendet werden. Sie können dazu die Option „Ignore Proxy“ konfigurieren.
• Bricht der Crawl Run nach einiger Zeit ab, da es z.B. ein Read-Timeout gegeben hat? Dabei kann es helfen, dass Sie die „Page Size“ auf einen niedrigeren Wert setzen. Sie können auch versuchen, „Maximum Download Retries“ und „Connection Timeout (Seconds)“ auf einen höheren Wert zu stellen oder „Ingnore Unsuccessful Entity Types“ aktivieren, damit zumindest versucht wird, Inhalte von anderen Tabellen zu indizieren.