Commonly Occurring Errors in Microsoft Graph 4

In addition to the third article of the series, this article covers some more case studies related to To Do Tasks. For this use case, I used the MS Graph Java SDK 5.42.0. If you haven’t read parts 1 and 2 of this series, here they are:

Part 1: “Commonly Occurring Errors in Microsoft Graph Integrations and How To Troubleshoot Them (Part 1)”

Part 2: “Commonly Occurring Errors in Microsoft Graph Integrations and How To Troubleshoot Them (Part 2)”

Read Tasks With a Specific Time Zone

Microsoft Graph Todo Task is a powerful tool for developers to integrate Microsoft To Do task management software into their applications. It enables them to create, update, and retrieve tasks using the Microsoft Graph API. One of the essential considerations when working with task management tools, like Microsoft To Do, is ensuring they operate in the correct time zone.

Time zone plays a crucial role in task management tools because they rely on deadlines and reminders to keep users on track. If a user creates a task and sets a deadline or reminder, it must be displayed accurately based on the user’s time zone. Developers working with the Microsoft Graph Todo Task must ensure their applications handle time zones correctly to avoid confusion and ensure that tasks are displayed accurately.

Microsoft Graph API provides built-in functionality for handling time zones. When creating or updating tasks, developers can set the time zone information for the task. The API supports the standard time zone format (e.g., “America/Los_Angeles”) and the Windows time zone format (e.g., “Pacific Standard Time”).

Developers can also use the Microsoft Graph API to retrieve the user’s time zone information. This can be useful when displaying tasks and reminders in the correct time zone. By default, the API returns the user’s time zone in the IANA time zone format (e.g., “America/Los_Angeles”). However, developers can also request the user’s time zone in the Windows time zone format.

When retrieving tasks using the Microsoft Graph API, developers can also specify the time zone in which they want to retrieve the tasks. This can be useful when displaying tasks to users in different time zones. By default, the API returns tasks in the user’s time zone. However, developers can also specify a different time zone using the “Prefer” header in the API request.

For instance, in Java: 

LinkedList<Option> requestOptions = new LinkedList<>();
requestOptions.add(new HeaderOption("Prefer", "outlook.timezone=" + """ + timeZone + """));

Beside the header adjustments, let’s take a look at how to create a ToDo task with a specific time zone:

String timeZone = "Pacific Standard Time"; //replace with the desired timezone
String apiEndpoint = "https://graph.microsoft.com/v1.0/me/tasks";
String json = "{n" +
                "  "subject": "Complete Task",n" +
                "  "body": {n" +
                "    "contentType": "Text",n" +
                "    "content": "This is a task with specific time zone"n" +
                "  },n" +
                "  "dueDateTime": {n" +
                "    "dateTime": "2021-12-01T14:30:00",n" +
                "    "timeZone": ""+timeZone+""n" +
                "  }n" +
                "}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(apiEndpoint))
            .header("Authorization", "Bearer " + accessToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

In the above code, replace the value of the timeZone variable with the desired time zone. Also, replace the subject and body properties of the task object with your own values. The dueDateTime property of the task object contains a dateTime and timeZone property. Set the dateTime property to the desired due date and time in ISO format. Set the timeZone property to the desired time zone.

Time zone is a crucial consideration when working with task management tools like Microsoft To Do. Developers working with the Microsoft Graph Todo Task must ensure their applications handle time zones correctly to avoid confusion and ensure tasks are displayed accurately. Microsoft Graph API provides built-in functionality for handling time zones and supports DST, making it easy for developers to create applications that work with tasks in different time zones.

Read the Changekey Property of ToDo Tasks

Based on a documented issue on Github from November 2020, there are missing properties from the Microsoft.Graph.todoTask resource type as compared to the Microsoft.OutlookServices.Task type.

Some of these properties are absolutely necessary for business logic and play a key role, according to the comments of the issue:

By now, not all requested  properties are available for use in Microsoft Graph v1.0. In the current version of the MS Graph Java SDK 5.42.0, the following properties are included within the default data model: 

In this use case, I will show how to read the changeKey from ToDo Tasks via the MS Graph APIs and the Java SDK. 

The changeKey is part of the ETag  that comes with the ToDo Task. To retrieve the ETag value for a ToDo task via Microsoft Graph, you can use the GET method on the tasks endpoint, along with the task ID.

Here is an example URL to retrieve the ETag value for a specific task:

https://graph.microsoft.com/v1.0/me/tasks/{task_id}?$select=etag

Replace {task_id} with the ID of the task you want to retrieve the ETag value for. The $select=etag query parameter will ensure that only the ETag value is returned in the response.

How do you read the changeKey from the ToDo task via the MS Graph Java SDK? 

The SDK contains the Java class AdditionalDataManager. The class holds additional properties that are not part of the default object’s schema, according to the Microsoft documentation. We can read all JSON elements provided by the response from the API and which are not included within the default data model. Let’s take a look at the following sample:

public static final String ODATA_ETAG = "@odata.etag";
public static final String PREFIX = "W/"";
public static final String SUFFIX = """;

String eTag = todoTask.additionalDataManager().get(ODATA_ETAG).getAsString();
String changeKey = convertETagToChangeKey(eTag);

private String convertETagToChangeKey(String eTag) {
        String changekey = "";
        if (Objects.nonNull(eTag) && eTag.startsWith(PREFIX)) {
            String noPrefixSubString = eTag.substring(PREFIX.length());
            if (noPrefixSubString.endsWith(SUFFIX)) {
                return noPrefixSubString.substring(0, noPrefixSubString.length() - 1);
            }
        }
        return changekey;
}

In this sample, we use the key @odata.etag to read the value of the ETag and remove the prefix and suffix of the ETag to get the value of the changeKey. 

Conclusion

At this point, you should have a better understanding of the common integration errors that may be seen in Microsoft Graph integrations and how to troubleshoot them. I hope this article was informative and useful. Feel free to comment below and share this article!