How to set an event charm in the Microsoft Graph API

The Graph API provides an easy way to manage calendar events.

To create a new event, make a POST request:

POST /me/events

In the request body, supply a JSON representation of the event object.

{
    "subject": "My event",
    "start": {
        "dateTime": "2023-06-14T08:00:00.000Z",
        "timeZone": "UTC"
    },
    "end": {
        "dateTime": "2023-06-14T09:00:00.000Z",
        "timeZone": "UTC"
    }
}

Event resource has many properties to customize the event, but the Graph API doesn't expose all of the fields related to an event.

Event charm

One of the field that can be set by many Outlook clients but not directly in the Graph API is an event charm:

img

Fortunately, the data related to the event charm is there on the server, stored in various MAPI properties. The Graph API can access arbitrary MAPI properties via extended properties.

Find MAPI property

Now, we have to figure out which MAPI property stores information about an icon. All of the various MAPI properties used by Outlook and Exchange are documented in MS-OXPROPS, or in a more specific document like MS-OXOCAL.

After some research, the documents mentioned above do not contain any information about a property for an event charm.

In that case, we need to try another way. There is the tool MFCMapi, which can be run on a machine with Outlook installed to connect to the user's mailbox and explore all of the MAPI properties on a specific item. This makes it a lot easier to find the property we need.

MFCMapi and exporing MAPI properties

Use the Outlook client and create two events, one without the event charm and another with the event charm.

img

Download the latest release of the MFCMapi.

Open MFCMapi and logon to your mailbox:

img

Select your default store and open the calendar folder:

img

Find previously created events and compare their properties:

img

The event with the charm has one additional property with the tag 0x84CD0003:

img

Read value of extended property

MAPI data type is PT_LONG which is the equivalent to the Integer type in the Graph API. Property id is 0x0027 and the guid of the namespace is {11000E07-B51B-40D6-AF21-CAA85EDAB1D0}.

The Graph API can identify the property by its namespace (the GUID) and a numeric identifier. The id of the single-value extended property will be Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x0027.

Make a request to read events, including the extended property related to the event charm:

GET https://graph.microsoft.com/v1.0/me/events?$expand=singleValueExtendedProperties($filter=id eq 'Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x0027')&$select=id,subject

The response:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('')/events(subject,singleValueExtendedProperties())",
    "value": [
        {
            "@odata.etag": "W/\"AgHex1lHnU6P4tmSFYQ4hwAI3IzR6Q==\"",
            "id": "AAMkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMABGAAAAAABxI4iNfZK7SYRiWw9sza20BwA7DGC6yx9ARZqQFWs3P3q1AAAASBOQAAACAd7HWUedTo-i2ZIVhDiHAAjdwbvNAAA=",
            "subject": "Event with charm",
            "singleValueExtendedProperties": [
                {
                    "id": "Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x0027",
                    "value": "Plane"
                }
            ]
        },
        {
            "@odata.etag": "W/\"AgHex1lHnU6P4tmSFYQ4hwAI3IzR6A==\"",
            "id": "AAMkAGRkZTFiMDQxLWYzNDgtNGQ3ZS05Y2U3LWU1NWJhMTM5YTgwMABGAAAAAABxI4iNfZK7SYRiWw9sza20BwA7DGC6yx9ARZqQFWs3P3q1AAAASBOQAAACAd7HWUedTo-i2ZIVhDiHAAjdwbvMAAA=",
            "subject": "Event without charm"
        }
    ]
}

For the event with a charm, there is the single-value extended property with the id Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x27 and the value Plane.

You probably expect that the value of the extended property will be a number not a string.

It's hard to explain but it looks like the Graph API reads the value of the MAPI property 0x0027 as the number but exposes it via the single-value extended property as the string. It means that when we want to set the event charm for a new/existing event via the Graph API, we need to know the correct name for the value of the extended property.

Possible values for extended property

To figure out all possible values for the extended property Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x27 use MFCMapi.

Change the numeric value of the MAPI property in the editor:

img

Save changes, and check what value will be returned when calling:

GET https://graph.microsoft.com/v1.0/me/events?$expand=singleValueExtendedProperties($filter=id eq 'Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x0027')&$select=id,subject

The table below shows all numeric values for the MAPI property, their relevant values for the extended property, and their icons to be displayed in Outlook clients:

Icon Name MAPI property value Graph extended property value
img Cat 1 Cat
img Dog 2 Dog
img Plane 3 Plane
img Document1 4 Document1
img FirstAid 5 FirstAid
img Trophy 6 Trophy
img Home 7 Home
img Pill 8 Pill
img Luggage 9 Luggage
img Cup 10 Cup
img Group 11 Group
img Timer 12 Timer
img Music 13 Music
img Shopping 14 Shopping
img Car 15 Car
img Star 16 Star
img Document2 17 Document2
img Person 18 Person
img Balloon 19 Balloon
img ForkKnife 20 ForkKnife
img Heart 21 Heart
img Soccer 22 Soccer
img Movie 23 Movie
img Chart 24 Chart
img Books 25 Books
img Cake 26 Cake
img Tv 27 Tv
img Travel 28 Travel
img PackageDelivery 29 PackageDelivery
img Promotion 30 Promotion
img Event 31 Event
img Hotel 32 Hotel
img CreditCard 33 CreditCard
img Bike 34 Not possible to set
img Boat 35 Not possible to set
img Breakfast 36 Not possible to set
img Brunch 37 Not possible to set
img Bus 38 Not possible to set
img Call 39 Not possible to set
img Camping 40 Not possible to set
img Chopsticks 41 Not possible to set
img Class 42 Not possible to set
img Dentist 43 Not possible to set
img FaceTime 44 Not possible to set
img Guitar 45 Not possible to set
img Gym 46 Not possible to set
img Island 47 Not possible to set
img Post 48 Not possible to set
img Meetings 49 Not possible to set
img Professional 50 Not possible to set
img Repair 51 Not possible to set
img Skype 52 Not possible to set
img Sprint 53 Not possible to set
img Taxi 54 Not possible to set
img Todo 55 Not possible to set
img Train 56 Not possible to set
img Exam 57 Not possible to set
img Goal 58 Not possible to set
img Teams 59 Not possible to set
img Focus 60 Not possible to set

The MAPI property accepts numeric values from range 1–60, and the extended property allows to set the names only for the first 30 numeric values.ws to set the names only for the first 30 numeric values.

Create/update an event with an event charm in the Graph API

To create an event with a charm, make a POST request and in the request body specify the extended property.

POST /me/events
{
    "subject": "My event",
    "start": {
        "dateTime": "2023-06-14T08:00:00.000Z",
        "timeZone": "UTC"
    },
    "end": {
        "dateTime": "2023-06-14T09:00:00.000Z",
        "timeZone": "UTC"
    },
	"singleValueExtendedProperties": [
        {
            "id": "Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x0027",
            "value": "Cat"
        }
    ]
}

To update the event charm of the existing event, make a PATCH request.

PATCH /me/events/{event_id}
{
	"singleValueExtendedProperties": [
        {
            "id": "Integer {11000E07-B51B-40D6-AF21-CAA85EDAB1D0} Id 0x0027",
            "value": "Dog"
        }
    ]
}

The possible values are Cat, Dog, Plane, Document1, FirstAid, Trophy, Home, Pill, Luggage, Cup, Group, Timer, Music, Shopping, Car, Star, Document2, Person, Balloon, ForkKnife, Heart, Soccer, Movie, Chart, Books, Cake, Tv, Travel, PackageDelivery, Promotion, Event, Hotel and CreditCard.

3
Buy Me a Coffee at ko-fi.com
An error has occurred. This application may no longer respond until reloaded. Reload x