Commonly Occurring Errors in Microsoft Graph Integrations and How To Troubleshoot Them (Part 6)

This article discusses the following example: changing a column value for a list item of a “user-defined” SharePoint list, which represents a PDF file within a sub-folder of the SharePoint drive, using a DriveItem, which also represents the PDF file. SharePoint lists are central data structures that make it possible to store, organize, and manage information in tabular form. The test aims to demonstrate and explain how the MS-Graph API can be successfully used to change values in a list and correctly transfer this change to SharePoint. This ensures that the integrity of the file is maintained after the change and that no unexpected errors occur during API communication.

Microsoft Graph API

The Microsoft Graph API is a REST-based programming interface that provides access to a variety of services and data within the Microsoft 365 platform. It offers developers the ability to access a central interface to read, write, and manage data from services such as Azure Active Directory, Outlook, OneDrive, SharePoint, Microsoft Teams, and many more.

• Access to Microsoft 365 data: Using the Graph API, developers can access user, group, calendar, email, file, task, and SharePoint data.
• Identity and access management: It enables identities and access rights to be managed via Azure Active Directory, including user management, groups, and policies.
• File management: The API can be used to create, modify, delete, or share files in OneDrive, SharePoint, and Teams.
• Real-time communication: The API provides access to communication data from Outlook and Microsoft Teams such as emails, calendars, and chats.
• It is a centralized API: Instead of using multiple APIs for different services (e.g., Outlook API, OneDrive API), the Microsoft Graph API provides a unified and consistent way to communicate.

SharePoint Lists and List Elements

A SharePoint list is a collection of data in SharePoint that is organized in the form of a table. It works similarly to a table in a database or an Excel spreadsheet and enables the storage, organization, and sharing of information within a SharePoint team or organization. Each list consists of columns, which can contain different types of data such as text, numbers, dates, people, or custom values, and rows, which are called list items. Each list has defined columns that describe the different types of information that belong to a list element (e.g., title, date, persons, metadata). Each line in a list represents a list element. This can be a data record or a file, e.g., a task, a contact, or a document in a document library. Lists can be easily customized by adding custom columns or changing the display order. There are different types of SharePoint lists:

• Custom lists: Create and customize your lists with any columns and content.
• Document library: A special list that contains documents (files), these are handled in the form of DriveItems and can be managed with metadata and versioning.
• Announcements: A list for managing notifications or announcements
• Task list: A list for tracking and managing tasks within a team
• Contacts: A list for managing contact data

A DriveItem is a resource in the Microsoft Graph API that represents a file, folder, or other data entry within a drive (e.g., OneDrive, SharePoint document library). Each DriveItem can be an object that represents a file (e.g., PDF, Word document, image), a folder, or a link to an external resource. It serves as a central element for accessing and managing files and folders in Microsoft 365 via the Graph API.

Test Case

First, make sure that a valid access token for the Microsoft Graph API is available to obtain authorization to access SharePoint data. Use the following link to obtain the access token:

https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

You need the TenantID, ClientID, and the ClientSecret to read this out. It is also important not to forget to define the appropriate rights on the Azure app. Next, the column to be read must be identified. The ListItem that represents the PDF file is retrieved from the SharePoint drive using the Microsoft Graph API. To do this, the SiteID, the DriveID, and the ListID must first be read.

SiteID

https://graph.microsoft.com/v1.0/sites/${Hostname}:/sites/${Sitename}

${hostname} is the name of the SharePoint instance and ${sitename} is the name of the default site.

ListID

https://graph.microsoft.com/v1.0/sites/${SiteID}/lists?filter=displayName eq ${DisplayName}&$select=id

${SiteID} is the ID of the page you want to read, and ${DisplayName} is the name of the subfolder. The select saves us, only the ID is returned.

DriveID

https://graph.microsoft.com/v1.0/sites/${SiteID}/drives

As above, ${SiteID} is the ID of the site that you want to read out in SharePoint.
Once you have identified all three IDs — SiteID, DriveID, and ListID — the next step is to download the list of elements of a subfolder on SharePoint. This is done with the following call:

https://graph.microsoft.com/v1.0/sites/${SiteID}/drives/${DriveID}/root:/${SubFolder}:/Children

Here, ${SiteID} and ${DriveID} are from the steps above and ${SubFolder} defines the relative path of the subfolder you want to read. The last call returns a list of so-called DriveItems.
In our case, a DriveItem represents the PDF that we want to read. With the last call, the so-called ${DriveItemID} is also read out for the items from the subfolder. Next, we need to read the so-called SharePoint IDs of a DriveItem so that we can determine the corresponding ListItemID of the DriveItemID. 

The call is as follows:

https://graph.microsoft.com/v1.0/sites/${SiteID}/drives/${DriveID}/items/${DriveItemID}/sharepointIds

A possible answer is as follows:

{
    "siteId": "site-id",
    "webId": "web-id",
    "listId": "list-id",
    "listItemId": "ListItemID",
    "listItemUniqueId": "list-item-unique-id",
    "uniqueId": "drive-item-unique-id"
}

The answer is pretty self-explanatory. With the ListItemID, the values of the columns of the SharePoint list can now be read out for a single row (list item). With the next call, we can finally read the column values for a list item that represents the PDF we are looking for:

https://graph.microsoft.com/v1.0/sites/${SiteID}/lists/${ListID}/items/${ListItemID}/fields

One possible answer could look like this:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('siteID')/lists('listID')/items('listItemID')/fields",
    "Title": "Plan",
    "Status": "In Process",
    "Person": "Max Mustermann",
    "Created": "2024-09-13T10:20:30Z",
    "InCharge": "Lisa Müller",
    "Expire Date": "2024-09-20",   
}

The response to the request shows the respective column name and the corresponding column value for the special list element. The values of the columns can now be changed with a patch call via the same endpoint. All you have to do is define a JSON in the request body that contains the column name and the new column value. Let's assume we want to change the “Title” column. Then the JSON must look like this:

{
    "Title": "Plan2"
}

Conclusion

In this test case, we demonstrated how the Microsoft Graph API can be used to change the value of a specific column of a list item in a SharePoint list representing a PDF file. By clearly structuring the API calls, from authentication and retrieving IDs to querying and modifying fields, we were able to demonstrate the efficiency and flexibility of the API for managing SharePoint data. 

This process illustrates how SharePoint lists can be used as a centralized data structure within an organization to efficiently manage files and metadata. The API provides a powerful and programmatic way to access and modify this data, simplifying the workflow in modern, collaborative environments. With the successful modification of the list items, the integrity of the file is maintained and the changes are accurately reflected in SharePoint without affecting the file itself. This demonstrates that the API is a reliable and scalable solution for managing SharePoint content.