- Publicity: Public Only All
ms-procs.tcl
Support for the Microsoft Graph API These interface classes support conversion from/to JSON and to the urlencoded calling patterns on the fly, just by specifying the Tcl variable names mith minor annotations (somewhat similar to the export_vars interface). Furthermore, the interface supports pagination: some Microsoft Graph API calls return per default just a partial number of results (e.g. first 100). To obtain all results multiple REST calls have to be issued to get the full result set. Over this interface, one can specify the desired maximum number of entries. To use the Microsoft Graph API, an "app" has to be registered/configured/authorized/...[1,2,3] by an administrator of the organization before an access token [4] can be obtained token from the Microsoft identity platform. The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph. This Interface is based on access tokens [4] and the /token endpoint [1] ("Get access without a user") and assumes, one has already obtained the client_id and client_secret to configure this service this way. In theory, this API will allow later to switch to newer versions of the Graph API when newer versions (currently post 1.0) of the Microsoft Graph API will come out. See also: https://openacs.org/xowiki/msgraph
This file defines the following Objects and Classes: ::ms::Graph
, ::ms::Authorize
- Location:
- packages/xooauth/tcl/ms-procs.tcl
- Author:
- Gustaf Neumann [1] https://docs.microsoft.com/en-us/graph/auth-v2-service [2] https://docs.microsoft.com/en-us/graph/auth/auth-concepts [3] https://docs.microsoft.com/en-us/graph/auth-register-app-v2 [4] https://oauth.net/id-tokens-vs-access-tokens/
Procedures in this file
- Class ::ms::Authorize (public)
- Class ::ms::Graph (public)
- ms::Authorize instproc login_url (public)
- ms::Authorize instproc logout (public)
- ms::Authorize instproc logout_url (public)
- ms::Graph instproc run_donecallback (public)
- ms::Graph instproc schedule_donecallback (public)
- ms::Graph instproc token (public)
- ms::Graph instproc {application get} (public)
- ms::Graph instproc {application list} (public)
- ms::Graph instproc {chat get} (public)
- ms::Graph instproc {chat messages} (public)
- ms::Graph instproc {group deleted} (public)
- ms::Graph instproc {group get} (public)
- ms::Graph instproc {group list} (public)
- ms::Graph instproc {group member add} (public)
- ms::Graph instproc {group member list} (public)
- ms::Graph instproc {group member remove} (public)
- ms::Graph instproc {group memberof} (public)
- ms::Graph instproc {group owner add} (public)
- ms::Graph instproc {group owner list} (public)
- ms::Graph instproc {group owner remove} (public)
- ms::Graph instproc {team archive} (public)
- ms::Graph instproc {team channel list} (public)
- ms::Graph instproc {team clone} (public)
- ms::Graph instproc {team create} (public)
- ms::Graph instproc {team delete} (public)
- ms::Graph instproc {team get} (public)
- ms::Graph instproc {team member add} (public)
- ms::Graph instproc {team member list} (public)
- ms::Graph instproc {team member remove} (public)
- ms::Graph instproc {team unarchive} (public)
- ms::Graph instproc {user get} (public)
- ms::Graph instproc {user list} (public)
- ms::Graph instproc {user memberof} (public)
- ms::Graph instproc {user me} (public)
- ms::Graph proc run_donecallback (public)
Detailed information
Class ::ms::Authorize (public)
::nx::Class ::ms::AuthorizeSupport for the Microsoft Microsoft identity platform ID tokens to login/logout via MS Azure accounts. https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens
- Testcases:
- No testcase defined.
Class ::ms::Graph (public)
::nx::Class ::ms::GraphThe "tenant" identifies an organization within azure. One OpenACS installation might talk to different tenants at the same time, in which case multiple instances of the Ms Class (or one of its subclasses) must be created. Possible values for the "tenant" property: - "common": Allows users with both personal Microsoft accounts and work/school accounts from Azure AD to sign into the application. - "organizations": Allows only users with work/school accounts from Azure AD to sign into the application. - "consumers": Allows only users with personal Microsoft accounts (MSA) to sign into the application. - tenant GUID identifier, or friendly domain name of the Azure AD, such as e.g. xxxx.onmicrosoft.com Details: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols
- Testcases:
- No testcase defined.
ms::Authorize method login_url (public)
<instance of ms::Authorize> login_url [ -prompt prompt ] \
[ -return_url return_url ] [ -login_hint login_hint ] \
[ -domain_hint domain_hint ] [ -code_challenge code_challenge ] \
[ -code_challenge_method code_challenge_method ]Returns the URL for logging in "oauth2/authorize" is defined in RFC 6749, but requests for MS id-tokens inversion v1.0 and v2.0 are defined here: https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens
- Switches:
- -prompt (optional)
- -return_url (optional)
- -login_hint (optional)
- -domain_hint (optional)
- -code_challenge (optional)
- -code_challenge_method (optional)
- Testcases:
- No testcase defined.
ms::Authorize method logout (public)
<instance of ms::Authorize> logoutPerform logout operation form MS in the background (i.e. without a redirect).
- Testcases:
- No testcase defined.
ms::Authorize method logout_url (public)
<instance of ms::Authorize> logout_url \
[ -return_url return_url ]Returns the URL for logging out. After the logout, azure redirects to the given page.
- Switches:
- -return_url (optional)
- Testcases:
- No testcase defined.
ms::Graph method run_donecallback (public)
<instance of ms::Graph> run_donecallback location callbackMethod to be finally executes the donecallback. First, we have to check whether the async operation has already finished. If this operation is still in progress, reschedule this operation.
- Parameters:
- location (required)
- callback (required)
- Testcases:
- No testcase defined.
ms::Graph method schedule_donecallback (public)
<instance of ms::Graph> schedule_donecallback secs location \
callbackAdd an atjob for the for the done callback. The job is persisted, such that even for long running operations and server restarts, the operation will continue after the server restart.
- Parameters:
- secs (required)
- location (required)
- callback (required)
- Testcases:
- No testcase defined.
ms::Graph method token (public)
<instance of ms::Graph> token [ -grant_type grant_type ] \
[ -scope scope ] [ -assertion assertion ] \
[ -requested_token_use requested_token_use ]Get bearer token (access token) from the /oauth2/v2.0/token endpoint, with timestamp validation (based on "expires_in") result. Obtaining the access token is MsGraph dependent. Probably, some of this can be factored out later to one of the super classes.
- Switches:
- -grant_type (optional, defaults to
"client_credentials")- -scope (optional, defaults to
"https://graph.microsoft.com/.default")- with prefconfigured permissions: use "https://graph.microsoft.com/.default" Comment: This method performs its own caching via nsvs. It would be better to use the ns_cache framework with it's built-in expiration methods via ns_cache_eval, but we get the expiration time provided from the non-cached call and not upfront, before this call. We do not want to use a hack with double ns_cache calls, so we leave this for the time being.
- -assertion (optional)
- -requested_token_use (optional)
- Testcases:
- No testcase defined.
ms::Graph method application get (public)
<instance of ms::Graph> application get [ -select select ] \
application_idGet the properties and relationships of an application object. Details: https://docs.microsoft.com/graph/api/application-list
- Switches:
- -select (optional)
- return selected attributes, e.g. id,appId,keyCredentials
- Parameters:
- application_id (required)
- Testcases:
- No testcase defined.
ms::Graph method application list (public)
<instance of ms::Graph> application list [ -count count ] \
[ -expand expand ] [ -filter filter ] [ -orderby orderby ] \
[ -search search ] [ -select select ] [ -top top ]Get the list of applications in this organization. Details: https://docs.microsoft.com/graph/api/application-list
- Switches:
- -count (optional)
- boolean, retrieves the total count of matching resources
- -expand (optional)
- retrieve related information via navigation property, e.g. members
- -filter (optional)
- retrieve a filtered subset of the tuples
- -orderby (optional)
- order tuples by some attribute
- -search (optional)
- returns results based on search criteria.
- -select (optional)
- return selected attributes, e.g. id,appId,keyCredentials
- -top (optional, integer, accept empty)
- sets the page size of results
- Testcases:
- No testcase defined.
ms::Graph method chat get (public)
<instance of ms::Graph> chat get chat_idRetrieve the properties and relationships of user object. Details: https://docs.microsoft.com/en-us/graph/api/chat-get
- Parameters:
- chat_id (required)
- Testcases:
- No testcase defined.
ms::Graph method chat messages (public)
<instance of ms::Graph> chat messages [ -top top ] chat_idRetrieve the properties and relationships of user object. Details: https://docs.microsoft.com/en-us/graph/api/chat-list-messages
- Switches:
- -top (optional, integer, accept empty)
- sets the page size of results (for chat, max is 50)
- Parameters:
- chat_id (required)
- Testcases:
- No testcase defined.
ms::Graph method group deleted (public)
<instance of ms::Graph> group deleted [ -count count ] \
[ -expand expand ] [ -filter filter ] [ -orderby orderby ] \
[ -search search ] [ -select select ] [ -top top ]List deleted groups. Since groups are large objects, use $select to only get the properties of the group you care about. Details: https://docs.microsoft.com/graph/api/directory-deleteditems-list
- Switches:
- -count (optional)
- boolean, retrieves the total count of matching resources
- -expand (optional)
- retrieve related information via navigation property, e.g. members
- -filter (optional)
- retrieve a filtered subset of the tuples
- -orderby (optional)
- order tuples by some attribute
- -search (optional)
- returns results based on search criteria.
- -select (optional, defaults to
"id,displayName,deletedDateTime")- return selected attributes, e.g. id,displayName,userPrincipalName
- -top (optional, integer, accept empty)
- sets the page size of results
- Testcases:
- No testcase defined.
ms::Graph method group get (public)
<instance of ms::Graph> group get [ -select select ] group_idGet the properties and relationships of a group object. To get properties that are not returned by default, specify them in a -select OData query option. Details: https://docs.microsoft.com/en-us/graph/api/group-get
- Switches:
- -select (optional)
- return selected attributes, e.g. displayName,mail,visibility
- Parameters:
- group_id (required)
- Testcases:
- No testcase defined.
ms::Graph method group list (public)
<instance of ms::Graph> group list [ -count count ] \
[ -expand expand ] [ -filter filter ] [ -orderby orderby ] \
[ -search search ] [ -select select ] [ -max_entries max_entries ] \
[ -top top ]To get a list of all groups in the organization that have teams, filter by the resourceProvisioningOptions property that contains "Team" (needs beta API): resourceProvisioningOptions/Any(x:x eq 'Team') Otherwise, one has to get the full list and filter manually. Since groups are large objects, use $select to only get the properties of the group you care about. Details: https://docs.microsoft.com/graph/teams-list-all-teams https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter
- Switches:
- -count (optional)
- boolean, retrieves the total count of matching resources
- -expand (optional)
- retrieve related information via navigation property, e.g. members
- -filter (optional)
- retrieve a filtered subset of the tuples
- -orderby (optional)
- order tuples by some attribute
- -search (optional)
- returns results based on search criteria.
- -select (optional, defaults to
"id,displayName,userPrincipalName")- return selected attributes, e.g. id,displayName,userPrincipalName
- -max_entries (optional)
- retrieve this desired number of tuples (potentially multiple API calls)
- -top (optional, integer, accept empty)
- return up this number of tuples per request (page size)
- Testcases:
- No testcase defined.
ms::Graph method group member add (public)
<instance of ms::Graph> group member add group_id principalsAdd a conversationMember to a group. Details: https://docs.microsoft.com/en-us/graph/api/group-post-members
- Parameters:
- group_id (required)
- principals (required)
- Testcases:
- No testcase defined.
ms::Graph method group member list (public)
<instance of ms::Graph> group member list [ -count count ] \
[ -filter filter ] [ -search search ] [ -max_entries max_entries ] \
[ -top top ] group_idGet a list of the group's direct members. A group can have users, organizational contacts, devices, service principals and other groups as members. Currently service principals are not listed as group members due to staged roll-out of service principals on Graph V1.0 endpoint. Details: https://docs.microsoft.com/en-us/graph/api/group-list-members
- Switches:
- -count (optional)
- boolean, retrieves the total count of matching resources
- -filter (optional)
- retrieve a filtered subset of the tuples
- -search (optional)
- returns results based on search criteria.
- -max_entries (optional)
- retrieve this desired number of tuples (potentially multiple API calls)
- -top (optional, integer, accept empty)
- sets the page size of results
- Parameters:
- group_id (required)
- Testcases:
- No testcase defined.
ms::Graph method group member remove (public)
<instance of ms::Graph> group member remove group_id principalRemove group member Details: https://docs.microsoft.com/en-us/graph/api/group-delete-members
- Parameters:
- group_id (required)
- principal (required)
- Testcases:
- No testcase defined.
ms::Graph method group memberof (public)
<instance of ms::Graph> group memberof [ -count count ] \
[ -filter filter ] [ -orderby orderby ] [ -search search ] \
group_idGet groups that the group is a direct member of. Details: https://docs.microsoft.com/en-us/graph/api/group-list-memberof
- Switches:
- -count (optional)
- when "true" return just a count
- -filter (optional)
- filter criterion
- -orderby (optional)
- sorting criterion, e.g. displayName
- -search (optional)
- search criterion, e.g. displayName:Video
- Parameters:
- group_id (required)
- Testcases:
- No testcase defined.
ms::Graph method group owner add (public)
<instance of ms::Graph> group owner add group_id principaladd an owner to a group. Details: https://docs.microsoft.com/en-us/graph/api/group-post-owners
- Parameters:
- group_id (required)
- principal (required)
- Testcases:
- No testcase defined.
ms::Graph method group owner list (public)
<instance of ms::Graph> group owner list group_idRetrieve a list of the group's owners. Details: https://docs.microsoft.com/en-us/graph/api/group-list-owners
- Parameters:
- group_id (required)
- Testcases:
- No testcase defined.
ms::Graph method group owner remove (public)
<instance of ms::Graph> group owner remove group_id user_idRemove group owner Details: https://docs.microsoft.com/en-us/graph/api/group-delete-owners
- Parameters:
- group_id (required)
- user_id (required)
- Testcases:
- No testcase defined.
ms::Graph method team archive (public)
<instance of ms::Graph> team archive \
[ -shouldSetSpoSiteReadOnlyForMembers shouldSetSpoSiteReadOnlyForMembers ] \
[ -donecallback donecallback ] [ -wait ] team_idArchive the specified team. When a team is archived, users can no longer send or like messages on any channel in the team, edit the team's name, description, or other settings, or in general make most changes to the team. Membership changes to the team continue to be allowed. Details: https://docs.microsoft.com/en-us/graph/api/team-archive
- Switches:
- -shouldSetSpoSiteReadOnlyForMembers (optional)
- This optional parameter defines whether to set permissions for team members to read-only on the SharePoint Online site associated with the team. Setting it to false or omitting the body altogether will result in this step being skipped.
- -donecallback (optional)
- cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status.
- -wait (optional, defaults to
"false")- when specified, perform up to 10 requests checking the status of the async command
- Parameters:
- team_id (required)
- Testcases:
- No testcase defined.
ms::Graph method team channel list (public)
<instance of ms::Graph> team channel list [ -filter filter ] \
[ -select select ] [ -expand expand ] team_idRetrieve the list of channels in this team. Details: https://docs.microsoft.com/en-us/graph/api/channel-list
- Switches:
- -filter (optional)
- retrieve a filtered subset of the tuples, e.g. "membershipType eq 'private'"
- -select (optional)
- select subset of attributes
- -expand (optional)
- retrieve related information via navigation property, e.g. members
- Parameters:
- team_id (required)
- Testcases:
- No testcase defined.
ms::Graph method team clone (public)
<instance of ms::Graph> team clone \
[ -classification classification ] [ -description description ] \
-displayName displayName -mailNickname mailNickname \
-partsToClone partsToClone [ -visibility visibility ] \
[ -donecallback donecallback ] [ -wait ] team_idCreate a copy of a team specified by "team_id". It is possible to copy just some parts of the old team (such as "apps", "channels", "members", "settings", or "tabs", or a comma-separated combination).
- Switches:
- -classification (optional)
- -description (optional)
- -displayName (required)
- -mailNickname (required)
- -partsToClone (required)
- specify e.g. as "apps,tabs,settings,channels"
- -visibility (optional)
- -donecallback (optional)
- cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status. Details: https://docs.microsoft.com/en-us/graph/api/team-clone
- -wait (optional, defaults to
"false")- when specified, perform up to 10 requests checking the status of the async command
- Parameters:
- team_id (required)
- of the team to be cloned (might be a template)
- Testcases:
- No testcase defined.
ms::Graph method team create (public)
<instance of ms::Graph> team create [ -description description ] \
-displayName displayName [ -visibility visibility ] -owner owner \
[ -donecallback donecallback ] [ -wait ]Create a new team. A team owner must be provided when creating a team in an application context. Details: https://docs.microsoft.com/en-us/graph/api/team-post
- Switches:
- -description (optional)
- -displayName (required)
- -visibility (optional)
- -owner (required)
- -donecallback (optional)
- cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status.
- -wait (optional, defaults to
"false")- when specified, perform up to 10 requests checking the status of the async command
- Testcases:
- No testcase defined.
ms::Graph method team delete (public)
<instance of ms::Graph> team delete team_idDelete group/team. When deleted, Microsoft 365 groups are moved to a temporary container and can be restored within 30 days. After that time, they're permanently deleted. Details: https://docs.microsoft.com/en-us/graph/api/group-delete
- Parameters:
- team_id (required)
- Testcases:
- No testcase defined.
ms::Graph method team get (public)
<instance of ms::Graph> team get [ -expand expand ] \
[ -select select ] team_idRetrieve the properties and relationships of the specified team. Every team is associated with a group. The group has the same ID as the team - for example, /groups/{id}/team is the same as /teams/{id}. For more information about working with groups and members in teams, Details: https://docs.microsoft.com/en-us/graph/api/team-get
- Switches:
- -expand (optional)
- retrieve related information via navigation property, e.g. members
- -select (optional)
- select subset of attributes
- Parameters:
- team_id (required)
- Testcases:
- No testcase defined.
ms::Graph method team member add (public)
<instance of ms::Graph> team member add [ -roles roles ] team_id \
principalAdd a conversationMember to the collection of a team. Details: https://docs.microsoft.com/en-us/graph/api/team-post-members
- Switches:
- -roles (optional, defaults to
"member")- Parameters:
- team_id (required)
- principal (required)
- Testcases:
- No testcase defined.
ms::Graph method team member list (public)
<instance of ms::Graph> team member list [ -filter filter ] \
[ -select select ] team_idGet the conversationMember collection of a team. Details: https://docs.microsoft.com/en-us/graph/api/team-list-members
- Switches:
- -filter (optional)
- restrict answers to a subset of tuples, e.g. (microsoft.graph.aadUserConversationMember/displayName eq 'Harry Johnson')
- -select (optional)
- select subset of attributes
- Parameters:
- team_id (required)
- Testcases:
- No testcase defined.
ms::Graph method team member remove (public)
<instance of ms::Graph> team member remove team_id principalRemove a conversationMember from a team. Details: https://docs.microsoft.com/en-us/graph/api/group-delete-members
- Parameters:
- team_id (required)
- principal (required)
- Testcases:
- No testcase defined.
ms::Graph method team unarchive (public)
<instance of ms::Graph> team unarchive \
[ -donecallback donecallback ] [ -wait ] team_idRestore an archived team. This restores users' ability to send messages and edit the team, abiding by tenant and team settings. Teams are archived using the archive API. Details: https://docs.microsoft.com/en-us/graph/api/team-unarchive
- Switches:
- -donecallback (optional)
- cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status.
- -wait (optional, defaults to
"false")- when specified, perform up to 10 requests checking the status of the async command
- Parameters:
- team_id (required)
- Testcases:
- No testcase defined.
ms::Graph method user get (public)
<instance of ms::Graph> user get [ -select select ] principalRetrieve the properties and relationships of user object. Details: https://docs.microsoft.com/en-us/graph/api/user-get
- Switches:
- -select (optional)
- return selected attributes, e.g. displayName,givenName,postalCode
- Parameters:
- principal (required)
- Testcases:
- No testcase defined.
ms::Graph method user list (public)
<instance of ms::Graph> user list [ -select select ] \
[ -filter filter ] [ -max_entries max_entries ] [ -top top ]Retrieve the properties and relationships of user object. For the users collection the default page size is 100, the max page size is 999, if you try $top=1000 you'll get an error for invalid page size. Details: https://docs.microsoft.com/en-us/graph/api/user-list
- Switches:
- -select (optional, defaults to
"displayName,userPrincipalName,id")- return selected attributes, e.g. displayName,givenName,postalCode
- -filter (optional)
- restrict answers to a subset, e.g. "startsWith(displayName,'Neumann')"
- -max_entries (optional)
- retrieve this desired number of tuples (potentially multiple API calls)
- -top (optional, integer, accept empty)
- return up this number of tuples per request (page size)
- Testcases:
- No testcase defined.
ms::Graph method user memberof (public)
<instance of ms::Graph> user memberof [ -count count ] \
[ -filter filter ] [ -orderby orderby ] [ -search search ] \
principalGet groups, directory roles, and administrative units that the user is a direct member of. Details: https://docs.microsoft.com/en-us/graph/api/user-list-memberof
- Switches:
- -count (optional)
- when "true" return just a count
- -filter (optional)
- filter criterion
- -orderby (optional)
- sorting criterion, e.g. displayName
- -search (optional)
- search criterion, e.g. displayName:Video
- Parameters:
- principal (required)
- Testcases:
- No testcase defined.
ms::Graph method user me (public)
<instance of ms::Graph> user me [ -select select ] \
[ -token token ]Retrieve the properties and relationships of the current user identified by the token. The "me" request is only valid with delegated authentication flow. Details: https://docs.microsoft.com/en-us/graph/api/user-get
- Switches:
- -select (optional)
- return selected attributes, e.g. displayName,givenName,postalCode
- -token (optional)
- Testcases:
- No testcase defined.
ms::Graph object method run_donecallback (public)
ms::Graph run_donecallback serialized_app_obj location callbackHelper method for running callbacks. In general, we cannot rely that the interface object (typically ms::app) exists also in the job-queue, where atjobs are executed. Therefore, the class method receives everything to reconstruct the used interface object.
- Parameters:
- serialized_app_obj (required)
- location (required)
- callback (required)
- Testcases:
- No testcase defined.
