Monday, July 13, 2015

EWS Contacts rollup Powershell module

In this post I'm going to try to rollup a number of different Contact Scripts I've posted over the past couple of years into one module that will hopefully make things a little easier to use when you want to do things with Contacts using EWS and Powershell

I've put the code for this script up in GitHub repo https://github.com/gscales/Powershell-Scripts/blob/master/EWSContacts/EWSContactFunctions.ps1 it's 1K+ lines and I hope to add a few more things to the script as I go (and fix bugs). But if anybody has idea's please use GitHub to submit them. You can download the script as a zip from here

So here's what it can do at the moment

Get-Contact 

This can be used to get a Contact from the Mailbox's default contacts folder, other contacts sub folder or the Global Address List eg to get a contact from the default contact folder by searching using the Email Address (This will return a EWS Managed API Contact object).

Example 1

Get-Contact -MailboxName mailbox@domain.com -EmailAddress contact@email.com

This will search the default contacts folder using the ResolveName operation in EWS, it also caters for contacts that where added from the Global Address List in Outlook. When you add a contact from the GAL the email address that is stored in the Mailbox's contacts Folder uses the EX Address format. So in this case when you go to resolve or search on the SMTP address it won't find the contact that has been added from the GAL with this address. To cater for this the GAL is also searched for the EmailAddress you enter in (using ResolveName), if a GAL entry is returned (that has a matching EmailAddress) then the EX Address is obtained using Autodiscover and the UserDN property and then another Resolve is done against the Contacts Folder using the EX address.

Because ResolveName allows you to resolve against more then just the Email address I've added a -Partial Switch so you can also do partial match searches. Eg to return all the contacts that contain a particular word (note this could be across all the properties that are searched) you can use

Get-Contact -MailboxName mailbox@domain.com -EmailAddress glen -Partial

By default only the Primary Email of a contact is checked when you using ResolveName if you want it to search the multivalued Proxyaddressses property you need to use something like the following

Get-Contact -MailboxName  mailbox@domain.com -EmailAddress smtp:info@domain.com -Partial

Or to search via the SIP address you can use

Get-Contact -MailboxName  mailbox@domain.com -EmailAddress sip:info@domain.com -Partial

(using the Partial switch is required in this case because the EmailAddress your search on won't match the PrimaryAddress of the contact so in this case also you can get partial matches back).

There is also a -SearchGal switch for this cmdlet which means only the GAL is searched eg

Get-Contact -MailboxName mailbox@domain.com -EmailAddress gscales@domain.com -SearchGal

In this case the contact object returned will be read only (although you can save it into a contacts folder which I've used in another cmdlet).

Finally if your contacts aren't located in the default contacts folder you can use the folder parameter to enter in the path to folder that you want to search eg

Get-Contact -MailboxName mailbox@domain.com -EmailAddress gscales@domain.com -Folder "\Contacts\SubFolder"

Create-Contact

This can be used to create a contact, I've added parameters for all the most common properties you would set in a contact, some contact property need to be set via Extended properties (if you need to set this you can either add it in yourself or after you create the contact use Get-Contact and update the contact object).

Example 1 to create a contact in the default contacts folder

Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe"

to create a contact and add a contact picture

Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe" -photo 'c:\photo\Jdoe.jpg'

to create a contact in a user created subfolder

 Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe" -Folder "\MyCustomContacts"

This cmdlet uses the EmailAddress as unique key so it wont let you create a contact with that email address if one already exists.

Update-Contact

This Cmdlet can be used to update an existing contact the Primary email address is used as a unique key so this is the one property you can't update. It will take the Partial switch like the other cmdlet but will always prompt before updating in this case.

Example1 update the phone number of an existing contact

Update-Contact  -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -MobilePhone 023213421

Example 2 update the phone number of a contact in a users subfolder

Update-Contact  -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -MobilePhone 023213421 -Folder "\MyCustomContacts"

Delete-Contact

This Cmdlet can be used to delete a contact from a contact folders

eg to delete a contact from the default contacts folder

Delete-Contact -MailboxName mailbox@domain.com -EmailAddress email@domain.com

to delete a contact from a non user subfolder

Delete-Contact -MailboxName mailbox@domain.com -EmailAddress email@domain.com -Folder \Contacts\Subfolder

Export-Contact

This cmdlet can be used to export a contact to a VCF file, this takes advantage of EWS ability to provide the contact as a VCF stream via the MimeContent property.

To export a Contact to a vcf use

Export-Contact -MailboxName mailbox@domain.com -EmailAddress address@domain.com -FileName c:\export\filename.vcf

If the file already exists it will handle creating a unique filename

To export from a contacts subfolder use

Export-Contact -MailboxName mailbox@domain.com -EmailAddress address@domain.com -FileName c:\export\filename.vcf -folder \contacts\subfolder

Export-GALContact

This cmdlet exports a Global Address List entry to a VCF file, unlike the Export-Contact cmdlet which can take advantage of the MimeStream provided by the Exchange Store with GAL Contact you don't have this available. The script creates aVCF file manually using the properties returned from ResolveName. By default the GAL photo is included with the file but I have included a -IncludePhoto switch which will use the GetUserPhoto operation which is only available on 2013 and greater.

Example 1 to save a GAL Entry to a vcf

Export-GalContact -MailboxName user@domain.com -EmailAddress email@domain.com -FileName c:\export\export.vcf

Example 2 to save a GAL Entry to vcf including the users photo

Export-GalContact -MailboxName user@domain.com -EmailAddress email@domain.com -FileName c:\export\export.vcf -IncludePhoto

Copy-Contacts.GalToMailbox

This Cmdlet copies a contact from the Global Address list to a local contacts folder. The EmailAddress in used as a unique key so the same contact won't be copied into a local contacts folder if it already exists. By default the GAL photo isn't included but I have included a -IncludePhoto switch which will use the GetUserPhoto operation which is only available on 2013 and greater.

Example 1 to Copy a Gal contacts to local Contacts folder

Copy-Contacts.GalToMailbox -MailboxName mailbox@domain.com -EmailAddress email@domain.com

Example 2 Copy a GAL contact to a Contacts subfolder

Copy-Contacts.GalToMailbox -MailboxName mailbox@domain.com -EmailAddress email@domain.com  -Folder \Contacts\UnderContacts

4 comments:

Anonymous said...

Hello Glen,

Exactly what I needed.

Thnx for yet again a great script!!

Remco

Zachary Loeber said...

Clever coding as always Glen, thanks for being such a comprehensive EWS dev source on the internet. I've begun putting together a semi-formal module for Powershell and EWS. Your input would be highly regarded (as I'd eventually like to roll in some more of your work as time permits). If you get a few moments to look over what is in place thus far and let me know your thoughts I'd be very appreciative. https://github.com/zloeber/EWSModule

Laeeq Qazi said...

Hi Glen,
Do you think it is possible to export Global Address List using EWS, where it contains more than 5000 objects (Users, Contacts, and Groups)? I know about the limit of ResolveName() method, which returns max 100 entries.
I have a non-admin user, so using Remote PowerShell (and Get-recipient) is currently not an option.
Thanks

Anonymous said...

Hello,

is it possible to delete all contacts from a special folder?

Thank you!

best regards,
Florian