Prepopulating Outlook Contacts with the Graph API…Another Way

I had a project at work where I needed to streamline uploading contacts from a public folder to a user’s personal contacts. I was able to find this article to get me started. It really helped figuring out how to take a CSV file and use the MS Graph API to import the data into a user profile.

I was coming from an environment where we used to have an On Prem / Hosted Exchange so the information I needed was already there, but it was in a format that was incompatible to the new M365 environment. There were some differences to account for.

The Differences in My Situation

My requirements were a bit different:

  1. While the article shows you how to upload the CSV into the root of contacts, I needed to upload the data into a specific folder in contacts. The way we use contacts is the root is used for personal contacts and a folder below is used for staff contacts. It easily syncs to our Android phones. Sometimes we need to do a mass delete of staff contacts and this will not interfere with personal contacts.
  2. The Sample contact list in the article is a very small sample. I needed to figure out all the contact fields MS Graph / M365 uses.
  3. There was another contact list I needed to automate as well but it used a lot of fields that are only available in Office and not Microsoft 365. Office contact fields and M365 Contact fields don’t really link up. If you are NOT creating a contact list CSV from scratch (which most of you probably are doing), you must look at the field mappings that I will provide later in the article.
  4. I also needed to upload staff photos. Unfortunately using “For Each” does not work (I will show you later) and went with the old standard “while” loop!

So now that I have told you what difference I was up against. I will show you how I made things work.

Create a Registered App in Azure AD

Before you can use MS Graph to automate a lot of the functionality in Outlook you need to create an app in Azure AD. I like to think of it as login credentials that your MS Graph / PowerShell uses to get access to the M365 environment.

By default, only Global Administrator, Cloud Application Administrator and Application Administrator roles have access.  You will need to give permission for the app to do the following:

  • Contacts.ReadWrite application permission.
  • Also, make sure to grant admin consent for the permission to allow the script to access the contacts for all users.
  • You will need the following information for your script, the Application (client) ID and Directory (tenant) ID from the Overview page:
Content Provisioning
Content Provisioning
  • Lastly, open the Certificates & Secrets page and create a new client secret. Note the value of the secret. This combination of the App Identifier, Tenant identifier, and App secret will allow our script to authenticate and use the assigned permission to interact with user mailboxes.

Creating the CSV File

This where I had mentioned Earlier if you were taking an older Office Contact CSV and need to get it to work with M365 you will have problems. I will give you a list of the older Office fields and what they map to in M365. If they don’t, I will note it as such. You will have to use another field in M365 (if you can) to map to (This list is not exhaustive):

Office Contact FieldM365 Equivalent
File Asnot manditory but is involved with title of contact in business card view (fileAS)
Display Namemust create or MS Graph will not create contact record(displayName)
Assistant’s NameassistantName
Business Country/RegioncountryOrRegion
Business FaxNo Equivalent
Web Page AddressbusinessHomePage
Business Citycity
Business Faxfax
Business PhonebusinessPhone
Business Phone 2businessPhone2
Business Statestate
Business Streetstreet
CompanycompanyName
Departmentdepartment
E-mail Addressemailaddress
E-mail Display Nameemailname
E-mail 2 Addressemailaddress2
E-mail 2 Display Nameemailname2
E-mail 3 Addressemailaddress3
E-mail 3 Display Nameemailname3
First NamegivenName
Home PhonehomePhone
Home Phone 2homePhone2
Initialsinitials
Job TitlejobTitle
Last NamesurName
Manager’s Namemanager
Middle NamemiddleName
Mobile PhonemobilePhone
NotespersonalNotes
Other FaxNo Equivalent
Other PhoneNo Equivalent
Radio PhoneNo Equivalent
TitleNo Equivalent that I know of
Zip / Postal codepostalCode
Contact Field Mappings

When you export your old contact file into a CSV, now you know what you will have to change the field names so the data will import properly using MS Graph. As mentioned above DisplayName must be populated, or the import won’t work.

One more VERY IMOPRTANT ITEM:

If using email addresses, the record can only have one or three email addresses in it. When you try to use only two or one in any other spot than the first field, the creation of the record will fail. Please ask Microsoft about this (LOL)?

Now that you have the format in which to create your CSV, let’s go on to the next step.

Creating the Scripts

To upload to the user’s contacts (in this case a contact folder), you need to create 3 scripts. One calls the other when it is done:

  1. A script that declares the App Registration parameters and passes them to the subsequent scripts.
  2. Another script that imports the contact info from a CSV file you specify.
  3. Lastly, a Script that uploads contact photos from a folder you specify.

Declare App Registration Parameters

All this script is doing is taking the parameters you set in your Azure AD App registration (Client Secret, Client ID, and Tenant ID) and loading them into variables. It also loads the mailbox you wish to upload the contacts to and the path to the CSV file for good measure. Lastly, it calls the import contact PowerShell script.

Import the Contact Info From CSV

This is where the fun begins! This script has several functions which it calls in order

  1. It imports the CSV file.
  2. Checks to see if the contact folder already exists.
  3. If it does it deletes it and recreates for import. If not, it creates for import.
  4. For each contact record in the CSV file, it creates a contact record in the users Outlook Contacts
  5. To end this script, it calls the upload photo script.

Upload Photos from a Folder

This script uses the same CSV file, and it matches each First and Last name with the naming convention of contact photos you have stored somewhere (Firstname Lastname.jpg) and uploads them to the user’s corresponding contact record.

The key takeaway here is to make sure all contact photos are named exactly as the first and last name of the person they belong to.

Another feature of the script is scrubs names with apostrophes. If single quotes are misinterpreted in PowerShell, things break. Make sure the corresponding photo is also named without the apostrophe.

I mentioned earlier in the article that “for each” method does not work when going through each record and uploading a photo. That is OK though. A while loop does the trick. After you get a count of the records in the CSV, it is a matter of going though each record an uploading the photo.

Advice on Troubleshooting

As with all scripting, you need to test, test and test some more before it ends up in production. Start with one record and get it to work. If the record doesn’t work, you may need to go field by field to narrow it down.

As an example, the personal notes field is a text field but cannot start with a “+” sign. It breaks the import somehow (I found this out the hard way).

Another piece of advice is to make sure you DO NOT name your field headings the same as the contact fields you are importing. For example, the contact field name for a person’s email display name is “emailname”. In your CSV, do not call it that. Call it something different like “emaildisplay”.

As well, if you are unsure on syntax and field format, you can always connect with Graph Explorer. You can easily connect to you own Outlook and run commands manually to see how they are supposed to look like or to test your syntax before you put it in the script.

I found it quite helpful.

Download the Example Files

But before yo do consider tipping me. It was some work to generate this script and it would help a long wat to keeping the site going….

I have the files located here:  (Download Sample Script). You can download them and customize for your environment.

Final Thoughts

There are probably a lot of organizations that have been using Outlook for several years. More than likely, you are coming from either an On Prem or Hosted Exchange environment. Trying to get your contact information into M365 takes a little bit of work, but it can be done. It is automation at its finest!

I hope this information will help you on your journey.

If you find this post useful please consider buying me a coffee. It will keep me caffeinated so I can provide more Quick IT Tips!

Avatar photo

I am an IT professional with over twenty years experience in the field. I have supported thousands of users over the years. The organizations I have worked for range in size from one person to hundreds of people. I have performed support from Help Desk, Network / Cloud Administration, Network Support, Application Support, Implementation and Security.

Pin It on Pinterest