Procedures

Automation procedures in the Microsoft SharePoint book.

The following documentation is for Microsoft SharePoint v2.1.0 (BDK).

Make sure to add both the Microsoft SharePoint and the Microsoft Office 365 Books to your agent before using these automation procedures.

to add a column to a slist

Adds a column to a given SharePoint list using the Microsoft Graph API.

For now, it will remain the same as the BCI version. In the future, we should try to support more col types, opening up the configuration for them.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The list to which the column will be added.	sharepoint list	Yes	(no default)
name	The name of the column to be added.	text	Yes	(no default)
description	The description of the column to be added.	text	No	(no default)

Examples

add a column to the list
  the name is "NewColumn"
  the description is "The newest column"

to add an (item) to a slist

Adds an item to a given SharePoint list using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The list to which the item will be added.	sharepoint list	Yes	(no default)
item	The item to be added to the list. The fields in the Dict should match the column names in the list.	json	Yes	(no default)

Output Concepts

Concept	Description	Type
item	None.	sharepoint list item

Examples

create a json
use the above as the item body
set the item body's "Title" to "First Item"
set the item body's "column1" to "col 1 value"
add the item body to the list

to copy an item to a folder

Copies an item (folder or file) to a given folder using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
item	The item (folder or file) that will be copied.	sharepoint file reference or sharepoint folder reference	Yes	(no default)
folder	The destination folder where the file will be copied.	sharepoint folder reference	Yes	(no default)
item name	The new name for the copy. If this isn't provided, the same name will be used as the original.	text	No	(no default)
conflict behavior	The behavior when a conflict occurs. Possible values are 'fail', 'replace', 'rename'.	text	No	rename

Examples

Copy an item to a folder

get a folder at "/My Site/My Documents/My Folder"
use the above as the source folder
get a folder at "/My Site/My Documents/My Other Folder"
use the above as the destination folder
copy the source folder to the destination folder

to create a (folder) in a document library

Creates a new folder at the root of the given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
document library	The document library where the folder will be created.	sharepoint document library	Yes	(no default)
folder name	The name of the folder to be created.	text	Yes	(no default)
conflict behavior	The behavior when a conflict occurs. Possible values are 'fail', 'replace', 'rename'.	text	No	rename

Output Concepts

Concept	Description	Type
folder	A sharepoint document library folder representing the created folder.	sharepoint folder reference

Examples

Create a folder named "My New Folder" in the document library "My Documents" the folder name is "My New Folder"

get site from sharepoint whose name is "Human Resources"
get some site's document libraries
create a folder in the first library

to create a (folder) in another folder

Creates a new folder at the given SharePoint document library item using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
another folder	The folder under which the new folder will be created.	sharepoint folder reference	Yes	(no default)
folder name	The name of the folder to be created.	text	Yes	(no default)
conflict behavior	The behavior when a conflict occurs. Possible values are 'fail', 'replace', 'rename'.	text	No	rename

Output Concepts

Concept	Description	Type
folder	A sharepoint document library item representing the created folder.	sharepoint folder reference

Examples

Create a folder named "My New Folder" under the folder "My Folder"

get a folder at "/My Site/My Documents/My Folder"
use the above as the other folder
create a folder in the other folder
  the folder name is "My New Folder"

to create a list in a sharepoint site

Creates a new list in a given SharePoint site using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
site	The site where the list will be created.	sharepoint site	Yes	(no default)
list name	The name of the list to be created.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	A SharepointList object representing the created list.	sharepoint list

Examples

create a list in the site
the list name is "My List"

to delete a column from a list

Deletes a column from a given SharePoint list using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
column	The column to be deleted.	sharepoint list column	Yes	(no default)

Examples

delete the column from the list

to delete a slist

Deletes a list in a given SharePoint site using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The list to be deleted.	sharepoint list	Yes	(no default)

Examples

delete the list

to delete an item

Deletes an item (folder or file) within a given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
item	The item (folder or file) to be deleted.	sharepoint file reference or sharepoint folder reference	Yes	(no default)

Examples

Delete an item

get a folder at "/My Site/My Documents/My Folder"
get the folder's items
delete the first item

to delete an item from list

Deletes one or many items in a given SharePoint list using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
item	The item or items to be deleted.	list of sharepoint list item or sharepoint list item	Yes	(no default)

Examples

delete the created item in list

get the list as the slist
get the slist's items whose "Title" is "First Item"
use the above as the items
delete the items in list

to download a file

Downloads a file from a given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
file	The SharePoint file that will be downloaded.	sharepoint file reference	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	The downloaded file	file

Examples

Download a file

get a folder at "/My Site/My Documents/My Folder"
get the folder's items
download the first item

to edit an item

Edits an item in a given SharePoint list using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
item	The item to be edited.	sharepoint list item	Yes	(no default)

Examples

The created item is a JSON or a SharepointListItem concept

set the created item's "field.Title" to "Updated Title"
edit the created item

to get a (folder's items)

FILTER - CAPABLE

Retrieves all child items from the specified document library folder using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
folder	The document library folder from which to retrieve items.	sharepoint folder reference	Yes	(no default)

Output Concepts

Concept	Description	Type
folder's items	A list of items within the specified document library item.	sharepoint file reference or sharepoint folder reference

Examples

Retrieve all items from the folder "My Folder"

get a folder at "/My Site/My Documents/My Folder"
get the folder's items

to get a (folder) at a path

Retrieves the root folder of a given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
path	The path to the folder to retrieve with the following format: ////...	text	Yes	(no default)

Output Concepts

Concept	Description	Type
folder	A sharepoint document library item representing the folder at the specified path.	sharepoint folder reference

Examples

Retrieve the root folder of the document library "My Documents" in the site "My Site"

get a folder at "/My Site/My Documents"

Retrieve the folder "My Folder" within the document library "My Documents" in the site "My Site"

get a folder at "/My Site/My Documents/My Folder"

to get a (root folder) from a document library

Retrieves the root folder of a given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
document library	The document library from which to retrieve the root folder.	sharepoint document library	Yes	(no default)

Output Concepts

Concept	Description	Type
root folder	The root folder of the specified document library.	sharepoint folder reference

Examples

Retrieve the root folder of the document library "My Documents"

get site from sharepoint whose name is "Human Resources"
get some site's document libraries
use the above as the testing libraries
get a root folder from the first testing library

to get some (items) from a document library

FILTER - CAPABLE

Retrieves all items within a given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
document library	The document library from which to retrieve items.	sharepoint document library	Yes	(no default)

Output Concepts

Concept	Description	Type
items	A list of items within the specified document library.	sharepoint file reference or sharepoint folder reference

Examples

get site from sharepoint whose name is "Human Resources"
get some site's document libraries

to get some (site's document libraries)

Retrieves all document libraries within a given SharePoint site using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
site	A SharePointSite object representing the site from which to retrieve document libraries.	sharepoint site	Yes	(no default)

Output Concepts

Concept	Description	Type
site's document libraries	A list of document libraries within the specified site.	sharepoint document library

Examples

get site from sharepoint whose name is "Human Resources"
get some site's document libraries

to get some (sites) from sharepoint

FILTER - CAPABLE

Retrieves SharePoint sites accessible via the Microsoft Graph API.

Output Concepts

Concept	Description	Type
sites	A list of sharepoint sites.	sharepoint site

Examples

Retrieve accessible sites from SharePoint

get sites from sharepoint
process each site as follows
  say site's name

Retrieve a single site by name

get sites from sharepoint whose name is "Human Resources"

to get some (slist's items)

FILTER - CAPABLE

Retrieves all items within a given SharePoint list using the Microsoft Graph API.

When using it, it is very important to mark the item you are working with as a "slist" (Sharepoint list) so that the Brain matches this procedure.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The list from which to retrieve items.	sharepoint list	Yes	(no default)
include empty columns	Whether to include empty columns in the table.	boolean	No	False
limit	The maximum number of items to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
slist's items	A list of items within the specified list.	sharepoint list item

Examples

Get the items in a list

get the list as the slist
get the slist's items

Get the items in a list filtered by a column

get the list as the slist
get the slist's items whose "Title" is "First Item"

Get the items in a list filtered by a column and include empty columns

get the list as the slist
get the slist's items whose "Title" is "First Item"
    the include empty columns is "True"

to move an item to a folder

Moves an item (folder or file) to a given folder using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
item	An item (folder or file) that will be moved.	sharepoint file reference or sharepoint folder reference	Yes	(no default)
folder	The destination folder where the item will be moved.	sharepoint folder reference	Yes	(no default)
file name	The new name for the move. If this isn't provided, the same name will be used as the original.	text	No	(no default)
conflict behavior	The behavior when a conflict occurs. Possible values are 'fail', 'replace', 'rename'.	text	No	rename

Examples

Move an item to a folder

get a folder at "/My Site/My Documents/My Folder"
use the above as the source folder
get a folder at "/My Site/My Documents/My Other Folder"
use the above as the destination folder
move the source folder to the destination folder

to rename a (slist)

Renames a list in a given SharePoint site using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The list to be renamed.	sharepoint list	Yes	(no default)
name	The new name for the list.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
slist	the renamed slist	sharepoint list

Examples

rename the list
the name is "My Renamed List"

to rename a column in a list

Edits a column in a given SharePoint list using the Microsoft Graph API.

IMPORTANT: This rename does not affect the internal name of the column, only the display name.

Input Concepts

Concept	Description	Type	Required	Default Value
column	The name of the column to be edited.	sharepoint list column	Yes	(no default)
new column name	The new name for the column.	text	Yes	(no default)
description	The new description for the column.	text	No

Output Concepts

Concept	Description	Type
answer	None.	sharepoint list column

Examples

rename the column in the list
the new column name is "New Column Name"
the description is "The new column description"

to rename an item to a name

Renames a folder or a file using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
item	A SharePoint file that will be renamed.	sharepoint file reference or sharepoint folder reference	Yes	(no default)
name	The new name for the file.	text	Yes	(no default)
conflict behavior	The behavior when a conflict occurs. Possible values are 'fail', 'replace', 'rename'.	text	No	rename

Examples

Rename a file

get a folder at "/My Site/My Documents/My Folder"
get the folder's items
rename the first item to "My New File.txt"

to retrieve a (document library) at a url

Retrieves a SharePoint document library by its web URL using the Microsoft Graph API.

URL Structure: https://{tenant}.sharepoint.com/sites/{sitename}/{libraryname} Example: https://contoso.sharepoint.com/sites/bdk-testing/Shared%20Documents/Forms/AllItems.aspx Note: The library name is extracted from the URL path. Extra path segments like "Forms/AllItems.aspx" are ignored.

Input Concepts

Concept	Description	Type	Required	Default Value
url	The web URL of the document library to retrieve.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
document library	A SharePoint document library object.	sharepoint document library

Examples

Retrieve a document library by its URL

retrieve a document library by url "https://contoso.sharepoint.com/sites/HR/Documents"

Get a document library by URL and list its contents

retrieve a document library by url "https://contoso.sharepoint.com/sites/Finance/Shared Documents"
use the above as the library
get some items from the library

to retrieve a (file) at a url

Retrieves a SharePoint file by its web URL using the Microsoft Graph API.

URL Structure: SharePoint sharing link format with a file type indicator: https://{tenant}.sharepoint.com/:{type}:/s/{sitename}/{encoded-file-id}?e={share-token} File type indicators: ❌ (Excel), :w: (Word), :p: (PowerPoint), ⭕ (OneNote), :u: (other) Example: https://contoso.sharepoint.com/❌/s/bdk-testing/IQBeb0d3aEHrQ6FjalfpQ0YMAaGJLzwchRkDm49QQonv9Zs?e=kMch0g To get this URL: Right-click on the file in SharePoint and select "Copy link".

Input Concepts

Concept	Description	Type	Required	Default Value
url	The web URL (sharing link) of the file to retrieve.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
file	A SharePoint file reference object.	sharepoint file reference

Examples

Retrieve a file by its URL

retrieve a file by url "https://contoso.sharepoint.com/:x:/s/HR/AbC123..."

Get a file by URL and download it

retrieve a file by url "https://contoso.sharepoint.com/:w:/s/Finance/XyZ789..."
use the above as the file
download the file

to retrieve a (folder) at a url

Retrieves a SharePoint folder by its web URL using the Microsoft Graph API.

URL Structure: SharePoint sharing link format with :f: indicating a folder: https://{tenant}.sharepoint.com/:f:/s/{sitename}/{encoded-folder-id}?e={share-token} Example: https://contoso.sharepoint.com/:f:/s/bdk-testing/IgAu9BS6my2MRKogPH9TanUJAdITnMhz9MC63mh2yYcQofw?e=Qg73q2 To get this URL: Right-click on the folder in SharePoint and select "Copy link".

Input Concepts

Concept	Description	Type	Required	Default Value
url	The web URL (sharing link) of the folder to retrieve.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
folder	A SharePoint folder reference object.	sharepoint folder reference

Examples

Retrieve a folder by its URL

retrieve a folder by url "https://contoso.sharepoint.com/:f:/s/HR/AbC123..."

Get a folder by URL and list its contents

retrieve a folder by url "https://contoso.sharepoint.com/:f:/s/Finance/XyZ789..."
use the above as the folder
get the folder's items

to retrieve a (site) at a url

Retrieves a SharePoint site by its web URL using the Microsoft Graph API.

URL Structure: https://{tenant}.sharepoint.com/sites/{sitename} Example: https://contoso.sharepoint.com/sites/bdk-testing

Input Concepts

Concept	Description	Type	Required	Default Value
url	The web URL of the SharePoint site to retrieve.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
site	A SharePoint site object.	sharepoint site

Examples

Retrieve a site by its URL

retrieve a site at "https://contoso.sharepoint.com/sites/HR"

Get a site by URL and then retrieve its lists

retrieve a site at "https://contoso.sharepoint.com/sites/Finance"
use the above as the site
retrieve the site's lists

to retrieve a (slist) at a url

Retrieves a SharePoint list by its web URL using the Microsoft Graph API.

URL Structure: https://{tenant}.sharepoint.com/sites/{sitename}/Lists/{listname}/AllItems.aspx Example: https://contoso.sharepoint.com/sites/bdk-testing/Lists/BDK%20Test%20List%201/AllItems.aspx Note: The list name is extracted from the path segment after "Lists/". The "/AllItems.aspx" suffix is optional and ignored if present.

Input Concepts

Concept	Description	Type	Required	Default Value
url	The web URL of the SharePoint list to retrieve.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
slist	A SharePoint list object.	sharepoint list

Examples

Retrieve a list by its URL

retrieve a slist by url "https://contoso.sharepoint.com/sites/HR/Lists/Employees"

Get a list by URL and retrieve its items

retrieve a slist by url "https://contoso.sharepoint.com/sites/Projects/Lists/Tasks"
use the above as the slist
get the slist's items

to retrieve a slist as a (table)

Retrieve a sharepoint list as a table.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The reference to the sharepoint list.	sharepoint list	Yes	(no default)
include empty columns	Whether to include empty columns in the table.	boolean	No	False

Output Concepts

Concept	Description	Type
table	The list as a table.	table

Examples

retrieve the list as a table

to retrieve some (column definitions) from a slist

FILTER - CAPABLE

Retrieves the column definitions of a given SharePoint list using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
slist	The list from which the schema will be retrieved.	sharepoint list	Yes	(no default)

Output Concepts

Concept	Description	Type
column definitions	A list of column definitions in the specified list.	sharepoint list column

Examples

retrieve column definitions from the list

retrieve column definitions from the list whose name is "Title"

to retrieve some (site's lists)

FILTER - CAPABLE

Retrieves all lists within a given SharePoint site using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
site	A SharePointSite object representing the site from which to retrieve document libraries.	sharepoint site	Yes	(no default)
limit	The maximum number of lists to retrieve.	number	No	(no default)

Output Concepts

Concept	Description	Type
site's lists	A list of SharePoint lists within the specified site.	sharepoint list

Examples

get some sites from sharepoint whose name is "Human Resources"
use the above as the site
retrieve the site's lists

get some sites from sharepoint whose name is "Human Resources"
use the above as the site
retrieve the site's lists whose name is "My List"

to retrieve some (site's subsites)

FILTER - CAPABLE

Retrieves all subsites within a given SharePoint site using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
site	A SharePointSite object representing the site from which to retrieve subsites.	sharepoint site	Yes	(no default)

Output Concepts

Concept	Description	Type
site's subsites	A list of SharePoint subsites within the specified site.	sharepoint site

Examples

Retrieve subsites from a SharePoint site.

use the above as the site
retrieve some site's subsites

to upload a file to a folder and get the file reference

Uploads a file to a given SharePoint document library using the Microsoft Graph API.

Input Concepts

Concept	Description	Type	Required	Default Value
folder	The document library folder where the file will be uploaded.	sharepoint folder reference	Yes	(no default)
file	The content of the file to be uploaded as bytes.	file	Yes	(no default)
file name	The name of the file to be uploaded.	text	Yes	(no default)
conflict behavior	The behavior when a conflict occurs. Possible values are 'fail', 'replace', 'rename'.	text	No	rename

Output Concepts

Concept	Description	Type
file reference	An item representing the uploaded file.	sharepoint file reference

Examples

Upload a file named "My File.txt" to the folder "My Folder" the file name is "My File.txt"

get a folder at "/My Site/My Documents/My Folder"
use the above as the folder
the new file                                                       # This will ask a question, you need to upload a file
upload the new file to the folder