Sys.Microsoft
Sys.Microsoft gives server-side code access to Microsoft 365 and Microsoft Entra ID through the Microsoft Graph API. Two clients cover the common cases:
SimpleGraphApplicationClientacts as an app registration, with application permissions (client credentials).SimpleGraphUserClientacts on behalf of a user who signed in to Lowgile through a Microsoft identity provider, with delegated permissions.
Both clients expose Graph resources as list clients and item clients, which build the Graph requests for you. Sys.Microsoft also re-exports the Microsoft libraries the clients are built on.
Availability: Server
Properties
Section titled “Properties”AzureIdentity
Section titled “AzureIdentity”export * as AzureIdentity from '@azure/identity'The Azure Identity library (@azure/identity 4.13.3), re-exported as-is. It provides credential classes that obtain Microsoft Entra ID tokens.
const credential = new Sys.Microsoft.AzureIdentity.ClientSecretCredential(tenantId, clientId, clientSecret)Type: module namespace of @azure/identity · Availability: Server
AzureTokenCredentials
Section titled “AzureTokenCredentials”export * as AzureTokenCredentials from '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials/index.js'The Azure token credential authentication provider of the Microsoft Graph JavaScript client (@microsoft/microsoft-graph-client 3.0.7), re-exported as-is. It connects an AzureIdentity credential to a GraphClient client.
const authProvider = new Sys.Microsoft.AzureTokenCredentials.TokenCredentialAuthenticationProvider(credential, { scopes: ['https://graph.microsoft.com/.default'],})Type: module namespace of @microsoft/microsoft-graph-client/authProviders/azureTokenCredentials · Availability: Server
Note
The type declarations for this module are missing, so the code editor offers no completion or type checking for it.
GraphClient
Section titled “GraphClient”export * as GraphClient from '@microsoft/microsoft-graph-client'The Microsoft Graph JavaScript client (@microsoft/microsoft-graph-client 3.0.7), re-exported as-is. Use it for Graph requests that the simple clients do not cover.
const client = Sys.Microsoft.GraphClient.Client.initWithMiddleware({ authProvider })const me = await client.api('/me').get()Type: module namespace of @microsoft/microsoft-graph-client · Availability: Server
OpenAi
Section titled “OpenAi”export * as OpenAi from '@azure/openai'The @azure/openai package, version 2.0.0, re-exported as-is. In this version the package exports nothing at runtime: it only adds Azure-specific types to the openai package. To use Azure OpenAI, use Sys.Ai.SimpleAi.
Type: module namespace of @azure/openai (empty) · Availability: Server
Classes
Section titled “Classes”SimpleGraphApplicationClient
Section titled “SimpleGraphApplicationClient”A Graph client that authenticates as an app registration in Microsoft Entra ID with a client secret. It can do whatever the application permissions granted to the app registration allow.
const graph = new Sys.Microsoft.SimpleGraphApplicationClient({ tenantId: '00000000-0000-0000-0000-000000000000', clientId: '11111111-1111-1111-1111-111111111111', clientSecret: clientSecret, // for example from a configuration item})
const salesUsers = await graph.users.get({ select: ['id', 'displayName', 'mail'], filter: { department: 'Sales', accountEnabled: true }, orderBy: ['displayName'], limit: 0, // all pages})
await graph.users.item(salesUsers[0].id).sendMail({ subject: 'Monthly report', body: { contentType: 'text', content: 'The report is ready.' }, toRecipients: [{ emailAddress: { address: 'controlling@example.com' } }],})constructor()
Section titled “constructor()”constructor(connectionOptions: GraphApplicationClientConnectionOptions, options?: GraphClientOptions)Creates a client for an app registration. The token is requested with the scope .default, so the client has all application permissions granted to the app registration.
| Parameter | Type | Description |
|---|---|---|
connectionOptions | GraphApplicationClientConnectionOptions | Credentials of the app registration. |
options | GraphClientOptions | Optional. Graph version and request batching. |
GraphApplicationClientConnectionOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
tenantId | string | Yes | ID of the Microsoft Entra tenant. |
clientId | string | Yes | Application (client) ID of the app registration. |
clientSecret | string | Yes | Client secret of the app registration. |
GraphClientOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
version | 'v1.0' | 'beta' | string | No | Graph API version. Defaults to the class’s defaultVersion, which is 'v1.0'. |
batchRequestsWithinMs | number | No | If set, requests made within this many milliseconds are combined into one Graph $batch request of up to 20 requests. If not set, each request is sent on its own. |
Availability: Server
defaultVersion
Section titled “defaultVersion”defaultVersion: 'v1.0' | 'beta' | (string & {})The Graph API version used by new clients that do not set version. Defaults to 'v1.0'.
Type: 'v1.0' | 'beta' | string · Availability: Server
get users(): SimpleGraphListClient<string, typeof UserDomainClient, User, string>Returns a list client for /users. Its item clients are user clients (see the domain client table below).
Type: SimpleGraphListClient · Availability: Server
groups
Section titled “groups”get groups(): SimpleGraphListClient<string, typeof GroupDomainClient, Group, "uniqueName">Returns a list client for /groups. Groups can also be addressed by uniqueName with itemByAlternateKey().
Type: SimpleGraphListClient · Availability: Server
drives
Section titled “drives”get drives(): SimpleGraphListClient<string, typeof DriveDomainClient, Drive, string>Returns a list client for /drives (OneDrive and SharePoint document libraries).
Type: SimpleGraphListClient · Availability: Server
get sites(): SimpleGraphListClient<string, typeof SiteDomainClient, Site, string>Returns a list client for /sites (SharePoint sites).
Type: SimpleGraphListClient · Availability: Server
servicePrincipals
Section titled “servicePrincipals”get servicePrincipals(): SimpleGraphListClient<string, typeof ServicePrincipalDomainClient, ServicePrincipal, "appId">Returns a list client for /servicePrincipals. Service principals can also be addressed by appId with itemByAlternateKey().
Type: SimpleGraphListClient · Availability: Server
applications
Section titled “applications”get applications(): SimpleGraphListClient<string, typeof ApplicationDomainClient, Application, "uniqueName" | "appId">Returns a list client for /applications (app registrations). Applications can also be addressed by appId or uniqueName with itemByAlternateKey().
Type: SimpleGraphListClient · Availability: Server
booking
Section titled “booking”get booking(): BookingDomainClientReturns a client for Microsoft Bookings, with the list clients businesses and currencies.
Type: BookingDomainClient · Availability: Server
SimpleGraphUserClient
Section titled “SimpleGraphUserClient”A Graph client that acts on behalf of a user, with the delegated permissions the user granted when signing in through a Microsoft identity provider. It has all members of SimpleGraphApplicationClient (defaultVersion, users, groups, drives, sites, servicePrincipals, applications and booking), plus me.
const graph = new Sys.Microsoft.SimpleGraphUserClient({ userOrId: Sys.User.currentUser, identityProviderId: 'entra', // ID of the identity provider the user signed in with})const files = await graph.me.drive.root.children.get({ select: ['name', 'size', 'webUrl'] })constructor()
Section titled “constructor()”constructor(connectionOptions: GraphUserClientConnectionOptions, options?: GraphClientOptions)Creates a client for a user’s Microsoft account.
| Parameter | Type | Description |
|---|---|---|
connectionOptions | GraphUserClientConnectionOptions | Either a Lowgile user and identity provider, or an access token. |
options | GraphClientOptions | Optional. Graph version and request batching, as for SimpleGraphApplicationClient. |
GraphUserClientConnectionOptions fields
Pass one of these two shapes:
| Field | Type | Required | Description |
|---|---|---|---|
userOrId | User | string | Yes, with identityProviderId | The Lowgile user, or their ID. Lowgile uses the access token stored when the user signed in through the identity provider, and refreshes it if it is about to expire. |
identityProviderId | string | Yes, with userOrId | ID of the identity provider the user signed in with. |
accessToken | string | Yes, with scopes | A Graph access token obtained elsewhere. |
scopes | string[] | Yes, with accessToken | The scopes of the access token. |
The token is fetched once, when the client is created, and is not refreshed afterwards. Create a new client for long-running work. If the user has no valid token for the identity provider, the first request fails.
Availability: Server
get me(): UserDomainClientReturns a user client for /me, the signed-in user.
Type: UserDomainClient · Availability: Server
SimpleGraphListClient
Section titled “SimpleGraphListClient”A list client stands for a Graph collection, such as /users or /me/messages. It reads, counts and creates items, and gives item clients for single items. You get list clients from the properties of the Graph clients and of item clients; you do not create them yourself.
All requests are sent through the Graph $batch endpoint. A request that Graph answers with an error status rejects with a GraphBatchItemError, which has the HTTP status and the response body.
get(getOptions?: GetListOptions<ItemType>): Promise<ItemType[]>Reads items of the collection.
| Parameter | Type | Description |
|---|---|---|
getOptions | GetListOptions<ItemType> | Optional. Selection, filter, sorting and paging. |
GetListOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
select | (keyof ItemType)[] | No | Properties to return ($select). |
expand | ExpandableKeys<ItemType>[] | ExpandableObject<ItemType> | No | Related objects to include ($expand). As an object, each key maps to true or to nested select, expand, filter, orderBy, skip and limit options. |
filter | Filter<ItemType> | No | Filter condition ($filter), written as an object. See below. |
orderBy | (keyof ItemType)[] | No | Properties to sort by ($orderby). |
skip | number | No | Number of items to skip ($skip). |
limit | number | No | Maximum number of items. If omitted, only the first page that Graph returns is read. A positive number reads pages until that many items are found. 0 or a negative number reads all pages. |
count | boolean | No | Requests the total count ($count). |
headers | Record<string, string | number> | No | Additional request headers. |
additionalQueryParams | Record<string, string | number | boolean> | No | Additional query parameters, for example $search. |
verbose | boolean | No | Writes the request URL to the server console. |
A filter object combines conditions with and. Each key is a property name, and its value is one of:
| Value | Meaning |
|---|---|
A string, number, boolean or Date | The property equals the value. |
| An array | The property equals one of the values. |
{ $eq, $ne, $gt, $ge, $lt, $le } | Comparison with the value. |
{ $startsWith, $endsWith, $contains } | Text comparison (string properties). |
{ $any, $all } | A nested filter that any or all elements of a collection property must match. |
{ $count } | A comparison with the number of elements of a collection property. |
| A nested filter object | Conditions on the properties of an object property. |
Use $and, $or (arrays of filters) and $not to combine conditions, and $isOfType to restrict to a Graph type such as 'microsoft.graph.user'. For example, { $or: [{ department: 'Sales' }, { jobTitle: { $startsWith: 'Head' } }] }.
Returns: Promise<ItemType[]> · Availability: Server
Note
A has condition on an array property is sent with the wrong value. Use $any instead. String values that contain an apostrophe produce an invalid filter.
getAndCount()
Section titled “getAndCount()”getAndCount(getOptions?: GetListOptions<ItemType>): Promise<[ItemType[], number]>Reads items like get() and also returns the total number of matching items.
| Parameter | Type | Description |
|---|---|---|
getOptions | GetListOptions<ItemType> | Optional. As for get(). |
Returns: Promise<[ItemType[], number]>: the items and the total count. · Availability: Server
count()
Section titled “count()”count(countOptions: GetListCountOptions<ItemType>): Promise<number>Returns the number of items that match a filter, without reading them.
| Parameter | Type | Description |
|---|---|---|
countOptions | GetListCountOptions<ItemType> | The GetListOptions fields except select, expand, orderBy and skip. Pass {} to count all items. |
Returns: Promise<number> · Availability: Server
create()
Section titled “create()”create(data: ItemType): Promise<ItemType>Creates an item in the collection.
| Parameter | Type | Description |
|---|---|---|
data | ItemType | The new item, as a Graph object. |
Returns: Promise<ItemType>: the created item, as returned by Graph. · Availability: Server
addReference()
Section titled “addReference()”addReference(id: string): Promise<void>Adds a reference to an existing object to the collection, for example a member to a group’s members.
| Parameter | Type | Description |
|---|---|---|
id | string | The @odata.id of the object, its full Graph URL. |
Returns: Promise<void> · Availability: Server
item()
Section titled “item()”item(id: ItemIdType): InstanceType<ItemClientClass>Returns the item client for one item of the collection. No request is sent until you call a method on it.
| Parameter | Type | Description |
|---|---|---|
id | ItemIdType | ID of the item. For users, the user principal name also works. |
Returns: the item client of the collection’s type · Availability: Server
itemByAlternateKey()
Section titled “itemByAlternateKey()”itemByAlternateKey(alternateKey: AlternateKeyType | (string & {}), alternateId: string): InstanceType<ItemClientClass>Returns the item client for an item addressed by an alternate key, such as an application’s appId.
| Parameter | Type | Description |
|---|---|---|
alternateKey | AlternateKeyType | string | Name of the alternate key property. |
alternateId | string | Value of the alternate key. |
Returns: the item client of the collection’s type · Availability: Server
appendPathForItem()
Section titled “appendPathForItem()”appendPathForItem(path: string): SimpleGraphItemClient<object>Returns a generic item client for a Graph path below this collection, for resources the typed clients do not cover.
| Parameter | Type | Description |
|---|---|---|
path | string | Path to append, starting with /. |
Returns: SimpleGraphItemClient<object> · Availability: Server
appendPathForList()
Section titled “appendPathForList()”appendPathForList(path: string): SimpleGraphListClient<string, any, object, string>Returns a generic list client for a Graph path below this collection.
| Parameter | Type | Description |
|---|---|---|
path | string | Path to append, starting with /. |
Returns: SimpleGraphListClient<string, any, object, string> · Availability: Server
get $url(): stringReturns the Graph path of the collection, for example /users.
Type: string · Availability: Server
list()
Section titled “list()”list(getOptions?: GetListOptions<ItemType>): Promise<ItemType[]>Deprecated. Use get() instead. Reads items of the collection.
| Parameter | Type | Description |
|---|---|---|
getOptions | GetListOptions<ItemType> | Optional. As for get(). |
Returns: Promise<ItemType[]> · Availability: Server
SimpleGraphItemClient
Section titled “SimpleGraphItemClient”An item client stands for one Graph object, such as a user or a file. Each kind of object has its own item client (a domain client) that adds navigation properties and actions to the methods below. You get item clients from item(), itemByAlternateKey() or navigation properties such as me, drive or manager.
| Domain client | Reached through | Adds, among others |
|---|---|---|
UserDomainClient | users.item(id), me, manager | messages, mailFolders, mailFolder_inbox and the other well-known folders, events, calendar, calendars, drive, drives, joinedTeams, directReports, manager, photo, presence, sendMail(), listEvents(), listReminders(), setManager(), changePassword(), revokeSignInSessions() |
GroupDomainClient | groups.item(id) | members, members_ofTypeUser, owners, calendar, conversations, threads, drive, site, sites, memberOf, addFavorite(), removeFavorite() |
DriveDomainClient | drives.item(id), drive | root, items, itemByAbsolutePath(), specialFolder_documents and other special folders, search() |
DriveItemDomainClient | root, items.item(id), children.item(id) | children, versions, permissions, uploadFile(), downloadFileContent(), downloadFileContentAsFormat(), replaceFileContent(), move(), copy(), copyAndWait(), createLink(), invite() |
SiteDomainClient | sites.item(id), site | drive, lists, permissions, sites |
ApplicationDomainClient | applications.item(id) | owners(), appRoles, addPassword(), removePassword() |
ServicePrincipalDomainClient | servicePrincipals.item(id) | owners(), byAppId() |
MessageDomainClient | messages.item(id) | attachments, sendDraft(), reply(), replyAll(), forward(), copyToFolder(), moveToFolder() |
The code editor lists all members of each domain client.
get(getOptions?: GetItemOptions<ItemType>): Promise<ItemType>Reads the object.
| Parameter | Type | Description |
|---|---|---|
getOptions | GetItemOptions<ItemType> | Optional. The select, expand, headers, additionalQueryParams and verbose fields of GetListOptions. |
Returns: Promise<ItemType> · Availability: Server
update()
Section titled “update()”update(data: ItemType, options?: PatchItemOptions): Promise<ItemType>Changes the given properties of the object (HTTP PATCH).
| Parameter | Type | Description |
|---|---|---|
data | ItemType | The properties to change. |
options | PatchItemOptions | Optional. headers, verbose, and eTag: if set, the change only succeeds if the object still has this ETag. |
Returns: Promise<ItemType> · Availability: Server
replace()
Section titled “replace()”replace(data: ItemType, options?: PutItemOptions): Promise<ItemType>Replaces the object (HTTP PUT).
| Parameter | Type | Description |
|---|---|---|
data | ItemType | The new object. |
options | PutItemOptions | Optional. headers and verbose. |
Returns: Promise<ItemType> · Availability: Server
deleteObject()
Section titled “deleteObject()”deleteObject(options?: DeleteItemOptions): Promise<void>Deletes the object.
| Parameter | Type | Description |
|---|---|---|
options | DeleteItemOptions | Optional. headers, verbose, and eTag: if set, the object is only deleted if it still has this ETag. |
Returns: Promise<void> · Availability: Server
setReference()
Section titled “setReference()”setReference(fieldName: keyof ItemType, id: string): Promise<void>Sets a single-valued reference of the object, such as a user’s manager.
| Parameter | Type | Description |
|---|---|---|
fieldName | keyof ItemType | Name of the reference property. |
id | string | The @odata.id of the referenced object, its full Graph URL. |
Returns: Promise<void> · Availability: Server
deleteReference()
Section titled “deleteReference()”deleteReference(): Promise<void>Removes the reference this item client stands for, for example a member from a group when called on members.item(id). The referenced object itself is not deleted.
Returns: Promise<void> · Availability: Server
appendPathForItem()
Section titled “appendPathForItem()”appendPathForItem(path: string): SimpleGraphItemClient<object>Returns a generic item client for a Graph path below this object.
| Parameter | Type | Description |
|---|---|---|
path | string | Path to append, starting with /. |
Returns: SimpleGraphItemClient<object> · Availability: Server
appendPathForList()
Section titled “appendPathForList()”appendPathForList(path: string): SimpleGraphListClient<string, any, object, string>Returns a generic list client for a Graph path below this object.
| Parameter | Type | Description |
|---|---|---|
path | string | Path to append, starting with /. |
Returns: SimpleGraphListClient<string, any, object, string> · Availability: Server
get $url(): stringReturns the Graph path of the object, for example /users/1234.
Type: string · Availability: Server
GraphTypes
Section titled “GraphTypes”export type * as GraphTypes from '@lg/backend/data/microsoft/graph-types.js'Type-only namespace with the Graph object types from @microsoft/microsoft-graph-types 2.43.1, such as User, Group, Message, Event, Drive, DriveItem, Site, Team, Application and ServicePrincipal. Use them to type variables, for example const message: Sys.Microsoft.GraphTypes.Message = { subject: 'Hello' }.
Availability: Server