AUTOMATISIERUNG DES ONBOARDING …...Integrationsszenarien, wie dieses, ist im Microsoft-Universum...
67
1 AUTOMATISIERUNG DES ONBOARDING-PROZESSES EINES NEUEN MITARBEITERS MIT HILFE VON MODERNEN INTEGRATIONSTECHNOLOGIEN
Transcript of AUTOMATISIERUNG DES ONBOARDING …...Integrationsszenarien, wie dieses, ist im Microsoft-Universum...
1
AUTOMATISIERUNG DES ONBOARDING-PROZESSES
EINES NEUEN MITARBEITERS MIT HILFE VON MODERNEN
INTEGRATIONSTECHNOLOGIEN
1
INHALTSVERZEICHNIS
1 Einfuumlhrung 2
11 Motivation 2
12 Herangehensweise 2
2 Durchfuumlhrung 4
21 Einfuumlhrung 4
22 Vorbereitung 5
221 Dynamics 365 CRM 5
222 WCF Service 14
223 BizTalk Server Development 19
2
1 EINFUumlHRUNG
11 Motivation
Die eBiz Consulting GmbH (eBiz) ist Microsoft Gold Partner mit den Schwerpunkten Integration
Automation und Kollaboration Dazu buumlndelt die eBiz ihre Leistungen in den zwei Bereichen
Systemintegration und Teamintegration
Kollaboration im Microsoft-Umfeld bedeutet natuumlrlich dass das Oumlkosystem um Office 365 zu den
taumlglichen Arbeitsmitteln in der Firma gehoumlrt Daher gehoumlrt es gleichermaszligen natuumlrlich zum
Aufnahmeprozess eines neuen Mitarbeiters in der Firma dass der Mitarbeiter eine O365-Lizenz
bekommt und in die Domaumlne der eBiz aufgenommen wird Uumlber die O365 Lizenz wird fuumlr den
Mitarbeiter eine persoumlnliche Mailbox erstellt und der Zugriff auf verschiedene Tools und Apps
ermoumlglich (SharePoint Team Skype4Business)
Nun ist es ein lang gehegter Wunsch des einzigen Administrators in der Firma dass neue Mitarbeiter
nicht mehr manuell angelegt werden muumlssen sondern dass die dazu noumltigen Schritte automatisch
erfolgen Das hat weniger etwas mit einer natuumlrlichen Mitarbeiter-Fluktuation in der Firma zu tun
als vielmehr damit dass manuelle Prozesse generell anfaumlllig fuumlr Fehler sind So moumlchte man
sicherstellen dass jeder neuer Mitarbeiter vom ersten Arbeitstag an Zugriff auf seine Arbeitsmittel
hat auch wenn der Administrator durch Dinge wie Urlaub Krankheit oder Kaffee in der Tastatur
verhindert ist
12 Herangehensweise
Bevor eine Person zum Mitarbeiter der eBiz wird hat sie sich in aller Regel vorher bei der eBiz
beworben Ein denkbarer Kanal dafuumlr waumlre zB die Bewerbung via E-Mail
Wer sich bei der eBiz bewirbt wird innerhalb des CRM-Systems MS Dynamics 365 CRM als
Contact-Objekt DSGVO konform angelegt das Daten wie Name Adresse und Telefonnummer
beinhaltet - dieselben Daten die auch bei der O365-Provisionierung gebraucht werden dort aber
haumlndisch eingetippt werden muumlssen
Das haumlndische Eintippen zu vermeiden ist das Ziel der Software-Loumlsung die im Rahmen dieses
Artikels prototypisch entwickelt wird
Es geht darum Contacts die gewisse Kriterien erfuumlllen (Einstellung erfolgt und damit technsich
isEmployee == true) aus dem CRM herauszuholen und dann fuumlr Folgeprozesse (wie eben die
Provisionierung in Office 365 und Azure) wieder zu verwenden Dazu muss ein Nachrichtenfluss
geschaffen werden der verschiedene Applikationen integriert Das bevorzugte Werkzeug fuumlr
Integrationsszenarien wie dieses ist im Microsoft-Universum der BizTalk Server inklusive seiner
Peripherietechnologien (NET PowerShell WCF SQL Server Azure)
Der geplante Ablauf soll durch die folgende Darstellung verdeutlicht werden
3
Co
nta
ct
GetC
on
tact
(Cri
tera
)
Sta
tus
Pro
visi
on
(Co
nta
ct)
Contact
Criteria
BizTalk ermoumlglicht eine Uumlberpruumlfung ob ein Kontakt mit dem Status IsEmployee == true in
Dynamics vorhanden sind holt diesen dann ab und verwendet die Daten um die Provisionierung in
O365 durchzufuumlhren
4
2 DURCHFUumlHRUNG
21 Einfuumlhrung
Dieser Artikel stellt ein Integrationsszenario mit BizTalk Server sowie eine entsprechende
Vorgehensweise zur Umsetzung vor
Erforderliche Grundkenntnisse
bull BizTalk Server
bull C und NET
bull Windows Communication Foundation (WCF)
bull Windows PowerShell
bull Azure Administration
bull OAuth 20 Azure Active Directory
bull Rest JSON und OData
bull MS Dynamics 365 CRM
Voraussetzungen
bull Azure Subscription
bull VMRechner mit installiertem BizTalk Server Stack + Visual Studio
bull Office365 Plan Testlizenz mit Dynamics 365 CRM
Loumlsungsstrategie
Die nachfolgende Darstellung gibt einen Uumlberblick uumlber die Loumlsungsstrategie innerhalb der
geplanten Architektur
Receive MessageBox
Send
Receive
Send
Receive
Contact
CriteriaJSON
1
2
3
4
Die Loumlsungsstrategie beruumlcksichtigt die individuellen Besonderheiten der zu integrierenden Systeme
inklusive Datenformat und Struktur sowie Schnittstellen zu den benoumltigten Ressourcen
Details die daruumlber hinausgehen wurden hier zugunsten der Uumlbersichtlichkeit eingespart und werden
im weiteren Artikelverlauf wieder aufgegriffen
Schritt 1 Eingangskanal fuumlr die Abfragekriterien Einrichten
5
Initial des Prozesses ist das Ablegen einer Datei in einem Ordner Diese Datei beinhaltet die
Information welchen Kriterien (CRM-) Kontakte entsprechen muumlssen um provisioniert zu werden
und liegt im JSON-Format vor
Das JSON-Dokument gelangt durch eine Receive-Pipeline (in der eine Transformation ins XML-
Format erfolgt) in die Messagebox
Schritt 2 Kontakt-Objekt aus Dynamics 365 CRM abholen
Ein Send Port abonniert die Information aus Schritt 1 und verwendet sie um einen API-Call auf
Dynamics zu starten Dynamics gibt als Antwort einen Contact zuruumlck der den Kriterien entspricht
Schritt 3 Provisionierungskanal einrichten
Die ContactXML aus Schritt 2 wird von einem weiteren Send Port abonniert der die Informationen
darin verwendet um einen Webservice anzusprechen der die Logik ausfuumlhrt um die
Provisionierung in Office 365 anzustoszligen O365 gibt daraufhin eine Information uumlber den Verlauf
des Provisionierungsvorgangs zuruumlck und der Status der Provision wird als finaler Output des
Prozesses in der MessageBox abgelegt
Schritt 4 Szenario abschlieszligen
Kontakt-Objekt sowie die Information ob die Provisionierung erfolgreich war befinden sich nun in
der MessageBox Von hier aus koumlnnen die Daten fuumlr weitere Prozesse verwendet werden
(beispielsweise fuumlr ein automatisiertes SharePoint-Announcement Willkommensmail an den neuen
Mitarbeiter etc)
22 Vorbereitung
221 Dynamics 365 CRM
Ein kurzer Ausflug in die Dynamics 365 Galaxie
Die Moumlglichkeit zur Verwaltung von Contacts gehoumlrt standardmaumlszligig zum Produktumfang von
Dynamics 365 Die Contact-Eigenschaft IsEmployee jedoch nicht Das ist aber kein Problem da
Dynamics die Moumlglichkeit bietet den standardmaumlszligig ausgelieferten Datenbestand an die eigenen
Prozesse anzupassen Dazu ist folgendes noumltig
1 Hinzufuumlgen des Attributs bdquoIsEmployeeldquo zur Entitaumlt Contact
2 Anlegen der Dummy Kontakte
3 Zugriffspunkte von Dynamics CRM nutzen
2211 HINZUFUumlGEN DES ATTRIBUTS ISEMPLOYEE ZUR ENTITAumlT CONTACT
Wir rufen httpsportalofficecom auf loggen uns als Administrator unserer O365-Instanz ein und
navigieren dann mit der Maus auf die Kachel gt [Admin]
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
1
INHALTSVERZEICHNIS
1 Einfuumlhrung 2
11 Motivation 2
12 Herangehensweise 2
2 Durchfuumlhrung 4
21 Einfuumlhrung 4
22 Vorbereitung 5
221 Dynamics 365 CRM 5
222 WCF Service 14
223 BizTalk Server Development 19
2
1 EINFUumlHRUNG
11 Motivation
Die eBiz Consulting GmbH (eBiz) ist Microsoft Gold Partner mit den Schwerpunkten Integration
Automation und Kollaboration Dazu buumlndelt die eBiz ihre Leistungen in den zwei Bereichen
Systemintegration und Teamintegration
Kollaboration im Microsoft-Umfeld bedeutet natuumlrlich dass das Oumlkosystem um Office 365 zu den
taumlglichen Arbeitsmitteln in der Firma gehoumlrt Daher gehoumlrt es gleichermaszligen natuumlrlich zum
Aufnahmeprozess eines neuen Mitarbeiters in der Firma dass der Mitarbeiter eine O365-Lizenz
bekommt und in die Domaumlne der eBiz aufgenommen wird Uumlber die O365 Lizenz wird fuumlr den
Mitarbeiter eine persoumlnliche Mailbox erstellt und der Zugriff auf verschiedene Tools und Apps
ermoumlglich (SharePoint Team Skype4Business)
Nun ist es ein lang gehegter Wunsch des einzigen Administrators in der Firma dass neue Mitarbeiter
nicht mehr manuell angelegt werden muumlssen sondern dass die dazu noumltigen Schritte automatisch
erfolgen Das hat weniger etwas mit einer natuumlrlichen Mitarbeiter-Fluktuation in der Firma zu tun
als vielmehr damit dass manuelle Prozesse generell anfaumlllig fuumlr Fehler sind So moumlchte man
sicherstellen dass jeder neuer Mitarbeiter vom ersten Arbeitstag an Zugriff auf seine Arbeitsmittel
hat auch wenn der Administrator durch Dinge wie Urlaub Krankheit oder Kaffee in der Tastatur
verhindert ist
12 Herangehensweise
Bevor eine Person zum Mitarbeiter der eBiz wird hat sie sich in aller Regel vorher bei der eBiz
beworben Ein denkbarer Kanal dafuumlr waumlre zB die Bewerbung via E-Mail
Wer sich bei der eBiz bewirbt wird innerhalb des CRM-Systems MS Dynamics 365 CRM als
Contact-Objekt DSGVO konform angelegt das Daten wie Name Adresse und Telefonnummer
beinhaltet - dieselben Daten die auch bei der O365-Provisionierung gebraucht werden dort aber
haumlndisch eingetippt werden muumlssen
Das haumlndische Eintippen zu vermeiden ist das Ziel der Software-Loumlsung die im Rahmen dieses
Artikels prototypisch entwickelt wird
Es geht darum Contacts die gewisse Kriterien erfuumlllen (Einstellung erfolgt und damit technsich
isEmployee == true) aus dem CRM herauszuholen und dann fuumlr Folgeprozesse (wie eben die
Provisionierung in Office 365 und Azure) wieder zu verwenden Dazu muss ein Nachrichtenfluss
geschaffen werden der verschiedene Applikationen integriert Das bevorzugte Werkzeug fuumlr
Integrationsszenarien wie dieses ist im Microsoft-Universum der BizTalk Server inklusive seiner
Peripherietechnologien (NET PowerShell WCF SQL Server Azure)
Der geplante Ablauf soll durch die folgende Darstellung verdeutlicht werden
3
Co
nta
ct
GetC
on
tact
(Cri
tera
)
Sta
tus
Pro
visi
on
(Co
nta
ct)
Contact
Criteria
BizTalk ermoumlglicht eine Uumlberpruumlfung ob ein Kontakt mit dem Status IsEmployee == true in
Dynamics vorhanden sind holt diesen dann ab und verwendet die Daten um die Provisionierung in
O365 durchzufuumlhren
4
2 DURCHFUumlHRUNG
21 Einfuumlhrung
Dieser Artikel stellt ein Integrationsszenario mit BizTalk Server sowie eine entsprechende
Vorgehensweise zur Umsetzung vor
Erforderliche Grundkenntnisse
bull BizTalk Server
bull C und NET
bull Windows Communication Foundation (WCF)
bull Windows PowerShell
bull Azure Administration
bull OAuth 20 Azure Active Directory
bull Rest JSON und OData
bull MS Dynamics 365 CRM
Voraussetzungen
bull Azure Subscription
bull VMRechner mit installiertem BizTalk Server Stack + Visual Studio
bull Office365 Plan Testlizenz mit Dynamics 365 CRM
Loumlsungsstrategie
Die nachfolgende Darstellung gibt einen Uumlberblick uumlber die Loumlsungsstrategie innerhalb der
geplanten Architektur
Receive MessageBox
Send
Receive
Send
Receive
Contact
CriteriaJSON
1
2
3
4
Die Loumlsungsstrategie beruumlcksichtigt die individuellen Besonderheiten der zu integrierenden Systeme
inklusive Datenformat und Struktur sowie Schnittstellen zu den benoumltigten Ressourcen
Details die daruumlber hinausgehen wurden hier zugunsten der Uumlbersichtlichkeit eingespart und werden
im weiteren Artikelverlauf wieder aufgegriffen
Schritt 1 Eingangskanal fuumlr die Abfragekriterien Einrichten
5
Initial des Prozesses ist das Ablegen einer Datei in einem Ordner Diese Datei beinhaltet die
Information welchen Kriterien (CRM-) Kontakte entsprechen muumlssen um provisioniert zu werden
und liegt im JSON-Format vor
Das JSON-Dokument gelangt durch eine Receive-Pipeline (in der eine Transformation ins XML-
Format erfolgt) in die Messagebox
Schritt 2 Kontakt-Objekt aus Dynamics 365 CRM abholen
Ein Send Port abonniert die Information aus Schritt 1 und verwendet sie um einen API-Call auf
Dynamics zu starten Dynamics gibt als Antwort einen Contact zuruumlck der den Kriterien entspricht
Schritt 3 Provisionierungskanal einrichten
Die ContactXML aus Schritt 2 wird von einem weiteren Send Port abonniert der die Informationen
darin verwendet um einen Webservice anzusprechen der die Logik ausfuumlhrt um die
Provisionierung in Office 365 anzustoszligen O365 gibt daraufhin eine Information uumlber den Verlauf
des Provisionierungsvorgangs zuruumlck und der Status der Provision wird als finaler Output des
Prozesses in der MessageBox abgelegt
Schritt 4 Szenario abschlieszligen
Kontakt-Objekt sowie die Information ob die Provisionierung erfolgreich war befinden sich nun in
der MessageBox Von hier aus koumlnnen die Daten fuumlr weitere Prozesse verwendet werden
(beispielsweise fuumlr ein automatisiertes SharePoint-Announcement Willkommensmail an den neuen
Mitarbeiter etc)
22 Vorbereitung
221 Dynamics 365 CRM
Ein kurzer Ausflug in die Dynamics 365 Galaxie
Die Moumlglichkeit zur Verwaltung von Contacts gehoumlrt standardmaumlszligig zum Produktumfang von
Dynamics 365 Die Contact-Eigenschaft IsEmployee jedoch nicht Das ist aber kein Problem da
Dynamics die Moumlglichkeit bietet den standardmaumlszligig ausgelieferten Datenbestand an die eigenen
Prozesse anzupassen Dazu ist folgendes noumltig
1 Hinzufuumlgen des Attributs bdquoIsEmployeeldquo zur Entitaumlt Contact
2 Anlegen der Dummy Kontakte
3 Zugriffspunkte von Dynamics CRM nutzen
2211 HINZUFUumlGEN DES ATTRIBUTS ISEMPLOYEE ZUR ENTITAumlT CONTACT
Wir rufen httpsportalofficecom auf loggen uns als Administrator unserer O365-Instanz ein und
navigieren dann mit der Maus auf die Kachel gt [Admin]
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
2
1 EINFUumlHRUNG
11 Motivation
Die eBiz Consulting GmbH (eBiz) ist Microsoft Gold Partner mit den Schwerpunkten Integration
Automation und Kollaboration Dazu buumlndelt die eBiz ihre Leistungen in den zwei Bereichen
Systemintegration und Teamintegration
Kollaboration im Microsoft-Umfeld bedeutet natuumlrlich dass das Oumlkosystem um Office 365 zu den
taumlglichen Arbeitsmitteln in der Firma gehoumlrt Daher gehoumlrt es gleichermaszligen natuumlrlich zum
Aufnahmeprozess eines neuen Mitarbeiters in der Firma dass der Mitarbeiter eine O365-Lizenz
bekommt und in die Domaumlne der eBiz aufgenommen wird Uumlber die O365 Lizenz wird fuumlr den
Mitarbeiter eine persoumlnliche Mailbox erstellt und der Zugriff auf verschiedene Tools und Apps
ermoumlglich (SharePoint Team Skype4Business)
Nun ist es ein lang gehegter Wunsch des einzigen Administrators in der Firma dass neue Mitarbeiter
nicht mehr manuell angelegt werden muumlssen sondern dass die dazu noumltigen Schritte automatisch
erfolgen Das hat weniger etwas mit einer natuumlrlichen Mitarbeiter-Fluktuation in der Firma zu tun
als vielmehr damit dass manuelle Prozesse generell anfaumlllig fuumlr Fehler sind So moumlchte man
sicherstellen dass jeder neuer Mitarbeiter vom ersten Arbeitstag an Zugriff auf seine Arbeitsmittel
hat auch wenn der Administrator durch Dinge wie Urlaub Krankheit oder Kaffee in der Tastatur
verhindert ist
12 Herangehensweise
Bevor eine Person zum Mitarbeiter der eBiz wird hat sie sich in aller Regel vorher bei der eBiz
beworben Ein denkbarer Kanal dafuumlr waumlre zB die Bewerbung via E-Mail
Wer sich bei der eBiz bewirbt wird innerhalb des CRM-Systems MS Dynamics 365 CRM als
Contact-Objekt DSGVO konform angelegt das Daten wie Name Adresse und Telefonnummer
beinhaltet - dieselben Daten die auch bei der O365-Provisionierung gebraucht werden dort aber
haumlndisch eingetippt werden muumlssen
Das haumlndische Eintippen zu vermeiden ist das Ziel der Software-Loumlsung die im Rahmen dieses
Artikels prototypisch entwickelt wird
Es geht darum Contacts die gewisse Kriterien erfuumlllen (Einstellung erfolgt und damit technsich
isEmployee == true) aus dem CRM herauszuholen und dann fuumlr Folgeprozesse (wie eben die
Provisionierung in Office 365 und Azure) wieder zu verwenden Dazu muss ein Nachrichtenfluss
geschaffen werden der verschiedene Applikationen integriert Das bevorzugte Werkzeug fuumlr
Integrationsszenarien wie dieses ist im Microsoft-Universum der BizTalk Server inklusive seiner
Peripherietechnologien (NET PowerShell WCF SQL Server Azure)
Der geplante Ablauf soll durch die folgende Darstellung verdeutlicht werden
3
Co
nta
ct
GetC
on
tact
(Cri
tera
)
Sta
tus
Pro
visi
on
(Co
nta
ct)
Contact
Criteria
BizTalk ermoumlglicht eine Uumlberpruumlfung ob ein Kontakt mit dem Status IsEmployee == true in
Dynamics vorhanden sind holt diesen dann ab und verwendet die Daten um die Provisionierung in
O365 durchzufuumlhren
4
2 DURCHFUumlHRUNG
21 Einfuumlhrung
Dieser Artikel stellt ein Integrationsszenario mit BizTalk Server sowie eine entsprechende
Vorgehensweise zur Umsetzung vor
Erforderliche Grundkenntnisse
bull BizTalk Server
bull C und NET
bull Windows Communication Foundation (WCF)
bull Windows PowerShell
bull Azure Administration
bull OAuth 20 Azure Active Directory
bull Rest JSON und OData
bull MS Dynamics 365 CRM
Voraussetzungen
bull Azure Subscription
bull VMRechner mit installiertem BizTalk Server Stack + Visual Studio
bull Office365 Plan Testlizenz mit Dynamics 365 CRM
Loumlsungsstrategie
Die nachfolgende Darstellung gibt einen Uumlberblick uumlber die Loumlsungsstrategie innerhalb der
geplanten Architektur
Receive MessageBox
Send
Receive
Send
Receive
Contact
CriteriaJSON
1
2
3
4
Die Loumlsungsstrategie beruumlcksichtigt die individuellen Besonderheiten der zu integrierenden Systeme
inklusive Datenformat und Struktur sowie Schnittstellen zu den benoumltigten Ressourcen
Details die daruumlber hinausgehen wurden hier zugunsten der Uumlbersichtlichkeit eingespart und werden
im weiteren Artikelverlauf wieder aufgegriffen
Schritt 1 Eingangskanal fuumlr die Abfragekriterien Einrichten
5
Initial des Prozesses ist das Ablegen einer Datei in einem Ordner Diese Datei beinhaltet die
Information welchen Kriterien (CRM-) Kontakte entsprechen muumlssen um provisioniert zu werden
und liegt im JSON-Format vor
Das JSON-Dokument gelangt durch eine Receive-Pipeline (in der eine Transformation ins XML-
Format erfolgt) in die Messagebox
Schritt 2 Kontakt-Objekt aus Dynamics 365 CRM abholen
Ein Send Port abonniert die Information aus Schritt 1 und verwendet sie um einen API-Call auf
Dynamics zu starten Dynamics gibt als Antwort einen Contact zuruumlck der den Kriterien entspricht
Schritt 3 Provisionierungskanal einrichten
Die ContactXML aus Schritt 2 wird von einem weiteren Send Port abonniert der die Informationen
darin verwendet um einen Webservice anzusprechen der die Logik ausfuumlhrt um die
Provisionierung in Office 365 anzustoszligen O365 gibt daraufhin eine Information uumlber den Verlauf
des Provisionierungsvorgangs zuruumlck und der Status der Provision wird als finaler Output des
Prozesses in der MessageBox abgelegt
Schritt 4 Szenario abschlieszligen
Kontakt-Objekt sowie die Information ob die Provisionierung erfolgreich war befinden sich nun in
der MessageBox Von hier aus koumlnnen die Daten fuumlr weitere Prozesse verwendet werden
(beispielsweise fuumlr ein automatisiertes SharePoint-Announcement Willkommensmail an den neuen
Mitarbeiter etc)
22 Vorbereitung
221 Dynamics 365 CRM
Ein kurzer Ausflug in die Dynamics 365 Galaxie
Die Moumlglichkeit zur Verwaltung von Contacts gehoumlrt standardmaumlszligig zum Produktumfang von
Dynamics 365 Die Contact-Eigenschaft IsEmployee jedoch nicht Das ist aber kein Problem da
Dynamics die Moumlglichkeit bietet den standardmaumlszligig ausgelieferten Datenbestand an die eigenen
Prozesse anzupassen Dazu ist folgendes noumltig
1 Hinzufuumlgen des Attributs bdquoIsEmployeeldquo zur Entitaumlt Contact
2 Anlegen der Dummy Kontakte
3 Zugriffspunkte von Dynamics CRM nutzen
2211 HINZUFUumlGEN DES ATTRIBUTS ISEMPLOYEE ZUR ENTITAumlT CONTACT
Wir rufen httpsportalofficecom auf loggen uns als Administrator unserer O365-Instanz ein und
navigieren dann mit der Maus auf die Kachel gt [Admin]
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
3
Co
nta
ct
GetC
on
tact
(Cri
tera
)
Sta
tus
Pro
visi
on
(Co
nta
ct)
Contact
Criteria
BizTalk ermoumlglicht eine Uumlberpruumlfung ob ein Kontakt mit dem Status IsEmployee == true in
Dynamics vorhanden sind holt diesen dann ab und verwendet die Daten um die Provisionierung in
O365 durchzufuumlhren
4
2 DURCHFUumlHRUNG
21 Einfuumlhrung
Dieser Artikel stellt ein Integrationsszenario mit BizTalk Server sowie eine entsprechende
Vorgehensweise zur Umsetzung vor
Erforderliche Grundkenntnisse
bull BizTalk Server
bull C und NET
bull Windows Communication Foundation (WCF)
bull Windows PowerShell
bull Azure Administration
bull OAuth 20 Azure Active Directory
bull Rest JSON und OData
bull MS Dynamics 365 CRM
Voraussetzungen
bull Azure Subscription
bull VMRechner mit installiertem BizTalk Server Stack + Visual Studio
bull Office365 Plan Testlizenz mit Dynamics 365 CRM
Loumlsungsstrategie
Die nachfolgende Darstellung gibt einen Uumlberblick uumlber die Loumlsungsstrategie innerhalb der
geplanten Architektur
Receive MessageBox
Send
Receive
Send
Receive
Contact
CriteriaJSON
1
2
3
4
Die Loumlsungsstrategie beruumlcksichtigt die individuellen Besonderheiten der zu integrierenden Systeme
inklusive Datenformat und Struktur sowie Schnittstellen zu den benoumltigten Ressourcen
Details die daruumlber hinausgehen wurden hier zugunsten der Uumlbersichtlichkeit eingespart und werden
im weiteren Artikelverlauf wieder aufgegriffen
Schritt 1 Eingangskanal fuumlr die Abfragekriterien Einrichten
5
Initial des Prozesses ist das Ablegen einer Datei in einem Ordner Diese Datei beinhaltet die
Information welchen Kriterien (CRM-) Kontakte entsprechen muumlssen um provisioniert zu werden
und liegt im JSON-Format vor
Das JSON-Dokument gelangt durch eine Receive-Pipeline (in der eine Transformation ins XML-
Format erfolgt) in die Messagebox
Schritt 2 Kontakt-Objekt aus Dynamics 365 CRM abholen
Ein Send Port abonniert die Information aus Schritt 1 und verwendet sie um einen API-Call auf
Dynamics zu starten Dynamics gibt als Antwort einen Contact zuruumlck der den Kriterien entspricht
Schritt 3 Provisionierungskanal einrichten
Die ContactXML aus Schritt 2 wird von einem weiteren Send Port abonniert der die Informationen
darin verwendet um einen Webservice anzusprechen der die Logik ausfuumlhrt um die
Provisionierung in Office 365 anzustoszligen O365 gibt daraufhin eine Information uumlber den Verlauf
des Provisionierungsvorgangs zuruumlck und der Status der Provision wird als finaler Output des
Prozesses in der MessageBox abgelegt
Schritt 4 Szenario abschlieszligen
Kontakt-Objekt sowie die Information ob die Provisionierung erfolgreich war befinden sich nun in
der MessageBox Von hier aus koumlnnen die Daten fuumlr weitere Prozesse verwendet werden
(beispielsweise fuumlr ein automatisiertes SharePoint-Announcement Willkommensmail an den neuen
Mitarbeiter etc)
22 Vorbereitung
221 Dynamics 365 CRM
Ein kurzer Ausflug in die Dynamics 365 Galaxie
Die Moumlglichkeit zur Verwaltung von Contacts gehoumlrt standardmaumlszligig zum Produktumfang von
Dynamics 365 Die Contact-Eigenschaft IsEmployee jedoch nicht Das ist aber kein Problem da
Dynamics die Moumlglichkeit bietet den standardmaumlszligig ausgelieferten Datenbestand an die eigenen
Prozesse anzupassen Dazu ist folgendes noumltig
1 Hinzufuumlgen des Attributs bdquoIsEmployeeldquo zur Entitaumlt Contact
2 Anlegen der Dummy Kontakte
3 Zugriffspunkte von Dynamics CRM nutzen
2211 HINZUFUumlGEN DES ATTRIBUTS ISEMPLOYEE ZUR ENTITAumlT CONTACT
Wir rufen httpsportalofficecom auf loggen uns als Administrator unserer O365-Instanz ein und
navigieren dann mit der Maus auf die Kachel gt [Admin]
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
4
2 DURCHFUumlHRUNG
21 Einfuumlhrung
Dieser Artikel stellt ein Integrationsszenario mit BizTalk Server sowie eine entsprechende
Vorgehensweise zur Umsetzung vor
Erforderliche Grundkenntnisse
bull BizTalk Server
bull C und NET
bull Windows Communication Foundation (WCF)
bull Windows PowerShell
bull Azure Administration
bull OAuth 20 Azure Active Directory
bull Rest JSON und OData
bull MS Dynamics 365 CRM
Voraussetzungen
bull Azure Subscription
bull VMRechner mit installiertem BizTalk Server Stack + Visual Studio
bull Office365 Plan Testlizenz mit Dynamics 365 CRM
Loumlsungsstrategie
Die nachfolgende Darstellung gibt einen Uumlberblick uumlber die Loumlsungsstrategie innerhalb der
geplanten Architektur
Receive MessageBox
Send
Receive
Send
Receive
Contact
CriteriaJSON
1
2
3
4
Die Loumlsungsstrategie beruumlcksichtigt die individuellen Besonderheiten der zu integrierenden Systeme
inklusive Datenformat und Struktur sowie Schnittstellen zu den benoumltigten Ressourcen
Details die daruumlber hinausgehen wurden hier zugunsten der Uumlbersichtlichkeit eingespart und werden
im weiteren Artikelverlauf wieder aufgegriffen
Schritt 1 Eingangskanal fuumlr die Abfragekriterien Einrichten
5
Initial des Prozesses ist das Ablegen einer Datei in einem Ordner Diese Datei beinhaltet die
Information welchen Kriterien (CRM-) Kontakte entsprechen muumlssen um provisioniert zu werden
und liegt im JSON-Format vor
Das JSON-Dokument gelangt durch eine Receive-Pipeline (in der eine Transformation ins XML-
Format erfolgt) in die Messagebox
Schritt 2 Kontakt-Objekt aus Dynamics 365 CRM abholen
Ein Send Port abonniert die Information aus Schritt 1 und verwendet sie um einen API-Call auf
Dynamics zu starten Dynamics gibt als Antwort einen Contact zuruumlck der den Kriterien entspricht
Schritt 3 Provisionierungskanal einrichten
Die ContactXML aus Schritt 2 wird von einem weiteren Send Port abonniert der die Informationen
darin verwendet um einen Webservice anzusprechen der die Logik ausfuumlhrt um die
Provisionierung in Office 365 anzustoszligen O365 gibt daraufhin eine Information uumlber den Verlauf
des Provisionierungsvorgangs zuruumlck und der Status der Provision wird als finaler Output des
Prozesses in der MessageBox abgelegt
Schritt 4 Szenario abschlieszligen
Kontakt-Objekt sowie die Information ob die Provisionierung erfolgreich war befinden sich nun in
der MessageBox Von hier aus koumlnnen die Daten fuumlr weitere Prozesse verwendet werden
(beispielsweise fuumlr ein automatisiertes SharePoint-Announcement Willkommensmail an den neuen
Mitarbeiter etc)
22 Vorbereitung
221 Dynamics 365 CRM
Ein kurzer Ausflug in die Dynamics 365 Galaxie
Die Moumlglichkeit zur Verwaltung von Contacts gehoumlrt standardmaumlszligig zum Produktumfang von
Dynamics 365 Die Contact-Eigenschaft IsEmployee jedoch nicht Das ist aber kein Problem da
Dynamics die Moumlglichkeit bietet den standardmaumlszligig ausgelieferten Datenbestand an die eigenen
Prozesse anzupassen Dazu ist folgendes noumltig
1 Hinzufuumlgen des Attributs bdquoIsEmployeeldquo zur Entitaumlt Contact
2 Anlegen der Dummy Kontakte
3 Zugriffspunkte von Dynamics CRM nutzen
2211 HINZUFUumlGEN DES ATTRIBUTS ISEMPLOYEE ZUR ENTITAumlT CONTACT
Wir rufen httpsportalofficecom auf loggen uns als Administrator unserer O365-Instanz ein und
navigieren dann mit der Maus auf die Kachel gt [Admin]
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
5
Initial des Prozesses ist das Ablegen einer Datei in einem Ordner Diese Datei beinhaltet die
Information welchen Kriterien (CRM-) Kontakte entsprechen muumlssen um provisioniert zu werden
und liegt im JSON-Format vor
Das JSON-Dokument gelangt durch eine Receive-Pipeline (in der eine Transformation ins XML-
Format erfolgt) in die Messagebox
Schritt 2 Kontakt-Objekt aus Dynamics 365 CRM abholen
Ein Send Port abonniert die Information aus Schritt 1 und verwendet sie um einen API-Call auf
Dynamics zu starten Dynamics gibt als Antwort einen Contact zuruumlck der den Kriterien entspricht
Schritt 3 Provisionierungskanal einrichten
Die ContactXML aus Schritt 2 wird von einem weiteren Send Port abonniert der die Informationen
darin verwendet um einen Webservice anzusprechen der die Logik ausfuumlhrt um die
Provisionierung in Office 365 anzustoszligen O365 gibt daraufhin eine Information uumlber den Verlauf
des Provisionierungsvorgangs zuruumlck und der Status der Provision wird als finaler Output des
Prozesses in der MessageBox abgelegt
Schritt 4 Szenario abschlieszligen
Kontakt-Objekt sowie die Information ob die Provisionierung erfolgreich war befinden sich nun in
der MessageBox Von hier aus koumlnnen die Daten fuumlr weitere Prozesse verwendet werden
(beispielsweise fuumlr ein automatisiertes SharePoint-Announcement Willkommensmail an den neuen
Mitarbeiter etc)
22 Vorbereitung
221 Dynamics 365 CRM
Ein kurzer Ausflug in die Dynamics 365 Galaxie
Die Moumlglichkeit zur Verwaltung von Contacts gehoumlrt standardmaumlszligig zum Produktumfang von
Dynamics 365 Die Contact-Eigenschaft IsEmployee jedoch nicht Das ist aber kein Problem da
Dynamics die Moumlglichkeit bietet den standardmaumlszligig ausgelieferten Datenbestand an die eigenen
Prozesse anzupassen Dazu ist folgendes noumltig
1 Hinzufuumlgen des Attributs bdquoIsEmployeeldquo zur Entitaumlt Contact
2 Anlegen der Dummy Kontakte
3 Zugriffspunkte von Dynamics CRM nutzen
2211 HINZUFUumlGEN DES ATTRIBUTS ISEMPLOYEE ZUR ENTITAumlT CONTACT
Wir rufen httpsportalofficecom auf loggen uns als Administrator unserer O365-Instanz ein und
navigieren dann mit der Maus auf die Kachel gt [Admin]
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
6
Dann wieder auf die Kachel gt [Admin Centers] gt [Dynamics 365]
Instanz auswaumlhlen gt [Open]
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
7
[Settings] gt [Customization] gt [Customizations]hellip
hellip wir waumlhlen dann [Customize the System]
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
8
Und suchen im Popup-Fenster unter Entities die Entitaumlt Contact heraus und legen mit new unter
Fields unser Attribut IsEmployee an (Abschlieszligen mit Save and Close)
Bei Erfolg ist das neue Field unter [View] gt [Custom] zu sehen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
9
Zu guter Letzt muss die Eigenschaft new_isemployee noch fuumlr den CRM-Administrator in der
Weboberflaumlche konfigurierbar sein Dazu wechseln wir in den Menuumlpunkt Forms und waumlhlen
Contact aus Im Popup-Fenster waumlhlen wir das Attribut aus dem Field Explorer aus und legen es
per Drag and Drop im Formular ab
2212 ANLEGEN DER DUMMY OBJEKTE
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
10
Zuruumlck im Hauptmenuuml unter [Sales] gt [Contacts] hat man die Moumlglichkeit seine Kontakte zu
verwalten
Hier lege ich fuumlr Testzwecke die folgenden Dummy-Bewerber an
bull Max Mustermann angestellt (isEmployee == true)
bull Alexander Nowak nicht angestellt (isEmployee == false)
Und benutze dazu das gerade von uns frisierte Eingabeformular das ich mit Klick auf new aufrufe
um die Kontakte anzulegen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
11
Bitte beachten Die fuumlr die Provisionierung benoumltigten Daten sind innerhalb unseres Testszenarios
lediglich Vorname Nachname und isEmployee
2213 ZUGRIFFSPUNKTE VON DYNAMICS 365 CRM NUTZEN
Uumlber [Settings] gt [Customization] gt [Customizations] gt [Developers Resources] gelangt man zu den
Endpunkten die das CRM bietet um programmatisch auf dessen Daten zuzugreifen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
12
Interessant ist fuumlr unseren Anwendungsfall die Sektion Instance Web API Hinter der Service Root
URL verbirgt sich ein RESTful Webservice der nach OData Standard implementiert ist und den
Zugriff auf unser Contact-Objekt erlaubt
Um zu uumlberpruumlfen ob das Anlegen des Custom Fields funktioniert hat rufen wir die ODATA-Route
zum EntitySet contacts uumlber die entsprechende URI auf und pruumlfe die Antwort des Service
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
13
Ein alternativer Weg dies zu tun ist das OData-Schluumlsselwort $metadata zu benutzen und dann
mit [STRG+F] die Seite nach dem Namen des Custom Fields zu durchsuchen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
14
An dieser Stelle sind alle noumltigen Arbeitsschritte innerhalb von Dynamics 365 CRM vorgenommen
und wir koumlnnen uns der Konfiguration von BizTalk Server zuwenden
222 WCF Service
Innerhalb des Szenarios ist ein WCF-Service vorgesehen der von BizTalk angesprochen wird um
mit O365 zu sprechen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
15
Um das zu bewerkstelligen sind die folgenden Schritte noumltig
1 Vorbereitung Download der Visual Studio Solution
2 Service in Visual Studio erstellen und anpassen
3 Service in IIS bereitstellen
2221 VORBEREITUNG DOWNLOAD DER VISUAL STUDIO SOLUTION
Der von Microsoft empfohlene Weg programmatisch auf den eigenen O365-Tenant zuzugreifen
ist Windows PowerShell Microsoft stellt mit dem MSOnline-PowerShell-Modul
(AdministrationConfig-V111660-GAmsi) cmdlets bereit die die Interaktion mit der Cloud
vereinfachen
Die Aufgabe des WCF-Service (in der Cloud oder On-Prem) ist es Provisionierungsinformationen
entgegenzunehmen und die Provisionierung in O365 mit diesen Informationen durchzufuumlhren
Dazu muss der Service eine PowerShell-Session ausfuumlhren die dem folgenden Script entspricht
ltltProvision-PSps1gtgt
Script Sowie Contracts und Operations des ProvisionService stehen als VS-Solution auskommentiert
zum Download bereit
Es muss nur noch der eigentliche Service erstellt werden (WCFProvisionService) der die Operations
uumlberhaupt durch Clients nutzbar macht Abhaumlngigkeiten werden in der nachfolgenden Abbildung
dargestellt
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
16
Reference
SystemManagementAutomation
ProvisionService(Web-Application)
Servicesvc
provision(Employee Admin)
Services (NET Library)
ProvisionService
provision(Employee Admin)
-ObjectIdGlobal String
-isLicensedGlobal String-WhenCreatedGlobal DateTime
Contracts (NET Library)
Employee
+City String+Country String
Admin
+principal String+password String
ltltSchnittstellegtgt
IProvisionService
provision(Employee Admin)
WCF-Framework
SystemRuntimeSerialization SystemServiceModel
2222 SERVICE IN VISUAL STUDIO ERSTELLEN UND ANPASSEN
Wir oumlffnen die Solution in Visual Studio und fuumlgen via [Rechtsklick] auf die Solution gt [Add] gt [New
Web Site] gt [WCF Service] die SVC-Seite hinzu die unseren Service repraumlsentiert
Das Projekt erhaumllt die Bezeichnung ProvisionWCFService und Referenzen auf die Projekte
Contracts und Services (Die Elemente unter App_Code koumlnnen geloumlscht werden)
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
17
In Servicesvc ersetzen wir den bestehenden Code durch die nachfolgende Zeile
lt ServiceHost Service=ServicesProvisionService gt
Weiterhin ersetzen wir den Code der Webconfig mit diesem hier
ltxml version=10gt
ltconfigurationgt
ltstartupgt
ltsupportedRuntime version=v40 sku=NETFrameworkVersion=v452gt
ltstartupgt
ltappSettingsgt
ltadd key=aspnetUseTaskFriendlySynchronizationContext value=true gt
ltappSettingsgt
ltsystemserviceModelgt
ltservicesgt
ltservice name =ServicesProvisionService behaviorConfiguration=ServiceGatewayBehaviorgt
ltendpoint address= binding=basicHttpBinding
contract=ContractsServiceContractsIProvisionServicegt
lthostgt
ltbaseAddressesgt
ltadd baseAddress=httplocalhostProvisionServicegt
ltbaseAddressesgt
lthostgt
ltservicegt
ltservicesgt
ltbehaviorsgt
ltserviceBehaviorsgt
ltbehavior name=ServiceGatewayBehaviorgt
ltserviceDebug includeExceptionDetailInFaults=truegt
lt-- To avoid disclosing metadata information set the values below to false before
deployment --gt
ltserviceMetadata httpGetEnabled=true httpsGetEnabled=truegt
lt-- To receive exception details in faults for debugging purposes set the value below to
true Set to false before deployment to avoid disclosing exception information --gt
ltbehaviorgt
ltserviceBehaviorsgt
ltbehaviorsgt
ltprotocolMappinggt
ltadd binding=basicHttpsBinding scheme=https gt
ltprotocolMappinggt
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
18
ltserviceHostingEnvironment aspNetCompatibilityEnabled=false multipleSiteBindingsEnabled=true gt
ltsystemserviceModelgt
ltsystemwebgt
ltcompilationgt
ltassembliesgt
ltadd assembly=SystemManagementAutomation Version=3000 Culture=neutral
PublicKeyToken=31BF3856AD364E35gt
ltassembliesgt
ltcompilationgt
ltsystemwebgt
ltsystemwebServergt
ltmodules runAllManagedModulesForAllRequests=truegt
lt--
To browse web app root directory during debugging set the value below to true
Set to false before deployment to avoid disclosing web app folder information
--gt
ltdirectoryBrowse enabled=truegt
ltsystemwebServergt
ltconfigurationgt
2223 SERVICE IN IIS BEREITSTELLEN
Der WCF Service kann dann lokal oder auch auf einer beliebigen VM (etwa in Azure) gehostet
werden Wichtig ist dabei die Installation von MSOnline auf der Maschine wo der Service betrieben
werden soll
Ich entscheide mich dazu den ProvisionService auf der Lokalen BizTalk-Maschine zu betreiben und
erstelle dazu eine Application mit dem Alias ProvisionService im IIS Manager
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
19
Wir koumlnnen nun die Webseite in Visual Studio kompilieren und dem lokalen IIS zur Verfuumlgung
stellen
Der Service laumlsst sich dann uumlber den Browser aufrufen und durch Hinzufuumlgen des Parameters wsdl
zur URL sollte die folgende Schnittstellenbeschreibung zu sehen sein
223 BizTalk Server Development
Nun da alle Fremdsysteme eingerichtet sind kann die BizTalk-Entwicklung folgen Sie hat das Ziel
die Fremdsysteme zu integrieren und damit den Nachrichtenfluss herzustellen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
20
ltltSystemgtgt
eBizCon Onboarding (BizTalk)
ltltFremdsystemgtgt
Dynamics CRM
ltltFremdsystemgtgt
WCF-
ProvisionService
ltltFremdsystemgtgt
O365
ltltFremdsystemgtgt
Azure Active
Directory
greift auf
AAD zu
Stellt
Kontakte
bereit
Fuumlhrt Provisionierung
in O365 und AAD
durch
Ruft
Kontakte
aus CRM ab
2231 SCHRITT 1 ndash EINGANGSKANAL FUumlR DIE ABFRAGEKRITERIEN EINRICHTEN
Receive MessageBox
Contact
CriteriaJSON
Der Prozess wird dadurch ausgeloumlst dass eine JSON-Datei in einem Ordner abgelegt wird die die
Information enthaumllt welche Kontakt-Objekte uns im CRM interessieren
Die JSON-Datei sieht wie folgt aus
EntitySet contacts
Criteria new_isemployee eq true
Diese JSON wird im weiteren Verlauf noch mehrfach benoumltigt und kann daher auf dem Desktop unter
der Bezeichnung ContactCriteriaJsonInstancejson abgespeichert werden
Damit aber mit dieser Information innerhalb von BizTalk gearbeitet werden kann muss zuerst ein
Receive Port eingerichtet werden der als Eingangskanal fuumlr die erwaumlhnte JSON-Datei dient
Dazu sind die folgenden Arbeitsschritte auszufuumlhren
1 BizTalk Application anlegen (Admin Console)
2 Receive Port anlegen (Admin Console)
3 Receive Location anlegen (Admin Console)
4 Custom Receivepipeline erstellen und deployen (Visual Studio)
5 Receive Location konfigurieren (Admin Console)
6 XML-Schema aus JSON generieren und Receive Location updaten
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
21
Das Ablegen der JSON Datei stellt derzeit nur einen Workaround da Fuumlr einen produktiven Einsatz
sind andere Mechanismen notwendig (eg BizTalk Scheduled Task Adapter)
22311 BIZTALK APPLICATION ANLEGEN
Biztalk Applications sind logische Container um Artefakte wie Send- und Receive Ports Mappings etc
gemaumlszlig ihren Verwendungszwecks in uumlbersichtliche Pakete zu verpacken Demnach richten wir fuumlr
unser Szenario das Onboarding eines neuen Mitarbeiters auch eine gesonderte Application ein
Wir rufen die Admin Console auf und fuumlgen eine neue Application hinzuhellip
Ich habe mich fuumlr eine Application mit der Bezeichnung eBizConOnboardingApplication
entschieden
22312 RECEIVE PORT ANLEGEN
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
22
Ports sind Kanaumlle fuumlr Nachrichten die in BizTalk eingehen (Receive Ports) und aus BizTalk heraus
versendet werden (Send Ports) Receive Ports sind logische Behaumlltnisse fuumlr Receive Locations die eine
tiefere Spezifizierung erlauben und sich Adapter zunutze machen um mit verschiedensten Protokollen
mit der Auszligenwelt zu kommunizieren
Der Ordner in der die JSON-Dateien abgelegt werden die den Prozess ausloumlsen dient schlicht als
Dateiablage und erwartet keine Ruumlckantwort Aumlhnlich wie ein oumlffentlicher Briefkasten der vom
Postboten lediglich geleert wird Aus diesem Grund ist One-way Receive Port die passende Option
fuumlr unseren Anwendungsfallhellip
Es gilt als guter Stil bei der Benennung der BizTalk Artefakte eine gewisse Notation einzuhalten
damit man sich spaumlter noch in seiner Solution zurechtfindet Die empfohlene Notation fuumlr Ports
lautet
[Application]_[Richtung]_[GegenstandZweck]
dementsprechend heiszligt der Receive Port fuumlr ContactCriteriaJSON-Dateien
Onboarding_Receive_ContactCriteria
Und erscheint nach Klick auf [OK] in der Auflistung der Receive Ports innerhalb der Admin Console
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
23
22313 RECEIVE LOCATION ANLEGEN
Receive Locations befinden sich innerhalb von Receive Ports Sie bieten vielfaumlltige (Eingangs-)
Schnittstellen nach auszligen indem sie konfigurierbare Softwarebausteine sogenannte Adapter
verwenden So gibt es einen Adapter fuumlr FILE SQL HTTP usw Daruumlber hinaus ist es auch moumlglich
bestehende Adapter zu erweitern oder eigene Adapter zu programmieren
Mit Rechtsklick auf den soeben erstellten Receive Port und [New] gt [Receive Location] statten wir
den Port mit Faumlhigkeit aus einen Dateiordner zu uumlberwachen in den wir spaumlter die JSON-Dateien
droppen werden
Zunaumlchst erhaumllt die Location erst einmal einen aussagekraumlftigen Bezeichner
bdquoOnboarding_Receive_ContactCriteria_FILEldquo
Fuumlr die erste Konfiguration genuumlgt es FILE auszuwaumlhlen und unter [Configurehellip] gt [General] den
Ordner festzulegen der abgehoumlrt werden soll Ich habe mir zu diesem Zweck den folgenden
Dateipfad angelegt
bdquoCeBizConOnboardingMessagesReceiveCriteriaJSONsldquo
Bei File Mask moumlchten wir erreichen dass nur Dateien von der Location beachtet werden sollen
die im JSON-Format vorliegen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
24
Unser Anwendungsfall sieht vor dass JSON-Dateien in den Ordner abgelegt werden Innerhalb des
BizTalk Servers wird aber jede Nachricht im XML-Format verarbeitet Insofern ist die Einstellung
PassThruReceive fuumlr unseren Anwendungsfall nicht ausreichend Es wird eine Pipeline benoumltigt die
eingehende JSONs ins XML-Format bringt
22314 CUSTOM RECEIVE PIPELINE ERSTELLEN UND DEPLOYEN
Pipelines beinhalten Verarbeitungsschritte die eine Nachricht passiert bevor sie ans Ziel zugestellt
werden Diese Verarbeitungsschritte werden durch Stages abgegrenzt
Stages in einer Receive Pipeline
bull Decode - Dekodieren der Nachricht gt beinhaltet Dinge wie Entschluumlsselung
bull Dissassemble ndash only Message Probing gt Pruumlfung des Namespace um zu pruumlfen ob ein
Schema vorhanden ist gegen das die eingehende Nachricht validiert werden kann
bull Validate - Pruumlfung ob die eingehende Nachricht das Schema erfuumlllt
bull Resolve Party - feststellen wer der Absender der Nachricht ist
Stages in einer Send Pipeline
bull Pre-Assemble - Custom Operations
bull Assemble - Erstellen der Ausgangsnachricht (kann zB beinhalten dass mehrere
Nachrichten zu einer zusammengefuumlgt werden und dergleichen)
bull Encode - Passiert unmittelbar bevor die Nachricht abgeschickt wird
Eigene (Custom) Pipelines koumlnnen in Visual Studio erstellt werden Dazu oumlffnen wir VS als
Administrator und legen eine neue Solution mit dem Namen eBizConOnboarding an und erstellen
das Projekt Pipelines innerhalb dieser Solution
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
25
Fuumlr eine gute Uumlbersicht empfiehlt es sich die Solution entsprechend der BizTalk Application zu
benennen und fuumlr jedes Artefakt ein eigenes Projekt anzulegen
Mit [Rechtsklick] auf das Pipeline-Projekt gt [Addhellip] gt [New Item] gelangen wir zum Wizard fuumlr die
Erstellung von BizTalk Artefakten Wir waumlhlen die Receive Pipeline und vergeben die aussagekraumlftige
Bezeichnung JsonReceivePipeline
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
26
Im Anschluss koumlnnen wir die benoumltigten Pipeline-Bestandteile einfach aus der Toolbox per Drag and
Drop hinzufuumlgen
Die Send Pipeline wird zwar im Szenario nicht benoumltigt ist aber schnell erstellt Sie beinhaltet
entsprechend nur das JSON encoder Element
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
27
Um die Pipelines nun in unsere BizTalk Application zu bringen bietet uns Visual Studio mittels
[Rechtsklick] auf SolutionProjekt die bequeme Option Deploy Damit werden die BizTalk-Artefakte
die mittels GUI erstellt worden sind in DLLs kompiliert signiert und in den GAC deployt
Hierzu muss in den Projekt-Properties unter Signing ein Strong Key generiert werden
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
28
der mit Klick auf OK auch in der Solution zu sehen isthellip
Zusaumltzlich muss in den Projekt-Properties unter Deployment der Name der BizTalk Applikation
richtig eingetragen sein
(Wichtig Signatur und Application Name muumlssen bei jedem BizTalk-Projekt vorhanden sein dass
deployt werden soll ansonsten erhalten wir in Visual Studio entsprechende Fehlermeldungen)
Nun koumlnnen mit einem Rechtsklick auf das Pipelines-Projekt und Deploy die Pipelines zur
Application hinzugefuumlgt werden und sind bei Erfolg auch in der Administration Console zu sehen
(notfalls F5 druumlcken)
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
29
22315 RECEIVE LOCATION KONFIGURIEREN
Nun muss der Receive Location bdquoOnboarding_Receive_ContactCriteria_FILEldquo noch auf die gerade
erstellte bdquoJsonReceivePipelineldquo umgeruumlstet werden
Wir navigieren also zur Receive Location und koumlnnen nun die PassThruPipeline durch unsere gerade
bereitgestellten JsonReceivePipeline ersetzen
22316 XML-SCHEMA AUS JSON GENERIEREN UND RECEIVE LOCATION UPDATEN
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
30
XML-Schemas (praumlzise XML Schema Definition - XSD) werden im BizTalk-Kontext ua dazu
verwendet um Nachrichten die Receive Ports passieren zu validieren undoder in neue Nachrichten
zu transformieren (Mapping) Sie stellen Vorschriften und Bedingungen die XML-Dateien erfuumlllen
muumlssen um als valide zu gelten Man kann sie sich wie eine Schablone vorstellen durch die eine
XML-Datei reibungsfrei hindurch passen muss
Um XML Schemas zu definieren wurde die XML Schema Definition Language geschaffen Wer die
XSDL beherrscht koumlnnte mit einem simplen Texteditor (zB Notepad) Schemas definieren die
problemlos von BizTalk verwendet werden koumlnnen Das ist dann je nach Umfang der Daten mehr
oder weniger aufwendig bis schmerzhaft Aber vor allem ist das gar nicht noumltig
Denn zu den groszligen Staumlrken von BizTalk zaumlhlt die umfangreiche Toolpalette Dazu gehoumlren
zahlreiche Wizards fuumlr verschiedene Zwecke So existiert auch ein Wizard um XML-Schemas aus
JSON Dateien zu generieren den wir im Visual Studio wiederfinden
Zuruumlck in Visual Studio
Da wir nun eine neue Artefaktkategorie zu unserer Visual Studio Solution hinzufuumlgen erstellen wir
zunaumlchst das BizTalk-Projekt ExternalSchemas und rufen dort den erwaumlhnten Wizard auf indem
wir mit einem Rechtsklick [Add] gt [New Item] gt [JSON Schema Wizard] aufrufen
Der Wizard erwartet eine JSON-Datei als Input (das ist die ContactCriteriaJsonInstancejson die wir
im Schritt 1 auf dem Desktop abgelegt haben) Weiterhin muss man Root und Namespace
festlegen (fuumlr Message Probing benoumltigt)
Mit Klick auf Finish liest der Wizard die JSON-Datei aus und erstellt eine XSD die den Aufbau der
JSON widerspiegelt
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
31
Die Unterscheidung zwischen Internal- und External Schemas obliegt den Praumlferenzen des Entwicklers
Es gibt auch Entwickler die saumlmtliche Schemas in einem einzigen Projekt unterbringen Auf der
anderen Seite kann man natuumlrlich auch fuumlr jede Quelle und jedes Ziel ein dediziertes Schema-Projekt
anlegen Mit den Projekten InternalSchemas und ExternalSchemas soll im Rahmen unseres Szenarios
der Uumlbersichtlichkeit jedoch genuumlge getan sein
Wichtig Das eben erstellte Schema schreibt auch die Struktur vor in die die JSON von der
JsonReceivePipeline gebracht werden soll
Nun haben wir in der Schema-Definition Root Node und Namespace festgelegt Beides sind
Elemente die in einer JSON klassischerweise nicht vorhanden sind
Um dieses Delta zu fuumlllen muss die vorher erstellte Pipeline in der Receive Location noch
entsprechend nachjustiert werden
Wir begeben uns also zuruumlck in die Receive Location Onboarding_Receive_ContactCriteria_FILE
klicken auf [hellip] neben [JsonReceivePipeline] und belegen dort RootNode und RootNodeNamespace
mit denselben werten die wir dem JSON Schema Wizard mitgebgeben haben
2232 SCHRITT 2 ndash KONTAKT-OBJEKT AUS DYNAMICS 365 CRM ABHOLEN
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
32
MessageBox
Send
Receive
Schritt 2 sieht vor dass die Information aus Schritt 1 (Abfragekriterium) fuumlr eine REST-Request zum
API Resource Endpoint von unserem Dynamics 365 CRM Tenant verwendet wird
Wie die Abbildung bereits zeigt wird das Kriterium im XML-Format vom Send Port verwendet
Dies ist noumltig da der Send Port einen WebHttp-Adapter verwendet der Dynamics 365 ansteuert
und dieser mit sogenannten Promoted Properties aus der ContactCriteraXML arbeitet Die Werte
aus den Promoted Properties entscheiden uumlber die endguumlltige URI die vom Adapter aufgerufen
wird
Was das im Detail bedeutet wird in diesem Abschnitt erklaumlrt
Noumltige Schritte
1 Promoted Properties festlegen
2 Send Port einrichten und Konfigurieren
3 JSON in ein XML-Objekt uumlberfuumlhren
4 ContactXML auf Canonical Schema mappen
5 Map in BizTalk konfigurieren
22321 PROMOTED PROPERTIES FESTLEGEN
Alle Nachrichten die durch BizTalk hindurchgehen werden erfasst und in der MessageBox abgelegt
Wenn Werte aus diesen Nachrichten an anderer Stelle in BizTalk verwenden moumlchte (etwa in
Orchestrations oder in Send Ports) dann muss man explizit angeben welche Werte das sind da alle
anderen Felder der XML-Datei bei der Verarbeitung ignoriert werden um Rechenaufwand zu sparen
Diesen Vorgang nennt man Property Promotion
Innerhalb der Schema Definition bdquoContactCriteriaxsdldquo legen wir durch [Rechtsklick] gt [Promote]
zunaumlchst EntitySet als Promoted Property fest (Quick Promotion soll genuumlgen)
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
33
Und tun danach dasselbe fuumlr Criteria Das angestrebte Ergebnis sieht dann so aus
Um Promoted Properties zu identifizieren nutzt BizTalk sogenannte Property Schemas die in Visual
Studio automatisch bei der Quick Promotion erstellt werden sofern noch nicht vorhanden
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
34
Poperty1 wird automatisch mitgeneriert und kann ignoriert oder auch geloumlscht werden
Zum Deployment der Schemas muumlssen die uumlblichen Schritte erfolgen (Signatur + Application
Name) wobei wir nun die zuvor erstellte Datei myOnboardingKeysnk wiederverwenden koumlnnen
22322 SEND PORT EINRICHTEN UND KONFIGURIEREN
Zunaumlchst muss ein passender Send Port angelegt werden Da der Send Port nun nicht nur in eine
Richtung arbeitet sondern nach Absenden der Request auch eine Antwort (Naumlmlich das Kontakt-
Objekt) von Dynamics erwartet ist Static Solicit-Response Send Porthellip die richtige Option in diesem
Fall
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
35
Auch hier gelten natuumlrlich wieder die bekannten Konventionen wonach die Bezeichnung des Send
Port wie folgt lautet bdquoOnboarding_SSR_Contactldquo
Der fuumlr REST-Calls vorgesehene BizTalk Adaper lautet WCF-WebHttp Wir muumlssen auf die Promoted
Properties der ContactCriteriaXML zugreifen und waumlhlen daher bei Send Pipeline XMLTransmit
Da die JSON-Antwort des Service wieder in XML transformiert werden muss muss bei Receive
Pipeline unsere JsonReceivePipeline ausgewaumlhlt werden Fuumlr den Moment stellen wir dort aber
PassThru ein (wird im weiteren Verlauf aufgeklaumlrt)
In der Adapterkonfiguration legen wir im Reiter [General] die URI des REST-Service fest den wir
ansprechen wollen Weiterhin muss die HTTP-Methode sowie das Variablenmapping (von den
Promoted Properties zur URI) festgelegt werden
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
36
Beim Variablenmapping orientieren wir uns am Property Schema das wir eben erstellt haben
Refresher Variablenmapping
Alles begann mit einer JSON Die JSON ist unsere initiale Nachricht und beinhaltet die Informationen
fuumlr die Request an Dynamics Aus der JSON wurde mithilfe einer XSD eine XML-Datei dessen
Properties promoted sind Die Property-Promotions sind in einem PropertySchema erfasst das
verwendet wird um die Informationen aus der XML auslesen zu koumlnnen und schlieszliglich die finale GET-
Request zu bauen die wir an die Dynamics CRM API senden Die nachfolgende Darstellung zeigt wie
die einzelnen Komponenten zusammenspielen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
37
22323 TEST ndash CONTACT REQUEST 1
Eine einfache Methode schnell zu sehen ob der Nachrichtenfluss funktioniert wie geplant ist einen
dedizierten Send Port einzurichten
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
38
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactJSON
Send
Dieser erhaumllt von mir die Bezeichnung SendPort1 hat einen Filter auf Onboarding_SSR_Contact
und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM
ab Wir sind nun fuumlr den ersten Testlauf bereit Ports koumlnnen gestartet und die Receive Location
enabled werden und wir koumlnnen die Datei
ContactCriteriaJsonInstancejson
vom Desktop in den Ordner copypasten der von unserer Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Zu erwarten ist nun im besten Fall dass das Kontakt-Objekt bdquoMax Mustermannldquo im Ordner
ContactsFromCRM landet
Oder eben das hier
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
39
22324 EXKURS OAUTH 20
Der Grund fuumlr die Fehlermeldung 401 ist offensichtlich mangelnde Authentifizierung
Dazu muss verstanden werden dass die API unserer Dynamics 365 Instanz mittels Azure Active
Directory (AAD) abgeriegelt ist AAD ist der Identity Provider von Microsoft der den OAuth 20
Standard implementiert
OAuth 20 beschreibt sich selbst wie folgt
The OAuth 20 authorization framework enables a third-party application to obtain limited access
to an HTTP service either on behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service or by allowing the third-party application to
obtain access on its own behalf
Dabei sieht das Framework die folgenden vier Rollen vor
bull Resource Datenstamm Service hellip
bull Resource Owner in der Regel menschlich besitzt die Resource und moumlchte darauf zugreifen
bull Client Wird vom Resource Owner verwendet um auf die Resource zuzugreifen
bull Authority kennt alle Teilnehmer und regelt Zugriffe
Die Authentifizierung an der Resource erfolgt dabei stets via Access Token das von der Authority
an den Client vergeben wird der nur mit zulaumlssigem Token Zugriff auf die Resource erhaumllt
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
40
Resource Owner
ResourceClient
Authority
Ist registriert bei Vertraut
Gewaumlhrt Token
Bestaumltigt Clientzugriff
Greift zu auf
benutzt besitzt
OAuth 20 gibt weiterhin je nach Szenario (Client-Server Server-Server ) verschiedene
Moumlglichkeiten vor wie die Teilnehmer interagieren koumlnnen - sogenannte Workflows Die folgenden
Workflows werden von Authority Providern wie Google und Azure Active Directory problemlos
unterstuumltzt
bull Authorization Code Grant Flow
bull Implicit Grant Flow
bull Resource Owner Password Grant Flow
bull Client Credentials Flow
Fuumlr unser Szenario ist es erforderlich dass BizTalk selbststaumlndig (ohne manuelle Eingabe des
Passwortes durch den Resource Owner) im Namen eines dedizierten Nutzers auf die Kontakte
zugreifen kann zu denen auch der dedizierte Nutzer Zugriff hat
Dazu muumlssen wir BizTalk die User Credentials mitgeben Fuumlr dieses Szenario ist der Resource Owner
Password Grant Flow das Mittel der Wahl der kurz erklaumlrt werden soll
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
41
Authorization Endpoint
Token Endpoint
Authenticate Client App
cID+cSecret + Resource Owner Password Credentials
Redirect back to client with Token in Params
Valid
ate
To
ken
Request Data
Access-Token Header
1
2
Schritt 1 Der Client (in unserem Fall der BizTalk Sendport) ruft die URL des Authorization Endpoints
auf und gibt ClientID ClientSecret sowie die Password Credentials des Resource Owners als
Paramter mit Als Antwort erhaumllt er das Token mit dem er Zugang zur Resource bekommt
Schritt 2 Mit dem Token im HTTP-Authorization-Header wendet sich der Client (im Namen des
Resource Owners) an die API von unserer Dynamics 365 CRM Instanz Diese laumlsst das Token vom
Token Endpoint der Authority pruumlfen und gibt bei Erfolg die angeforderten Daten zuruumlck
223241 OAUTH ROLLEN IM AAD FESTLEGEN
Der Workflow verlangt nach den folgenden Artefakten
bull UserPassword
bull UserName
UserPassword und Username sind geklaumlrt Aber zum Workflow gehoumlrt auch noch
bull RedirectUri (Redirect URI des Clients der im AAD registriert ist)
bull ClientID (Application ID des Clients der im AAD registriert ist)
bull ResourceId (Root des Dynamics-Tenants)
bull Authority (OAUTH 20 AUTHORIZATION ENDPOINT AAD)
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
42
Diese muumlssen in der Authority festgelegt werden
Da es sich bei Dynamics um einen Dienst von Microsoft handelt bietet es sich an auch gleich
Microsoft als Identityprovider und somit das AAD als Authority zu nutzen Um zum AAD zu
gelangen rufen wir httpsportalazurecom auf loggen uns mit unserer Subscription ein
(die auf der auch der Office 365Dynamics-Tenant laumluft) und navigieren in der Uumlbersicht links zu
Azure Active Directory
Nun befinden wir uns in der Authority und koumlnnen alle Rollen festlegen Relevant ist hier der Punkt
App Registrations Hier legen wir durch Klick auf New Application registration den Client in
unserem Szenario an
Es handelt sich um eine Native Application die die Bezeichnung BTS-Zugriff erhaumllt Die Redirect
Uri ist zwar aus konzeptioneller Sicht fuumlr den Workflow nicht wichtig wird aber vom AAD dennoch
als Identifizierungsmerkmal gebraucht
Mit Klick auf Create wird der Client angelegt Hier sehen wir auch schon die Application ID die wir
fuumlr den Token Request brauchen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
43
Somit koumlnnen wir ClientId und Redirect Uri nun abhaken
Uumlber Required Permissions koumlnnen wir festlegen dass der gerade angelegte Client auf unsere
Dynamics CRM zugreifen darf
Die ResourceId lautet dann https[TENANT]apicrm4dynamicscom
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
44
Nun fehlt nur noch die Authority Dazu muss man sich wieder zu App Registrations begeben und
etwas weiter oben nach Endpoints suchen
Wie man dann sieht hat Azure Active Directory einiges an Zugriffsmoumlglichkeiten zu bieten Fuumlr unser
Szenario benoumltigen wir den OAUTH 20 AUTHORIZATION ENDPOINT
223242 OAUTH MIT CUSTOM BEHAVIORS IN BIZTALK IMPLEMENTIEREN UND CRM-CALL
ABSCHLIEszligEN
Die Informationen die wir nun vorliegen haben sind
bull UserPassword
bull UserName
bull RedirectUri
bull ClientID
bull ResourceId
bull Authority
Und inzwischen verstehen wir sogar die Fehlermeldung von vorhin besserhellip
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
45
hellipdort wird uns ResourceId und Authority sogar bereits serviert
Nun da wir im AAD alles fuumlr den Resource Owner Password Grant Flow vorbereitet haben muumlssen
wir unserem bdquoOnboarding_SSR_Contactldquo Send Port nur noch beibringen sich auch entsprechend zu
benehmen Das wird uumlber den Reiter Behaviour geregelt
Behaviors kommen aus dem WCF-Universum und beschreiben was passieren soll bevor Nachrichten
versendet werden nachdem Nachrichten empfangen worden sind
Wir oumlffnen die Admin Console und navigieren zu [eBizConOnboardingApplication] gt [Send Ports]
gt [Onboarding_SSR_Contact] gt Configure gt Behavior
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
46
Hier ist derzeit noch nicht wirklich etwas zu sehen Wir muumlssen unsere Behavior erst noch definieren
und dann im Send Port hinzufuumlgen Und wie geht das
2232421 CUSTOM BEHAVIORS IM SEND PORT ANWENDEN
Am Ende des Tages handelt es sich bei einer Behavior um eine NET - Klassenbibliothek die in den
GAC deployt und der machineconfig hinzugefuumlgt werden muss (32 und 64bit) Das VS-
Projekt das die noumltige Behavior enthaumllt steht auskommentiert als Download bereit
Wenn das Deployment erfolgreich war so steht die DLL auch im Send Port als EndpointBehavior
zur Auswahl und kann unserem OAuth 20 Workflow konfiguriert werden
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
47
2232422 TEST ndash CONTACT REQUEST 2
Nachdem der Send Port nun gepatcht ist und mit OAuth 20 umgehen kann koumlnnen wir einen
erneuten Versuch starten Daten aus dem CRM anzufragen Dazu begeben wir uns zuruumlck in den
Ordner der von der Receive Location abgehoumlrt wird
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und kopieren dort wieder die ContactCriteriaJsonInstanceJSON hinein Diesmal erwarten wir keine
Fehlermeldung sondern eine JSON-Datei im Ordner ContactsFromCRM welche die von uns
abgefragten Kontaktinformationen enthaumllt
22325 JSON IN EIN XML-OBJEKT UumlBERFUumlHREN
Um die JSON auf dem Weg zur MessageBox in XML zu uumlberfuumlhren wenden wir dieselben Schritte
an wie in Schritt 2 - XML-Schema aus JSON generieren verwenden nun aber die Kontakt-JSON-
Datei aus dem Ordner
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
48
CeBizConOnboardingMessagesContactsFromCRM
Die wir gerade von Dynamics erhalten haben Als Namespace verwenden wir
httpExternalSchemasContact
Nachdem das Schema deployt ist muumlssen wir natuumlrlich noch die Pipeline im Send Port
Onboarding_SSR_Contact nachjustieren
Refresher Zu Testzwecken haben wir bdquoSendPort1ldquo eingerichtet SendPort1 hat einen Filter auf
Onboarding_SSR_Contact und legt alles was aus den abonnierten Port kommt im Ordner
CeBizConOnboardingMessagesContactsFromCRM ab Dieses Mal erwarten wir jedoch einen
CRM-Kontakt im XML-Format
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
49
Receive MessageBox
Send
Receive
Contact
CriteriaJSON
1
2
ContactXML
Send
SendPort1 muss daher noch geringfuumlgig angepasst werden
An dieser Stelle kann der uumlbliche Testablauf durchgespielt werden
Wir copypasten bdquoContactCriteriaJsonInstancejsonldquo vom Desktop in den Ordner der von unserer
Receive Location uumlberwacht wird naumlmlich
CeBizConOnboardingMessagesReceiveCriteriaJSONs
Und siehe da
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
50
Max Mustermann wurde als JSON von Dynamics CRM erhalten und liegt nun im XML Format in
unserem Ordner
22326 CONTACTXML AUF CANONICAL SCHEMA MAPPEN
Ein Dynamics 365 CRM Kontakt wird durch zahlreiche Eigenschaften beschrieben deutlich mehr
Eigenschaften als wir fuumlr unser Szenario benoumltigen daher uumlberfuumlhren wir ihn in einen kanonischen
Aufbau ein Canonical Schema
Canonical Schemas gehoumlren zu den Best Practices im Integrationskontext Als konisch wird ein Schema
dann bezeichnet wenn es als Ausgangsobjekt fuumlr die meisten (moumlglichst alle) Integrationen im
Szenario dient Das Canonical Schema enthaumllt eine Fuumllle von Informationen uumlber ein Objekt was es
ermoumlglicht Die Integration von Folgeandwendungen die dieses Objekt betreffen flexibel und einfach
zu gestalten
Bevor das eigentliche Mapping stattfinden kann muss zunaumlchst einmal ein entsprechendes Schema
vorliegen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
51
Unser Szenario hat die Provisionierung in Office 365 zum Ziel Office 365 nutzt das Azure Active
Directory fuumlr die Nutzerverwaltung Der Aufbau eines AAD-Nutzerkontos soll daher als Vorbild fuumlr
unser Canonical Schema dienen
Wie Nutzerkonten im AAD aufgebaut sind erfaumlhrt man indem man die folgenden Befehle in
PowerShell ausfuumlhrt (MSOnline notwendig)
1 Connect-MsolService (Dann Credentials des O365-Tenants eingeben)
2 Get-MsolUser -UserPrincipalName UserPrincipalNameo365tenantdomain | fl
Das aus diesem Aufbau resultierende Canonical Schema mit der Bezeichnung
EmployeeEnvelopexsd steht zum Download bereit und muss nur noch in unsere Visual Studio
Solution importiert werden Der Uumlbersicht halber erstellen wir zunaumlchst das Projekt
InternalSchemas in unserer VS-Solution und fuumlgen das Schema dann via [Rechtsklick] gt [Add] gt
[Extisting Itemhellip] zum Projekt hinzu
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
52
(Wichtig Damit die InternalSchemas in der Admin Console sichtbar sind muss das Projekt natuumlrlich
deployt werden Dazu nicht vergessen fuumlr das Projekt in den Properties noch die Signatur und
Application Name festzulegen)
Nun da das Canonical Schema vorliegt kann das eigentliche Mapping stattfinden
MessageBox
BizTalk Maps dienen dazu Nachrichten zu transformieren Visual Studio bietet dafuumlr eine grafische
Benutzeroberflaumlche in die sich die Datentransformationen bequem per Drag and Drop eintragen
lassen
Gemaumlszlig Best Practice legen wir nun das Projekt Maps an Die Benamung der Map folgt der Vorgabe
[ExtInt]_[Quellschema]_To_[ExtInt]_[Zielschema] und lautet demnach
Ext_Contact_to_Int_EmployeeEnvelopebtm
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
53
Bevor Source und Destination Schemas auswaumlhlbar sind muumlssen wir fuumlr das Projekt bdquoMapsldquo die
Referenz auf die Schema-Projekte setzen
Erst dann kann die Festlegung von Source und Destination erfolgen
[Open Source Schema] gt [Maps] gt [References] gt [ExternalSchemas] gt [Schemas] gt
[ExternalSchemasConact]
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
54
[Open Destination Schema] gt [Maps] gt [References] gt [InternalSchemas] gt [Schemas] gt
[InternalSchemasEmployeeEnvelope]
Sind Source und Destination Schema festgelegt so kann das Mapping durchgefuumlhrt werden
FirstName und LastName lassen sich dabei noch 11 uumlbernehmenhellip
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
55
Fuumlr die anderen relevanten Felder wurde aber der Einfachheit halber der String Concatenate
Functoid eingesetzt Um zu klaumlren was hier genau passiert sollen zunaumlchst die einzelnen Felder die
mittels Functoid befuumlllt werden erlaumlutert werden
bull CorrelationID - Identifizierer der Nachricht des Vorgangs uumlber BizTalk-Grenzen hinaus
(Hier TestMessage)
bull MessageStatus - gibt Aufschluss daruumlber wie die Verarbeitung im WCF-ProvisonService
verlaufen ist (Hier Not Provisioned)
bull Tenant - Mandant Hinweis auf O365-Instanz zur Anwendung von Business Rules (Hier
eBizTI)
bull LicenseDescription - enthaumllt die O365-Lizenz die dem user zugewiesen werden soll (Hier
eBizTIDYN365_ENTERPRISE_PLAN1)
bull UsageLocation - richtet sich nach dem Azure-Tenant und dem Teil der Welt des
Rechenzentrums in dem er betrieben wird (Hier DE)
bull UserPrincipalName - eindeutiger Bezeichner des O365-Users der provisioniert werden soll
(Hier testUserteamintegrationde)
bull AdminPrincipalName - UserPrincipalName des O365-Admins in dessen Namen ( mit
dessen Berechtigung) die Provisionierung durchgefuumlhrt wird (Hier [YourAdminLogin])
bull AdminPassword - Password des O365-Admins (Hier [YourAdminPassword])
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
56
Durch den String Concatenate Functoid werden all diese Werte hart in die Nachricht geschrieben
In einem Multi-Mandanten-Szenario wuumlrde man die variable Zuweisung der Werte durch die
Business Rule Engine bewerkstelligen
Die Map ist nun erstellt und kann deployt werden Dazu legen wir in den Properties wieder die
Signatur fest und die Application zu der die Map hinzugefuumlgt werden soll
hellipund koumlnnen mit Rechtsklick auf das Projekt Maps und dann [deploy] die Maps unserer BizTalk-
Application bereitstellen
22327 MAP IN BIZTALK KONFIGURIEREN
Wir legen die gerade bereitgestellte Map Ext_Contact_to_Int_EmployeeEnvelopebtm als Inbound
Map in dem Send Port fest der das Kontaktobjekt aus Dynamics abholt
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
57
Nach Durchfuumlhrung des uumlblichen Tests mittels SendPort1 sollte das Kontaktobjekt das im Ordner
ContactsFromCRM dem Canonical Schema gerecht werden
2233 SCHRITT 3 ndash PROVISIONIERUNGSKANAL EINRICHTEN
MessageBox
Send
Receive
Nun da das Canonical Schema und das zugehoumlrige Mapping in unserer BizTalk-Solution vorliegen
koumlnnen wir die weiteren Schritte ausfuumlhren um diesen Teil des Szenarios komplett zu machen
1 Send Port zur Kommunikation mit dem WCF-Service einrichten
2 WCF-Service konsumieren um Schemata fuumlr Request und Response zu generieren
3 Notwendige Informationen des Canonical Schema auf die WCF-Request mappen
4 WCF-Response zuruumlck auf das Canonical Schema mappen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
58
22331 SEND PORT ZUR KOMMUNIKATION MIT DEM WCF-SERVICE EINRICHTEN
Was wir fuumlr unser Szenario benoumltigen ist ein Send Port der mit dem WCF-ProvisionService
kommuniziert Der Send Port soll nicht nur Anfragen senden sondern auch die Antwort vom Service
entgegennehmen
Um den entsprechenden Send Port anzulegen begeben wir uns in die Admin Console und erstellen
unter unserer Application einen Static Solicit-Response Send Port mit der konventionsgetreuen
Bezeichnung Onboarding_SSR_WCF
22332 WCF-SERVICE KONSUMIEREN UM SCHEMATA FUumlR REQUEST UND RESPONSE ZU
GENERIEREN
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
59
Sobald der WCF-Service aus Schritt Prep - WCF Service Vorbereiten online gegangen ist sollte
dieser mittels bdquoBizTalk WCF-Consuming Wizardldquo konsumiert werden um die entsprechenden
Schemata zu generieren die wir fuumlr den weiteren Nachrichtenfluss benoumltigen
Dazu wechseln wir wieder ins Visual Studio verwenden den Wizard um die Schemas aus der
Schnittstellenbeschreibung des ProvisionService zu generieren (Um die Uumlbersichtlichkeit zu wahren
wurde innerhalb des ExternalSchemas-Projektes ein Ordner mit entsprechend aussagekraumlftigem
Namen angelegt) [Rechtsklick auf ExternalSchemas] gt [Add] gt [Add Generated Items] gt hellip
hellip[Consume Adapter Service] gt [Add] gt hellip
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
60
hellipRadio bei Metadata Exchange (MEX) Endpoint gt Nexthellip
hellip[Bei Metadata Adresse (URL) fuumlgen wir den Endpoint unseres ProvisionService ein] gt [Get] gt [Next]
gt hellip
Woraufhin der Wizard die Schemas im Ordner anlegt Relevant ist fuumlr uns nun die XSD-Datei mit
dem Namen ProvisionService_tempuri_org da diese die Operationen beinhaltet die wir mit dem
Send Port aufrufen wollen
Abschlieszligend muss das ExternalSchemas-Projekt natuumlrlich erneut deployt werden damit in der
Admin Console damit gearbeitet werden kann
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
61
22333 NOTWENDIGE INFORMATIONEN DES CANONICAL SCHEMA AUF DIE WCF-REQUEST
MAPPEN
MessageBox
Die CRM Kontaktdaten liegen nun in Form des kanonischen EmployeeEnvelope vor Als naumlchstes
muumlssen die Informationen aus der kanonischen Nachricht in die ProvisionRequest uumlberfuumlhrt werden
Auch hier wird wieder ein Mapping noumltig Entsprechend ist im VS-projekt Maps die BizTalk Map
mit der Bezeichnung ldquoInt_EmployeeEnvelope_to_Ext_ProvisionRequestrdquo anzulegen
Source Schema ist unser bdquoEmployeeEnvelopexsdldquo und Destination Schema ist die vorher mittels
Wizard generierte bdquoProvisionService_tempuri_orgxsdldquo (als Root Node waumlhlen wir die Operation die
vom Service ausgefuumlhrt werden soll gt in unserem Fall provision)
Zugunsten der Uumlbersichtlichkeit wurden im Bild nur die fuumlr die Provisionierung unbedingt noumltigen
Mappings eingetragen Die Felder isLicensed ObjectId und WhenCreated beschreiben den
Verlauf der Datenverarbeitung im Service und werden demnach erst auf dem Ruumlckweg ausgefuumlllt
Sie bedeuten im Einzelnen
isLicensed - gibt Auskunft daruumlber ob der User (bereits) lizensiert ist
ObjectId - Guid des AAD-Benutzerkontos bei erfolgreicher Provisionierung
WhenCreated - Zeitstempel der Erstellung des AAD-Benutzerkontos bei erfolgreicher
Provisionierung
22334 WCF-RESPONSE AUF DAS CANONICAL SCHEMA MAPPEN
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
62
MessageBox
Nachdem der Service die Anfrage verarbeitet hat muss die Antwort wieder in unser kanonisches
Format gebracht werden Hierzu erstellen wir die Map
Ext_ProvisionResponse_to_Int_EmployeeEnvelope und verfahren wie gehabt
Die Maps koumlnnen nun deployt und dem Send Port Onboarding_SSR_WCF hinzugefuumlgt werden
Da wir Maps verwenden wollen stellen wir zunaumlchst beide Pipelines auf XMLhellip
Und legen dann Inbound- und Outbound Map festhellip
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
63
Zusaumltzlich muss der Filter so angepasst werden dass bdquoOnboarding_SSR_WCFldquo Nachrichten
abonniert die der Port bdquoOnboarding_SSR_Contactldquo in der MessageBox ablegt
2234 SCHRITT 4 - SZENARIO ABSCHLIEszligEN
Um das Abschlussergebnis des Szenarios zu betrachten gibt es mehrere Moumlglichkeiten Man kann
entweder den bereits bestehenden SendPort1 neu konfigurieren oder einen dedizierten SendPort2
einrichten der alles Moumlgliche tun kann (Versand des Provisionierungsstatus per E-Mail Weitergabe
an eine Logic App REST-Service etc)
Ich entscheide mich fuumlr die erste Option und aumlndere den Filter in SendPort1 von
BTSSPName == Onboarding_SSR_Contact
Auf BTSSPName == Onboarding_SSR_WCF
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
64
Anschlieszligend aumlndere ich auch den Ordner in den das Testergebnis abgelegt werden soll auf
CeBizConOnboardingMessagesProvisionResult
Den ich extra dafuumlr anlege
22341 ERWARTETER ABLAUF
Der WCF-ProvisionService sowie alle Ports sind eingerichtet und aktiviert Gemaumlszlig der Subscriptions
im BizTalkServer und des damit einhergehenden Nachrichtenflusses sollte nachdem die Datei
ldquoContactCriteriaJsonInstanceJSONrdquo in den Ordner ldquoReceiveCriteriaJSONsrdquo kopiert wird folgendes
passieren
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
65
1 Die Receive Location ldquoOnboarding_Receive_ContactCriteria_FILErdquo holt die Nachricht ab
wandelt sie zu XML um und legt sie in der MessageBox ab
2 Der Static Solicit-Response-Port ldquoOnboarding_SSR_Contactrdquo der diese Nachricht abonniert
hat fuumlhrt damit eine Request auf unsere Dynamics 365 CRM Instanz aus Die JSON-Antwort
vom CRM wird ebenso wie in der Receive Location zuvor in XML umgewandelt Durch die
Inbound-Map ldquoExt_Contact_to_Int_EmployeeEnveloperdquo wird die Response dann in die
Schemadefinition des EmployeeEnvelope ldquogestanztrdquo bevor sie in der MessageBox abgelegt
wird
3 Der Static Solicit-Response-Port ldquoOnboarding_SSR_WCFrdquo abonniert die Nachrichten von
ldquoOnboarding_SSR_Contactrdquo und greift sich in diesem Zug den gerade erhaltenen CRM-
Kontakt um diesen an den WCF-ProvisonService weiterzureichen Dieser fuumlhrt die
Provisionierung in Office 365 durch
4 Um das Ergebnis zu uumlberpruumlfen haben wir ldquoSendPort1rdquo eingerichtet Fuumlr diesen Send Port
liegt eine Subscription auf ldquoOnboarding_SSR_WCFrdquo vor Er greift also die finale Antwort vom
WCF-Service ab was im besten Fall der erfolgreich provisionierte AAD-Nutzer ist und legt
sie im XML Format im Ordner ldquoProvisionResultrdquo ab
22342 Ergebnis
Nachdem nun ein letztes Mal die Abfragekriterien fuumlr unseren CRM-Kontakt im Ordner
ldquoReceiveCriteriaJSONsrdquo abgelegt worden sind sehen wir nur noch wie sie von der Receive Location
abgeholt werden und beobachten dann gespannt den Ordner bdquoProvisionResultldquo der doch einige
Sekunden lang unberuumlhrt bleibt bis endlich die Nachricht vom WCF-Service eintrifft
Um Tricks auszuschlieszligen pruumlfen wir im Admin Center nach ob Max Mustermann tatsaumlchlich in
unserer Office 365 Instanz angelegt worden ist und eine Lizenz erhalten hathellip
66
Und koumlnnen das Szenario damit abschlieszligen
66
Und koumlnnen das Szenario damit abschlieszligen
