Microsoft Excel integration

Back to list of integrations

Use the Microsoft Excel integration to let agents read and write workbooks, worksheets, rows, cells, and tables in OneDrive or SharePoint through Microsoft Graph.

Authentication	Actions	Workflow triggers
OAuth 2.0 App (User Delegated), OAuth 2.0 Client Credentials	33	4

​

Supported actions

Actions are Microsoft Excel operations that an agent runs as Action Tools during a conversation. You can also run them from an Integration node in a workflow.

Group	Actions
Workbooks	Create Workbook, Get Workbooks, Find Workbook, Delete Workbook
Worksheets	Create Worksheet, Add a Worksheet to a Workbook, Get Worksheets, Find Worksheet, Get Worksheet by ID, Rename Worksheet, Copy Worksheet, Clear Worksheet, Delete Worksheet
Rows and cells	Append Row to Worksheet, Append Multiple Rows, Get Worksheet Rows, Update Worksheet Rows, Get Worksheet Columns, Get Cells in Range, Clear Cells by Range, Clear Column by Index, Clear Row by ID, Delete Row
Tables	Create Table, Get Table Rows, Get Table Columns, Append Rows to a Table, Lookup Table Column, Find Row, Get Row by ID, Convert to Range, Delete Table
Advanced	Custom API Call

​

Workflow triggers

Triggers are Microsoft Excel events that start a workflow automatically. Select them as app triggers when you configure a workflow.

Trigger	Fires when

​

Prerequisites

• Workbooks in .xlsx format, stored in OneDrive or a SharePoint document library.

​

Set up the integration

1. Register an Entra ID app

   Register an app in Microsoft Entra ID, create a client secret, and copy the Application (client) ID and Directory (tenant) ID. Add Microsoft Graph permissions (for example Files.ReadWrite.All and Sites.ReadWrite.All, plus offline_access for delegated access) as Delegated or Application permissions, grant admin consent, and for delegated access add the Artemis Callback URL as a Web redirect URI.

2. Create the auth profile

   In Integrations, select Microsoft Excel > Connect. On Project Auth Profiles, select New Profile > Integration Profile > Microsoft Excel > Continue. Select an Auth Type, configure the fields, and select Create Profile. For delegated access, select Authorize.

   OAuth 2.0 App (User Delegated)

   Enter the Microsoft identity platform endpoints if Artemis doesn’t pre-fill them (https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize and .../token), the delegated Scopes, Client ID, and Client Secret.

   Usage Mode: Preconfigured shares one authorization across users; JIT and Preflight ask each user to authorize, during or before the session. See Auth profiles.

   OAuth 2.0 Client Credentials

   Keep Authorize Using as Client Secret and the pre-filled Token URL and Scopes. Enter Client ID and Client Secret.

3. Create the action tool

   In Tools, select New Tool > Action > Microsoft Excel > Continue. Select the Action and Auth Profile, set parameter defaults (leave a value empty for the agent to supply at runtime), and select Create Tool. Then assign the tool to an agent.

​

Action reference

Most actions take the same location parameters: storageSource (default OneDrive), siteId and documentId for SharePoint storage, workbookId, and worksheetId. Select them in order, because each list depends on the previous one.

​

Workbooks

Create Workbook

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
name	string	Workbook name.

Get Workbooks

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
limit	number	Maximum results.

Find Workbook

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
fileName	string	Workbook name.

Delete Workbook

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.

​

Worksheets

Create Worksheet

Adds a worksheet with optional default headers.

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
name	string	Worksheet name.
headers	array	Optional header row.

Add a Worksheet to a Workbook

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheet_name	string	Worksheet name.

Get Worksheets

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
returnAll	boolean	Returns all worksheets. Default: False.
limit	number	Maximum results.

Find Worksheet

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
sheetName	string	Worksheet name.
exactMatch	boolean	Requires an exact name match. Default: False.

Get Worksheet by ID

Returns worksheet metadata.

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.

Rename Worksheet

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
new_name	string	New name.

Copy Worksheet

Copies a worksheet to the same or another workbook.

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
folderId	enum	Folder that contains the workbook. Leave empty to search the drive (up to 1000 folders).
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
destinationWorkbookId	enum	Destination workbook.
newWorksheetName	string	Name of the copy.
copyMode	enum	Copy formulas (recalculated) or values only. Default: Values and formulas.

Clear Worksheet

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
range	string	Optional range to clear.

Delete Worksheet

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.

​

Rows and cells

Append Row to Worksheet

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
isFirstRowHeaders	boolean	The first row contains headers. Default: False.
values	object	Values to insert.

Append Multiple Rows

Appends rows, optionally only those that meet a filter.

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
values	object	Rows to insert.
filterColumn	enum	Filter column.
filterType	enum	Filter type.
filterValue	object	Filter value.

Get Worksheet Rows

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
range	string	Range, for example A2:B2.
headerRow	number	Header row number.
firstDataRow	number	First data row number.
useFilter	boolean	Enables column filters. Default: False.
filterList	object	Filters.

Update Worksheet Rows

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
row_number	number	Row to update.
isFirstRowHeaders	boolean	The first row contains headers. Default: False.
values	object	New values.

Get Worksheet Columns

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.

Get Cells in Range

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
range	string	Range, for example A1:C10.

Clear Cells by Range

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
range	string	Range to clear.
applyTo	enum	What to clear. Default: All (Contents and Formatting).

Clear Column by Index

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
column_index	number	Column index.
applyTo	enum	What to clear. Default: All (Contents and Formatting).

Clear Row by ID

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
row_id	number	Row ID.
applyTo	enum	What to clear. Default: All (Contents and Formatting).

Delete Row

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
row_id	number	Row number.

​

Tables

Create Table

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
selectRange	enum	How to pick the range. Default: Automatically.
range	string	Range for the table.
hasHeaders	boolean	The range has headers. Default: True.

Get Table Rows

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.
limit	number	Maximum results.

Get Table Columns

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.
limit	number	Maximum results.

Append Rows to a Table

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.
values	object	Rows to append.

Lookup Table Column

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.
lookup_column	string	Column to search.
lookup_value	string	Value to find.
return_all_matches	boolean	Returns every match. Default: False.

Find Row

Finds a row by column value, for example the row where ID is 123.

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.
lookup_column	enum	Column to search.
lookup_value	string	Value to find.

Get Row by ID

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.
row_id	number	Row ID.

Convert to Range

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table to convert.

Delete Table

Parameter	Type	Description
storageSource	enum	Where the workbook lives. Default: OneDrive.
siteId	enum	SharePoint site, for SharePoint storage.
documentId	enum	SharePoint document library.
workbookId	enum	Workbook.
worksheetId	enum	Worksheet.
tableId	enum	Table.

​

Advanced

Custom API Call

Parameter	Type	Description
url	object	Endpoint URL.
method	enum	HTTP method.
headers	object	Additional request headers. Artemis injects the authorization header.
queryParams	object	Query parameters.
body_type	enum	Body type. Default: None.
body	object	Request body.
response_is_binary	boolean	Turn on for binary responses. Default: False.
failsafe	boolean	Returns no error when the call fails.
timeout	number	Timeout, in seconds.
followRedirects	boolean	Follows HTTP redirects. Default: False.

​

Troubleshoot common issues

Issue	Resolution
AADSTS50011 redirect URI mismatch	Add the exact Callback URL as a Web redirect URI in the app registration.
AADSTS65001 consent required	Grant admin consent for the API permissions, and then authorize again.
403 Forbidden	Add the missing Microsoft Graph permission for the action, and grant consent.
Workbook or worksheet lists are empty	Check storageSource, and for SharePoint select siteId and documentId first.
Rows land in the wrong columns	Set isFirstRowHeaders and match values keys to the header names.

Related articles:

• Auth profiles
• Action Tools
• Microsoft SharePoint integration
• Excel API in Microsoft Graph