RPA.MSGraph

module RPA.MSGraph

class RPA.MSGraph.MSGraph

MSGraph(client_id: Optional[str] = None, client_secret: Optional[str] = None, token: Optional[Token] = None, refresh_token: Optional[str] = None, redirect_uri: Optional[str] = None, vault_backend: bool = False, vault_secret: Optional[str] = None, file_backend_path: Optional[Path] = WindowsPath('/temp'))

The MSGraph library wraps the O365 package, giving robots the ability to access the Microsoft Graph API programmatically.

OAuth Configuration

Graph’s API primarily authenticates via the OAuth 2.0 authorization code grant flow or OpenID Connect. This library exposes the OAuth 2.0 flow for robots to authenticate on behalf of users. A user must complete an initial authentication flow with the help of our OAuth Graph Example Bot.

For best results, register an app in Azure AD and configure it as so:

  • The type is “Web App”.
  • Redirect URI should be https://login.microsoftonline.com/common/oauth2/nativeclient
  • The app should be a multi-tenant app.
  • Accounts in any organizational directory is checked.
  • Has relevant permissions enabled, check the Microsoft Graph permissions reference for a list of permissions available to MS Graph apps.

variable ROBOT_LIBRARY_DOC_FORMAT

ROBOT_LIBRARY_DOC_FORMAT = 'REST'

variable ROBOT_LIBRARY_SCOPE

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

method authorize_and_get_token

authorize_and_get_token(authorization_url: str)

Exchanges the OAuth authorization URL obtained from Generate OAuth Authorization URL for an access token. This library maintains the user access token for current requests and returns the refresh token to be stored in a secure location (e.g., the Robocorp Control Room Vault).

  • Parameters: authorization_url – The full URL retrieved by the user after completing authorization to Microsoft.
  • Returns: A refresh token which should be stored securely for future sessions.

method configure_msgraph_client

configure_msgraph_client(client_id: str, client_secret: str, refresh_token: Optional[str] = None, redirect_uri: Optional[str] = None)

Configures the MS Graph client. If a refresh token is known, it can be provided to obtain a current user token to authenticate with. A new refresh token is returned if one is provided.

Parameters
  • client_id – Application client ID.
  • client_secret – Application client secret.
  • refresh_token – Authorization refresh token obtained from prior OAuth flows.
  • redirect_uri – Must be provided with client ID and client secret if not using the default.
  • Returns: A new refresh token if one was provided, or None.

method create_sharepoint_list

create_sharepoint_list(list_data: dict, site: Site)

Creates a sharepoint list and returns the instance.

Parameters
  • list_data – Dictionary with the data for the new list.
  • site – Site instance obtained from Get Sharepoint Site.
  • Returns: SharePoint List that was created.

SharepointList objects have additional properties that can be accessed with dot-notation, see examples below.

method download_file_from_onedrive

download_file_from_onedrive(target_file: Union[File, str], to_path: Optional[Union[str, Path]] = None, name: Optional[str] = None, resource: Optional[str] = None, drive: Optional[Union[Drive, str]] = None)

Downloads a file from Onedrive.

The downloaded file will be saved to a local path.

Parameters
  • target_file – DriveItem or file path of the desired file.
  • to_path – Destination folder of the downloaded file, defaults to the current directory.
  • name – New name for the downloaded file, with or without extension.
  • resource – Name of the resource if not using default.
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • Returns: Path to the downloaded file.
download_file_from_share_link(share_url: str, to_path: Optional[Union[str, Path]] = None, name: Optional[str] = None)

Downloads file from the share link.

The downloaded file will be saved to a local path.

Parameters
  • share_url – URL of the shared file
  • to_path – Destination folder of the downloaded file, defaults to the current directory.
  • name – New name for the downloaded file, with or without extension.
  • Returns: The Path to the downloaded file.

method download_file_from_sharepoint

download_file_from_sharepoint(target_file: Union[File, str], site: Site, to_path: Optional[Union[str, Path]] = None, name: Optional[str] = None, drive: Optional[Union[Drive, str]] = None)

Downloads file from SharePoint.

The downloaded file will be saved to a local folder.

Parameters
  • target_file – DriveItem or file path of the desired file.
  • site – Site instance obtained from Get Sharepoint Site.
  • to_path – Destination folder of the downloaded file, defaults to the current directory.
  • name – New name for the downloaded file, with or without extension.
  • drive – A Drive object or a Drive ID as a string.
  • Returns: Path to the downloaded file.

method download_folder_from_onedrive

download_folder_from_onedrive(target_folder: Union[Folder, str], to_path: Optional[Union[str, Path]] = None, resource: Optional[str] = None, drive: Optional[Union[Drive, str]] = None)

Downloads a folder from OneDrive with all of its contents, including subfolders.

Caution when downloading big folder structures. The downloaded folder will be saved to a local path.

Parameters
  • target_folder – DriveItem or path of the desired folder.
  • to_path – Destination folder where the download will be saved to, defaults to the current directory.
  • resource – Name of the resource if not using default.
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • Returns: Path to the downloaded folder.

method find_onedrive_file

find_onedrive_file(search_string: str, target_folder: Optional[Union[Folder, str]] = None, include_folders: Optional[bool] = False, resource: Optional[str] = None, drive: Optional[Union[Drive, str]] = None)

Returns a list of files found in OneDrive based on the search string. If a folder is not specified, the search is done in the entire drive and may include items that were shared with the user. It is possible to pass root as the target folder in order to avoid this behavior.

The files returned are DriveItem objects and they have additional properties that can be accessed with dot-notation, see List Files In Onedrive Folder for details.

Parameters
  • search_string – String used to search for file in Onedrive. Values may be matched across several fields including filename, metadata, and file content.
  • target_folder – Folder where to search for files.
  • include_folders – Boolean indicating if should return folders as well.
  • resource – Name of the resource if not using default.
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • Returns: List of DriveItems found based on the search string.

method generate_oauth_authorization_url

generate_oauth_authorization_url(client_id: Optional[str] = None, client_secret: Optional[str] = None, redirect_uri: Optional[str] = None, scopes: Optional[list] = None)

Generates an authorization URL which must be opened by the user to complete the OAuth flow. If no scopes are provided, the default scope is used which is all scopes defined in the Get Scopes keyword.

Parameters
  • client_id – Application client ID.
  • client_secret – Application client secret.
  • redirect_uri – Can be provided with client ID and client secret if not using the default.
  • scopes – A list of scopes in the form required by the API. Use the helper function Get scopes.
  • Returns: The URL the user must follow to complete their portion of the OAuth flow.

method get_drive_instance

get_drive_instance(resource: Optional[str] = None, drive_id: Optional[str] = None)

Returns the specified drive from the specified resource. If either is not provided, defaults are returned.

Parameters
  • resource – Name of the resource if not using default.
  • drive_id – The Drive ID as a string.
  • Returns: The requested Drive object.

method get_file_instance

get_file_instance(drive: Union[Drive, str], file: Union[File, str])

Returns a File object from the provided drive. If a File object is provided, it is reobtained from the API.

Parameters
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • file_path – A File object or path as a string.

method get_folder_instance

get_folder_instance(drive: Optional[Union[Drive, str]] = None, folder: Optional[Union[Folder, str]] = None)

Returns a folder object from the provided drive. If a folder object is provided, it is reobtained from the API.

Parameters
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • folder – A Folder object or folder path as a string.

method get_items_from_sharepoint_list

get_items_from_sharepoint_list(list_name: str, site: Site)

Returns the items on a SharePoint list as a table. The list is found by it’s display name.

Parameters
  • list_name – Display name of the SharePoint list.
  • site – Site instance obtained from Get Sharepoint Site.
  • Returns: Table or list of dicts of the items.

method get_me

get_me()

Returns the MS Graph object representing the currently logged in user. A User object is returned. Properties of the user can be accessed like so:

method get_scopes

get_scopes(*scopes: str)

Returns the proper scope definitions based on the provided “scope helpers”, which are enumerated below. You can pass none to get all scopes. Basic is included in all other scopes. The provided object can be passed to the scopes parameter when calling Generate OAuth Authorization URL.

  • basic

  • mailbox

  • mailbox_shared

  • message_send

  • message_send_shared

  • message_all

  • message_all_shared

  • address_book

  • address_book_shared

  • address_book_all

  • address_book_all_shared

  • calendar

  • calendar_shared

  • calendar_all

  • calendar_shared_all

  • users

  • onedrive

  • onedrive_all

  • sharepoint

  • sharepoint_dl

  • settings_all

  • tasks

  • tasks_all

  • presence

  • Parameters: scopes – Scopes requested. If left empty, all scopes will be returned.

  • Returns: A list of Scopes which can be passed to authorization keywords.

method get_sharepoint_site

get_sharepoint_site(*args: str, resource: Optional[str] = '')

Returns a SharePoint site.

Parameters
  • args – The SharePoint site to retrieve, see documentation for different methods of defining the site.
  • resource – Name of the resource if not using default.
  • Returns: SharePoint Site instance.

There are multiple ways of retrieving a SharePoint site:

The return is of type Site and it has additional properties that can be accessed with dot-notation. See examples below.

method list_files_in_onedrive_folder

list_files_in_onedrive_folder(target_folder: Optional[Union[Folder, str]] = None, include_folders: Optional[bool] = False, resource: Optional[str] = None, drive: Optional[Union[Drive, str]] = None)

Returns a list of files from the specified OneDrive folder.

The files returned are DriveItem objects and they have additional properties that can be accessed with dot-notation.

Parameters
  • target_folder – Path of the folder in Onedrive. If none is provided, will return files from the root of Onedrive.
  • include_folders – Boolean indicating if should return folders as well.
  • resource – Name of the resource if not using default.
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • Returns: List of DriveItems in the folder.

method list_files_in_sharepoint_site_drive

list_files_in_sharepoint_site_drive(site: Site, include_folders: Optional[bool] = False, drive: Optional[Union[Drive, str]] = None, target_folder: Optional[Union[Folder, str]] = None)

List files in the SharePoint Site drive.

If the drive is not set, the default Document Library will be used. The drive can be obtained from the keyword List Sharepoint Site Drives.

The files returned are DriveItem objects and they have additional properties that can be accessed with dot-notation, see List Files In Onedrive Folder for details.

Parameters
  • site – Site instance obtained from Get Sharepoint Site.
  • include_folders – Boolean indicating if should return folders as well.
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • target_folder – Path of the folder in the Sharepoint drive. If none is provided, will return files from the root of the drive.
  • Returns: List of DriveItems present in the Site drive.

method list_sharepoint_site_drives

list_sharepoint_site_drives(site: Site)

Get a list of Drives available in the SharePoint Site.

  • Parameters: site – Site instance obtained from Get Sharepoint Site.
  • Returns: List of Drives present in the SharePoint Site.

method refresh_oauth_token

refresh_oauth_token(refresh_token: Optional[str] = None)

Refreshes the user token using the provided refresh_token. The user token is retained in the library and a new refresh token is returned. If no token is provided, this keyword assumes the Robocorp Vault is being used as a backend and attempts to refresh it based on that backend.

  • Parameters: refresh_token – The refresh token to use to refresh the session.
  • Returns: A refresh token which should be stored securely for future sessions.

method search_for_users

search_for_users(search_string: str, search_field: str = 'displayName', resource: str = 'users')

Returns a list of User objects from the Active Directory based on the provided search string.

User objects have additional properties that can be accessed with dot-notation, see Get Me for additional details.

Parameters
  • search_string – Text to search for.
  • search_field – Where to search. Defaults to display name.
  • resource – Name of the resource if not using default.

method upload_file_to_onedrive

upload_file_to_onedrive(file_path: str, target_folder: Optional[Union[Folder, str]] = None, resource: Optional[str] = None, drive: Optional[Union[Drive, str]] = None)

Uploads a file to the specified OneDrive folder.

The uploaded file is returned as a DriveItem object and it has additional properties that can be accessed with dot-notation, see List Files In Onedrive Folder for details.

Parameters
  • file_path – Path of the local file being uploaded.
  • target_folder – Path of the folder in Onedrive.
  • resource – Name of the resource if not using default.
  • drive – A Drive object or Drive ID as a string. If not provided, will use the default drive.
  • Returns: The newly created DriveItem.