Handleiding aanspreken Exchange Web Services (EWS) met de TaskCentre Web Service Connector Tool (WSCT)
Inhoud Inleiding ........................................................................................................................................................3 Vooraf ...........................................................................................................................................................3 Contacten .....................................................................................................................................................5 Mappen van standaard velden .................................................................................................................5 Mappen van contact velden .....................................................................................................................6 Taken ............................................................................................................................................................8 Afspraken ...................................................................................................................................................11 Mogelijke problemen .................................................................................................................................13 Veld kan niet gekoppeld worden ............................................................................................................13 Te grote log entries .................................................................................................................................15 Unauthorized ..........................................................................................................................................15 RequestServerVersion in de SOAP header .............................................................................................15 The underlying connecLon was closed ...................................................................................................16 Unable to connect to remote server ......................................................................................................17
1
Inleiding
Dit document beschrijO het gebruik van de Item OperaLons van Exchange Web Services met de Web Service Connector Tool in TaskCentre. De Item OperaLons in Exchange 2010 hebben betrekking op email berichten, contactpersonen, taken, agenda afspraken, en staan verder beschreven op de MSDN website onder Item OperaLons. 2
Vooraf
Voor het gebruik van web services met de Web Service Connector Tool moet Exchange ingericht zijn en de web service benaderbaar zijn voor een bepaalde gebruiker. Dit kan gecontroleerd worden door MicrosoO Office Outlook te starten en door een Ctrl + Klik op tray icon en selecteer Test Email AutoConfigura@on....
In het opkomende venster kan het Email Address ingevuld worden en op Test geklikt worden, en de gegevens onder Protocol: Exchange HTTP gecontroleerd worden. Onthoud hier de Web Service URL die eindigt op /EWS/Exchange.asmx.
Daarna kan in TaskCentre onder System -‐> Tools -‐> Execute -‐> Web Service Connector Tool de WSDL Web Service Configura@on aangemaakt worden. Op het tabblad Endpoints moet de Web Service URL ingevuld worden.
Nu kan de Web Service Connector Tool stap gebruikt worden in taken. Bij het uitvoeren van de taak met deze stap kunnen een aantal problemen optreden. Deze worden verderop besproken bij 6. Dit document beschrijO specifiek de Exchange web services. Een meer gedetailleerde beschrijving van het inrichten en gebruik van de Web Service Connector Tool staat op de Orbis SoOware Benelux website (doorklikken naar Orbis TaskCente & Tools en Webservices), in het document Voorbeeld verzoek in Synergy Enterprise. 3
Contacten
De exchange web service voor het aanmaken van een contactpersoon staat beschreven op de MSDN website. Voor het aanmaken van de contactpersonen moet in een taak een recordset stap (bijvoorbeeld een Database Query (OLEDB) stap) en een Web Service Connector stap aangemaakt worden. In de voorbeelden in dit document worden alle waarden vanuit een Database Query (OLEDB) recordset gemapped. Op het tabblad Web service moet de eerder geconfigureerde web service en de Opera@on CreateItem gekozen worden.
Mappen van standaard velden
3.1
Op het tabblad Mappings bij moeten de volgende twee acributen gemapped worden: •
WebService -‐> CreateItem -‐> o
CreateItem -‐> SavedItemFolderId -‐> DisLnguisedFolderID -‐>
o
@Id
RequestServerVersion -‐>
@Version
Het acribuut @Id moet gevuld worden met de waarde “contacts”. Mogelijke waarden voor dit acribuut staan op de MSDN website. Het acribuut @Version moet gevuld worden met de versie van Exchange, in dit voorbeeld de waarde “Exchange2010”. Mogelijke waarden voor de versie van Exchange staan beschreven op de MSDN website.
Mappen van contact velden
3.2
Voor het aanmaken van de nieuwe contacten zelf moeten de volgende velden gemapped worden: •
WebService -‐> CreateItem -‐> CreateItem -‐> Items -‐> ChoiceItems -‐> Contact -‐> o
FileAs
o
GivenName
o
CompanyName
o
EmailAddresses -‐> Entry -‐>
o
EmailAddressDicLonaryEntryType
PhysicalAddress -‐> Entry -‐> PhysicalAddressDicLonaryEntryType -‐>
Street
City
o
State
CountryOrRegion
PhoneNumbers -‐> Entry -‐>
PhoneNumberDicLonaryEntryType
o
JobTitle
o
Surname
Na koppelen van deze waarden kan de taak gestart worden, en het resultaat kan gecontroleerd worden in MicrosoO Office Outlook.
4
Taken
Taken worden op een vergelijkbare manier met contacten aangemaakt, de exchange web service staat beschreven op de MSDN website. Voor het mappen van de standaard velden, zie 3.1. Omdat taken bij een persoon horen moet ook het veld EmailAddress gemapped worden. Het acribuut @Id moet gevuld worden met de waarde “tasks”. •
Webservice -‐> CreateItem -‐> o
o
CreateItem -‐> SavedItemFolderId -‐> ChoiceItems -‐> DisLnguishedFolderId
Mailbox -‐> EmailAddress
@Id
RequestServerVersion -‐>
@Version
Daarnaast worden voor het aanmaken van een taak de volgende velden gemapped. Het veld Recurrence kan niet direct gemapped worden, zie hiervoor 6.1. •
WebService -‐> CreateItem -‐> CreateItem -‐> Items -‐> ChoiceItems -‐> Task -‐> o
Subject
o
Body
o
Recurrence
o
StartDate
Na uitvoeren van de TaskCentre taak is in MicrosoO Office Outlook een taak aangemaakt voor de gebruiker.
5
Afspraken
Afspraken worden op een vergelijkbare manier met contacten en taken aangemaakt, de exchange web service staat beschreven op de MSDN website. Voor het mappen van de standaard velden, zie 3.1. Omdat afspraken bij een persoon horen moet ook het veld EmailAddress gemapped worden. Het acribuut @Id moet gevuld worden met de waarde “calendar”. •
Webservice -‐> CreateItem -‐> o
CreateItem -‐> SavedItemFolderId -‐> ChoiceItems -‐> DisLnguishedFolderId
Mailbox -‐> EmailAddress
o
CreateItem -‐> SavedItemFolderId -‐>
o
@Id
SendMeeLngInvitaLons
RequestServerVersion -‐>
@Version
De mogelijk waarden voor SendMee@ngInvita@ons staan op de MSDN website.
Daarnaast worden voor het aanmaken van een afspraak de volgende velden gemapped. •
WebService -‐> CreateItem -‐> CreateItem -‐> Items -‐> ChoiceItems -‐> CalendarItem -‐> o
Subject
o
Start
o
End
Na uitvoeren van de taak is in MicrosoO Office Outlook de afspraak aangemaakt.
6
Mogelijke problemen Veld kan niet gekoppeld worden
6.1
Probleem Bij de web service URL eindigend op /EWS/Exchange.asmx hoort een /EWS/Types.xsd specificaLe. Als een veld hierin complex type is (xs:complexType) wat niet afgeleid is van een basis type, dan kan dit in de Web Service Connector Tool niet gekoppeld worden. Oplossing Een voorbeeld is het volgende veld wat aangeeO of het een terugkerende taak betreO. •
WebService -‐> CreateItem -‐> CreateItem -‐> Items -‐> ChoiceItems -‐> Task -‐> Recurrence
Dit veld is in de specificaLe EWS/Types.xsd van het type TaskRecurrenceType. Op de MSDN website staat een voorbeeld voor het vullen van dit veld die overeen komt met de specificaLe: <WeeklyRegeneration>
1
<StartDate>2006-‐08-‐15
Om het veld Recurrence toch te vullen met deze inhoud kan de XML als tekst in de query geselecteerd worden. select '<WeeklyRegeneration>
1 <StartDate>2006-08-15 ' as Recurrence
Om deze in de web service connector mee te geven kan door en rechts-‐klik op Recurrence onder Tool Input en Op@ons te kiezen in het Element Op@ons venster Create Element containing gekozen worden en daar de het veld Recurrence uit het browser venster ingesleept worden.
Andere complexe types kunnen op een vergelijkbare manier gemapped worden, waarbij de voorbeelden in de MSDN documentaLe en desnoods de /EWS/Types.xsd doorzocht moet worden voor het aanmaken van de juiste XML.
Te grote log entries
6.2
Foutmelding “an excepLon was raised while iniLalising the operaLon:
Log entry string is too long. A string wricen to the event log cannot exceed 32766 characters.” Oplossing Dit probleem treedt op in build 650 release SR3 en zou in release SR4 opgelost zijn. Een oplossing in SR3 is om LogLevel en LogType op 0 zecen in de registry. Dit is zijn de volgende keys. •
HKEY_LOCAL_MACHINE\SOFTWARE\Orbis SoOware\TaskCentre\Logging
•
HKEY_LOCAL_MACHINE\SOFTWARE\Orbis SoOware\TaskCentre\Logging\Dtl
Unauthorized
6.3
Foutmelding “System.Net.WebExcepLon: The request failed with HTTP status 401: Unauthorized.” Oplossing De gebruiker moet rechten hebben om de webservice aan te spreken. De volgende gebruiker credenLals kunnen invloed hebben op de authorisaLe:
6.4
•
AuthenLcaLon op de gekozen webservice Webservice Connector Tool configuraLe
•
ImpersonaLon in TaskCentre
•
ImpersonaLon op de taak met de Webservice Connector stap
•
Log On informaLe TaskCentre Server service
RequestServerVersion in de SOAP header
Foutmelding “System.Web.Services.Protocols.SoapExcepLon: The request is valid but does not specify the correct server version in the RequestServerVersion SOAP header.” Oplossing
Dit probleem is op de MSDN website beschreven. Er is een foute RequestServerVersion gekoppeld, zie eerdere beschrijving van de RequestServerVersion. Dit kan getest worden in de Web Service Configura@ons bij het kiezen van de web service en Test... te kiezen, de laatste operaLe GetPasswordExpira@onDate te kiezen en RequestServerVersion te vullen met een geldige waarde, en op Test te drukken.
6.5
The underlying connection was closed
Foutmelding “System.Net.WebExcepLon: The underlying connecLon was closed: Could not establish trust relaLonship for the SSL/TLS secure channel.” Oorzaak Dit probleem kan meerdere oorzaken hebben waaronder een cerLficaat dat niet meer geldig is. Gecontroleerd moet worden of de exchange web service vanaf een andere server of op de Exchange server zelf beschikbaar is.
6.6
Unable to connect to remote server
Foutmelding “ S y s t e m . N e t .W e b E x c e p L o n : U n a b l e t o c o n n e c t t o t h e r e m o t e s e r v e r -‐ -‐ -‐ > System.Net.Sockets.SocketExcepLon: No connecLon could be made because the target machine acLvely refused it 127.0.0.1:8888” Oorzaak De exchange web service kan vanaf de machine niet benaderd worden. Dit kan meerdere oorzaken hebben waaronder een blokkering door de firewall, of een ander programma dat de poort blokkeert.
