Saturday, May 03, 2008

Creating a Contact with Exchange Web Services from Powershell

The following is a script that demonstrates how to create a contact using a SOAP string and a simple web request. While this is not a very elegant solution as long as you have your SSL certs sorted out it should work okay. I was planning something a little cooler but time is really short at moment but this is still okay though. When creating a contact there are a few properties that you should set to get a fully working contact object. So the first part of the script is divided into required props which if you are using this in a pipeline you should always make sure you set. If you don’t you may find things like your contacts don’t appear properly when you try to use the contact in the Outlook Address book. The rest of the properties are optional which you can set if you have the information. This is not a complete list of contact properties that can be set within EWS just the majority of the most common ones for a full list please refer to the Exchange SDK. The big advantage if you’re using scripting with EWS in Powershell compared to VBS. is if you combine this script with some simple Import-csv code you can basically create contacts with in a mailbox from any properly formatted CSV (no matter where it came from).

The changeable part of this script is the credential section which allows you to specify the credentials to use when connecting to EWS if you don’t want to specify the credentials you can comment out the following lines

$unUserName = "username"
$psPassword = "password"
$dnDomainName = "domain"
$cdUsrCredentials = new-object System.Net.NetworkCredential($unUserName , $psPassword , $dnDomainName)

To change the script to use the currently logged on user credentials you need to change the following lines

# $WDRequest.Credentials = $cdUsrCredentials
$WDRequest.UseDefaultCredentials = $True

The only other thing you may want to change is to make the script use impersonation if you want to create contacts in mailboxes other than the one associated with the security credentials you are using. The impersonation header should be something like

<t:ExchangeImpersonation> `
<t:ConnectingSID> `
<t:SID>" + $siSIDToSearch.SID + "</t:SID> `
</t:ConnectingSID>" `
</t:ExchangeImpersonation>" `

I’ve put a downloadable copy of the script here the script itself looks like

#Required Props
$subject = "Skippy(Skippys Email)"
$EmailDisplayAS = "Skippy Roo(Skippys Emaill)"
$EmailDisplayName = "skippy@acme.com"
$EmailAddress1 = "skippy@acme.com"
$FileAs = "Roo, Skippy"

#Optional Props

$givenName = "Skippy"
$middleName = "The"
$Surname = "Roo"
$nickName = "Skip"
$CompanyName = "Skips Helicopters"
$HomeStreet = "32 Walaby Street"
$HomeCity = "Maroobra"
$HomeState = "NSW"
$HomeCountry = "Australia"
$HomePostCode = "2000"
$BusinessStreet = "45 Emu Place"
$BusinessCity = "Woolloomooloo"
$BusinessState = "NSW"
$BusinessCountry = "Australia"
$BusinessPostCode = "2000"
$HomePhone = "9999-99999"
$HomeFax = "9999-99999"
$BusinessPhone = "9999-99999"
$BusinessFax = "9999-99999"
$MobilePhone = "999-9999-99999"
$AssistantName = "Wally"
$BusinessWebPage = "www.skipshelis.com"
$Department = "Flying"
$OfficeLocation = "1st Floor"
$Profession = "Pilot"

$soapString = "<?xml version=`"1.0`" encoding=`"utf-8`" ?> `
<soap:Envelope xmlns:soap=`"http://schemas.xmlsoap.org/soap/envelope/`"
xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`" `
xmlns:xsd=`"http://www.w3.org/2001/XMLSchema`">`
<soap:Header>`
<RequestServerVersion Version=`"Exchange2007_SP1`" xmlns=`"http://schemas.microsoft.com/exchange/services/2006/types`"
/> `
</soap:Header>`
<soap:Body> `
<CreateItem MessageDisposition=`"SaveOnly`" xmlns=`"http://schemas.microsoft.com/exchange/services/2006/messages`">`
<SavedItemFolderId> `
<DistinguishedFolderId Id=`"contacts`" xmlns=`"http://schemas.microsoft.com/exchange/services/2006/types`"
/>`
</SavedItemFolderId>`
<Items>`
<Contact xmlns=`"http://schemas.microsoft.com/exchange/services/2006/types`"> `
<Subject>" + $subject + "</Subject> `
<ExtendedProperty>`
<ExtendedFieldURI PropertySetId=`"00062004-0000-0000-C000-000000000046`"
PropertyId=`"32898`" PropertyType=`"String`" /> `
<Value>SMTP</Value> `
</ExtendedProperty>`
<ExtendedProperty>`
<ExtendedFieldURI PropertySetId=`"00062004-0000-0000-C000-000000000046`"
PropertyId=`"32896`" PropertyType=`"String`" /> `
<Value>" + $EmailDisplayAS + "</Value> `
</ExtendedProperty>`
<ExtendedProperty>`
<ExtendedFieldURI PropertySetId=`"00062004-0000-0000-C000-000000000046`"
PropertyId=`"32900`" PropertyType=`"String`" /> `
<Value>" + $EmailDisplayName + "</Value> `
</ExtendedProperty>`
<FileAs>" + $fileas + "</FileAs> `
<GivenName>" + $givenName + "</GivenName> `
<MiddleName>" + $middleName + "</MiddleName> `
<Nickname>" + $nickName + "</Nickname> `
<CompanyName>" + $CompanyName + "</CompanyName> `
<EmailAddresses>`
<Entry Key=`"EmailAddress1`">" + $EmailAddress1 + "</Entry> `
</EmailAddresses>`
<PhysicalAddresses>`
<Entry Key=`"Home`">`
<Street>" + $HomeStreet + "</Street> `
<City>" + $HomeCity + "</City> `
<State>" + $HomeState + "</State> `
<CountryOrRegion>" + $HomeCountry + "</CountryOrRegion> `
<PostalCode>" + $HomePostCode + "</PostalCode> `
</Entry>`
<Entry Key=`"Business`">
<Street>" + $BusinessStreet + "</Street> `
<City>" + $BusinessCity + "</City> `
<State>" + $BusinessState + "</State> `
<CountryOrRegion>" + $BusinessCountry + "</CountryOrRegion> `
<PostalCode>" + $BusinessPostCode + "</PostalCode> `
</Entry>`
</PhysicalAddresses>`
<PhoneNumbers>`
<Entry Key=`"HomePhone`">" + $HomePhone + "</Entry> `
<Entry Key=`"HomeFax`">" + $HomeFax + "</Entry> `
<Entry Key=`"BusinessPhone`">" + $BusinessPhone + "</Entry> `
<Entry Key=`"BusinessFax`">" + $BusinessFax + "</Entry> `
<Entry Key=`"MobilePhone`">" + $MobilePhone + "</Entry> `
</PhoneNumbers>`
<AssistantName>" + $AssistantName + "</AssistantName> `
<BusinessHomePage>" + $BusinessWebPage + "</BusinessHomePage> `
<Department>" + $Department + "</Department> `
<OfficeLocation>" + $OfficeLocation + "</OfficeLocation> `
<Profession>" + $Profession + "</Profession> `
<Surname>" + $Surname + "</Surname> `
</Contact>`
</Items>`
</CreateItem>`
</soap:Body>`
</soap:Envelope>"

$unUserName = "username"
$psPassword = "password"
$dnDomainName = "domain"
$cdUsrCredentials = new-object System.Net.NetworkCredential($unUserName ,
$psPassword , $dnDomainName)

$mbURI = "https://servername/EWS/Exchange.asmx"

$WDRequest = [System.Net.WebRequest]::Create($mbURI)
$WDRequest.ContentType = "text/xml"
$WDRequest.Headers.Add("Translate", "F")
$WDRequest.Method = "POST"
$WDRequest.Credentials = $cdUsrCredentials
# $WDRequest.UseDefaultCredentials = $True
$bytes = [System.Text.Encoding]::UTF8.GetBytes($soapString)
$WDRequest.ContentLength = $bytes.Length
$RequestStream = $WDRequest.GetRequestStream()
$RequestStream.Write($bytes, 0, $bytes.Length)
$RequestStream.Close()
$WDResponse = $WDRequest.GetResponse()
$ResponseStream = $WDResponse.GetResponseStream()
$readStream = new-object System.IO.StreamReader $ResponseStream
$textresult = $readStream.ReadToEnd()
if ($textresult.indexofany("ResponseClass=`"Success`"")){
"Contact Created Sucessfully"
}
else {
$textresult
}

4 comments:

JMinnick said...

This is awesome and I am trying to work with your examples to delete a folder by folderID but I am not having any luck...

I'm sorry for the link but I am not able to post the code in my script on this blog it appears..

http://www.microsoft.com/communities/newsgroups/en-us/default.aspx?&lang=en&cr=US&guid=&sloc=en-us&dg=microsoft.public.windows.powershell&p=1&tid=209e8e03-673c-4eac-9f6a-80e157b5ab5b

Scroll down a bit to the 7th post if you would be so kind.

Any suggestions would be greatly appreciated..

Thank you!

Sean said...

Glen, where did you come up with the Property Set ID of "00062004-0000-0000-C000-000000000046" ?

It worked wonderfully but I'm not sure where it came from.

Thanks, Sean

Steve Thresher said...

00062004-0000-0000-C000-000000000046 is the property FileAs. See here for details:

http://msdn.microsoft.com/en-us/library/aa563318.aspx

Anonymous said...

Hello, I use your script can create contact on exchange 2010 SP2 but the value emaildisplayas and EmailDisplayName not work. The fill on exchange owa just show emailaddress only. Please help.