> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/import-agents-sharepoint/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

{% hint style="danger" %}
We highly recommend using [our SharePoint built-in connector](/reference-manual/built-in-connectors/sharepoint.md) instead of this import agent.
{% endhint %}

## 1. Setting up the main app registration in Entra ID

The Elimity Insights import agent for SharePoint authenticates as an Entra ID enterprise application. Create a new app registration in Entra ID by following these steps:

1. Register a new application ('App registrations' > 'New registration').
   * Name: e.g. `elimity-insights`
   * Leave other configurations untouched, simply click 'Register'
   * Note down the client and tenant identifiers
2. Assign Graph API permissions to the newly created app registration.
   * 'API permissions' > 'Add a permission'
   * 'Microsoft Graph' > 'Application permissions' > 'Sites.Read.All'
3. Grant admin consent for these permission assignments.
4. Generate a client secret for the app registration ('Certificates & secrets' > 'Client secrets' > 'New client secret') and securely note down the secret value.

## 2. Setting up the worker app registrations in Entra ID

Detailed scanning of SharePoint sites takes quite a bit of time. Customers must provide at least one 'worker' app registration, but we recommend multiple workers for large SharePoint tenants.

To set up 'worker' app registrations, follow a procedure like the one described in step 1 to create one or more new app registrations, but instead of the Graph permissions assign the following SharePoint permissions:

* If you don't want to import file permissions, then grant 'SharePoint' > 'Application permissions' > 'Sites.Read.All'.
* If you want to import file permissions, then grant 'SharePoint' > 'Application permissions' > 'Sites.FullControl.All'.

Additionally, instead of generating a client secret, generate and upload a certificate for each app registration:

1. Generating a certificate pair is typically customer-specific, the following example command uses OpenSSL: `openssl req -days 999 -keyout key.pem -newkey rsa -nodes -out cert.pem -subj '/CN=elimity-insights' -x509`.
2. Securely note down the private key.
3. Upload the certificate to the worker app registration in Entra ID and note down the certificate thumbprint that you see in Entra ID.

## 3. Creating a source in Elimity Insights

Firstly create a new SharePoint source in Elimity Insights, but do not enable automatic imports. Instead, generate API credentials for this source and note down the resulting identifier and token.

## 4. Configuring the agent

To configure your import agent, mount an HJSON configuration file at `/app/config/config.hjson` with the properties listed below. Refer to the following attachment for a starting point:

{% file src="/files/b8gerQFQ79leMg51tePA" %}

Edit the following properties in this file to configure the import agent to your needs:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>clientId</code></td><td><code>string</code></td><td>Unique identifier of the main app registration you set up in step 1</td></tr><tr><td><code>clientSecret</code></td><td><code>string</code></td><td>Client secret value for the main app registration you set up in step 1</td></tr><tr><td><code>cronPattern</code></td><td><code>string</code></td><td>Optional CRON pattern describing when the import agent should run (refer to <a href="https://crontab.guru">https://crontab.guru</a> for example patterns); omit if you just want to run the agent once</td></tr><tr><td><code>fileExclusionPattern</code></td><td><code>string</code></td><td>Optional <a href="https://en.wikipedia.org/wiki/Glob_(programming)">glob</a> pattern to exclude files based on their server-relative URLs; omit if you just want to import all files</td></tr><tr><td><code>includeRegularFiles</code></td><td><code>boolean</code></td><td>Indicates whether to also scan regular files (not only directories)</td></tr><tr><td><code>insightsSourceId</code></td><td><code>number</code></td><td>Source identifier you noted down in step 3</td></tr><tr><td><code>insightsSourceToken</code></td><td><code>string</code></td><td>Source token you noted down in step 3</td></tr><tr><td><code>insightsUrl</code></td><td><code>string</code></td><td>HTTP(S) API URL of your Elimity Insights instance, e.g. <code>"https://example.elimity.com/api"</code></td></tr><tr><td><code>listItemPageSize</code></td><td><code>number</code></td><td>Maximum number of SharePoint list items to retrieve in a single page; we recommend a value of <code>5000</code></td></tr><tr><td><code>roleAssignmentChunkSize</code></td><td><code>number</code></td><td>Maximum number of SharePoint list items to retrieve in a single page; we recommend a value of <code>100</code></td></tr><tr><td><code>skipFiles</code></td><td><code>boolean</code></td><td>Indicates whether to skip scanning regular files and directories for each site</td></tr><tr><td><code>skipPersonalSites</code></td><td><code>boolean</code></td><td>Indicates whether to skip scanning personal sites</td></tr><tr><td><code>skipRoleAssignments</code></td><td><code>boolean</code></td><td>Indicates whether you want to skip scanning role assignments for each file; make sure you granted the <code>Sites.FullControl.All</code> permission when enabling this option</td></tr><tr><td><code>targets</code></td><td><code>list[object]</code></td><td>Describes which SharePoint sites to import; use <code>[]</code> to target all sites in your tenant</td></tr><tr><td><code>targets[].hostname</code></td><td><code>string</code></td><td>Hostname of the SharePoint site you want to import, e.g. <code>example-tenant.sharepoint.com</code></td></tr><tr><td><code>targets[].path</code></td><td><code>string</code></td><td>Absolute path of the SharePoint site you want to import, e.g. <code>/sites/ExampleSite</code></td></tr><tr><td><code>tenantId</code></td><td><code>string</code></td><td>Unique identifier of your Entra ID tenant, which you noted down in step 1</td></tr><tr><td><code>workers</code></td><td><code>record[object]</code></td><td>Record mapping client identifiers for worker app registrations to credential objects</td></tr><tr><td><code>workers[].privateKey</code></td><td><code>string</code></td><td>Private key for the worker’s app registration you set up in step 2</td></tr><tr><td><code>workers[].thumbprint</code></td><td><code>string</code></td><td>Thumbprint for the worker’s app registration you set up in step 2</td></tr></tbody></table>

## 5. Deploying the agent

Having configured the agent and having created a source in Elimity Insights, you can now deploy the agent to regularly import data from your SharePoint tenant and upload it to Elimity Insights. Since we distribute the agent as a Docker image, our recommendation for deployment is to use a CaaS solution like Google Cloud Run or Azure Container Apps. If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to [our documentation about gateways and import agents](/technical-guides/gateways-and-import-agents.md) for additional details.

## 6. Following up on the import

The import agent outputs logs to indicate its progress, for a manual Windows Server deployment you can check these with `docker-compose logs`.


---

# 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://docs.elimity.com/import-agents-sharepoint/step-by-step-deployment-guide.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.