RPA.MSGraph library | Robocorp documentation

Authorize And Get Token

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).

Arguments

Argument	Type	Default value	Description
authorization_url	str	null	The full URL retrieved by the user after completing authorization to Microsoft.

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

Configure Msgraph Client

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.

Arguments

Argument	Type	Default value	Description
client_id	str	null	Application client ID.
client_secret	str	null	Application client secret.
refresh_token	str, None	None	Authorization refresh token obtained from prior OAuth flows.
redirect_uri	str, None	None	Must be provided with client ID and client secret if not using the default.

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

Create Sharepoint List

Creates a sharepoint list and returns the instance.

Arguments

Argument	Type	Default value	Description
list_data	dict	null	Dictionary with the data for the new list.
site	Site	null	Site instance obtained from Get Sharepoint Site.

param list_data:
	Dictionary with the data for the new list.
param site:	Site instance obtained from Get Sharepoint Site.
return:	SharePoint List that was created.

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

Download File From Onedrive

Downloads a file from Onedrive.

Arguments

Argument	Type	Default value	Description
target_file	File, str	null	DriveItem or file path of the desired file.
to_path	str, Path, None	None	Destination folder of the downloaded file, defaults to the current directory.
name	str, None	None	New name for the downloaded file, with or without extension.
resource	str, None	None	Name of the resource if not using default.
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.

The downloaded file will be saved to a local path.

param target_file:
	`DriveItem` or file path of the desired file.
param to_path:	Destination folder of the downloaded file, defaults to the current directory.
param name:	New name for the downloaded file, with or without extension.
param resource:	Name of the resource if not using default.
param drive:	A `Drive` object or Drive ID as a string. If not provided, will use the default drive.
return:	Path to the downloaded file.

Download File From Share Link

Downloads file from the share link.

Arguments

Argument	Type	Default value	Description
share_url	str	null	URL of the shared file
to_path	str, Path, None	None	Destination folder of the downloaded file, defaults to the current directory.
name	str, None	None	New name for the downloaded file, with or without extension.

The downloaded file will be saved to a local path.

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

Download File From Sharepoint

Downloads file from SharePoint.

Arguments

Argument	Type	Default value	Description
target_file	File, str	null	DriveItem or file path of the desired file.
site	Site	null	Site instance obtained from Get Sharepoint Site.
to_path	str, Path, None	None	Destination folder of the downloaded file, defaults to the current directory.
name	str, None	None	New name for the downloaded file, with or without extension.
drive	Drive, str, None	None	A Drive object or a Drive ID as a string.

The downloaded file will be saved to a local folder.

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

Download Folder From Onedrive

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

Arguments

Argument	Type	Default value	Description
target_folder	Folder, str	null	DriveItem or path of the desired folder.
to_path	str, Path, None	None	Destination folder where the download will be saved to, defaults to the current directory.
resource	str, None	None	Name of the resource if not using default.
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.

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

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

Find Onedrive File

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.

Arguments

Argument	Type	Default value	Description
search_string	str	null	String used to search for file in Onedrive. Values may be matched across several fields including filename, metadata, and file content.
target_folder	Folder, str, None	None	Folder where to search for files.
include_folders	bool, None	False	Boolean indicating if should return folders as well.
resource	str, None	None	Name of the resource if not using default.
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.

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.

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

Generate Oauth Authorization Url

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.

Arguments

Argument	Type	Default value	Description
client_id	str, None	None	Application client ID.
client_secret	str, None	None	Application client secret.
redirect_uri	str, None	None	Can be provided with client ID and client secret if not using the default.
scopes	list, None	None	A list of scopes in the form required by the API. Use the helper function Get scopes.

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

Get Drive Instance

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

Arguments

Argument	Type	Default value	Description
resource	str, None	None	Name of the resource if not using default.
drive_id	str, None	None	The Drive ID as a string.

param resource:	Name of the resource if not using default.
param drive_id:	The Drive ID as a string.
return:	The requested `Drive` object.

Get File Instance

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

Arguments

Argument	Type	Default value	Description
drive	Drive, str	null	A Drive object or Drive ID as a string. If not provided, will use the default drive.
file	File, str	null

param file_path:
param drive:	A `Drive` object or Drive ID as a string. If not provided, will use the default drive.
	A `File` object or path as a string.

Get Folder Instance

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

Arguments

Argument	Type	Default value	Description
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.
folder	Folder, str, None	None	A Folder object or folder path as a string.

param drive:	A `Drive` object or Drive ID as a string. If not provided, will use the default drive.
param folder:	A `Folder` object or folder path as a string.

Get Items From Sharepoint List

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

Arguments

Argument	Type	Default value	Description
list_name	str	null	Display name of the SharePoint list.
site	Site	null	Site instance obtained from Get Sharepoint Site.

param list_name:
	Display name of the SharePoint list.
param site:	Site instance obtained from Get Sharepoint Site.
return:	Table or list of dicts of the items.

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:

Get Scopes

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.

Arguments

Argument	Type	Default value	Description
scopes	str	null	Scopes requested. If left empty, all scopes will be returned.

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

param scopes:	Scopes requested. If left empty, all scopes will be returned.
return:	A list of Scopes which can be passed to authorization keywords.

Get Sharepoint Site

Returns a SharePoint site.

Arguments

Argument	Type	Default value	Description
args	str	null	The SharePoint site to retrieve, see documentation for different methods of defining the site.
resource	str, None		Name of the resource if not using default.

param args:	The SharePoint site to retrieve, see documentation for different methods of defining the site.
param resource:	Name of the resource if not using default.
return:	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.

List Files In Onedrive Folder

Returns a list of files from the specified OneDrive folder.

Arguments

Argument	Type	Default value	Description
target_folder	Folder, str, None	None	Path of the folder in Onedrive. If none is provided, will return files from the root of Onedrive.
include_folders	bool, None	False	Boolean indicating if should return folders as well.
resource	str, None	None	Name of the resource if not using default.
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.

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

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

List Files In Sharepoint Site Drive

List files in the SharePoint Site drive.

Arguments

Argument	Type	Default value	Description
site	Site	null	Site instance obtained from Get Sharepoint Site.
include_folders	bool, None	False	Boolean indicating if should return folders as well.
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.
target_folder	Folder, str, None	None	Path of the folder in the Sharepoint drive. If none is provided, will return files from the root of the 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.

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

List Sharepoint Site Drives

Get a list of Drives available in the SharePoint Site.

Arguments

Argument	Type	Default value	Description
site	Site	null	Site instance obtained from Get Sharepoint Site.

param site:	Site instance obtained from Get Sharepoint Site.
return:	List of Drives present in the SharePoint Site.

Refresh Oauth Token

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.

Arguments

Argument	Type	Default value	Description
refresh_token	str, None	None	The refresh token to use to refresh the session.

param refresh_token:
	The refresh token to use to refresh the session.
return:	A refresh token which should be stored securely for future sessions.

Search For Users

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

Arguments

Argument	Type	Default value	Description
search_string	str	null	Text to search for.
search_field	str	displayName	Where to search. Defaults to display name.
resource	str	users	Name of the resource if not using default.

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

param search_string:
	Text to search for.
param search_field:
	Where to search. Defaults to display name.
param resource:	Name of the resource if not using default.

Upload File To Onedrive

Uploads a file to the specified OneDrive folder.

Arguments

Argument	Type	Default value	Description
file_path	str	null	Path of the local file being uploaded.
target_folder	Folder, str, None	None	Path of the folder in Onedrive.
resource	str, None	None	Name of the resource if not using default.
drive	Drive, str, None	None	A Drive object or Drive ID as a string. If not provided, will use the default drive.

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.

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