Documentation:SysGraphAPI

SysGraphAPI

This page was created by Hans.karlsen on 2024-06-11. Last edited by Wikiadmin on 2026-07-29.

SysGraphAPI lets Turnkey applications that use the GraphAPI2023 model pattern search Microsoft 365 documents and retrieve Azure AD users and groups.

Overview

SysGraphAPI is the entry class in the GraphAPI2023 model pattern. Use the pattern when your application needs to work with Microsoft 365 content, including Office 365 and SharePoint documents, or with Azure AD (Active Directory) directory data.

The pattern separates the Graph operation, stored authentication tokens, and returned data into dedicated classes. For example, a user can refresh their OpenID Connect access token, search for a document, and present the returned SysGraphAPIResultRow instances in a ViewModel.

Add and use the pattern

The GraphAPI2023 model pattern is available from GitHub. Merge the pattern into the model before creating functionality that depends on its classes.

Use this workflow in your application:

Add the GraphAPI2023 pattern to your model.
Ensure the current user has a SysToken containing the access and refresh tokens used for the Microsoft connection.
Refresh the access token when required by calling SysUser.OpenIdConnectAccessTokenRefresh.
Call the required operation on SysGraphAPI, such as Search for documents or GetUsers for directory users.
Use the returned result objects in your ViewModel. For example, show document rows from SysGraphAPIResultRow, or show group names from SysGraphAPIGroup.

The server has built-in support for the methods listed on Pattern supported methods. Confirm each method's parameters, return values, and error behavior in API documentation and in the merged pattern.

Pattern classes

Class	Purpose	Example use
`SysGraphAPI`	Main entry point for Microsoft Graph-related functionality.	Call `Search` to retrieve document references that match a user's search.
`SysToken`	Holds encrypted access and refresh tokens. The access token can be refreshed through `SysUser.OpenIdConnectAccessTokenRefresh`.	Refresh the token before a document lookup when the existing access token is no longer usable.
`SysGraphAPIResultRow`	Represents a document reference returned from a search or lookup.	Display the document reference in a document-results ViewModel, then navigate within its folder structure.
`SysGraphAPIGroup`	Represents an Azure AD group returned by a group operation.	List the groups associated with a principal user.
`SysGraphAPIResultUser`	Represents an Azure AD user returned by a user operation.	Display users returned from `GetUsers` or users found through a group ID.

Available operations

SysGraphAPI has server-supported operations for token inspection, directory lookup, document search, drive-item lookup, content retrieval, thumbnails, and ad hoc queries.

Area	Supported methods	Example
Token inspection	`GetDecodedAccessToken` `GetDecodedRefreshToken`	Inspect decoded token information while diagnosing a connection.
Users and groups	`GetUsersFromGroupId` `GetGroupsFromPrincipalUser` `GetUsers`	Retrieve the users in a known group ID, or retrieve groups for a principal user.
Search and lookup	`Search` `LookUpFromUrl` `LookUpLocationFromDriveIdAndId` `LookUpFromDriveIdAndIdAndVersion`	Search for a document, or resolve a document reference from a URL, drive ID, item ID, and, where applicable, version.
Drive content and thumbnails	`DriveDriveItemToThumbnailUrl` `DriveDriveItemToThumbnailData` `GetContentFromDriveIdAndIdAndVersion`	Obtain a thumbnail for a search-result row or retrieve the content for a specific drive item and version.
Custom query	`AdHocGetQuery`	Run a query when the built-in lookup operations do not match the required retrieval.

SysGraphAPIResultRow also supports folder navigation:

NavigateDownInFolder moves from a result row into a folder.
NavigateUpToParentFolder moves from a result row to its parent folder.

Example: present document search results

A document-search ViewModel can use this sequence:

Refresh the current user's access token with SysUser.OpenIdConnectAccessTokenRefresh when needed.
Invoke SysGraphAPI.Search with the search input defined by the merged pattern.
Bind the resulting SysGraphAPIResultRow objects to the results area of the ViewModel.
When the user selects a folder result, use NavigateDownInFolder to show its contents. Use NavigateUpToParentFolder to return to the parent folder.
For a file result, use a drive-item lookup or content method when the application needs its location, version, thumbnail, or content.

Do not treat a SysGraphAPIResultRow as the file content itself. It is a returned document reference; retrieve content through the relevant SysGraphAPI operation when content is required.

Token handling

SysToken stores encrypted access and refresh tokens. Keep token refresh in the application flow that performs Graph operations rather than duplicating token data in your own model classes.

Use SysUser.OpenIdConnectAccessTokenRefresh for access-token refresh. This method is supported in Turnkey, as are the SysGraphAPI operations on this page. The decoded-token methods are intended for inspection; avoid presenting token information in end-user views.

Turnkey support

The methods described here are built-in supported methods in Turnkey. Their server implementation is maintained independently of the model pattern, so use the supported method names exactly as listed in Pattern supported methods.

Contents