Microsoft BizTalk Adapter voor Microsoft Dynamics CRM 4.0Handleiding voor installatie en gebruik

Augustus 2009

De gegevens in dit document inclusief URL's en andere verwijzingen naar internetwebsites, kan zonder kennisgeving worden gewijzigd. Tenzij anders aangegeven zijn de hierin beschreven voorbeelden van bedrijven, organisaties, producten, domeinnamen, e-mailadressen, logo's, personen, plaatsen en gebeurtenissen fictief. Associaties met werkelijk bestaande bedrijven, organisaties, producten, domeinnamen, e-mailadressen, logo's, personen, plaatsen of gebeurtenissen zijn onbedoeld en mogen niet worden afgeleid. Het voldoen aan alle toepasselijke auteursrechtwetten is de verantwoordelijkheid van de gebruiker. Onverlet de rechten volgens het auteursrecht mag geen enkel deel van dit document worden gereproduceerd, opgeslagen of opgenomen in een ophaalsysteem, noch overgebracht in enige vorm of via enig middel (elektronisch, mechanisch, fotokopie, opname of anderszins), noch voor enig doel, zonder de uitdrukkelijke schriftelijke toestemming van Microsoft Corporation.

Microsoft heeft mogelijk patenten, patentaanvragen, merken, auteursrechten of andere intellectuele eigendomsrechten die betrekking hebben op de inhoud van dit document. Behalve voor zover uitdrukkelijk aangegeven in geschreven gebruiksrechtovereenkomsten van Microsoft geeft de verstrekking van dit document geen licenties voor deze octrooien, handelsmerken, auteursrechten of intellectuele eigendomsrechten.

2009 Microsoft Corporation. Alle rechten voorbehouden.

Microsoft, MS-DOS, Windows, Windows Server, Windows Vista, BizTalk, Great Plains, Microsoft Dynamics en Visual Studio zijn gedeponeerde merken of merken van Microsoft Corporation in de Verenigde Staten en/of andere landen.

Alle overige merken zijn eigendom van hun respectieve eigenaars.

Inhoud

Inleiding...............................................................................................................................4Productoverzicht..................................................................................................................4Ondersteuning......................................................................................................................4Installatie..............................................................................................................................5Op locatie: Een verzendingspoort maken als de gebruiker van het BizTalk Server-proces tevens de gebruiker voor Microsoft Dynamics CRM is......................................................6Op locatie: Een verzendingspoort maken als de gebruiker van het BizTalk Server-proces niet de gebruiker voor Microsoft Dynamics CRM is..........................................................8

De host maken.................................................................................................................8Het hostexemplaar maken................................................................................................9De nieuwe verzendingshandler voor de adapter maken................................................10De verzendingspoort maken met de nieuwe verzendingshandler..................................11

IFD: Een verzendingspoort maken....................................................................................12Het schema ophalen...........................................................................................................13Run-timegedrag.................................................................................................................21Een beveiligde logboekpadmap maken.............................................................................22Bekende problemen...........................................................................................................22

InleidingDit document biedt een productoverzicht en beschrijft de installatie en het gebruik van de Microsoft® BizTalk® Server Adapter voor Microsoft Dynamics® CRM 4.0

In dit document wordt beschreven hoe u een verzendingspoort voor deze adapter kunt maken en schema's van Microsoft Dynamics CRM kunt ophalen.

Deze handleiding is bedoeld voor gebruikers die op de hoogte zijn met de basisbegrippen van Microsoft BizTalk Server en Microsoft Visual Studio®.

Productoverzicht

Doel van deze versie

De integratie tussen Microsoft Dynamics CRM en externe zakelijke toepassingen mogelijk maken.

Productscope

De Microsoft® BizTalk® Server 2006 Adapter voor Microsoft Dynamics® CRM 4.0 biedt de volgende mogelijkheden. 1. Beschikbaarheid van Microsoft Dynamics CRM als een verzendingsadapter

2. Ontdekken en gebruik van acties/entiteitsschema's voor verschillende Microsoft

Dynamics CRM-organisaties.

De gebruiker kan bovenstaande mogelijkheden van de adapter gebruiken om een verbinding te maken tussen Microsoft Dynamics CRM en andere toepassingen via de BizTalk Server met de arrangements- en toewijzingsmogelijkheden van de BizTalk Server.

OndersteuningOndersteuning voor de Microsoft® BizTalk® Server Adapter voor Microsoft Dynamics™ CRM 4.0 is beperkt tot de gebieden die in deze Handleiding voor installatie en gebruik zijn aangegeven. Deze gebieden omvatten:

Installatie Verzendingspoorten creëren Schema ophalen van Microsoft CRM

Installatie Vereisten voor de installatie

Voordat u de installatie van Microsoft BizTalk Adapter voor Microsoft Dynamics CRM 4.0 kunt uitvoeren, moet aan de volgende eisen zijn voldaan.1. Een van de volgende ondersteunde versies van BizTalk Server en de vereisten

ervan zijn geïnstalleerd en geconfigureerd:a. BizTalk Server 2009b. BizTalk Server 2006 R2c. BizTalk Server 2006

2. Een ondersteunde versie van Visual Studio is geïnstalleerd.a. BizTalk Server 2009 vereist Visual Studio 2008 SP1.b. BizTalk Server 2006 en 2006 R2 vereisen Visual Studio 2005.

Zie de pagina Systeemvereisten voor BizTalk Server op de website van BizTalk Server voor meer informatie over de vereisten voor BizTalk Server. Houd er rekening mee dat er geen ondersteuning voor deze vereisten is inbegrepen in de ondersteuning voor de Adapter-installatie.

Installatie-instructies1. Download het exe-bestand van het Microsoft Downloadcentrum.2. Dubbelklik op het EXE-bestand. De installatiewizard wordt geopend om u te

begeleiden bij de installatie.3. Nadat de installatie is voltooid, wordt Microsoft Dynamics CRM 4.0

weergegeven in de lijst met adapters in de Beheerconsole voor BizTalk Server zoals weergegeven in afbeelding 1. De Beheerconsole voor BizTalk Server wordt geïnstalleerd met Microsoft BizTalk Server.

4. De gebruiker moet een lokale beheerder zijn en lid zijn van de groep SSO-beheerders om de installatie te kunnen uitvoeren.

Afbeelding 1

Op locatie: Een verzendingspoort maken als de gebruiker van het BizTalk Server-proces tevens de gebruiker voor Microsoft Dynamics CRM is

Volg deze stappen om de verzendingspoort te maken als het BizTalk Server-proces wordt uitgevoerd met de referenties van een Microsoft Dynamics CRM-gebruiker.

Opmerking: De onderstaande stappen zijn voor Microsoft BizTalk Server 2006. U kunt dezelfde stappen gebruiken voor BizTalk Server 2009 door de overeenkomstige toepassingskoppelingen te gebruiken in de map Microsoft BizTalk Server 2009 in het menu Start.

1. Klik op Start en wijs Microsoft BizTalk Server 2006 aan , open BizTalk-beheer en vouw Toepassingen uit, en vouw vervolgens BizTalk-toepassing 1 uit.

2. Klik met de rechtermuisknop op Verzendingspoorten, wijs Nieuw aan en selecteer vervolgens het gewenste type poort.

3. Als het geselecteerde type poort Statisch is, volgt u stap 5-9 om de verzendingshandler op te geven.

4. Als het type poort Dynamisch is, hoeft u geen verzendingshandler te maken, omdat de dynamische poort de standaardverzendingshandler gebruikt.

5. Het dialoogvenster voor eigenschappen van de verzendingspoort wordt geopend zoals aangegeven in afbeelding 2.

6. Typ in het vak Naam de naam van de verzendingspoort.7. Selecteer in de lijst Type de optie Microsoft Dynamics CRM. Klik op

Configurerenom de URL van Microsoft Dynamics CRM weer te geven, selecteer AD-verificatie en kies een van de ingevulde organisaties.

8. Controleer in de lijst Verzendingshandler , of de standaardinstelling BizTalkServer-toepassing is geselecteerd.

9. Selecteer in de lijst Pipeline verzenden XML verzenden of selecteer XML ontvangen voor de responspipeline als u een tweerichtingspoort voor gewenste antwoorden gebruikt.

10. Klik op OK.

Afbeelding 2

Op locatie: Een verzendingspoort maken als de gebruiker van het BizTalk Server-proces niet de gebruiker voor Microsoft Dynamics CRM is

Volg deze stappen om een verzendingspoort te maken als de gebruiker van Microsoft Dynamics CRM andere referenties heeft dan de gebruiker van het BizTalk Server-proces, of als u meerdere verzendingspoorten naar meerdere Microsoft Dynamics CRM-servers maakt.

Dit scenario omvat de volgende stappen:

1. Maak de host. 2. Maak het hostexemplaar.3. Maak de nieuwe verzendingshandler voor de Microsoft Dynamic CRM-adapter.4. Maak de verzendingspoort met de nieuwe verzendingshandler.

Opmerking: De onderstaande stappen zijn voor Microsoft BizTalk Server 2006. U kunt dezelfde stappen gebruiken voor BizTalk Server 2009 door de overeenkomstige toepassingskoppelingen te gebruiken in de map Microsoft BizTalk Server 2009 in het menu Start.

De host maken1. Klik op Start, wijs Microsoft BizTalk Server 2006 aan, open BizTalk-beheer, en

vouw Platform-instellingen uit.2. Klik met de rechtermuisknop op Hosts, wijs Nieuw en selecteer Host.

Het dialoogvenster voor eigenschappen van de host wordt geopend zoals aangegeven in afbeelding 3.

3. Typ een hostnaam in het vak Naam.4. Selecteer in de lijst Type de optie Wordt uitgevoerd.5. Voer in het vak Windows-groep de naam van de groep voor BizTalk-

toepassingsgebruikers of BizTalk Server-beheerders en klik vervolgens op OK.

Afbeelding 3

Het hostexemplaar maken1. Klik op Start, wijs Microsoft BizTalk Server 2006 aan, open BizTalk-

beheer,en vouw Platform-instellingen uit.2. Klik met de rechtermuisknop op Hostexemplaren, wijs Nieuw aan en selecteer

Hostexemplaar. Het dialoogvenster voor eigenschappen van de host wordt geopend zoals aangegeven in afbeelding 4.

3. Selecteer een naam in de lijst Hostnaam.4. Selecteer een server in de lijst Server.5. Klik op Configureren. Het dialoogvenster Aanmeldingsreferenties wordt

geopend.6. Typ in de vakken Aanmelden en Wachtwoord de domeinaanmeldingsnaam en

het wachtwoord van de Microsoft Dynamics CRM-gebruiker. Dit zijn de referenties die worden gebruikt om het hostexemplaar uit te voeren en de verzendingshandler te maken (zoals uitgelegd in de volgende procedure) voor de Microsoft Dynamics CRM-adapter onder deze host. Controleer of deze gebruiker deel uitmaakt van de BizTalk-toepassingsgebruikers.

7. Klik op OK.

Afbeelding 4

De nieuwe verzendingshandler voor de adapter maken1. Klik op Start, wijs Microsoft BizTalk Server 2006 aan, open BizTalk-

beheer, en vouw Platform-instellingen uit.2. Vouw het knooppunt Adapters uit en selecteer vervolgens Microsoft

Dynamics CRM.3. Klik met de rechtermuisknop op Microsoft Dynamics CRM 4.0, wijs Nieuw

aan en klik vervolgens op Verzendingshandler. Het dialoogvenster voor eigenschappen van de adapterhandler van Microsoft Dynamics CRM wordt geopend zoals aangegeven in afbeelding 5.

4. Selecteer in de lijst Hostnaam de host die u in de vorige procedure hebt gemaakt en klik op OK.

5. Als u het hostexemplaar wilt starten (of opnieuw starten), klikt u met de rechtermuisknop op het hostexemplaar en vervolgens op Start (of Opnieuw opstarten).

Afbeelding 5

De verzendingspoort maken met de nieuwe verzendingshandler1. Klik op Start en wijs Microsoft BizTalk Server 2006 aan, open

BizTalk-beheer en vouw Toepassingen uit, en vouw vervolgens BizTalk-toepassing 1 uit.

2. Klik met de rechtermuisknop op Verzendingspoorten, wijs naar Nieuw en selecteer Statische eenrichtingspoort of Statische poort voor gewenste antwoorden. Het dialoogvenster voor eigenschappen van de verzendingspoort wordt geopend zoals aangegeven in afbeelding 6a.

3. Typ in het vak Naam de naam van de verzendingspoort.4. Selecteer in de lijst Type de optie Microsoft Dynamics CRM 4.0. Klik

op Configurerenom de URL van Microsoft Dynamics CRM weer te geven, selecteer AD-verificatie en kies een van de ingevulde organisaties.

5. Selecteer in de lijst Verzendingshandler de host die in de vorige procedure is gemaakt.

6. Selecteer in de lijst Pipeline verzenden XML verzenden of selecteer XML ontvangen als u een tweerichtingspoort voor gewenste antwoorden gebruikt. Klik vervolgens op OK.

Afbeelding 6a

IFD: Een verzendingspoort makenDe adapter heeft de externe domeinreferenties nodig om te communiceren met IFD-installaties van Microsoft Dynamics CRM 4.0. Alle stappen gelden voor de bovenstaande installaties op locatie van Microsoft Dynamics CRM 4.0, behalve bij het configureren van een verzendingspoort, klikt u eerst op de knop Configureren tijdens het aanmaken van de verzendingspoort, vervolgens selecteert u de Formulierafhankelijke verificatie en voert u de IFD-referenties in. Zie afbeelding 6b hieronder.

Afbeelding 6b

Het schema ophalenVolg deze stappen om de schema’s voor entiteiten of acties van Microsoft Dynamics CRM op te halen.

Opmerking: De onderstaande stappen zijn voor Microsoft Visual Studio 2005. U kunt dezelfde stappen gebruiken voor Visual Studio 2008 door de overeenkomstige toepassingskoppelingen te gebruiken in de map Microsoft Visual Studio 2008 in het menu Start.

1. Klik op Start, wijs Programma's aan, wijs Microsoft Visual Studio .NET aan en klik vervolgens op Microsoft Visual Studio .NET.

2. Wijs in Visual Studio .NET in het menu Bestand de optie Nieuw aan en klik op Project. Het dialoogvenster voor nieuwe projecten wordt geopend zoals aangegeven in afbeelding 7.

3. Klik in het venster Solution Explorer met de rechtermuisknop op BizTalk Server-project, wijs Toevoegen aan en klik vervolgens op Gegenereerde items toevoegen.Het dialoogvenster Gegenereerde items toevoegen wordt geopend, zoals weergegeven in afbeelding 8.

4. Selecteer Adaptermetagegevens toevoegen in Categorieën, klik vervolgens op Toevoegen.De wizard voor het toevoegen van de adapter wordt geopend, zoals weergegeven in afbeelding 9.

5. Selecteer in de lijst met geregistreerde adapters de optie Microsoft Dynamics CRM 4.0.

6. Selecteer in de lijst Poort de poort die in de vorige procedure is gemaakt en klik op Volgende. Het dialoogvenster Gebruikersreferenties van Microsoft Dynamics CRM verschijnt zoals weergegeven in afbeelding 10a (op locatie) en 110b (IFD).

7. Selecteer AD in de vervolgkeuzelijst Type verificatie voor op locatie en formulierafhankelijke verificatie voor IFD. Typ de gebruikersnaam en het wachtwoord in de invoervakken voor Gebruikersnaam en Wachtwoord van de Microsoft Dynamics CRM-gebruiker. Klik op CRM-organisaties ophalen, selecteer de organisatie en klik op OK. Het dialoogvenster voor de entiteiten en acties van Microsoft Dynamics CRM wordt geopend zoals aangegeven in afbeelding 11.

8. Vouw de structuur van de lijst met entiteiten en acties uit door op het plusteken te klikken. In afbeelding 12 ziet u de uitgevouwen lijst.

9. Schakel de selectievakjes in voor alle entiteiten of acties waarvoor schema’s moeten worden opgehaald en klik op Volgende. De opgehaalde schema’s worden weergegeven in de weergave van de oplossingsverkenner van Visual Studio zoals aangegeven in afbeelding 13.

Afbeelding 7

Afbeelding 8

Afbeelding 9

Afbeelding 10 a

Afbeelding 10b

Afbeelding 11

Afbeelding 12

Afbeelding 13

Run-timegedragDe Microsoft BizTalk Server Adapter voor Microsoft Dynamics CRM 4.0 verwerkt de XML die wordt verzonden van BizTalk Server en voert de acties Create, Update en Delete van de entiteiten uit en alle andere mogelijke acties die worden ondersteund in Microsoft Dynamics CRM 4.0 op basis van de waarden die aanwezig zijn in de binnenkomende XML.

In het hoofdknooppunt van entiteiten- en actieschema’s bevindt zich een kenmerk genaamd ‘crm_action’.Het volgende is het gedrag van Microsoft BizTalk Adapter voor Microsoft Dynamics CRM 4.0 wanneer de binnenkomende XML (de getransformeerde /gedefinieerde XML) wordt ontvangen, als:

het kenmerk crm_action leeg is: (1) Als het primaire sleutelknooppunt van de entiteit (bijvoorbeeld accountid

voor Account) niet aanwezig is in de XML of als het knooppunt een lege waarde heeft, gaat de adapter ervan uit dat dit een actie create is.

(2) Als het primaire sleutelknooppunt van de entiteit een correcte GUID-waarde heeft, gaat de adapter ervan uit dat het een actie update is.

het kenmerk crm_action een waarde bevat: (1) Als de actie create, update of delete is, worden respectievelijk de acties

create, update en delete uitgevoerd. (2) Als de actie execute is, voert deze adapter de gevraagde actie uit met

behulp van de Microsoft Dynamics CRM SDK. Voorbeelden van acties zijn ConvertQuoteToSalesOrderRequest, ConvertProductToKitRequest en SetStateAccountRequest. Zie de voor een volledig overzicht van alle mogelijke acties. Microsoft Dynamics CRM 4.0 SDK.

Een speciaal geval: Als u de actie create wilt uitvoeren waarbij vooraf u de GUID voor de entiteit wilt opgeven. U wilt bijvoorbeeld een account maken waarbij de account-id {684FD04E-E515-491f-AF25-F9258A3C9F03} is.

Oplossing:(1) De input-XML naar de adapter (die het resultaat kan zijn van een

schematransformatie) moet de volgende knooppunten met de opgegeven waarden bevatten.

(a) <accountid> {684FD04E-E515-491f-AF25-F9258A3C9F03} </accountid>

(b) crm_action=”create” [crm_action is een kenmerk.]

Een beveiligde logboekpadmap maken U kunt een foutopsporingsfunctie gebruiken om te controleren of het schema dat bij het arrangement hoort, de juiste XML voor de Microsoft Dynamics CRM SDK genereert. Deze functie wisselt af met behulp van een registerinstelling. Als Debug = true in het register, controleert de adapter de waarden in de XML (wat komt door een transformatie/schema in het arrangement) tegen alle kenmerken van een entiteit en de hiervoor toegestane waarden.

Waarschuwing: Als het register incorrect wordt gewijzigd, kan dit ernstige problemen veroorzaken waardoor u het besturingssysteem opnieuw moet installeren. Microsoft kan niet garanderen dat problemen die worden veroorzaakt door onjuist gebruik van het register, kunnen worden opgelost. Het gebruik van het register is voor eigen risico.

Als de XML onjuiste waarden bevat, wordt er een fout vastgelegd in een logboekbestand dat wordt gemaakt in een map die wordt opgegeven door de registersleutel LogPath in hetzelfde registerpad waar Debug staat.

Belangrijk: Het registerpad is “HKEY_CLASSES_ROOT\CLSID\{D38D5DCC-2B30-43b9-9C69-3BBFD0926986}”. Deze map moet worden beveiligd met de juiste bevoegdheden en referenties, zodat alleen gebruikers met de juiste referenties en bevoegdheden logboekbestanden in deze map kan maken en openen.

Bekende problemen1. Door verwijdering van entiteiten wordt de GUID niet geretourneerd in de

antwoord-XML die wordt geretourneerd door Microsoft Dynamics CRM.

2. U kunt een lijst met entiteiten en acties ophalen met <verkeerd domein>\ <juiste aanmelding> <juiste wachtwoord> als de computer een domeincontroller is.

3. De compilatie van het BizTalk-project mislukt als de volgende stappen niet worden uitgevoerd na het ophalen van het schema. De gebruiker moet de juiste verwijzing in het arrangement instellen voor het schema dat is opgehaald. Volg de onderstaande stappen om compilatiefouten te vermijden.

a. Open het arrangement.b. Ga naar de weergave voor het arrangement, vouw de typen uit, vouw de

berichttypen met meerdere delen uit, vouw het knooppunt <naam van het opgehaalde schema + verzoek> uit en klik op Parameters.

c. Klik in het venster Eigenschappen op de vervolgkeuzelijst naast het veld 'Type' en selecteer het opgehaalde schema.

d. Sla het arrangement op en compileer het.