> For the complete documentation index, see [llms.txt](https://documentation.ardoq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ardoq.com/integrations/out-of-the-box-integrations/sharepoint.md).
# SharePoint
Learn how to configure a SharePoint site and its Excel documents so that Ardoq can import them.
{% hint style="info" %}
The Sharepoint integration requires that an Azure administrator configures several parameters in your Microsoft Azure instance before the integration can connect. The examples here will use the Microsoft Graph Explorer for the configuration.
{% endhint %}
## Overview
The Sharepoint integration is designed to automate the import of Excel files from a Microsoft Sharepoint site. This way you can write data to Excel files from any other service and have Ardoq import the file on a daily or weekly schedule.
For users who want to move Excel files over to SharePoint schedules, we've also added a configuration copying functionality to simplify the transition.
## Integration Pre-requisites
{% stepper %}
{% step %}
### Create a Sharepoint site for your Excel files
You will need to create a dedicated SharePoint site for storing the Excel files you want to import and upload the Excel you want to schedule.
{% endstep %}
{% step %}
### Create an Azure AD application
Create the application in the [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and save the application ID.
{% endstep %}
{% step %}
### Create a client secret for the application
1. Select the application
2. Go to **Certificates & secrets**
3. Select **Client secrets** tab
4. Create a new client secret and save it
{% endstep %}
{% endstepper %}
## Option 1 — Set Up Full Sites Permissions
Now we'll need to configure permissions for the Azure AD app we created in pre-requisites step 2. This will give the Azure app full permissions to access any Sharepoint site in your tenant. If you prefer a more limited security approach, look at Option 2.
1. Go to your app and to **Manage** > **API Permissions**.
2. Click **Add a permission**
3. Select **Microsoft Graph** under **Microsoft APIs**
4. Select **Application permissions**
5. Search for "sites" in the search bar
6. Enable **Sites.FullControl.All** and **Sites.Selected**
7. Click **Add permissions**
You'll be taken back to the Configured permissions section, where you should click **Grant admin consent for \[your tenant]**.
Your permissions should now look like the following:
You can now proceed to creating a SharePoint connection in Ardoq.
## Option 2 — Set Up Limited Sites Permissions
This approach gives your Azure app access only to the Sharepoint site with your Excel files and no others.
### Step 1 — Grant Sites.Selected permission to Azure app
You'll need to grant your Azure app the **Sites.Selected** permission:
### Step 2 — Get Sharepoint Site ID
1. Go to [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)
2. Log in to your Microsoft account in Graph Explorer
We'll need to make a request in the Graph Explorer to get the Site ID for the Sharepoint site we created earlier.
In the Graph Explorer, set the request type to **GET**.
The request has the form:
```
https://graph.microsoft.com/v1.0/sites/{hostname}.sharepoint.com:/sites/{site_path}?$select=id
```
* `{hostname}` is the name of your Sharepoint domain
* `{site_path}` is the name of your Sharepoint site as it appears in the URL
For example:
```
https://graph.microsoft.com/v1.0/sites/ardoq.sharepoint.com:/sites/TestUploadSpace?$select=id
```
Once executed our example query returns the following:
```
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites(id)/$entity",
"id": "ardoq.sharepoint.com,7d5125e9-9f68-4e58-9c50-039bb6c097e6,a6cadcae-49aa-465c-8bd9-646e249cb576"
}
```
The **id** in this case is the Site ID and we want to save this value to use later.
### Step 3 — Set Permissions for Sharepoint Site
We'll do this step by making an API call to set app permissions using an API client (like Postman, Insomnia, Bruno, etc.).
#### Configure OAuth 2.0
Create a new request in your API client and add an OAuth 2.0 authorization.
1. Go to the **Authorization** tab
2. Set the authorization type to OAuth2.0
3. Set the following fields:
1. Set **Grant Type** to **Client Credentials**
2. Set **Access Token URL** to the endpoint: `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token`
1. Where `{tenant_id}` is your MS365 tenant ID
3. Set **Client ID** to your Application (client) ID for the Azure application you created
4. Set **Client Secret** to the value of the secret your created for your application
5. Set **Scope** to `offline_access https://graph.microsoft.com/.default`
#### Configure Request
Set the request type to POST and use the following endpoint structure:
```
https://graph.microsoft.com/v1.0/sites/{Site ID}/permissions
```
Site ID is the ID we retrieved in the previous step.
Set the JSON body of the request to follow this form:
```
{
"roles": [
"write"
],
"grantedToIdentities": [
{
"application": {
"id": "{client_id}",
"displayName": "{app_name}"
}
}
]
}
```
**Client ID** is the Application (client) ID of your Azure app. App name is the display name to give to the app.
The body of the request should look like this:
When this request is successfully completed it will return a 201 Created response.
## Setting Up the Connection
The Sharepoint integration happens at the Excel file level. That is, every individual connection will only reference a single Excel file in your Sharepoint site. You will need to set up a new connection for every new Excel file you wish to import, but the Tenant ID, Application ID, and client secret will remain the same.
### Connection Parameters
You'll need the following parameters to configure the Sharepoint integration within Ardoq:
1. **Tenant ID**
1. Which you can find with [these steps](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant)
2. **File URL**
1. Which can be retrieved by opening your file from your Sharepoint site and copying the URL
2. Ardoq expects the following formatting for the URL:
```
https://ardoq.sharepoint.com/:x:/r/sites/TestUploadSpace/_layouts/15/Doc.aspx?sourcedoc=%7BCAA10748-A989-487B-8691-F733B73E0D5D%7D&file=TPM%20-%20Technology%20Portfolio%20Management%20Excel%20Template(3).xlsx
```
3. **Application ID**
1. Which can be retrieved from the application you created in pre-requisities step 2
4. **Client secret**
1. Which you should have saved in the pre-requisites step 3
### Ardoq Integration
In the Ardoq main menu go to Home > Import and Integrations, click View all integrations and select Sharepoint.
Go to the Connections tab and click Create new connection.
Give your connection a descriptive name and fill in the Sharepoint file URL, tenant ID, Application ID, and the client secret.
### Importing Data
When you open your connection, the worksheets from your Excel file will be loaded in as individual tables (including any hidden worksheets you may have in the file):
Select the relevant tables and any columns you wish to import. From here you can perform the mapping and import process as usual, including setting a schedule for the import.
### Copying Existing Excel Configurations
If you already have a prepared configuration for a specific Excel file, you can copy that configuration over to SharePoint.
Go to the Configurations tab in the Excel importer and click the ⋮ button to open the context menu.
Click **Copy to...** then provide name for the configuration copy and the destination — in this case SharePoint.
Once the configuration is copied, you can use it as the basis for configuring a SharePoint integration.
## Troubleshooting
### Client Secret Expiration
Keep in mind that the client secrets you generate have a default expiration period of 180 days. You'll need to create a new client secret and update your connection once the secret expires.
### SharePoint URLs
Microsoft SharePoint has multiple ways to share a document through SharePoint, but not all of them are compatible with Ardoq's integration.
For instance, the URL generated by clicking a document in SharePoint and selecting Copy link will not work with the Ardoq integration.
That is, links to Excel files that use formats like the following will not work:
```
https://ardoq.sharepoint.com/:x:/s/Site3/EURYKKPV-XxCnyXKGZz3IokBi8s-teaFh64P31QTjV4_SQ?e=YUMbCe
```
We recommend opening your Excel file in your browser and copying the URL from the address bar. The file format should look like the following:
```
https://ardoq.sharepoint.com/:x:/r/sites/Site3/_layouts/15/Doc.aspx?sourcedoc={A3285844-F9D5-427C-9F25-CA199CF72289}&file=AR - Application Rationalization Excel Import Template(1).xlsx&action=default
```
