> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration.md).

# How to set up the Excel 365 integration

An Admin connects Excel 365 once at the account level. After that, anyone in the workspace can build metrics from the workbooks in your OneDrive or SharePoint.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the Excel 365 integration](#set-up-the-excel-365-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Excel 365 in a metric](#use-excel-365-in-a-metric)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Excel 365 integration

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* Admin role at the account level
* A Microsoft 365 account with the Excel workbooks you want to use stored in OneDrive or SharePoint
* For service account auth: permission to register an app in Microsoft Entra ID (Azure AD) and grant admin consent for Microsoft Graph permissions
  {% endhint %}

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Office 365 Excel**.

<figure><img src="/files/NwQpxY4swwf92APx6NVB" alt="Configure Excel page in the unconfigured state. The left pane shows Select integration type with Service account selected and marked Recommended, and Login with your Office 365 account (oAuth) below it. The right pane shows Office 365 Service Account with a How to setup Office 365 Excel service account info panel and empty Tenant ID, Client ID, and Client Secret fields above a Save Service Account button."><figcaption><p>Configure Excel, unconfigured</p></figcaption></figure>

The **Configure Excel** page opens with two options under **Select integration type**: **Service account** (selected by default and marked **Recommended**) and **Login with your Office 365 account (oAuth)**. Switching the method later disconnects the current one, so pick the one that fits before you save:

* [**Service account (recommended)**](#service-account-recommended) - Server-to-server access through a Microsoft Entra ID app, so the connection isn't tied to one person's login. Best when your team shares the Smaply account.
* [**OAuth**](#oauth) - Signs Smaply in as one person and reads the Excel files that account can already open. Simpler when only one person needs the data.

{% tabs %}
{% tab title="Service account (recommended)" %}
{% hint style="info" icon="tag" %}

#### Plan availability

Service account auth is available on the **Governance** plan. OAuth auth (the other tab) is available on all plans that include metrics integrations.
{% endhint %}

The service account is a Microsoft Entra ID app registration that connects to your files through Microsoft Graph. You register the app, grant it one Graph permission with admin consent, create a client secret, and enter three credentials in Smaply.

Keep the **Configure Excel** page open in another tab. You'll come back to it at the end to enter the credentials.

{% stepper %}
{% step %}
**Register an app in Microsoft Entra ID**

In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID > App registrations** and click **+ New registration**.

On the **Register an application** page, give the app a recognisable name (for example, `Smaply Office 365 connector`), choose **Accounts in this organizational directory only (Single tenant)**, leave the **Redirect URI** blank, and click **Register**.

<figure><img src="/files/MSc8dSMyyqb6Egk4hDjm" alt="Azure Register an application form with a Name field, Supported account types set to single tenant, and an empty Redirect URI section."><figcaption><p>Register an application</p></figcaption></figure>

For full background on app registrations, see [Microsoft's quickstart on registering an application](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app).
{% endstep %}

{% step %}
**Assign the Microsoft Graph permission**

On the registered app, open **API permissions** and click **+ Add a permission**. Choose **Microsoft Graph**, then **Application permissions**, tick **Files.Read.All**, and click **Add permissions**.

<figure><img src="/files/hGpvff8ECjhRo0kktT8P" alt="Azure Configured permissions table for Microsoft Graph showing Files.Read.All as an application permission that reads files in all site collections, with admin consent required."><figcaption><p>API permissions > Microsoft Graph > Files.Read.All</p></figcaption></figure>

Smaply only needs **Files.Read.All**. The screenshot above also lists **User.Read** (added automatically by Azure) and **User.Read.All**; you don't need to add **User.Read.All** for this integration.

Back on the **API permissions** page, click **Grant admin consent for \[your directory]** and confirm in the dialog.

<figure><img src="/files/R8jGsOom8O03nszmDMjH" alt="Azure Grant admin consent confirmation dialog asking whether to grant consent for the requested permissions for all accounts in the directory, with Yes and No buttons."><figcaption><p>Grant admin consent confirmation</p></figcaption></figure>

{% hint style="warning" %}

#### **Important: Without admin consent the connection authenticates but reads no files**

The grant button only appears for a directory admin. If the **Admin consent required** column says **Yes** but consent isn't granted, Smaply connects and then returns an empty workbook list. Grant consent before relying on the integration.
{% endhint %}
{% endstep %}

{% step %}
**Create a client secret**

In the same app, open **Certificates & secrets**, and on the **Client secrets** tab click **+ New client secret**. Give it a description and an expiry, then click **Add**.

<figure><img src="/files/cBKWNxZW57sB7dhshijo" alt="Azure Certificates and secrets page with the Add a client secret panel open, showing a Description field and a 365 days (12 months) expiry."><figcaption><p>Certificates &#x26; secrets > + New client secret</p></figcaption></figure>

Copy the secret **Value** immediately.

<figure><img src="/files/yoIStmdIZX5CMOCGBcwd" alt="Azure client secrets table after creation, showing the new secret with its Value partly hidden and a copy-to-clipboard control next to it."><figcaption><p>Copy the secret Value before leaving the page</p></figcaption></figure>

{% hint style="danger" %}

#### **Warning: The client secret value cannot be re-shown**

Azure displays the secret value only at creation time. Once you navigate away, only the secret ID stays visible. If you lose the value, generate a new secret.
{% endhint %}
{% endstep %}

{% step %}
**Enter the credentials in Smaply**

Open the registered app's **Overview** page and copy the **Application (client) ID** and the **Directory (tenant) ID**.

Return to the **Configure Excel** page in Smaply and paste the values into the three fields:

* **Tenant ID** - The **Directory (tenant) ID** from the app overview.
* **Client ID** - The **Application (client) ID** from the same page.
* **Client Secret** - The secret **Value** you copied when you created the client secret.

<figure><img src="/files/eJdSuh5Ut1Co67lrKWDt" alt="Configure Excel page with the Service account integration type selected. The right pane shows Office 365 Service Account with empty Tenant ID, Client ID, and Client Secret fields above a Save Service Account button, and a How to setup Office 365 Excel service account info panel above the form."><figcaption><p>Configure Excel, Service account selected</p></figcaption></figure>

Click **Save Service Account**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="OAuth" %}
OAuth signs Smaply in as you. The connection reads the Excel files your Microsoft account can already open in OneDrive or SharePoint, and tokens are tied to your individual access.

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* A Microsoft 365 account with access to at least one Excel file in OneDrive or SharePoint
* If your organisation requires admin approval for third-party app consent, a Microsoft admin available to approve the grant
  {% endhint %}

{% stepper %}
{% step %}
**Choose Login with your Office 365 account (oAuth)**

On the **Configure Excel** page, select **Login with your Office 365 account (oAuth)**. The right pane changes to **Connect Office 365 Excel** with a three-step info panel and the **Connect Office 365 Excel** button.

<figure><img src="/files/qqz3N5gOT7uCWUQPlu4k" alt="Configure Excel page with Login with your Office 365 account (oAuth) selected. The right pane shows Connect Office 365 Excel with a How to setup Office 365 Excel info panel listing three numbered steps and a Connect Office 365 Excel button below."><figcaption><p>Configure Excel, OAuth selected</p></figcaption></figure>

Click **Connect Office 365 Excel**. Smaply redirects you to Microsoft.
{% endstep %}

{% step %}
**Sign in and grant permissions**

Sign in with the Microsoft account that can open the Excel files you want to use in Smaply. On Microsoft's consent screen, review the permissions Smaply requests:

* **Read all files that you have access to**
* **Sign you in and read your profile**
* Optionally, **Consent on behalf of your organisation** (only available to admins)

<figure><img src="/files/kqXnmKHbzo1II3fbvgV8" alt="Microsoft Permissions requested consent screen for the Smaply Office 365 app from More than Metrics GmbH, requesting access to read all files you have access to and to sign you in and read your profile, with Cancel and Accept buttons."><figcaption><p>Microsoft permissions screen for Smaply</p></figcaption></figure>

Click **Accept**. If your organisation requires admin approval for third-party apps, the consent screen tells you to ask an admin instead, and the connection completes once an admin approves it.
{% endstep %}

{% step %}
**Authorise the connection**

Microsoft sends you back to Smaply and the **Configure Excel** page shows the connected state. Smaply refreshes OAuth tokens automatically, so you don't need to sign in again unless the token is revoked.

{% hint style="warning" %}
If you revoke Smaply's access in your Microsoft account or lose access to a file, the connection drops and metrics that depend on it stop pulling data. For team-wide use, switch to a Service account so the connection isn't tied to one person's login.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

#### Verify the setup

Open the **Configure Excel** page and confirm it shows the connected state. Then create a test metric with **Source** set to **Excel (Office 365)**: if the **Spreadsheet** picker lists your workbooks, the connection is working.

If the picker stays empty or you see a connection error, see Troubleshooting below.

***

#### Use Excel 365 in a metric

With the connection in place, anyone in your account can add Excel 365 data to a metric card on any journey map. See [How to use Excel 365 in a metric](/integrations/metrics-tools/excel-365/how-to-use-excel-365-in-a-metric.md) for the field mapping and how to pick a workbook and sheet.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Excel** page means Smaply cannot reach Office 365 with the stored credentials.

* For service account: re-check the **Tenant ID**, **Client ID**, and **Client Secret** values for typos or trailing whitespace, and confirm the client secret hasn't expired in Microsoft Entra ID.
* For OAuth: click **Connect Office 365 Excel** again from the Configure page. The token may have expired or been revoked.

</details>

<details>

<summary><strong>The Spreadsheet picker is empty or shows no workbooks</strong> - Permissions issue</summary>

The connection succeeds but no workbooks appear when you build a metric.

* For service account: confirm you granted admin consent for the **Files.Read.All** Microsoft Graph permission. Without the grant, Smaply authenticates but can't read any files.
* For OAuth: confirm the signed-in Microsoft account has access to at least one Excel file in OneDrive or SharePoint.

</details>

<details>

<summary><strong>Microsoft asked for admin approval during OAuth</strong> - Consent issue</summary>

The Microsoft consent screen tells you the app needs admin approval before you can complete the connection.

* Some organisations require an admin to pre-approve third-party app grants. Ask your Microsoft admin to approve Smaply, then return to the **Configure Excel** page and click **Connect Office 365 Excel** again.
* If admin approval isn't an option for your org, use the Service account method instead.

</details>

<details>

<summary><strong>Metrics that worked previously have stopped pulling</strong> - Token revoked</summary>

Metrics that worked before now show errors and stop pulling data.

* For OAuth, the usual cause is the grant being revoked, either by signing out of Microsoft everywhere or by an admin removing the Smaply app. Open the **Configure Excel** page and click **Connect Office 365 Excel** to re-establish the grant.
* If the same person keeps losing the connection, switch to a Service account so it isn't tied to one Microsoft session.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

The connection works but the metric returns nothing or values that don't look right.

* Confirm the workbook and sheet the metric points at still exist with the same names. Renaming or moving a file in OneDrive or SharePoint breaks the metric until it's re-pointed.
* Confirm the data values you mapped still sit in the same columns in the source workbook.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Embed cards</strong></td><td>Embed live external content on a journey map instead of pulling values as a metric.</td><td><a href="/pages/OZrRWKElbHcwoxQO8mln">/pages/OZrRWKElbHcwoxQO8mln</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/integrations/metrics-tools/excel-365/how-to-set-up-the-excel-365-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.