Underbilag 2A-5 - Retningslinjer BizTalk · Web view5.2.Versionering med Namespace12 5.3.Fælles Skemaer13 5.3.1.XML Skema Typer13 5.3.2.Versionering af skemaer14 6.Fejlhåndtering

Region Sjælland - Arkitektur Guideline Retningslinjer for implementering af integrationsløsningerVer. 1.1

R e t n i n g s l i n j e r f o r i m p l e m e n t e r i n g a f i n t e g r a t i o n s l ø s n i n g e r

Indholdsfortegnelse

1. Indledning.....................................................................................................31.1. Dokumentets målgruppe.................................................................................31.2. BizTalk miljøet................................................................................................31.3. Referencer.......................................................................................................41.4. Vedligeholdelse...............................................................................................51.5. Dokumentansvarlig.........................................................................................5

2. Generelt om BizTalk Server........................................................................6

3. Kanonisk datamodel.....................................................................................73.1. Vedligeholdelse af datamodel.........................................................................7

4. Webservices...................................................................................................94.1. Kald af webservices........................................................................................94.2. Udstilling af webservices................................................................................9

4.2.1. Navne standard for webservices...................................................................................94.2.2. Granularitet af services.................................................................................................94.2.3. Webservice dokumentation........................................................................................104.2.4. Service katalog...........................................................................................................104.2.5. Service infrastruktur...................................................................................................10

5. XML Skemaer.............................................................................................125.1. Namespaces...................................................................................................125.2. Versionering med Namespace.......................................................................125.3. Fælles Skemaer.............................................................................................13

5.3.1. XML Skema Typer.....................................................................................................135.3.2. Versionering af skemaer.............................................................................................14

6. Fejlhåndtering i BizTalk orchestrations..................................................156.1. Orchestration Udstilles som WS/WCF Service............................................156.2. Orchestration Kalder WS/WCF Service.......................................................17

7. Anvendte kommunikationsformer............................................................197.1. Asynkron vs. synkron kommunikation.........................................................197.2. Request-response...........................................................................................197.3. Publish-subscribe..........................................................................................207.4. Retningslinjer for korrekt kommunikationsform..........................................20

8. Versionering................................................................................................21

R e g i o n S j æ l l a n d - A r k i t e k t u r g u i d e 2


8.1. Versionering sammen med Visual SVN.......................................................218.2. Versionering af webservices.........................................................................218.3. Retningslinjer for support af services............................................................22

9. Eksempel Applikation – Patient................................................................239.1. Visual Studio Project: Schemas....................................................................24

9.1.1. Default Namespace for et BizTalk projekt.................................................................249.1.2. Versionering af Skemaer (XSD)................................................................................259.1.1. Typer..........................................................................................................................269.1.2. Schema Imports..........................................................................................................279.1.3. Visual Studio Project Version....................................................................................27

9.2. Brug af Schemas fra andre Visual Studio projekter......................................289.2.1. References..................................................................................................................28

9.3. Lokale skemaer.............................................................................................289.3.1. Imports........................................................................................................................28

10. Deployment af projekter............................................................................2910.1. Proces for release af BizTalk projekter.........................................................29

11. Roller og rettigheder..................................................................................30

12. System dokumentation...............................................................................32

13. Summering af retningslinjer.....................................................................33



1. IndledningRegion Sjælland (RS) bruger Microsoft BizTalk Server 2009 som den centrale komponent ved implementering af data integrationer mellem regionens systemer.

Nærværende dokument beskriver retningslinjer for brug af BizTalk i forbindelse med udvikling og udrulning af integrationsprojekter. Dokumentet beskriver godkendte retningslinjer som skal følges af personer der arbejder med BizTalk projekter. De fastlagte retningslinjer er gældende for alle integrationsteknikker fx brug af web services, udveksling af filer, database tilgang eller andet.

1.1. Dokumentets målgruppeDokumentet henvender sig til projektledere, løsningsdesignere, it-arkitekter og udviklere som deltager i regionens integrationsprojekter. Derudover kan personer med interesse i teknisk implementering af systemintegration finde materialet relevant.

1.2. BizTalk miljøetRegion Sjælland’s BizTalk miljø omfatter:

• Microsoft Windows 2003 Server • Microsoft BizTalk 2009 • Microsoft SQL Server 2005• Microsoft Active Directory• Microsoft SharePoint 2007• VMware x86 (virtualiseringsmiljø)



1.3. ReferencerTabel 1 viser en række referencer som er relevant i forbindelse med implementering af BizTalk projekter.

Nr. Beskrivelse. Evt. Link

Ref. 1 Developing Integration Solutions using BizTalk (BizTalk Server 2006 R2, men også relevant for BizTalk Server 2009)

www.microsoft.com/downloads/de-tails.aspx?FamilyID=ed7bd0ee-1385-4041-8f2a-354594ee88f3&displaylang=en

Ref. 2 Microsoft BizTalk Server 2009 Operations Guide

www.microsoft.com/downloads/de-tails.aspx?displaylang=en&Fam-ilyID=46a77327-affb-4ca2-9451-67912babbb03

Ref. 3 BizTalk Server 2009 Performance Optimiz-ation Guide

www.microsoft.com/downloads/de-tails.aspx?displaylang=en&Fam-ilyID=24660797-0c8f-4687-9d5f-b76d99b37ec2

Ref. 4 Den Gode WebService www.sundcom.health-telematics.dk/svn/DGWS/Den%20Gode%20Webservice%201.1.pdf

Ref. 5 BizTalk Documenter www.codeplex.com/BizTalkDocu-menter

Ref. 6 Test værktøj for Basic Profile 1.1 compli-ance

www.ws-i.org/deliverables/work-inggroup.aspx?wg=testingtools

Ref. 7 Service katalog Kontakt Strategisk Stab, IT arkitektur

Ref. 8 Beskrivelse af Visual SVN Kontakt Koncern IT, Udviklingsafdelingen

Ref. 9 Retningsliner for support og udfasning af services

Kontakt Koncern IT, Udviklingsafdelingen

Ref. 10 Dokumentation på integrationsløsninger Kontakt Koncern IT, Udviklingsafdelingen

Tabel 1: Referenceliste


http://rediger.regionsjaelland.dk/services/Patient/V1_0/HentData

http://rediger.regionsjaelland.dk/services/Patient/V1_0/HentData

http://www.sundcom.health-telematics.dk/svn/DGWS/Den%20Gode%20Webservice%201.1.pdf



http://rediger.regionsjaelland.dk/services/Patient/V2_1/HentData?displaylang=en&FamilyID=24660797-0c8f-4687-9d5f-b76d99b37ec2



http://rediger.regionsjaelland.dk/services/Patient/V2_0/HentData?displaylang=en&FamilyID=46a77327-affb-4ca2-9451-67912babbb03



http://www.microsoft.com/downloads/details.aspx?FamilyID=ed7bd0ee-1385-4041-8f2a-354594ee88f3&displaylang=en




1.4. VedligeholdelseNærværende guideline skal opfattes som et levende dokument, hvilket betyder, at den løbende udvides og uddybes for at fastholde dens værdi. Det er derfor vigtigt at kommentarer omkring uhensigtsmæssigheder samt forslag til forbedringer rettes til Strategisk Stab, IT arkitektur.

Dato Forfatter Dokument version

Ændringer

21/3-2010 Claus Hansen / Jens Bay Clausen

Ver. 0.2 Første udgave af dokument


Ver. 0.3 Mere tekst tilføjet dokument


Ver. 0.4 Mere tekst tilføjet dokument


Ver. 0.5 Tekst tilføjet i afsnit 5,6, 8 og 9


Ver. 1.0 Første officielle version af dokument

Tabel 2: Versionering af dokument

1.5. DokumentansvarligKoncern IT, Udviklingsafdelingen i Region Sjælland er ansvarlig for dokumentet og koordinerer og godkender ændringer.



2. Generelt om BizTalk ServerRegion Sjælland bruger BizTalk som den centrale komponent der sikrer udveksling af data mellem regionens it-systemer. Integrationskomponenten (integrationsbrokeren) skal opfattes som en ’switchbox’ der transporterer data mellem systemerne dvs. skaber system-til-system kommunikation.

Regionens systemer har oftest forskellige dataformater (skemaer til beskrivelse af data objekter) hvorfor transformation og mapning af data er nødvendigt. Transformation af data og mapning implementeres med BizTalk.

BizTalk sikrer korrekt og sikkert forløb af de enkelte "proces orchestrations". Orchestrations indeholder "programlogik" til kommunikation mellem systemer f.eks. mapning og transformation af data. Orchestrations er tilstandsløse og indeholder ikke forretningslogik. Forretningslogik skal implementeres i de enkelte fagsystemer.

BizTalk persisterer ikke forretningsdata (udover den indbyggede messagebox funktion) da kommunikationen mellem systemers er ’kortvarige’ system-til-system kommunikation og uden behov for involvering af personer fx medarbejdere eller borgere. Ved udvikling af integrationsprojekter er det en grundregel at regionens fagsystemer ikke kommunikerer direkte med hinanden men altid "går" via BizTalk. Dette princip giver en "løs binding" mellem de enkelte fagsystemer.



3. Kanonisk datamodelRegion Sjælland anvender kanonisk datamodeller (common views) ved mapning af forskellige datastrukturer mellem to eller flere systemer. Princippet i den kanoniske datamodel er illustreret i Figur 1. Figuren viser at datastrukturer A og B mappes gennem den kanoniske datamodel i stedet for gennem direkte mapning. Dette giver flere fordele:

Tæt binding (logisk punkt-til-punkt kobling) mellem systemerne undgås Fremmer genbrug af datamodel imellem projekter Tilføjelse af nyt system kræver i princippet kun én mapning (fra

datamodel til system C)

Figur 1: Kanonisk datamodel

Figur 1 viser konceptuel brug af kanonisk datamodel. Figuren viser to systemer med forskellige data strukturer. Der mappes fra system A til den kanoniske datamodel (mapning A) og fra den kanoniske datamodel til system B (mapning B) i stedet for direkte mellem system A og B. Resultatet er tre BizTalk skemaer; ét for system A, ét for den kanoniske datamodel samt ét for system B.

Versionering af kanonisk datamodel er beskrevet i afsnit 8.

3.1. Vedligeholdelse af datamodelDet er erfaringsmæssigt vanskeligt at udvikle én fælles datamodel som passer til alle integrationsprojekter - datamodellen vil sandsynligvis indeholde for mange elementer. I stedet skal der udvikles en datamodel per logisk entitet fx en datamodel for patientoplysninger, en datamodel for medicinoplysninger osv.



Datamodellens elementer defineres og vedligeholdes i samarbejde mellem ejere af fagsystemerne og BizTalk udviklere. BizTalk skemaer som realiserer datamodeller versioneres i samme omfang som andre BizTalk komponenter.

Der skal implementeres en change management proces for vedligeholdelse og styring af datamodeller og entiteter. Strategisk Stab, IT Arkitektur er ansvarlig for processen.



4. WebservicesSom udgangspunkt findes der webservices som kaldes af RS og webservices som udstilles af RS. Dette afsnit fokuserer primært på services som udstilles af regionen.

4.1. Kald af webservicesImplementering af integrationsprojekter kræver ofte tilgang til webservices som er udstillet af andre instanser fx funktioner indenfor regionen, eksterne offentlige myndigheder eller private virksomheder. Disse services er ofte færdigimplementeret og hvor metode for kald af service samt datastruktur er klart defineret fx gennem en WSDL dokument. Det antages at RS har begrænset mulighed for at påvirke egenskaberne på disse services. Dette betyder at BizTalk skal implementere den nødvendige datakonvertering og programlogik så integrationsløsningen kan realiseres ifølge integrationsprojektets kravspecifikation.

4.2. Udstilling af webservicesAutoriseret adgang til Region Sjælland’s fagsystemer sker gennem kald af veldefinerede webservices. Webservices udstilles af BizTalk som kalder den eller de bagvedliggende systemer. Det må ikke udvikles direkte punkt-til-punkt forbindelser til/mellem fagsystemerne.

4.2.1. Navne standard for webservicesNavne på services og operationer skal forretningsmæssigt beskrive den tiltænkte funktionalitet således at de kan identificeres både af it-folk og forretningsfolk. Det anbefales at bruge hele ord i stedet for forkortelser i service navne og brug af ’mixed case’ notation for let læselighed. Der kan bruges danske navne på webservices og operationer men uden danske bogstaver dvs. æ=ae, ø=oe og å=aa.

Eksempel: PersonStamOplysningHent er et beskrivende navn på en service mens navnet OpdaterSystemXYZ skal undgås.

4.2.2. Granularitet af servicesEn generel udfordring i forbindelse med etablering af services er, at finde en passende granularitet for de services RS tilbyder. Services der tilbyder for bred

R e g i o n S j æ l l a n d - A r k i t e k t u r g u i d e 1 0


funktionalitet, er ikke praktiske at bruge, og medfører at man er nødt til at konstruere programlogik til at begrænse brugen til det nødvendige. Omvendt vil services med for snæver funktionalitet kun give et fragment af den ønskede funktionalitet, og medfører at man må konstruere programlogik for at sammenstille fragmenterne til meningsfulde services. Problemstillingen om service granularitet kan løses ved at bede forretningen om at definere hvad der kan betragtes som en passende granularitet for projektets services.

Det er det enkelte projekt som definerer mængden af forretningsservices der er behov for, for at projektets opgave kan løses. For at understøtte forretningsservices, kan det være nødvendigt at skulle udvikle nye services som udstilles af de relevante basissystemer. Services defineres af RS som konkrete XML datastrukturer og WSDL servicebeskrivelser i BizTalk.

4.2.3. Webservice dokumentationAlle webservices baseres som udgangspunkt på XML. En webservice specifikation består af en pakke hvis hovedbestanddele er de nødvendige XML skema filer (XSD), abstrakte WSDL filer. Derudover skal der laves et dokument (servicebeskrivelse) som beskriver servicens forventede funktionalitet.

4.2.4. Service katalogServices der udstilles af RS - fx webservices - skal registreres og dokumenteres i service kataloget. Strategisk Stab, IT arkitektur er ansvarlig for opdatering og vedligeholdelse af service kataloget. Link til service katalog findes i reference tabel 1.3.

4.2.5. Service infrastrukturFør en RS service kan deployes skal det fastlægges hvem der kan og må tilgå denne. Det tekniske setup (infrastruktur) er afhængig af om servicen skal kunne tilgås af interne systemer og/eller eksterne systemer. Strategisk Stab, IT arkitektur er ansvarlig for realisering af service infrastrukturen.

Kald af RS services indenfor regionenRS webservices som kun tilgås af RS egne systemer, deployes på samme server som afvikler applikationen.

Kald af RS services udenfor regionen



RS webservices som kan tilgås af systemer udenfor RS, deployes på samme server som afvikler applikationen men servicen skal kaldes gennem en Reverse Proxy.



5. XML Skemaer

5.1. NamespacesVed anvendelse af XML skemaer/dokumenter er det vigtigt at have en standard for namespace navne. Fordelen ved at have en beskrevet og ensartet model for namespaces vil oftest være vigtigere end selve standarden for navngivningen.

Til konstruktion af et namespace bruges:

http://<virksomhed>.<system>.<operation>_<version>

Hvilket giver et namespace som dette:

http://www.regionsjaelland.dk.Patient.HentData_v1

Når et BizTalk projekt oprettes i Visual Studio bygges et default namespace ud fra projektets navn. Alle nye BizTalk artefakter der tilføjes dette projekt vil arve projektets default namespace – hvis default namespace ikke er korrekt skal man huske at ændre for hvert artefakt. Adskillige steder indgår default namespace også i type-navnet for artefakten. Det kan være en kompliceret opgave at tilrette namespace for et artefakt efter det er brugt i løsningen. Det anbefales at tilrette projektets default namespace før der tilføjes BizTalk artefakter (se afsnit ”Eksempel Applikation – Patient”).

5.2. Versionering med NamespaceBizTalk Server finder skemaet for et XML dokument ved at kombinere følgende data fra dokumentet:

<namespace>#<root tag>

Root tag indgår i stien til alle elementer/attributes i XML skemaet/dokumentet. Hvis et skemas root tag ændres vil alle maps (transformeringer) der benytter dette skema i BizTalk være ugyldige næste gang de hentes ind i Visual Studio. En ændring af et skemas namespace påvirker ikke maps, og næste gang projektet bygges opdateres mappen automatisk til at benytte den nye version af skemaet.



Det anbefales at versionering af XML skemaer/dokumenter sker ved at ændre namespace. Formatet for version delen af namespace kan være en simpel tæller (fx ”v1”) eller noget mere sigende som datoen for idriftsættelse (fx. ”01042010”).

Versionering af XML skemaer/dokumenter må ikke forveksles med versionering af Visual Studio projekter/kode.

Versionering af XML skemaer/dokumenter beskriver versionen for XML dokumentets format og er synligt for de parter der udveksles data med, fx ved udstilling af web services.

Versionering af Visual Studio projekter beskriver versionen af den kode der behandler data. Typisk er denne version ikke synlig for andre end udviklere, test, drift mm.

5.3. Fælles SkemaerOfte indgår de samme XML skema typer eller strukturer i flere BizTalk løsninger. Ved udvikling placeres fælles typer/skemaer typisk i et Visual Studio selvstændigt projekt der kan indgå i flere forskellige Visual Studio projekter (se projektet ”Schemas” i afsnit ”Eksempel Applikation – Patient”).

Ved deployment af de fælles skemaer placeres disse typisk i dedikeret BizTalk applikation. Da XML skemaer loades fra Global Assembly Cache (GAC) behøver de BizTalk applikationer der benytter de fælles skemaer ikke at have en reference til den fælles BizTalk applikation.

5.3.1. XML Skema TyperXML skemaer bygges ved at anvende standard datatyper (boolean, int32, string) og egne typer:

Egne typer kan være simple – fx en standard type der modificeres med en ”restriction”. Se evt. eksemplet i afsnit ”Eksempel Applikation – Patient” hvor datatypen string via en logical expression begrænses til kun at være valid hvis indholdet passer i mønstret for et CPR nr.

Egne typer kan også være komplekse – fx en struktur for en adresse. En struktur opbygges ved at bruge andre simple eller komplekse typer.



5.3.2. Versionering af skemaerVersionering af skemaer er beskrevet i afsnit 8.



6. Fejlhåndtering i BizTalk orchestrationsUdvikling af orchestrations skal inkludere håndtering af fejl. Oftest er indsatsen der kræves for at håndtere en fejl i en orchestration mindre end den indsats der kræves for at sætte driftspersonale i stand til at håndtere fejlsituationer efter deployment.

6.1. Orchestration Udstilles som WS/WCF ServiceFølgende mønster anbefales til håndtering af fejl når en orchestration udstilles som en service.

Orchestration – udstiller methods oghåndterer fejlende method orchestrations.

Orc

hest

ratio

n –

impl

emen

tere

r den

en

kelte

met

hod

og h

åndt

erer

fejl.

. . .

. . .

Figur 2: Anbefalet mønster for fejlhåndtering

Mønstret med en orchestration der udstiller de enkelte methods kan benyttes til at samle flere methods under det samme service endpoint. Mønstret skal også anvendes hvis der kun er en method der skal udstilles/implementeres da det giver mulighed for at fange fejl i implementerings orchestration og evt. sende en fault message til den kaldende klient. Mønsteret er vist i følgende orchestration.



Figur 3: Eksempel på fejlhåndtering

Scope shapen i BizTalk konfigureres til at fange fejl på niveauet over den orchestration der implementerer den kaldte method. Hvis fejlen opstår i forbindelse med at response sendes til klienten er man nødt til at kontrollere om



response faktisk blev sendt – det gør vi ved at have en scope shape specifikt omkring den send shape der sender response. I exception handling delen kontrollerer man på ”Try Send” ved i decision shapen at teste med:

succeeded(<transaction name>)

hvor <transaction name> er navnet på scopen ”Try Send”. Se eksempel på implementering af dette mønter i afsnit ”Eksempel Applikation – Patient”.

6.2. Orchestration Kalder WS/WCF ServiceVed kald fra en orchestration (fx kald af en WS/WCF service eller kald af .NET assembly) anbefales mønsteret vist i følgende orchestration.

Til at fange og håndtere fejl i en orchestration benyttes en scope shape. Scope shapen kan konfigureres med bl.a. følgende parametre:

Transaction TypeTransaction Type None – scope shapen virker konceptuelt som en Try-Catch struktur i bl.a. C# programmering. En fejl der opstår i kode inde i scope shapen vil afbryde normal orchestration flow. Hvis en (eller flere) Exception Handlers er defineret vil orchestration flow skifte til den første relevante.

Transaction Type Long Running – gør det muligt bl.a. at angive en timeout og adressere den som en transaction (fx spørge om den er gennemført uden fejl ved kommandoen succeeded).

TimeOutTimeout konfigureres som et System.TimeSpan (se eksempel i afsnit ”Eksempel Applikation – Patient”).

Exception HandlerEn scope shape kan have et antal exception handlers. Exception handlers kaldes fra top til bund (den øverste først). Hver exception handler konfigureres til at håndtere en specifik type exception, så kun den exception handler der er konfigureret til den rigtige exception bliver kaldt.

Den sidste exception handler bør være af type General så alle fejl/exceptions håndteres.



Compensation Block (ikke vist) – en scope shape konfigureret som Long Running transaction kan ikke automatisk kompenseres. Det er muligt at tilføje en Compensation Block med orchestration kode der afvikles hvis en gennemført transaction (scope shape) skal kompenseres. Kompenserings kode kan kaldes automatisk (af BizTalk) eller specificeres i orchestration kode.

Figur 4: Flow for fejlhåndtering



7. Anvendte kommunikationsformerDer findes flere - principielle forskellige – kommunikationsformer som kan anvendes ved udveksling af data mellem flere systemer. Region Sjælland understøtter 2 kommunikationsformer som kortfattet beskrives:

- Request-response- Publish-subscribe

Request-response og publish-subscribe kan implementeres gennem asynkron eller synkron kommunikation.

7.1. Asynkron vs. synkron kommunikationAsynkron kommunikation kan sammenlignes med en brevudveksling. Afsenderen sender et brev til modtageren, som læser brevet, og evt. vælger at sende et svar på brevet tilbage efter et par dage. Postbudet får dermed ikke øjeblikkeligt et svar med tilbage til afsenderen.

Ved synkron kommunikation kan der drages en analogi til en samtale. Samtalen går frem og tilbage fra den ene part til den anden, og stiller den ene part et spørgsmål, forventer vedkommende at få et svar retur med det samme.

7.2. Request-response Request-response er en kommunikationsform for udveksling af information, hvor en requester sender en besked (meddelelse) til en replier system, der modtager og behandler beskeden, for til sidst at returnere et svar. Denne kommunikationsform er især almindelig i klient / server-arkitekturer.Request-response kommunikationsform realiseres oftest ved brug af synkron kommunikation, fx gennem et webservice kald via HTTP, som har en forbindelse åben og venter indtil responsen er leveret, eller timeout-periode udløber. Request-response kommunikation kan også gennemføres asynkront. I denne situation bruges et handler ID som er reference til sessionen. Svaret på det asynkrone kald returneres på et senere (ukendt) tidspunkt ved brug af handler ID’et. Der er typisk tæt kobling mellem afsender og modtager ved request-response kommunikation.



7.3. Publish-subscribePublish-subscribe er en asynkron kommunikationsform, hvor publishers udsender meddelelser til subscribers ved brug af (besked) subjects. Subscribers modtager meddelelser ved at abonnere på et eller flere subjects. Publisheren ved ikke om der er én eller flere tusinde subscribers på de enkelte besked subjects. Da bindingen mellem publishers og subscribers ikke er fastlagt på forhånd skabes en løs kobling hvilket oftest giver bedre skalerbarhed end request-response kommunikation.Publish/subscribe kan fx bruges når en myndighed abonnerer på information som med jævne mellemrum udsendes fra en anden myndighed.

7.4. Retningslinjer for korrekt kommunikationsformHvorvidt der skal bruges request-response eller publish-subscribe baseret på asynkron eller synkron kommunikation er afhængig af det enkelte integrationsscenario. Den bedst egnede kommunikationsform er bestemt af flere parametre herunder:

- Integrationsscenarie- Systemer i spil- Krav til performance

Der gives følgende retningslinjer til kommunikationsform:- Arkitekter og udviklere af BizTalk løsninger skal om muligt skabe løs

kobling mellem de enkelte systemer.- Valg om brug af synkron eller asynkron kommunikation vurderes af

arkitekter og udviklere ud fra forretningens krav og hvad der er bedst egnet for projektet.

- Ved system-til-system kommunikation bruges asynkron publish-subscribe kommunikation.

- Integrationsløsninger med interaktion mellem personer og systemer (fx opslag eller indrapportering) er synkron kommunikation baseret på request-response oftest bedst egnet.

Koncern IT, Udviklingsafdelingen og Strategisk Stab, IT arkitekter er ansvarlig for retningslinjerne og skal godkende eventuelle afvigelser.



8. Versionering

8.1. Versionering sammen med Visual SVNVersionering af artefakter/objekter i kode samt versionering af applikationer/løsninger i Visual SVN følger de gældende retningslinjer for Region Sjælland. Link til brug af Visual SVN findes i reference tabel 1.3.

8.2. Versionering af webservices Services - udstillet af Region Sjælland – skal versioneres. Versionering af services sker via namespace.

Der findes 2 niveauer for versionering af services: major og minor versioner. Tegnet ’_’ (underbar) bruges til at adskille major og minor versioner.

Major version:En major version omfatter væsentlig ændringer i en service fx ændret datatyper skemaer eller betydelige ændringer i funktionalitet

Minor version:En minor version omfatter mindre ændringer i en eller flere operationer fx fejlrettelser.

Eksempel 1 – major version:Eksempel 1 viser service Patient. Service Patient er version 1_0 og omfatter en operation HentData.www.regionsjaelland.dk/services/Patient/V 1 _0/HentData

Skemastruktur ændres nu for service HentData og den nye version bliver herefter version 2_0. Ny URL erwww.regionsjaelland.dk/services/Patient/V 2 _0/HentData

Eksempel 2 – minor version:Eksempel 2 viser service Patient. Service Patient er version 2_0 og omfatter en operation HentData. www.regionsjaelland.dk/services/Patient/V 2 _0/HentData

Der er en fejl ved operation HentData og fejlen rettes efterfølgende. Skema struktur forbliver uændret. Ny URL er www.regionsjaelland.dk/services/Patient/V2_ 1 /HentData


http://www.codeplex.com/BizTalkDocumenter

http://www.regionsjaelland.dk/services/Patient/V2_0/HentData

http://www.microsoft.com/downloads/details.aspx

http://www.microsoft.com/downloads/details.aspx


Der kan tilføjes nye operationer til en eksisterende service uden der ændres version. Fx kan service Patient tilføjes med en ny operation HentExcelData uden ændring af version. Der versioneres ikke på de enkelte operationer.

8.3. Retningslinjer for support af servicesLink til retningslinjer og proces for support af (web)services findes i reference tabel 1.3.



9. Eksempel Applikation – PatientFølgende eksempel applikation ”Patient” benyttes som udgangspunkt for de tekniske elementer i dette dokument. Applikationen Patient udstiller en WCF service med en method Patient.HentData. Method Patient.HentData kaldes med et CPR nr. og returnerer personlige, adresse og journal data om en patient.

Følgende emner dækkes ved gennemgang af eksempel applikationen: Struktur i Visual Studio for projektet Patient, projektet Schemas og projektet

Shared – herunder brugen af XSD typer, delte skemaer, delte BizTalk artefakter samt referencer mellem projekter.

Brug af XML namespaces for projekter og skemaer – herunder brug af namespace til versionering af XML dokumenter.

Versionering af projekter i Visual Studio. Fejlhåndtering når en orchestration udstilles som WCF service (Web Service). Fejlhåndtering når en orchestration kalder en service (WCF, Web Service). Deployment af bygget kode til BizTalk test/produktions miljøer – herunder

deployment af delte skemaer og referencer til delte (shared) BizTalk artefakter.

Typer defineret i skemaet Typer.xsd kan anvendes i fælles skemaer (PatientData.xsd) og lokale skemaer/projekter.

Projekterne Shared og Patient har en reference til projektet Schemas så fælles typer og skemaer kan anvendes.

I dette tilfælde oprettes en BizTalk applikation for hvert Visual Studio projekt. Alle applikationer kan benytte fælles skemaer da disse ligger i GAC’en.

Applikationen Patient har en reference til applikationen Shared så den kan benytte delte artifakter.

Figur 5: Reference oversigt



9.1. Visual Studio Project: SchemasProjektet Schemas indeholder definition af XSD typer og skemaer der deles af flere BizTalk applikationer. En XSD type kan være en simpel type, fx. en string med restriktioner og/eller validering eller en complex type, fx. en XML dokument struktur.

Figur 6: Schemas

9.1.1. Default Namespace for et BizTalk projektUmiddelbart efter oprettelse af et BizTalk projekt i Visual Studio bør default namespace tilrettes. Alle nye BizTalk artefakter der tilføjes dette projekt vil arve projektets default namespace – hvis default namespace ikke er korrekt skal man huske at ændre for hvert artefakt. Adskillige steder indgår default namespace også i type-navnet for artefakten. Det kan være en kompliceret opgave at tilrette namespace for et artefakt efter det er brugt i løsningen.Default namespace for et BizTalk projekt sættes ved at tage properties for projektet og vælge fanebladet ”Application” som vist her:

Figur 7: Default namespace

Ved anvendelse af XML dokumenter er det vigtigt at have en standard for namespace navne. Fordelen ved at have en beskrevet og ensartet model for namespaces vil oftest være vigtigere end selve standarden for navngivningen. I det følgende er vist hvordan namespace for et skema (typer.xsd) konstrueres med brug af projektets default namespace:



Figur 8: Target namespace

9.1.2. Versionering af Skemaer (XSD)BizTalk Server finder et skema for et XML dokument ved at kombinationen af følgende data fra dokumentet:

<namespace>#<root tag>

Root tag indgår i stien til alle elementer/attributes i XML dokumentet. Hvis et skemas root tag ændres vil alle maps (transformeringer) der benytter dette skema i BizTalk være ugyldige næste gang de hentes ind i Visual Studio. En ændring af et skemas namespace påvirker ikke maps, og næste gang projektet bygges opdateres mappen automatisk til at benytte den nye version af skemaet. I det følgende er namespace for skemaet typer.xsd ændret så det nu har version ”v1”:

Figur 9: Versionering af target namespace



9.1.1. Typer

Figur 10: Typer, properties og pattern



9.1.2. Schema Imports

Figur 11: Schema imports

9.1.3. Visual Studio Project Version

Figur 12: Visual Studio versionering



9.2. Brug af Schemas fra andre Visual Studio projekter

9.2.1. References

Figur 13: Referencer ved brug af andre Visual Studio projekter

9.3. Lokale skemaer

9.3.1. Imports

Figur 14: Import af lokale skemaer



10. Deployment af projekterDer findes 3 BizTalk miljøer hos Region Sjælland: udvikling, test/release og produktion. Regionen bruger Visual SVN som versioneringsværktøj af BizTalk projekter komponenter.

10.1.Proces for release af BizTalk projekterUdviklingsmiljøetI udviklingsmiljøet fortages udvikling af nye eller eksisterende BizTalk projekter. BizTalk projekter gemmes og versioneres i Visual SVN.

Test/release miljøetTest/release miljøet har 2 funktioner:

- Det bruges som buildmiljø af MSI pakker - Det bruges til test af BizTalk projekter.

BizTalk projektet kopieres fra Visual SVN til test miljøet. Applikationen slettes på test miljøet. Herefter genereres en MSI pakke som installeres i test miljøet. MSI pakken testes og releases.

ProduktionsmiljøetI produktionsmiljøet (prod) afvikles det færdige BizTalk projekt. BizTalk projekter leveres fra testmiljøet til produktionsmiljøet i form af en MSI pakke. Installation af MSI pakken er et samarbejde mellem BizTalk udviklere og driftspersonalet.Driftspersonalet er ansvarligt for vedligeholdelse af produktionsmiljøet og tester det installerede BizTalk projekt.

Figur 15: Proces for release af BizTalk projekter



Hvis et BizTalk projekt fejler i produktion skal den samlede release proces gennemføres igen.



11. Roller og rettighederDer findes en række roller som er involveret i BizTalk projekter hos Region Sjælland:

ForretningsrolleOpdragsgiver og ansvarlig for udarbejdelse af integrationsprojektets kravspecifikation og den nødvendige SLA.

ProjektlederrolleProjektlederen er ansvarlig for gennemførelse af BizTalk integrationsprojektet og udarbejdelse af dokumentation på løsning.

UdviklerrolleUdvikler BizTalk projektet ifølge kravspecifikation.

Test - og releaserolleTest personale tester BizTalk projektet i test miljøet i forhold til testplanen. Release personale genererer MSI pakke for BizTalk projekt og releaser projekt til produktionsmiljøet.

DriftsrolleInstallerer BizTalk projektet i produktionsmiljøet. Står for den monitorering og daglige drift af BizTalk projekter i produktionsmiljøet.



Nedenstående tabel viser ansvarsfordelingen for rollerne i forhold de forskellige BizTalk miljøer.

Udviklingsmiljø Test/release miljø

Produktionsmiljø

Forretningsrolle Ingen adgang Begrænset adgang evt. ifm. test

Ingen adgang

Projektlederrolle

Ingen adgang Begrænset adgang evt. ifm. test

Ingen adgang

Udviklerrolle Local admin rettigheder

Begrænset admin rettigheder

Begrænset adgang

Testrolle Ingen adgang Admin rettigheder

Ingen adgang

Releaserolle BizTalk udviklere Admin rettigheder

Ingen adgang

Driftsrolle Ingen adgang Admin rettigheder

Admin rettigheder

Tabel 3: Ansvarsfordeling for BizTalkmiljøer



12. System dokumentationEt BizTalk projekt omfatter en vis mængde dokumentation som skal være færdigt og godkendt før BizTalk projektet installeres i produktionsmiljøet. Dokumentationen er med til at sikre at projektet driftes forsvarligt og overholder den foruddefinerede Service Level Agreement (SLA). Det er BizTalk udviklere som laver dokumentation af projektet. BizTalk udviklere gennemgår og godkender dokumentationen i samarbejde med driftspersonalet.

Dokumentation af BizTalk projekter skal minimum indeholde:- Kortfattet beskrivelse af integrationsprojektet- Dokumentation på systemer som projektet bruger og er afhængige af - Tegninger på dataflow - Beskrivelse af endpoints / bindings- Kritiske områder som er relevant for projektet- Generering af HLP filer ved brug af BizTalk Documenter

Link til dokumentation på BizTalk projekter findes i reference tabel 1.3.

Projektleder sikrer at dokumentation gennemføres jf. gældende retningslinjer.



13. Summering af retningslinjerDette afsnit opsummerer beskrevne retningslinjer for brug af BizTalk i Region Sjælland.

1) Fagsystemer skal bruge BizTalk for udveksling af data.2) BizTalk er ’forbindelsesleddet’ mellem regionens systemer og persisterer

ikke forretningsdata. 3) BizTalk services er tilstandsløse og indeholder ikke forretningslogik.4) BizTalk persisterer ikke forretningsdata.5) Der bruges kanonisk datamodeller (common views) ved mapning mellem

forskellige systemformater.6) Webservices baseres på XML.7) Webservices har danske navne men ikke danske bogstaver.8) Ekstern tilgang til RS services skal gå igennem en Reverse Proxy. 9) Services som udstilles af RS skal registreres og dokumenteres i service

kataloget.10) Hvis et BizTalk projekt fejler i produktion skal den samlede release proces

gennemføres igen.11) Dokumentation af BizTalk projekt skal være færdigt og godkendt før

projektet installeres i produktionsmiljøet.12) Koncern IT, Udviklingsafdelingen og Strategisk Stab, IT arkitekter er

ansvarlig for retningslinjerne og skal godkende eventuelle afvigelser.


Documents

Underbilag 2A-5 - Retningslinjer BizTalk · Web view5.2.Versionering med Namespace12 5.3.Fælles Skemaer13 5.3.1.XML Skema Typer13 5.3.2.Versionering af skemaer14 6.Fejlhåndtering