> This is part 1 of 5 of the full documentation (pages 1–100 of 479).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.elimity.com/llms-full.txt/1
> Page index: https://docs.elimity.com/llms.txt

# 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
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.elimity.com/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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

---

# General information

Welcome to the official documentation site for Elimity Insights! We've collected some useful links below to help you get started quickly.

{% content-ref url="/spaces/IgcpDKoiMdsaJhGETR0z" %}
[Built-in connectors](https://docs.elimity.com/built-in-connectors/)
{% endcontent-ref %}

{% content-ref url="/spaces/EDnPjX1DSBebgxMCuWjh/pages/7f1NnCgOe7MC61fyXO86" %}
[Installation](/reference-manual)
{% endcontent-ref %}

{% content-ref url="/pages/LZZjoJjLr8sdGaILn3rQ" %}
[Release notes](/release-notes/v3.47.1)
{% endcontent-ref %}

{% content-ref url="/spaces/EDnPjX1DSBebgxMCuWjh/pages/qvQ5KsujNuCgNNfkUNFo" %}
[Server configuration](/reference-manual/server-configuration)
{% endcontent-ref %}


# Versioning policy

We aim to publish a feature release of Elimity Insights four times a year, typically on the second Thursday of the last month in each quarter. The two most recent feature releases also receive bug fixes and security updates in patches which do not follow a fixed schedule.

## Version numbering

Each feature release gets a semantic version number with a new 'minor' component (e.g. the next feature release after `v3.44.0` is `v3.45.0`). For patches we simply increment the 'patch' component (e.g. `v3.44.1` and `v3.44.2` would be the first two patch releases for `v3.44.0`).

### Upgrading

{% hint style="info" %}
The following section is only relevant for customers deploying Elimity Insights on-prem. For our SaaS customers we perform the necessary upgrade work behind the scenes.
{% endhint %}

Before upgrading to a new feature release it's very important to read through the release notes as they document all important changes and necessary preparation tasks. Typically you'll have to follow the steps below:

1. Shut down 'old' version of your Elimity Insights server
2. Perform database migrations
3. Start 'new' version of your Elimity Insights server

Upgrading to a patch release is typically much quicker. While you should of course still consult the release notes beforehand, in most cases you can just bump the image version and restart.

### Support

We provide official support for the latest patch versions of the two most recent feature releases. This means we process bug reports and security findings for those versions and patch them when needed. A similar policy applies for the other supporting components (e.g. LDAP gateway, LDAP proxy, SQL gateway, ...) we provide. More specifically we support those 'major' versions that were the most recent when we published a new feature release of Elimity Insights. These versions remain supported as long as they relate in this way to at least one feature release that is still supported.

You can easily check which images are officially supported by looking for the `stable` and `oldstable` tags.


# Updates

This page contains references to the release notes of all Elimity Insights versions starting from v3.44.0. We will update this overview whenever a new release comes out. For automatic notifications you can even subscribe to the RSS feed of this page.

{% updates format="full" %}
{% update date="2026-10-14" %}

## Elimity Insights `v3.47.1` is now available

Refer to [the release notes](/release-notes/v3.47.1) for additional information.
{% endupdate %}

{% update date="2026-10-14" %}

## Elimity Insights `v3.46.6` is now available

Refer to [the release notes](/release-notes/v3.46.6) for additional information.
{% endupdate %}

{% update date="2026-09-15" %}

## Elimity Insights `v3.46.5` is now available

Refer to [the release notes](/release-notes/v3.46.5) for additional information.
{% endupdate %}

{% update date="2026-09-10" %}

## Elimity Insights `v3.47.0` is now available

Refer to [the release notes](/release-notes/v3.47.0) for additional information.
{% endupdate %}

{% update date="2026-09-02" %}

## Elimity Insights `v3.46.4` is now available

Refer to [the release notes](/release-notes/v3.46.4) for additional information.
{% endupdate %}

{% update date="2026-09-02" %}

## Elimity Insights `v3.45.7` is now available

Refer to [the release notes](/release-notes/v3.45.7) for additional information.
{% endupdate %}

{% update date="2026-08-31" %}

## Elimity Insights `v3.46.3` is now available

Refer to [the release notes](/release-notes/v3.46.3) for additional information.
{% endupdate %}

{% update date="2026-08-24" %}

## Elimity Insights `v3.46.2` is now available

Refer to [the release notes](/release-notes/v3.46.2) for additional information.
{% endupdate %}

{% update date="2026-08-24" %}

## Elimity Insights `v3.45.6` is now available

Refer to [the release notes](/release-notes/v3.45.6) for additional information.
{% endupdate %}

{% update date="2026-08-05" %}

## Elimity Insights `v3.46.1` is now available

Refer to [the release notes](/release-notes/v3.46.1) for additional information.
{% endupdate %}

{% update date="2026-08-03" %}

## Elimity Insights `v3.46.0` is now available

Refer to [the release notes](/release-notes/v3.46.0) for additional information.
{% endupdate %}

{% update date="2026-08-03" %}

## Elimity Insights `v3.45.5` is now available

Refer to [the release notes](/release-notes/v3.45.5) for additional information.
{% endupdate %}

{% update date="2026-07-22" %}

## Elimity Insights `v3.45.4` is now available

Refer to [the release notes](/release-notes/v3.45.4) for additional information.
{% endupdate %}

{% update date="2026-07-22" %}

## Elimity Insights `v3.44.5` is now available

Refer to [the release notes](/release-notes/v3.44.5) for additional information.
{% endupdate %}

{% update date="2026-07-14" %}

## Elimity Insights `v3.45.3` is now available

Refer to [the release notes](/release-notes/v3.45.3) for additional information.
{% endupdate %}

{% update date="2026-07-14" %}

## Elimity Insights `v3.44.4` is now available

Refer to [the release notes](/release-notes/v3.44.4) for additional information.
{% endupdate %}

{% update date="2026-07-01" %}

## Elimity Insights `v3.44.3` is now available

Refer to [the release notes](/release-notes/v3.44.3) for additional information.
{% endupdate %}

{% update date="2026-07-01" %}

## Elimity Insights `v3.45.2` is now available

Refer to [the release notes](/release-notes/v3.45.2) for additional information.
{% endupdate %}

{% update date="2026-06-15" %}

## Elimity Insights `v3.45.1` is now available

Refer to [the release notes](/release-notes/v3.45.1) for additional information.
{% endupdate %}

{% update date="2026-06-10" %}

## Elimity Insights `v3.45.0` is now available

Refer to [the release notes](/release-notes/v3.45.0) for additional information.
{% endupdate %}

{% update date="2026-06-09" %}

## Elimity Insights `v3.44.2` is now available

Refer to [the release notes](/release-notes/v3.44.2) for additional information.
{% endupdate %}

{% update date="2026-04-17" %}

## Elimity Insights `v3.44.1` is now available

Refer to [the release notes](/release-notes/v3.44.1) for additional information.
{% endupdate %}

{% update date="2026-03-19" %}

## Elimity Insights `v3.44.0` is now available

Refer to [the release notes](/release-notes/v3.44.0) for additional information.
{% endupdate %}
{% endupdates %}


# v3.47.1

We are happy to announce release v3.47.1 of Elimity Insights, released on 14 October 2026.

## Summary

This section summarizes the most important changes in release v3.47.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply updated some internal dependencies to their latest versions.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.47.x to v3.47.1, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.47.0

We are happy to announce release v3.47.0 of Elimity Insights, released on 10 September 2026.

## Summary

This section summarizes the most important changes in release v3.47.0.

<details>

<summary>New functionality</summary>

* MCP server support
* Additional endpoint: `GET /api/agent/stored-query-results;format=json`
* Subscription count added to the stored queries page

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Tooltips for truncated values in data tables
* API errors are now reported in the interface
* Duplicate query subscriptions are now prevented
* Stored query table columns : 'scope', 'results' and 'public' are click-to-sort now
* Archived sources dont show up on the dashboard
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* *None*

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### MCP server support

The Elimity Insights MCP server makes an Elimity Insights tenant available to AI assistants through the [Model Context Protocol](https://modelcontextprotocol.io/). Users can then ask questions about their identity data from an MCP client (e.g. Claude Code, Claude Desktop, …) instead of clicking through the web application.

This release adds the platform side of that integration: the configuration options and authentication flow that the MCP server connects to. Both are stable and come with the same backwards compatibility guarantees as the rest of the platform.

The MCP server itself is a separate component: a stateless microservice that stores no data of its own and that fronts exactly one Elimity Insights tenant. It is still in testing and we expect to release it somewhere in October, so its tools can still change until then. Answers produced by an AI assistant are also not deterministic, so we don't recommend relying on them as evidence for audits or as input for automated processes yet.

### Additional endpoint: `GET /api/agent/stored-query-results;format=json`

Elimity Insights now provides a new endpoint to list the results of a stored query as JSON. The endpoint takes the stored query's identifier in the required `queryId` query parameter and returns the identifier and name of every matching entity. It can be called using an API token.

### Subscription count column

There now is an extra column in the stored query table showing how many notification channels are subscribed to each query. The count is also included in the Excel export. The column is only shown to users whose role allows them to see subscriptions.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FOiFxURSxGT9QKP6Cp9ge%2Fimage.png?alt=media&amp;token=5d204be0-a457-4d4c-a10f-7effd5d842f2" alt=""><figcaption></figcaption></figure>

## Bug fixes & improvements

### Tooltips for truncated values in data tables

Data table cells no longer hide values that are too large for the available column width. Hovering a cell now shows its full value in a tooltip.

### API errors are now reported in the interface

Elimity Insights now reports failing API calls in a snackbar containing the error returned by the server, instead of a generic message per screen. This makes it clear why an action did not succeed.

### Duplicate query subscriptions are now prevented

Adding a subscription that is identical to an existing subscription of the same stored query is no longer possible.

### Stored query table columns : 'scope', 'results' and 'public' are click-to-sort now

The columns 'scope', 'results' and 'public' can now be sorted in the stored query table by clicking on the corresponding column titles.

### Archived sources don't show up on the dashboard

* Archived sources are now hidden on the dashboard.
* Summary cards of archived sources are now hidden in the dialog.
* Reordering tiles now shows the source name of summary cards.
* Typo in the 'add card' dialog was corrected.

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* Fixed an issue where the interface could break after refreshing the page.
* More sortable columns: the 'scope', 'results' and 'public' columns are click-to-sort now.
* A name is now required when creating or editing a scope or an access profile.
* A logout button was added to the setup screen, so users can log out when they don't have any imports yet.
* The Entra ID built-in connector now includes a new 'employee type' attribute type for users.
* The DocuSign built-in connector no longer drops the relationships between users and their permission profiles.
* The 'download overview' button on the scope detail page now exports correctly.
* The 'column entities' step of the access review wizard now shows the actual number of included column entities.
* The icon of an entity type now follows that entity type when reordering entity types of a custom connector.
* The paginators of the change requests and user accounts pages no longer scroll out of view together with the table.
* Due to an update of our internal toolchain, requests bigger than 32MB failed. This is now fixed.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.47.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Migrate your database, as described in [our dedicated documentation](/reference-manual/installation/elimity-insights-server#upgrades).
5. Start the server and validate that it works as before.


# v3.46.6

We are happy to announce release v3.46.6 of Elimity Insights, released on 14 October 2026.

## Summary

This section summarizes the most important changes in release v3.46.6.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply updated some internal dependencies to their latest versions.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.46.6, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.46.5

We are happy to announce release v3.46.5 of Elimity Insights, released on 15 September 2026.

## Summary

This section summarizes the most important changes in release v3.46.5.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply updated some dependencies to their latest version.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.46.5, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.46.4

We are happy to announce release v3.46.4 of Elimity Insights, released on 2 September 2026.

## Summary

This section summarizes the most important changes in release v3.46.4.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply updated some dependencies to their latest version.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.46.4, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.46.3

We are happy to announce release v3.46.3 of Elimity Insights, released on 31 August 2026.

## Summary

This section summarizes the most important changes in release v3.46.3.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect most customers: we updated [our SAP SuccessFactors built-in connector](/reference-manual/built-in-connectors/sap-successfactors) to paginate users more efficiently.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.46.3, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.46.2

We are happy to announce release v3.46.2 of Elimity Insights, released on 24 August 2026.

## Summary

This section summarizes the most important changes in release v3.46.2.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply updated our compilation toolchain to use Go 1.26.6.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.46.2, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.46.1

We are happy to announce release v3.46.1 of Elimity Insights, released on 5 August 2026.

## Summary

This section summarizes the most important changes in release v3.46.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply reapplied a previous update of our compilation toolchain to use Go 1.26.5.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.46.x to v3.46.1, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.46.0

We are happy to announce release v3.46.0 of Elimity Insights, released on 3 August 2026.

## Summary

This section summarizes the most important changes in release v3.46.0.

<details>

<summary>New functionality</summary>

* Pagination in custom gateway imports
* Retrieval timestamps for reload events
* Additional endpoint: `GET /api/agent/linking-strategies`
* Evaluation duration added to the stored query page
* New user account role: `storedQueryManager`
* Global toggle for 'build history'
* Toggle option for 'build history' in the stored queries detail page
* Timestamps of last evaluation added to the stored query page
* Ownership of scopes can now be assigned explicitly
* Ownership of queries can now be assigned explicitly
* New 'Download as Excel' button on the stored queries overview page
* Support for timing out query evaluations during imports
* Support for pinning columns to stored queries

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Prevent large peer review tables from crashing the browser
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* New `queryTimeOutMinutes` configuration option

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### Pagination in custom gateway imports

Previously Elimity Insights pulled all entities and relationships in a single request, now it supports splitting the import into multiple pages (only SDK v2):

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FrS6ia8LvR0WYohix7JOb%2FScreenshot%202026-07-27%20at%2013-18-03%20Elimity.png?alt=media&amp;token=548fd704-738d-41de-8c32-8322329a2563" alt=""><figcaption></figcaption></figure>

### Retrieval timestamps for reload events

The imports tab of the source detail page now lists additional details about retrieval timestamps for reload events.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FdIPjfQBpeKArZWxKxZRO%2FScreenshot%202026-07-27%20at%2013-24-46%20Elimity.png?alt=media&amp;token=f4557e45-f9da-4e32-9acc-f14d7326aac8" alt=""><figcaption></figcaption></figure>

### Additional endpoint: `GET /api/agent/linking-strategies`

Elimity Insights now provides a new endpoint to list all linking strategies. The endpoint can be called using an API token.

### Evaluation duration added to the stored query page

Visiting a stored query's detail page now shows the elapsed running time of its current execution, making it easy to spot queries that are taking longer than expected.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fu7DdQDSidNVvexpQuKO8%2FScreenshot%202026-07-29%20at%2011-11-08%20Elimity.png?alt=media&amp;token=b1e90307-21cf-46da-9bc0-d7382822b8e4" alt=""><figcaption></figcaption></figure>

### Timestamps of last evaluation added to the stored query page

Similarly we also added a new 'Last evaluation during import' column to the stored query page.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fu7DdQDSidNVvexpQuKO8%2FScreenshot%202026-07-29%20at%2011-11-08%20Elimity.png?alt=media&amp;token=b1e90307-21cf-46da-9bc0-d7382822b8e4" alt=""><figcaption></figcaption></figure>

The same information is also available in the overview table listing all stored queries.

### New user account role: `storedQueryManager`

Elimity Insights now provides a new user account: `storedQueryManager` . Users who have this role can manage/assign stored queries and scopes of other users.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FU0PslwncyFlSwdhu6H0q%2FScreenshot%202026-07-27%20at%2013-46-45%20Elimity.png?alt=media&amp;token=a398fa67-ec65-4137-b2a4-c76b0875435d" alt=""><figcaption></figcaption></figure>

### Global toggle option for 'build history'

Administrators can now use the 'miscellaneous' tab on the 'advanced settings' page to set the default build history behaviour for newly created stored queries. This default has no effect on existing stored queries, and it can still be overridden per query.

When the toggle is on, new stored queries will preserve their history by default. When it is off, new stored queries will not build history by default and their history tab will not be shown. In both cases, the setting can be changed on any individual stored query afterwards.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FhpPMHpnceyJHQzRs91fv%2FScreenshot%202026-07-27%20at%2015-00-45%20Elimity.png?alt=media&amp;token=5a85a537-073a-4776-b214-fa6d8a377092" alt=""><figcaption></figcaption></figure>

### Toggle option for 'build history' in the stored queries detail page

A toggle option is now available to users with the `storedQueryManager` role or higher to determine whether Elimity Insights should build history for a specific stored query. The toggle is initially turned on due to the before mentioned global default.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FInTCtAYskCRPiHdxraMT%2FScreenshot%202026-07-27%20at%2013-50-42%20Elimity.png?alt=media&amp;token=2b0eac1d-4c03-4084-80bf-dd00eade8a6a" alt=""><figcaption></figcaption></figure>

The overview table listing all stored queries now also has a 'build history' column.

### Ownership of scopes can now be assigned explicitly

Users with role `storedQueryManager` or above can now assign ownership of a scope when creating or editing it. Enter the owner's email in the 'Owner' search bar.&#x20;

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FO8VjdmjPvTjkLpAqp6B4%2FScreenshot%202026-07-27%20at%2015-16-21%20Elimity.png?alt=media&amp;token=de3d55ed-ee00-44bb-a9c3-aa986fd820c2" alt=""><figcaption></figcaption></figure>

### Ownership of queries can now be assigned explicitly

Users with role `storedQueryManager` or above can now assign a different owner to a stored query when creating or editing it, provided the query has no scope.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FNUnINueBypVCdDpMYzUK%2FScreenshot%202026-07-27%20at%2015-13-22%20Elimity.png?alt=media&amp;token=b7b62850-1394-4bdd-aeb3-c03641ae67a4" alt=""><figcaption></figcaption></figure>

### New 'Download as Excel' button on the stored queries overview page

The stored queries page now offers a 'Download as Excel' button that exports every stored query you have access to, with its status, name, description, owner, scope, latest result count and public flag, to a `.xlsx` file. The export always covers the complete list, regardless of the filter or page currently shown in the table.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FuycwcyHFmcfCVUNl9Sht%2FScreenshot%202026-07-27%20at%2015-31-30%20Elimity.png?alt=media&amp;token=60905c82-9b2d-40f5-a109-3842988a1d85" alt=""><figcaption></figcaption></figure>

### Support for timing out query evaluations during imports

Elimity Insights v3.46.0 also brings support for timing out query evaluations during imports. More specifically, administrators can now enable a specific timeout in the 'miscellaneous' tab on the 'advanced settings' page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fr1bvCy51frRJkPPWosBX%2FScreenshot%202026-07-28%20at%2014-42-45%20Elimity.png?alt=media&amp;token=64b9af44-8491-4175-b345-1fb59cdac533" alt=""><figcaption></figcaption></figure>

Elimity Insights will discard stored query evaluations that exceed this timeout during an import.&#x20;

### Support for pinning columns to stored queries

The owner or a stored query manager of a stored query can now pin its columns from the column selector, using the new 'pin columns' option. Pinning columns sets the default columns for the query: everyone who opens it will start with these columns selected. Pinned columns can include attributes, the entity identifier, and columns from linked entities.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2F3rdt51m2KWDfb7fbuBBz%2FScreenshot%202026-07-29%20at%2009-55-02%20Elimity.png?alt=media&amp;token=db9adaff-0329-4bad-9168-f145e1783cd3" alt=""><figcaption></figcaption></figure>

Newly created stored queries start with all attributes pinned, and 'reset to default' restores this at any time. Pinning only sets the starting point, so anyone viewing the query can still change their own columns afterwards. You will only see and pin the columns you are permitted to view, and columns pinned by others that you cannot access are left unchanged.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FqvvS7nak4iYOIAjeCNg9%2Fimage.png?alt=media&amp;token=65bb8d8b-f2dc-4a13-b89a-8a9bb20a1465" alt=""><figcaption></figcaption></figure>

## Bug fixes & improvements

### Prevent large peer review tables from crashing the browser

When a peer review contains more than 10,000 cells, Elimity Insights no longer renders the table automatically, since a table that large can seriously degrade your browser's performance. Instead, the page reports the number of cells and offers two options: click 'Download' instead to export the full peer review to Excel without rendering it, or click 'Render anyway' to display the table in the browser regardless.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FacVv2vXn1yRuHeQzfysE%2Fimage.png?alt=media&amp;token=507663f1-c659-4c2b-b664-c50428a56c58" alt=""><figcaption></figcaption></figure>

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* Elimity Insights now writes a connector log when executing stored queries during an import.
* The [GitHub built-in connector](/reference-manual/built-in-connectors/github) now skips unresolvable team members instead of aborting the import.
* Access review page now refreshes the data on clicking the 'finalize and send' button.
* Elimity Insights now rejects stale snapshots when running multiple imports for the same source.
* The [DocuSign built-in connector](/reference-manual/built-in-connectors/docusign) no longer skips the first entry when retrieving users.
* The [LDIF built-in connector](/reference-manual/built-in-connectors/ldif) now checks if the file is UTF-8 encoded.
* The failing source's name is now displayed in the subject of failure emails.

## Deployment changes

### New `queryTimeOutMinutes` configuration option

Elimity Insights now provides a new configuration option to timeout queries for which evaluation takes too long. More specifically you can now add a `queryTimeOutMinutes` option in `config.hjson` to set the maximum query evaluation time in minutes. By default Elimity Insights applies a timeout of 10 minutes, customers using complex queries on large data sets should consider increasing this value.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.46.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Migrate your database, as described in [our dedicated documentation](/reference-manual/installation/elimity-insights-server#upgrades).
5. Start the server and validate that it works as before.


# v3.45.7

We are happy to announce release v3.45.7 of Elimity Insights, released on 2 September 2026.

## Summary

This section summarizes the most important changes in release v3.45.7.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we simply updated some dependencies to their latest version.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.45.7, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.45.6

We are happy to announce release v3.45.6 of Elimity Insights, released on 24 August 2026.

## Summary

This section summarizes the most important changes in release v3.45.6.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a small improvement that shouldn't affect any customers: we updated our compilation toolchain to use Go 1.26.6.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.45.6, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.45.5

We are happy to announce release v3.45.5 of Elimity Insights, released on 3 August 2026.

## Summary

This section summarizes the most important changes in release v3.45.5.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes two small fixes:

* We updated internal dependencies and base images to remediate container scanning findings.
* Access review managers now no longer have implicit import access to sources.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.45.5, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.45.4

We are happy to announce release v3.45.4 of Elimity Insights, released on 22 July 2026.

## Summary

This section summarizes the most important changes in release v3.45.4.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers: we simply updated our internal dependencies and base images to remediate container scanning findings.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.45.4, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.45.3

We are happy to announce release v3.45.3 of Elimity Insights, released on 14 July 2026.

## Summary

This section summarizes the most important changes in release v3.45.3.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers:

* We updated our compilation toolchain to Go 1.26.5.
* We updated our internal dependencies and base images to remediate container scanning findings.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.45.3, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.45.2

We are happy to announce release v3.45.2 of Elimity Insights, released on 1 July 2026.

## Summary

This section summarizes the most important changes in release v3.45.2.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers:

* We updated our compilation toolchain to Go 1.26.4.
* We updated our internal dependencies and base images to remediate container scanning findings.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.45.x to v3.45.2, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.45.1

We are happy to announce release v3.45.1 of Elimity Insights, released on 15 June 2026.

## Summary

This section summarizes the most important changes in release v3.45.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

This release only includes one minor bug fix:

* [The GitHub built-in connector](/reference-manual/built-in-connectors/github) now correctly deals with organizations that lack an explicit display name.


# v3.45.0

We are happy to announce release v3.45.0 of Elimity Insights, released on 10 June 2026.

## Summary

This section summarizes the most important changes in release v3.45.0.

<details>

<summary>New functionality</summary>

* Campaign archival
* Custom toolbar color
* Peer review traces
* Access review creation wizard

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Configurable page sizes for several tables across the UI
* Simplified registration process for the initial admin
* Highlight 'original' entities in trace dialogs
* Improved support for 'matching' and 'via' entity columns in data tables
* OAuth2 authentication for ITSM webhooks
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* End of support for PostgreSQL 15
* End of support for YAML configuration files
* End of support for command-line flags for database migrations

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### Campaign archiving

Elimity Insights v3.45.0 includes support for (un)archiving campaigns. Access review managers can now mark old campaigns as archived so they do not clutter the overview page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FBY8RsEH0JO58Q9eqlkR3%2FScreenshot%202026-05-27%20at%2008-36-33%20Elimity.png?alt=media&amp;token=0d93c59f-dbbe-4c0c-9b35-cce27c6c03ae" alt=""><figcaption></figcaption></figure>

When you archive a campaign we will ask whether you also want to delete all of its open and draft access reviews. Archiving a campaign also means its draft access reviews can no longer be edited. Apart from that, archival only determines whether a campaign shows up in the overview by default. If you do want to see these archived campaigns, simply use the designated slider at the top of the page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FI4TKdOXcJBbaX9CwIwF2%2FScreenshot%202026-05-27%20at%2008-37-09%20Elimity.png?alt=media&amp;token=e0c319a4-4ce8-47bd-a100-60601516c38b" alt=""><figcaption></figcaption></figure>

### Custom toolbar color

Another new feature in this release is the added support for configuring the toolbar color for your Elimity Insights tenant:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FOeTIpJmGUIOjm3gqqL3l%2FScreenshot%202026-05-27%20at%2008-47-55%20Elimity.png?alt=media&amp;token=30d51c74-1af1-4ebd-a15f-2884fc738e03" alt=""><figcaption></figcaption></figure>

Administrators can now open a new 'miscellaneous' tab on the 'advanced settings' page to override Elimity Insights' default blue toolbar color. This is a tenant-wide setting, so all users will see the same configured color:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2F0HdBfZeJemxNNbmbEQXh%2FScreenshot%202026-05-27%20at%2008-52-41%20Elimity.png?alt=media&amp;token=060f0f64-89c6-410c-8bdf-be2da87671d3" alt=""><figcaption></figcaption></figure>

### Peer review traces

Up until Elimity Insights v3.44.0 users could only show traces in data tables on entity detail pages. This release brings the same functionality to peer reviews:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FM6gd0u1G1oQBjAjrMHu4%2FScreenshot%202026-05-27%20at%2008-56-39%20Elimity.png?alt=media&amp;token=7fd3e7ab-6a64-4d68-bdbe-fde63e608db6" alt=""><figcaption></figcaption></figure>

Users can now right-click on any non-empty cell in peer review results to show traces between the selected row and column entity. You can also show all traces for a specific row or column (by opening its dropdown menu) and even for the entire table (by clicking the 'show traces' button in the top-right corner).

### Access review creation wizard

In Elimity Insights v3.45.0 we've also improved how access review managers can create and edit access reviews. The 'create access review' buttons in data tables and peer reviews now bring you to a dedicated wizard instead of opening a crowded dialog:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fezjty6xqHg2Rn1oqEuaq%2FScreenshot%202026-05-28%20at%2013-38-34%20Elimity.png?alt=media&amp;token=de08126a-877d-4d7e-8432-5b2773e5ce51" alt=""><figcaption></figcaption></figure>

This new wizard allows managing an explicit list of row and column entities which we automatically prefill based on the contents of your data table or peer review.

## Bug fixes & improvements

### Configurable page sizes for several tables across the UI

From Elimity Insights v3.45.0 onwards users can configure page sizes for several tables across our UI. The available options are 10 (default), 20, 50 and 100. This applies to the following tables:&#x20;

* Stored Queries, Scopes
* Change Requests
* Access Reviews
* User Accounts
* Assigned Users
* Logs

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fh8FondwKFm6YCmFC0Avz%2FScreenshot%202026-05-27%20at%2009-10-37%20Elimity.png?alt=media&amp;token=c7439135-1cde-49ea-8bff-975e76a67072" alt=""><figcaption></figcaption></figure>

### Simplified registration process for the initial admin

In previous releases of Elimity Insights registering the initial admin account involved setting the `defaultAccountEmail` configuration option and using on the email invite or relying on JIT provisioning via the IdP. In v3.45.0 we've simplified this process: for empty tenants the first user that logs in via the configured IdP can automatically register as administrator to perform the remaining setup steps. This also means the `defaultAccountEmail` configuration option now no longer has any effect.

### Highlight 'original' entities in trace dialogs <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

Showing traces between two entities that are linked in many different ways sometimes results in a large amount of 'dots' in the visualized graph. This can make it difficult to find the 'original' entities. In this release we've highlighted them with a different shape:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FXN1uBgEEF64UlSlqcPjn%2FScreenshot%202026-05-27%20at%2009-26-00%20Elimity.png?alt=media&amp;token=01cbaffc-41cc-4ab5-aba8-a4a7254f8275" alt=""><figcaption></figcaption></figure>

### Improved support for 'matching' and 'via' entity columns in data tables <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

In previous versions of Elimity Insights data tables did not support selecting 'matching' or 'via' entity columns for hierarchical entity types. In v3.45.0 we've removed this restriction, which for example enables users to search for groups that are members of other groups and also show those matching groups for each result:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fn1FGxBjXuysO2HUeqjqM%2FScreenshot%202026-05-27%20at%2009-58-02%20Elimity.png?alt=media&amp;token=93ccf5f8-b011-4e07-9dac-b3d875d04ca2" alt=""><figcaption></figcaption></figure>

Put differently, this change just adds extra 'matching' or 'via' entity column options for data tables on (stored) query and entity detail pages respectively. It only affects customers with sources having hierarchical entity types.

### OAuth2 authentication for ITSM webhooks <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

The v3.45.0 release also adds support for OAuth2 authentication in ITSM webhooks. Administrators can now configure a client ID, client secret, scope and token URL which Elimity Insights will use to retrieve an access token (via the OAuth2 client credentials flow) before triggering the webhook:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fv2ZcKRcX38SeRa5qpGEt%2FScreenshot%202026-05-27%20at%2012-12-40%20Elimity.png?alt=media&amp;token=cf2f635e-9062-4041-8e45-16212f953e01" alt=""><figcaption></figcaption></figure>

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* All trace dialogs now use a deterministic layout and color scheme.
* The Swagger UI now loads correctly again.
* Data tables on stored query pages no longer show any 'linked' entity columns by default.
* Default dashboards now include a section title for each active source.
* The detail pages for access reviews and campaigns now include some useful extra metrics. The access review list/overview also has two new columns, "Total change requests" and "Open change requests".
* Imports from custom gateways containing duplicates now fail more transparently.
* Setting up a burn-down chart no longer requires an existing history point as start date.
* Long dashboard card titles and query conditions now render properly instead of overflowing the UI.
* Pressing the 'search' button on the query page no longer resets the column selection for the table of results below (unless you're changing the 'main' entity type).
* The [GitHub built-in connector](/reference-manual/built-in-connectors/github) now supports importing from multiple organizations.
* The [SCIM built-in connector](/reference-manual/built-in-connectors/scim) now uses `userName` instead of `displayName` to name user entities.
* The [SharePoint built-in connector](/reference-manual/built-in-connectors/sharepoint) now supports failing its import when it encounters errors while interacting with the SharePoint API.
* We've renamed the [Delinea Secret Server built-in connector](/reference-manual/built-in-connectors/delinea-secret-server-cloud) to 'Delinea Secret Server Cloud'
* The [Entra ID built-in connector](/reference-manual/built-in-connectors/azure-ad) now includes a few new attribute types:
  * For users: 'Employee Hire Date' and 'Employee Leave Date'
  * For (app role) groups: 'On-premises security identifier'
* Opening a peer review from 'matching' entity columns that refer to relationship attributes now works as expected.

## Deployment changes

### End of support for PostgreSQL 15

As mentioned in release notes for v3.44.0, from v3.45.0 onwards Elimity Insights officially only supports PostreSQL 17.x.

### End of support for YAML configuration files

The v3.45.0 release also drops support for the `elimity.yml` and `secrets.yml` configuration files, again as mentioned in the release notes for v3.44.0. From now on we only support configuring Elimity Insights with `config.hjson` file or the `INSIGHTS_CONFIG_HJSON` environment variable.

### End of support for command-line flags for database migrations

Similarly we now only support configuring our database migration images with the `config.json` file, the command-line flags will no longer work.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.44.x to v3.45.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Migrate your database, as described in [our dedicated documentation](/reference-manual/installation/elimity-insights-server#upgrades).
5. Start the server and validate that it works as before.


# v3.44.5

We are happy to announce release v3.44.5 of Elimity Insights, released on 22 July 2026.

## Summary

This section summarizes the most important changes in release v3.44.5.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers: we simply updated our internal dependencies and base images to remediate container scanning findings.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.44.x to v3.44.5, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.44.4

We are happy to announce release v3.44.4 of Elimity Insights, released on 14 July 2026.

## Summary

This section summarizes the most important changes in release v3.44.4.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers:

* We updated our compilation toolchain to Go 1.26.5.
* We updated our internal dependencies and base images to remediate container scanning findings.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.44.x to v3.44.4, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.44.3

We are happy to announce release v3.44.3 of Elimity Insights, released on 1 July 2026.

## Summary

This section summarizes the most important changes in release v3.44.3.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers:

* We updated our compilation toolchain to Go 1.26.4.
* We updated our internal dependencies and base images to remediate container scanning findings.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.44.x to v3.44.3, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.44.2

We are happy to announce release v3.44.2 of Elimity Insights, released on 9 June 2026.

## Summary

This section summarizes the most important changes in release v3.44.2.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

This release only includes a few minor bug fixes & improvements:

* Opening a peer review from a 'matching' entity column that refers to a relationship attribute type now works as expected.
* Data tables now compute the initial number of results in a more efficient way which noticeably speeds up entity detail pages for customers with large data sources.


# v3.44.1

We are happy to announce release v3.44.1 of Elimity Insights, released on 17 April 2026.

## Summary

This section summarizes the most important changes in release v3.44.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

This release only includes a few minor bug fixes & improvements:

* Fixed a bug when downloading an Excel file from a stored query.
* Fixed a bug where downloading an Excel file resulted in an error when including 'via' entities.
* Provided additional logging and context for the [NTFS built-in connector](/reference-manual/built-in-connectors/ntfs).
* Summaries at the top of entity detail pages now load independently of the data tables further down, which improves responsiveness for customers with large datasets.


# v3.44.0

We are happy to announce release v3.44.0 of Elimity Insights, released on 19 March 2026.

## Summary

This section summarizes the most important changes in release v3.44.0.

<details>

<summary>New functionality</summary>

* Configure visible attribute types for access reviews
* Support for editing campaign names and due dates
* Support for configuring the access review toolbar text color

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Access profiles no longer apply for access reviews and access review managers
* Support authenticating to Postgres via Azure Managed Identity
* Support reading configuration from a config file for the migration CLI
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* Required update of the SharePoint and Jira Data Center gateways
* Added support for reading configuration from a single environment variable or file
* Official support for Postgres 15 and 17

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### Configure visible attribute types for access reviews

Elimity Insights v3.44.0 includes support for configuring visible attribute types for access reviews. You can now manage and select visible attribute types directly when creating access reviews. This functionality is also available in the campaign template creation wizard and when editing campaign templates.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FRr9a4jpDebnHwJfWVz64%2FScreenshot%202026-02-26%20at%2015-15-05%20Elimity.png?alt=media&amp;token=519e7590-bbb8-4900-a317-5a5db0f48e63" alt=""><figcaption></figcaption></figure>

### Support for editing campaign names and due dates

In this release, campaign names and due dates can now be easily edited after a campaign has been created.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FIhvOd5TsEx8BU9btURZc%2FScreenshot%202026-02-26%20at%2015-15-30%20Elimity.png?alt=media&amp;token=0946bf82-c147-4b52-bdb7-7eb03aa9ae44" alt=""><figcaption></figcaption></figure>

### Support for configuring the access review toolbar text color

The v3.44.0 release includes support for configuring the text color of the access review toolbar. You can now add the `accessReviewToolbarTextColor` configuration option to your `config.hjson` file. This works similarly to the existing `accessReviewToolbarBackgroundColor` option and defaults to white.

## Bug fixes & improvements

### Access profiles no longer apply for access reviews and access review managers

Access profiles no longer apply to access reviews. Users assigned the Access Review Manager role can now fully manage access reviews and campaigns, bypassing any previous access profile restrictions. This also means that access review managers can view identity data for all sources, so make sure to reassign roles as needed before you upgrade.

### Support authenticating to Postgres via Azure Managed Identity

For customers deploying in Azure environments, Elimity Insights now supports authenticating to your Postgres database using Azure Managed Identity, streamlining credentials management.

To enable this feature, simply set the `pgAzureManagedIdentity` flag to `true` in your `config.hjson` file. When enabled, Elimity Insights will retrieve an access token from Azure and use it as a password for authentication with PostgreSQL.

### Support reading configuration from a config file for the migration CLI&#x20;

To simplify the [database migration](/reference-manual/installation/elimity-insights-server#upgrades) process, the migration CLI now supports reading configuration from a `config.json` file instead of requiring lengthy command-line arguments.

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* Added 'Created by' column to the table of access reviews on the campaign details page; previously you could only find this information on the access review details page.
* Fixed an issue where filtering descriptions for data tables on entity detail pages showed incorrect counts.
* The [Entra ID built-in connector](/reference-manual/built-in-connectors/azure-ad) now includes 'app' and 'LastSuccessfulSignInDateTime' attribute types.
* We've added a few enhancements for the [SharePoint built-in connector](/reference-manual/built-in-connectors/sharepoint):
  * you can exclude files based on a configurable glob pattern, and
  * we added some extra attributes for each imported site.
* Customers using our [SCIM built-in connector](/reference-manual/built-in-connectors/scim) can now provide a bearer token instead of username and password for authentication.

## Deployment changes

### Required update of the SharePoint and Jira Data Center gateways <a href="#required-update-of-the-ntfs-gateway" id="required-update-of-the-ntfs-gateway"></a>

Customers using the [SharePoint](/gateways-sharepoint/step-by-step-deployment-guide) and [Jira Data Center](/gateways-jira-data-center/step-by-step-deployment-guide) built-in connectors must update their gateways to major versions 5 and 3 respectively.

### Added support for reading configuration from a single environment variable or file

Previously, configurations and secrets were split across two separate files (`elimity.yml` and `secrets.yml`).

Moving forward, you can consolidate your entire configuration into a single `config.hjson` file. Alternatively you can pass this unified configuration using a single new environment variable: `INSIGHTS_CONFIG_HJSON`. See [our dedicated documentation](/reference-manual/server-configuration) for more information.\
\
Please note that this will be the last release to support YAML file configuration.

### Official support for Postgres 15 and 17

Elimity Insights now officially supports PostgreSQL 15 and 17.&#x20;

Please note that this will be the last release to support PostgreSQL 15.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.43.x to v3.44.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Migrate your database, as described in [our dedicated documentation](/reference-manual/installation/elimity-insights-server#upgrades).
5. Start the server and validate that it works as before.


# v3.43.2

We are happy to announce release v3.43.2 of Elimity Insights, released on 18 March 2025.

## Summary

This section summarizes the most important changes in release v3.43.2.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a few minor bug fixes & improvements:

* Filters on 'count of via ...' in data tables on entity details pages now apply correctly.
* We've resolved an issue where for some data models filtering on relationship attributes in data tables on entity details pages did not work as expected.
* This patch release also brings performance fixes for endpoints that require data model information behind the scenes, which vastly improves the UI responsiveness in some cases.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.43.1 to v3.43.2, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.43.1

We are happy to announce release v3.43.1 of Elimity Insights, released on 25 February 2026.

## Summary

This section summarizes the most important changes in release v3.43.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* New `DatabaseAzureManagedIdentity` configuration option

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a few minor bug fixes & improvements:

* Elimity Insights now supports authenticating to PostgreSQL using Azure Managed Identity.
* We've tweaked our SCIM API to improve compatibility with Entra ID.
* CRON scheduling for custom gateway imports now works as expected.
* Entity detail pages no longer get stuck for sources with some specific relationship attribute types.

## Deployment changes <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

### New `DatabaseAzureManagedIdentity` configuration option

The v3.43.1 release allows on-premise customers to let Elimity Insights authenticate to PostgreSQL via Azure Managed Identity. More specifically, you can now (optionally) set the `DatabaseAzureManagedIdentity` flag in `secrets.yml`. In this case Elimity Insights will retrieve an access token from Azure and use it as a password for authentication with PostgreSQL. Refer to [the official documentation](https://learn.microsoft.com/en-us/azure/postgresql/security/security-connect-with-managed-identity) for additional information.

Note that you can also use this feature in our migration container by setting the `INSIGHTS_DATABASE_MIGRATE_AZURE_MANAGED_IDENTITY` environment variable to `1`.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.43.0 to v3.43.1, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Start the server and validate that it works as before.


# v3.43.0

We are happy to announce release v3.43.0 of Elimity Insights, released on 7 January 2026.

## Summary

This section summarizes the most important changes in release v3.43.0.

<details>

<summary>New functionality</summary>

* SailPoint IIQ built-in connector
* Webhook-based ITSM integrations

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* OAuth2 authentication for all gateway-based built-in connectors
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* Required update of the NTFS gateway
* Removal of the `AccessReviewRequestedChangesEmail` configuration option
* Removal of the `HttpsEnabled`, `TLSCertificate`, `TLSCertificateKey` and `TLSListeningPort` configuration options
* Removal of the `EnableOIDCAuthentication` and `EnablePasswordAuthentication` configuration options
* End of support for executable-based deployments

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### SailPoint IIQ built-in connector

Elimity Insights v3.43.0 includes support for SailPoint IIQ in its built-in connector library. This new connector imports users, accounts, entitlements, roles and applications from your SailPoint IIQ instance. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/sailpoint-iiq) for additional information.

### Webhook-based ITSM integrations

The v3.43.0 release also brings significant improvements for integrating with ITSM systems. Up until now, system admins had to set the `AccessReviewRequestedChangesEmail` configuration option and parse the incoming emails to create tickets in their ITSM system. We replaced this approach with a more flexible alternative based on webhooks. More specifically, admins can now simply configure a webhook URL which Elimity Insights triggers for each change request. Refer to [our dedicated documentation](/reference-manual/advanced-topics/itsm-webhook) for additional information.

## Bug fixes & improvements

### OAuth2 authentication for all gateway-based built-in connectors

Elimity Insights v3.42.0 brought some new configuration options to support strong authentication for imports via custom gateways. From v3.43.0 onwards, these configuration options also apply for all gateway-based built-in connectors. More specifically, Elimity Insights can now also use OAuth2 for authenticating requests to gateways for the following built-in connectors:

* [Jira Data Center](/reference-manual/built-in-connectors/jira-data-center)
* [NTFS](/reference-manual/built-in-connectors/ntfs)
* [SailPoint IIQ](/reference-manual/built-in-connectors/sailpoint-iiq)
* [SharePoint](/reference-manual/built-in-connectors/sharepoint)

We strongly recommend replacing the older authentication method based on secret tokens as soon as possible. Elimity Insights v3.44.0 will only support OAuth2 for gateway authentication.

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* The 'IMPORT FROM FILE UPLOADS' button on source detail pages now correctly links to the 'FILE UPLOADS' tab.
* Labels indicating the archivation status of attribute types and sources now appear in more places throughout the user interface
* The user interface now no longer constructs invalid or incorrect queries for some complex edge cases
* We slightly adjusted the look and feel of the usage logs tab on our advanced settings page to increase consistency

## Deployment changes

### Required update of the NTFS gateway

Customers using the NTFS built-in connector must update their gateways to major version 2. Note that the `secretTokenHash` config option is now no longer effective, please configure JWT validation as described in [our dedicated documentation](/gateways-ntfs/step-by-step-deployment-guide).

### Removal of the `AccessReviewRequestedChangesEmail` configuration option

Since Elimity Insights now supports webhook-based ITSM integrations, the `AccessReviewRequestedChangesEmail` configuration value in `elimity.yml` is no longer effective.

### Removal of the `HttpsEnabled`, `TLSCertificate`, `TLSCertificateKey` and `TLSListeningPort` configuration options

From v3.43.0 onwards Elimity Insights no longer supports serving HTTPS traffic directly. We instead require a production-grade HTTPS proxy to provide the best security. This means the `HttpsEnabled`, `TLSCertificate`, `TLSCertificateKey` and `TLSListeningPort` configuration options in `elimity.yml` will no longer be effective. Please refer to [our dedicated documentation](/reference-manual/installation/http-s-proxy) for additional guidance on HTTP(S) proxies.

### Removal of the `EnableOIDCAuthentication` and `EnablePasswordAuthentication` configuration options

To improve security even further we also removed password-based authentication in v3.43.0. More specifically, OIDC-based authentication is now mandatory (we were already strongly recommending it for every production-level deployment); the `EnableOIDCAuthentication` and `EnablePasswordAuthentication` configuration options in `elimity.yml` are no longer effective. This change should affect very few customers; please contact your Elimity representative if you need assistance with migrating to OIDC-based authentication.

### End of support for executable-based deployments

From v3.43.0 onwards, we only support container-based deployments of Elimity Insights. We provide migration assistance to the few customers that were still using plain executables.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.42.x to v3.43.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Upgrade your installation by bumping the container image version.
4. Migrate your database, as described in [our dedicated documentation](/reference-manual/installation/elimity-insights-server#upgrades).
5. Start the server and validate that it works as before.


# v3.42.3

We are happy to announce release v3.42.3 of Elimity Insights, released on 2 January 2026.

## Summary

This section summarizes the most important changes in release v3.42.3.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes 2 small bug fixes:

* The Entra ID built-in connector now provides additional logging when duplicate app role assignments are detected.
* Added some improvements to our SCIM API for increased compatibility with Okta.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.42.2 to v3.42.3, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.42.3, as described below.
4. Start the server and validate that it works as before.

### Installing the files for v3.42.3 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

Customers that set up a container-based installation of Elimity Insights can simply bump the server image version. If you're using plain executables, copy the following files from the v3.42.3 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-windows-x86_64.exe`


# v3.42.2

We are happy to announce release v3.42.2 of Elimity Insights, released on 27 October 2025.

## Summary

This section summarizes the most important changes in release v3.42.2.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes a single small bug fix:

* The Entra ID built-in connector now correctly determines group types based on whether they are security-enabled.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.42.1 to v3.42.2, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.42.2, as described below.
4. Start the server and validate that it works as before.

### Installing the files for v3.42.2 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

Customers that set up a container-based installation of Elimity Insights can simply bump the server image version. If you're using plain executables, copy the following files from the v3.42.2 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-windows-x86_64.exe`


# v3.42.1

We are happy to announce release v3.42.1 of Elimity Insights, released on 19 September 2025.

## Summary

This section summarizes the most important changes in release v3.42.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Minor bug fixes & improvements <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

This release only includes some small improvements that shouldn't affect any customers:

* We updated our compilation toolchain to Go 1.25.1.
* We updated the base images for our containers to Debian 13.1.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.42.0 to v3.42.1, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.42.1, as described below.
4. Start the server and validate that it works as before.

### Installing the files for v3.42.1 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

Customers that set up a container-based installation of Elimity Insights can simply bump the server image version. If you're using plain executables, copy the following files from the v3.42.1 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-windows-x86_64.exe`


# v3.42.0

We are happy to announce release v3.42.0 of Elimity Insights, released on 29 August 2025.

## Summary

This section summarizes the most important changes in release v3.42.0.

<details>

<summary>New functionality</summary>

* SCIM API management in the UI
* Atlassian Cloud built-in connector
* Gateway-based imports for custom sources

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Support for immediately copying registration links when creating user accounts
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* Removal of the `ScimPassword` configuration option
* `plv8` extension for PostgreSQL must be available
* New configuration options for gateway authentication

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### SCIM API management in the UI <a href="#h_01h9mxgpqs7sd6b0ewt9frpxbs" id="h_01h9mxgpqs7sd6b0ewt9frpxbs"></a>

The v3.42.0 release makes it possible for administrators to manage Elimity Insights' SCIM API in the UI. More specifically, they can enable, disable and regenerate tokens for the API in the new 'SCIM API' tab on the 'Advanced settings' page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FthgInw6x6mSNW2h732rW%2Fimage.png?alt=media&amp;token=74d68f40-49a4-47d1-8c05-977a10c1273a" alt=""><figcaption></figcaption></figure>

Refer to [our dedicated documentation](/reference-manual/advanced-topics/scim-provisioning) for additional information about Elimity Insights' SCIM API.

### Atlassian Cloud built-in connector

Elimity Insights v3.42.0 also includes a built-in connector for Atlassian Cloud, allowing connector admins to import users and groups their Atlassian Cloud organization. As always, [our dedicated documentation](/reference-manual/built-in-connectors/atlassian-cloud) contains additional information.

### Gateway-based imports for custom sources

The v3.42.0 release brings significant improvements for importing data into custom sources. Up until now, connector admins had to choose between manual imports, file uploads or import scripts pushing data to Elimity Insights' API. With this feature we offer an alternative to the import scripts that both requires less maintenance and is more user-friendly. More specifically, connector admins can now enable gateway-based imports for custom sources in the new 'CONFIG' tab on the source's detail page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FFdnY3Ve0OYerAgNhFffq%2Fimage.png?alt=media&amp;token=ab4f014a-6beb-4353-ad0a-cdc631ac2925" alt=""><figcaption></figcaption></figure>

Refer to [our dedicated documentation page](/reference-manual/advanced-topics/gateway-based-imports) for additional information about this feature.

## Bug fixes & improvements

### Support for immediately copying registration links when creating user accounts

From v3.42.0 onwards admins can immediately copy registration links when they (re)send invitation emails for new user accounts:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2F6XMh7eevV0OuCrvmrlRz%2Fimage.png?alt=media&amp;token=310de678-2ede-49d3-a413-aae594727faf" alt=""><figcaption></figcaption></figure>

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* [The SAP SuccessFactors built-in connector](/reference-manual/built-in-connectors/sap-successfactors) includes a new 'status' attribute type.
* Two new endpoints are available for clients authenticating with API tokens: `GET /api/agent/stored-queries;format=json` and `GET /api/agent/scopes`.
* We renamed the 'Azure AD' built-in connector to 'Entra ID', including related documentation.

## Deployment changes

### Removal of the `ScimPassword` configuration option

Since Elimity Insights now supports UI-based management of its SCIM API, the `ScimPassword` configuration value in `secrets.yml` is no longer effective. Migrating to v3.42.0 disables the API, customers using SCIM should re-enable it in the UI, which means Elimity Insights will generate a new token. Please contact your Elimity representative if you want to migrate your original `ScimPassword` value to v3.42.0.

### `plv8` extension for PostgreSQL must be available

From v3.42.0 onwards Elimity Insights uses the `plv8` extension in its database. On-premise customers must make sure this extension is available in their PostgreSQL server:

* Customers using 'Azure Database for PostgreSQL - Flexible Server' should make sure the `plv8` extension is allowed; refer to [the official documentation](https://learn.microsoft.com/en-us/azure/postgresql/extensions/how-to-allow-extensions?tabs=allow-extensions-portal) for additional information.
* For customers using 'Cloud SQL for PostgreSQL' by Google: this extension should just always be available. However, you'll need to (temporarily) grant the `cloudsqlsuperuser` role for the SQL user performing this migration.

Please contact your Elimity representative if you need additional assistance with ensuring `plv8` is available.

### New configuration options for gateway authentication

As mentioned previously, the v3.42.0 release includes a new feature for importing data into custom sources. Server administrators can configure how Elimity Insights should authenticate when contacting gateways to perform imports. The snippet below summarizes every new configuration option (all in `secrets.yml`), please refer to [our dedicated documentation](/reference-manual/advanced-topics/gateway-based-imports) for additional information.

```yaml
# EnableGatewayOAuth2
# ----------------------------
#
# Data type: boolean
#
# Status: Optional
#
# Default value: false
#
# Description: Determines whether Elimity Insights should use OAuth2 for authentication to gateways.

# GatewayOAuth2ClientId
# ----------------------------
#
# Data type: string
#
# Status: Required if `EnableGatewayOAuth2` is `true`
#
# Description: OAuth2 client ID to use when retrieving an access token for gateway authentication.

# GatewayOAuth2ClientSecret
# ----------------------------
#
# Data type: string
#
# Status: Required if `EnableGatewayOAuth2` is `true`
#
# Description: OAuth2 client secret to use when retrieving an access token for gateway authentication.

# GatewayOAuth2EndpointParams
# ----------------------------
#
# Data type: record[string]
#
# Status: Optional
#
# Description: Object mapping extra OAuth2 token endpoint parameters to `Expr` programs.

# GatewayOAuth2TokenUrl
# ----------------------------
#
# Data type: string
#
# Status: Required if `EnableGatewayOAuth2` is `true`
#
# Description: OAuth2 token URL to use when retrieving an access token for gateway authentication.
```

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.41.x to v3.42.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.42.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.42.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

Customers that set up a container-based installation of Elimity Insights can simply bump the server image version. If you're using plain executables, copy the following files from the v3.42.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database <a href="#h_01jbc65m99c2bwscx5jmhccxey" id="h_01jbc65m99c2bwscx5jmhccxey"></a>

Customers that set up a container-based installation of Elimity Insights should refer to [our dedicated installation documentation](/reference-manual/installation/elimity-insights-server#upgrades) for detailed upgrade instructions. If you're using plain executables, the database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-linux-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-linux-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-linux-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.42'
```


# v3.41.0

We are happy to announce release v3.41.0 of Elimity Insights, released on 11 June 2025.

## Summary

This section summarizes the most important changes in release v3.41.0.

<details>

<summary>New functionality</summary>

* Delinea Secret Server built-in connector
* Jira Data Center built-in connector
* Flexible file uploads

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Fix overly strict application of specific access profile combinations
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### Delinea Secret Server built-in connector <a href="#h_01h9mxgpqs7sd6b0ewt9frpxbs" id="h_01h9mxgpqs7sd6b0ewt9frpxbs"></a>

Elimity Insights v3.41.0 includes support for Delinea Secret Server in its built-in connector library. This new connector imports users, groups, roles, folders and secrets from your Delinea Secret Server instance. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/delinea-secret-server-cloud) for more details.

### Jira Data Center built-in connector

The v3.41.0 release also includes a built-in connector for Jira Data Center, allowing connector admins to import users, groups, roles and projects from their Jira Data Center instances. As always, [our dedicated documentation](/reference-manual/built-in-connectors/jira-data-center) contains additional information.

### Flexible file uploads

The v3.41.0 release also brings significant improvements for data imports via file uploads. More specifically, users with import access will now see a new 'file uploads' tab on the source details page.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FykcpgUKD11baPLtuCWPc%2Fimage.png?alt=media&amp;token=74e6ca3f-52d6-470a-b8de-7b174b7affc0" alt=""><figcaption></figcaption></figure>

This feature allows users to define which file uploads they expect for a data import and how to transform them into entities and relationships. Refer to [our dedicated documentation](/reference-manual/advanced-topics/flexible-file-uploads) for more details.

## Bug fixes & improvements

### Fix overly strict application of specific access profile combinations

Up until v3.41.0, Elimity Insights would sometimes apply specific combinations of access profiles too strictly. More specifically, in certain circumstances users would not see some attribute types even though they did have an access profile that granted the necessary permissions. The v3.41.0 release fixes this issue. If you're using multiple access profiles that each grant access to specific attributes of the same source, we recommend verifying that this bugfix actually results in the behaviour you want. Most of our customers aren't affected at all.

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* [The Azure built-in connector](/reference-manual/built-in-connectors/azure) includes 'kind' and 'subscription' attributes for roles.
* The source logs table now includes an 'auto-refresh' toggle to facilitate copy-pasting log lines.
* We added extra out-of-the-box controls for some built-in connectors (e.g. Active Directory, Azure AD and SharePoint).
* We updated all external links to our old knowledge base ([support.elimity.com](https://support.elimity.com/)); they now bring you to [docs.elimity.com](https://docs.elimity.com/).

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.40.x to v3.41.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.41.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.41.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

Customers that set up a container-based installation of Elimity Insights can simply bump the server image version. If you're using plain executables, copy the following files from the v3.41.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database <a href="#h_01jbc65m99c2bwscx5jmhccxey" id="h_01jbc65m99c2bwscx5jmhccxey"></a>

Customers that set up a container-based installation of Elimity Insights should refer to [our dedicated installation documentation](/reference-manual/installation/elimity-insights-server#upgrades) for detailed upgrade instructions. If you're using plain executables, the database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-linux-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-linux-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-linux-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.41'
```


# v3.40.0

We are happy to announce release v3.40.0 of Elimity Insights, released on 29 April 2025.

## Summary

This section summarizes the most important changes in release v3.40.0.

<details>

<summary>New functionality</summary>

* NTFS built-in connector
* Custom mail server support

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Invite multiple users via comma-separated list of email addresses
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

* Support for container-based deployments
* New configuration option for custom mail server support
* New mail server configuration options

</details>

## New functionality <a href="#h_01h9mxgpqsnkh8tpyx32gwcbsr" id="h_01h9mxgpqsnkh8tpyx32gwcbsr"></a>

### NTFS built-in connector <a href="#h_01h9mxgpqs7sd6b0ewt9frpxbs" id="h_01h9mxgpqs7sd6b0ewt9frpxbs"></a>

Elimity Insights v3.40.0 includes support for NTFS in its built-in connector library. This new connector imports trustees, access rights and files from your NTFS file systems. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/ntfs) for more details.

### Custom mail server support <a href="#h_01jd4xyrcvsv9f34bfjghqg98w" id="h_01jd4xyrcvsv9f34bfjghqg98w"></a>

The v3.40.0 release also adds support for admins to configure a custom mail server. If the `SupportCustomMailServer` system configuration option is enabled, then Elimity Insights will show an additional tab on the new advanced settings page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FzuqdaQVjbYhEupov4RAX%2Fimage.png?alt=media&amp;token=f5780887-d74e-4e8d-a593-ad36b1a4324c" alt=""><figcaption></figcaption></figure>

This feature allows admins to override the system-configured mail server, which is mainly useful for our SaaS customers.

## Bug fixes & improvements

### Invite multiple users via comma-separated list of email addresses <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

The v3.40.0 release includes a slight redesign of the user account invitation UI. Instead of manually adding email addresses one-by-one to invite multiple users, admins can now enter all email addresses in one comma-separated line.

### Minor bug fixes & improvements <a href="#h_01js1h4hg2ekpaqj0a5kpn1hc0" id="h_01js1h4hg2ekpaqj0a5kpn1hc0"></a>

As always, this new release brings some smaller bug fixes and improvements:

* [The Google Workspace built-in connector](/reference-manual/built-in-connectors/google-workspace) includes a 'type' attribute for group roles.
* [The SharePoint built-in connector](/reference-manual/built-in-connectors/sharepoint) can now also speed up site listing using multiple workers.
* [The Vercel built-in connector](/reference-manual/built-in-connectors/vercel) includes a 'type' attribute for project roles and team roles.
* Date picker components in the UI now use a European instead of American locale.

## Deployment changes

### Support for container-based deployments <a href="#h_01js1h5k9app499gtxrx38e4cm" id="h_01js1h5k9app499gtxrx38e4cm"></a>

From v3.40.0 onwards we provide Docker images for both the Elimity Insights server and the database migration script. We highly recommend container-based deployments for all on-prem deployments, but existing customers can keep using plain executables as usual. Refer to [our documentation about installing Elimity Insights servers](/reference-manual/installation/elimity-insights-server) for more details.

### New configuration option for custom mail server support <a href="#h_01js1h5wv9pzcd46np330rr08t" id="h_01js1h5wv9pzcd46np330rr08t"></a>

Elimity Insights now allows enabling custom mail server support by setting the `SupportCustomMailServer` configuration option to `true` in `elimity.yml`:

```yaml
# SupportCustomMailServer
# ----------------------------
#
# Data type: boolean
#
# Status: Optional
#
# Default value: false
#
# Description: determines whether admins can configure a custom mail server
```

### New mail server configuration options <a href="#h_01js1h65t1xmcesf4p8g8trtfp" id="h_01js1h65t1xmcesf4p8g8trtfp"></a>

This release adds a few new system configuration options in `secrets.yml` related to Elimity Insights' connection with a mail server:

```yaml
# SMTPEnableAuth
# ----------------------------
#
# Data type: boolean
#
# Status: Optional
#
# Default value: true
#
# Description: determines whether Elimity Insights should authenticate to the configured SMTP server

# SMTPEnableOAuth2
# ----------------------------
#
# Data type: boolean
#
# Status: Optional
#
# Default value: false
#
# Description: determines whether Elimity Insights should use OAuth2 for authentication to the configured SMTP server

# SMTPOAuth2ClientId
# ----------------------------
#
# Data type: string
#
# Status: Required if `SMTPEnableAuth` and `SMTPEnableOAuth2` are enabled
#
# Description: the client ID for OAuth2 authentication to the configured SMTP server

# SMTPOAuth2ClientSecret
# ----------------------------
#
# Data type: string
#
# Status: Required if `SMTPEnableAuth` and `SMTPEnableOAuth2` are enabled
#
# Description: the client secret for OAuth2 authentication to the configured SMTP server

# SMTPOAuth2Scope
# ----------------------------
#
# Data type: string
#
# Status: Required if `SMTPEnableAuth` and `SMTPEnableOAuth2` are enabled
#
# Description: the scope for OAuth2 authentication to the configured SMTP server

# SMTPOAuth2TokenUrl
# ----------------------------
#
# Data type: string
#
# Status: Required if `SMTPEnableAuth` and `SMTPEnableOAuth2` are enabled
#
# Description: the token URL for OAuth2 authentication to the configured SMTP server
```

For most customers the existing configuration should remain working as expected. However, customers that explicitly opt out of SMTP authentication by omitting the `SMTPUser` configuration option must now set `EnableSMTPAuth` to `false`.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.39.x to v3.40.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.40.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.40.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

Customers that set up a container-based installation of Elimity Insights can simply bump the server image version. If you're using plain executables, copy the following files from the v3.40.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database <a href="#h_01jbc65m99c2bwscx5jmhccxey" id="h_01jbc65m99c2bwscx5jmhccxey"></a>

Customers that set up a container-based installation of Elimity Insights should refer to [our dedicated installation documentation](/reference-manual/installation/elimity-insights-server#upgrades) for detailed upgrade instructions. If you're using plain executables, the database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-macos-x86_64`
* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.40'
```


# v3.39.1

We are happy to announce release v3.39.1 of Elimity Insights, released on 10 April 2025.

## Summary

This section summarizes the most important changes in release v3.39.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Improve query parser performance

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Improve query parser performance <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

The v3.39.1 release includes performance improvements for Elimity Insights' query parser. This change mainly affects customers building queries with a considerable complexity and nesting depth.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.39.x to v3.39.1, we suggest the following steps:

1. Make a backup of your existing installation directory.
2. Migrate your installation by installing the files for v3.39.1, as described below.
3. Start the server and validate that it works as before.

### Installing the files for v3.39.1 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.39.1, copy the following files from the v3.39.1 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`


# v3.39.0

We are happy to announce release v3.39.0 of Elimity Insights, released on 27 March 2025.

## Summary

This section summarizes the most important changes in release v3.39.0.

<details>

<summary>New functionality</summary>

* DocuSign built-in connector
* Reordering entity types for custom sources

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

*None*

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## New functionality

### DocuSign built-in connector <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

Elimity Insights v3.39.0 includes support for DocuSign in its built-in connector library. This new connector imports users, groups and permission profiles from your DocuSign environment. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/docusign) for more details.

### Reordering entity types for custom sources

The v3.39.0 release also includes support for reordering entity types of custom sources. Connector admins can now use the edit dialog on entity types' detail pages to adjust their ordering:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FSJYKPOB6x3uyGbQpd5HP%2Fimage.png?alt=media&amp;token=7fb1dab1-1956-460a-91de-5e2ea635c0bd" alt=""><figcaption></figcaption></figure>

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.38.x to v3.39.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.39.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.39.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.39.0, copy the following files from the v3.39.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database

The database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-macos-x86_64`
* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.39'
```


# v3.38.0

We are happy to announce release v3.38.0 of Elimity Insights, released on 6 March 2025.

## Summary

This section summarizes the most important changes in release v3.38.0.

<details>

<summary>New functionality</summary>

* Adobe built-in connector
* SharePoint built-in connector

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Directness labels in peer review Excel downloads
* GitHub built-in connector improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## New functionality

### Adobe built-in connector <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

Elimity Insights v3.38.0 includes support for Adobe in its built-in connector library. This new connector imports users and groups from your Adobe environment. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/adobe) for more details.

### SharePoint built-in connector

The v3.38.0 release also includes a built-in connector for SharePoint, allowing connector admins to import users, groups, roles, files and sites from their SharePoint tenants. As always, [our dedicated documentation](/reference-manual/built-in-connectors/sharepoint) contains additional information.

## Bug fixes & improvements <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

### Directness labels in peer review Excel downloads

The v3.38.0 release adds support for directness labels to Excel downloads on the peer review page. More specifically, the resulting spreadsheets will now use 'd', 'i' and 'di' instead of 'v' if you enabled the 'Show directness' option before downloading.

### GitHub built-in connector improvements

Elimity Insights v3.38.0 also includes a few minor improvements for the GitHub built-in connector:

* Imported repositories now include an additional 'visibility' attribute.
* Outside collaborators are no longer incorrectly linked to at most one repository.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.37.x to v3.38.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.38.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.38.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.38.0, copy the following files from the v3.38.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database

The database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-macos-x86_64`
* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.38'
```


# v3.37.0

We are happy to announce release v3.37.0 of Elimity Insights, released on 29 January 2025.

## Summary

This section summarizes the most important changes in release v3.37.0.

<details>

<summary>New functionality</summary>

* Salesforce connector
* Resumable access reviews
* In-place editing of stored queries
* Excel download for connector logs
* Autofilling campaign template assignees

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Traces dialog legend
* Creating peer review collections or campaign templates from data tables
* Access review filtering, sorting and exporting
* Connector improvements
  * Google Workspace
  * Windows File Shares
  * Lansweeper
* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## New functionality

### Salesforce connector <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

Elimity Insights v3.37.0 includes support for Salesforce in its built-in connector library. This new connector imports users, profiles and permissions from your Salesforce environment. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/adobe) for more details.

### Resumable access reviews

The v3.37.0 release also allows access reviewers to save their work and resume it later. More specifically, the access review wizard now includes a 'SAVE AS DRAFT' button:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FRFlcwr61I59aJlqdrqwH%2Fimage.png?alt=media&amp;token=4332a881-ac3b-4338-931e-84a9bc0a6454" alt=""><figcaption></figcaption></figure>

Access reviewers can simply click this button at any point during their review and safely close their window afterwards. Just revisit the access review's request link to resume where you left off.

### In-place editing of stored queries

Another new feature in v3.37.0 is support for in-place editing of stored queries. This allows users to correct mistakes in newly created queries:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2F5wCpLNSVMfBG145d0YlD%2Fimage.png?alt=media&amp;token=2f82a027-01f3-4884-b588-24c8d11e3f27" alt=""><figcaption></figcaption></figure>

However, it is important to notice that editing stored queries with historical data and/or links to dashboard cards might have undesirable effects. Elimity Insights clearly explains this:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2Fk7Tcr1AHx5sKFULvZBV5%2Fimage.png?alt=media&amp;token=7dfdc110-e5f3-439a-bc2b-85ca5851aa63" alt=""><figcaption></figcaption></figure>

### Excel download for connector logs

Elimity Insights v3.37.0 supports exporting connector logs to an Excel sheet. Connector admins can now simply click the 'DOWNLOAD AS EXCEL' button on the connector logs page:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FBMAUMhmAivLMauJSmIvo%2Fimage.png?alt=media&amp;token=477abfb1-2d1f-42c0-b517-cf5b00693cb5" alt=""><figcaption></figcaption></figure>

### Autofilling campaign template assignees

Additionally, the v3.37.0 release supports autofilling campaign template assignees. This helps access review managers with providing assignee names and emails for their campaign templates. More specifically, they can click the 'AUTOFILL' button in the campaign template assignee table:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FxRIwPtRWI4tpj1FPDs69%2Fimage.png?alt=media&amp;token=4bc981e7-7ffb-413c-a718-1295a42fdc22" alt=""><figcaption></figcaption></figure>

Clicking this button shows a dialog explaining how this feature works. The screenshot below shows an example of autofilling access review assignees for Active Directory users grouped by manager:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FzQEtrNzRRlyagl0KMQvK%2Fimage.png?alt=media&amp;token=e9cd6693-f505-4f5e-b0dd-10ee2ebe19fe" alt=""><figcaption></figcaption></figure>

The example configuration you see in the screenshot above automatically fills in the assigned manager's display name and email address for almost every access review in the campaign template:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FVlv8KcdM7pi6fi1eVZCz%2Fimage.png?alt=media&amp;token=c73503bb-92ee-49a2-a1a2-9354420d8f9e" alt=""><figcaption></figcaption></figure>

## Bug fixes & improvements <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

### Traces dialog legend

Traces dialogs in Elimity Insights v3.37.0 now also show a legend to clarify the node colors:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2F0hTyxPifu051byELN21T%2Fimage.png?alt=media&amp;token=25a0199d-4621-470d-97e8-7b0eccaf97b0" alt=""><figcaption></figcaption></figure>

### Creating peer review collections or campaign templates from data tables

From Elimity Insights v3.37.0 onwards, users can now also create peer review collections or campaign templates from data tables. More specifically, they can click the 'Create peer review collection' or 'Create campaign template' button in any data table's overflow menu:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FqOWFggpWiw4ZAsb4QMbL%2Fimage.png?alt=media&amp;token=fd7957f5-c3be-4a47-a7fd-4aa6a6dd7b15" alt=""><figcaption></figcaption></figure>

This button simply opens the peer review collection or campaign template wizard and pre-fills the initial step with the data tables underlying query:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FvrCsE4VjpI6Eac8DeEJo%2Fimage.png?alt=media&amp;token=4a9d99e9-be30-4418-8bae-ac0163c2f7ab" alt=""><figcaption></figcaption></figure>

### Access review filtering, sorting and exporting <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

The v3.37.0 release also brings some UI improvements to the campaign overview page. Access review managers can now filter, sort and export the access reviews in their campaigns. Additionally, Elimity Insights now shows which access reviews are overdue:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FTAAfw5IWJ9aX5cKGquKt%2Fimage.png?alt=media&amp;token=bb2c89f2-df16-4104-b6a3-41d6c669b030" alt=""><figcaption></figcaption></figure>

### Minor bug fixes & improvements <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

As always, this new release brings some smaller bugfixes and improvements:

* Campaign template assignee tables now also show a row count when all groups have been assigned.
* Query conditions on stored query pages now show source information for each entity type.
* The query condition dialog no longer trips up when searching for empty strings.
* Entity links in change request overview tables are now escaped correctly.
* [The Google Workspace connector](/reference-manual/built-in-connectors/google-workspace) supports importing external groups.
* [The Windows file shares connector](/reference-manual/built-in-connectors/windows-file-shares) has been replaced by [the Windows file shares import agent](https://docs.elimity.com/import-agents-windows-file-shares/) and now immediately logs an error message explaining this.
* Similarly, [the generic SQL import agent](https://docs.elimity.com/import-agents-sql/) now replaces [the Lansweeper connector](/reference-manual/built-in-connectors/lansweeper).

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.36.x to v3.37.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.37.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.37.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.37.0, copy the following files from the v3.37.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database

The database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-macos-x86_64`
* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.37'
```


# v3.36.0

We are happy to announce release v3.36.0 of Elimity Insights, released on 27 November 2024.

## Summary

This section summarizes the most important changes in release v3.36.0.

<details>

<summary>New functionality</summary>

* SAP SuccessFactors built-in connector
* Vercel built-in connector

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## New functionality

### SAP SuccessFactors built-in connector <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

Elimity Insights v3.36.0 includes support for SAP SuccessFactors in its built-in connector library. This new connector imports users from your SAP SuccessFactors environment. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/sap-successfactors) for more details.

### Vercel built-in connector

Another new entry in Elimity Insights' connector library is Vercel. The Vercel connector imports users, projects and teams from your Vercel account. As always, [our dedicated documentation](/reference-manual/built-in-connectors/vercel) contains additional information.

## Bug fixes & improvements <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

### Minor bug fixes & improvements

As always, the new release also brings some minor improvements:

* Elimity Insights v3.36.0 fixes some minor UI bugs:
  * radio buttons for selecting user account roles now render properly
  * no more double scrollbars in dashboard card setup dialogs
  * time series dashboard cards of height 1 no longer have a broken appearance
* this release also includes some changes to existing built-in connectors:
  * [the GitHub built-in connector](/reference-manual/built-in-connectors/github) now also explicitly imports repository permission types
  * [the Google Workspace built-in connector](/reference-manual/built-in-connectors/google-workspace) supports filtering users and groups, and includes external group members

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.35.x to v3.36.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.36.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.36.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.36.0, copy the following files from the v3.36.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database

The database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-macos-x86_64`
* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.36'
```


# v3.35.1

We are happy to announce release v3.35.1 of Elimity Insights, released on 20 November 2024.

## Summary

This section summarizes the most important changes in release v3.35.1.

<details>

<summary>New functionality</summary>

*None*

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Ensure Jira connector processes large amounts of users and groups correctly

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## Bug fixes & improvements

### Ensure Jira connector processes large amounts of users and groups correctly

This release fixes an issue related to the Jira connector not correctly processing large amounts of users and groups. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/jira) for additional information.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.35.x to v3.35.1, we suggest the following steps:

1. Make a backup of your existing installation directory.
2. Migrate your installation by installing the files for v3.35.1, as described below.
3. Start the server and validate that it works as before.

### Installing the files for v3.35.1 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.35.1, copy the following files from the v3.35.1 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`


# v3.35.0

We are happy to announce release v3.36.0 of Elimity Insights, released on 4 October 2024.

## Summary

This section summarizes the most important changes in release v3.35.0.

<details>

<summary>New functionality</summary>

* Google Workspace built-in connector

</details>

<details>

<summary>Bug fixes &#x26; improvements</summary>

* Minor bug fixes & improvements

</details>

<details>

<summary>Deployment changes</summary>

*None*

</details>

## New functionality

### Google Workspace built-in connector <a href="#h_01jqbxbjm9znha3yj0t3gv2p9f" id="h_01jqbxbjm9znha3yj0t3gv2p9f"></a>

Elimity Insights v3.35.0 adds a new entry to the built-in connector library: Google Workspace. This new connector imports users and groups from your Google Workspace or Cloud Identity environment. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/google-workspace) for more details.

## Bug fixes & improvements <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

### Minor bug fixes & improvements

As always, the new release also brings some minor improvements. From v3.35.0 onwards, the GitHub built-in connector will import custom property values for each repository. Refer to [our dedicated documentation](/reference-manual/built-in-connectors/github) for more information.

## Migration information <a href="#h_01h9mxgpqs599yv2hb64zhwdk9" id="h_01h9mxgpqs599yv2hb64zhwdk9"></a>

To migrate from v3.34.x to v3.35.0, we suggest the following steps:

1. Make a backup of your existing database.
2. Make a backup of your existing installation directory.
3. Migrate your installation by installing the files for v3.35.0, as described below.
4. Migrate your database, as described below.
5. Start the server and validate that it works as before.

### Installing the files for v3.35.0 <a href="#h_01h9mxgpqsdj7y3gp98dbbb8hy" id="h_01h9mxgpqsdj7y3gp98dbbb8hy"></a>

To install Elimity Insights v3.35.0, copy the following files from the v3.35.0 release to your current installation folder:

* The appropriate binary of Elimity Insights for your OS:
  * `elimity-insights-linux-x86_64`
  * `elimity-insights-macos-x86_64`
  * `elimity-insights-windows-x86_64.exe`
* The appropriate binary of the database migration tool for your OS:
  * `elimity-insights-database-migrate-macos-x86_64`
  * `elimity-insights-database-migrate-linux-x86_64`
  * `elimity-insights-database-migrate-windows-x86_64.exe`

### Migrating the database

The database migration is performed by running one of the following executables depending on your OS:

* `elimity-insights-database-migrate-macos-x86_64`
* `elimity-insights-database-migrate-linux-x86_64`
* `elimity-insights-database-migrate-windows-x86_64.exe`

You can use the command line argument `help` to get help info:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 help
```

You can use the command line argument `target-versions` to display the list of supported target versions:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 target-versions
```

To migrate your database, use a command similar to the following:

```shell-session
$ ./elimity-insights-database-migrate-macos-x86_64 migrate -dsn 'postgresql://<postgres-user>:<postgres-password>@<your-host>:5432/<your-elimity-db-name>' -target-version 'v3.35'
```


# Gateways and import agents

Elimity Insights gateways act as an intermediary between some of the built-in connectors in Elimity Insights and the source systems they pull data from. SaaS customers should typically not install or configure any gateways at all, since Elimity Insights will default to using the gateways managed by Elimity itself. On-prem customers however might consider self-hosting these gateways because of firewall restrictions.

Import agents on the other hand are often useful for both SaaS and on-prem customers. They facilitate importing from custom source systems like an SQL database server or LDAP directory. Import agents independently push data to an Elimity Insights custom source, following a schedule configured by the customer.

These pages provides more information about installing and upgrading Elimity Insights gateways and import agents.


# Prerequisites

We distribute all Elimity Insights gateways and import agents as OCI images for both Linux and Windows Server hosts. In most cases our recommendation for deploying these is to use a CaaS solution like Google Cloud Run or Azure Container Apps. Elimity Insights gateways typically are stateless HTTP servers that match most cloud providers' definition of a microservice, while import agents can run as a standalone job. Using a CaaS solution has the following advantages:

* No manual VM management
* Encrypted connections to gateways via out-of-the box HTTPS reverse proxy
* Cost-effective since you only pay when the gateway / agent is actually importing
* Great integration with your cloud provider's key vault for mounting secrets
* Configuration / monitoring / upgrades via your cloud provider's user-friendly UI

If using your cloud provider's container hosting solution is not an option, then refer to [our documentation about installing Docker](/technical-guides/working-with-containers/manual-deployments-with-docker-engine) (and Docker Compose, which we also recommend) on your server manually.


# Deployment examples

As mentioned previously, we recommend deploying Elimity Insights gateways and import agents using a CaaS solution. Refer to the following shell commands as an example of how to transfer an LDAP import agent image to your Azure Container Registry for deployment in Azure Container Apps:

```sh
# Step 1: Pull the original image from Elimity's Google Cloud artifact registry
# make sure you have installed and configured Google's credential helper for Docker
$ docker pull europe-west1-docker.pkg.dev/elimity-general/docker/ldap-import-agent:v2.0.1

# Step 2: Create an alias for the pulled image to use in your Azure Container Registry
$ docker tag \
    europe-west1-docker.pkg.dev/elimity-general/docker/ldap-import-agent:v2.0.1
    myregistry.azurecr.io/elimity-insights/ldap-import-agent:v2.0.1

# Step 3: Push the alias to your Azure Container Registry.
# Make sure you have configured Docker to authenticate with Azure Container Registry
$ docker push myregistry.azurecr.io/elimity-insights/ldap-import-agent:v2.0.1
```

If deploying using a CaaS solution is not an option, then refer to the following Docker Compose specification for an example of how to deploy an LDAP import agent and a Vercel gateway manually on Windows Server 2022:

```yaml
services:
  ldap-import-agent:
    image: europe-west1-docker.pkg.dev/elimity-general/docker/ldap-import-agent:v2.0.1-nanoserver-ltsc2022
    restart: always
    volumes:
      - ./config:C:/app/config

  vercel-gateway:
    image: europe-west1-docker.pkg.dev/elimity-general/docker/vercel-gateway:v1.1.3-nanoserver-ltsc2022
    ports:
      - 8080:80
    restart: always
```


# Working with containers

We provide OCI images for every component in a deployment of Elimity Insights. Typically we publish multiple variants to support different platforms (e.g. Linux, Windows Server 2019, Windows Server 2022, ...). In general our recommendation for deploying these images is to use a CaaS solution like Google Cloud Run or Azure Container Apps. We do however also support manual deployments on e.g. Windows Server with Docker Engine.


# Container registry

We host the Elimity Insights gateways and import agents in our own Google Cloud artifact registry at `europe-west1-docker.pkg.dev/elimity-general/docker`.

## Naming convention

We provide images for usage on Linux and Windows. These images are labeled with the following naming convention:

* Every release is given a version number (e.g. `v1.2.0`)
* Linux images are labeled with this version number without suffix (e.g. `v1.2.0`)
* Windows images are labeled with a suffix for the specific version of Windows (e.g. `v1.2.0-nanoserver-ltsc2022` for Windows Server 2022)

## Authentication

You can log in to our registry using your customers.elimity.com account. Contact your Elimity representative if you don't have such an account yet.

We recommend installing [Google's credential helper for Docker](https://cloud.google.com/artifact-registry/docs/docker/authentication#standalone-helper) to simplify the authentication process during using Docker. To do so, download the latest release as explained on that page and set it up using the instructions shown [here](https://github.com/GoogleCloudPlatform/docker-credential-gcr#configuration-and-usage). In this case the registry domain to add is `europe-west1-docker.pkg.dev`. After configuring, log in with the Docker credential helper and you can pull images from our container registry using the standard `docker` or `docker-compose` CLI.


# Manual deployments with Docker Engine

If using a CaaS solution is not an option, then another alternative we support is a manual deployment with Docker Engine. This page provides some additional guidance on how to install and use Docker Engine and Docker Compose (which we also recommend to simplify container management).

## Installation

### Docker Engine and Docker Compose

The exact steps to install Docker Engine and Docker Compose depend on your host platform:

{% tabs %}
{% tab title="Windows Server" %}

1. Run Microsoft's official PowerShell script to install Docker Engine as explained in [their documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-2).
2. Install Docker Compose standalone as explained in [the official documentation](https://docs.docker.com/compose/install/standalone/#on-windows-server). Note that you should place the `docker-compose.exe` file next to `docker.exe`, which probably is in `C:\Windows\System32`.
3. Verify that both `docker` and `docker-compose` CLIs are installed correctly.
   {% endtab %}

{% tab title="Linux" %}

1. Follow the steps outlined in [the official installation manual](https://docs.docker.com/engine/install/) to install Docker Engine for your specific OS.
2. Verify that both the `docker` and `docker compose` CLIs are installed correctly.
   {% endtab %}
   {% endtabs %}

### GCR Docker credential helper

As mentioned in [the documentation about our container registry](/technical-guides/working-with-containers/container-registry) we host our images in a Google Cloud Artifact Registry at `europe-west1-docker.pkg.dev`. To pull images from this registry, authenticating with a customers.elimity.com account is required. We recommend installing Google's credential helper for Docker to facilitate this process. Refer to [their official documentation](https://cloud.google.com/artifact-registry/docs/docker/authentication#standalone-helper) for detailed instructions. Verify that the `docker-credential-gcr` CLI is installed correctly and listed in your system `PATH`. Now execute the following commands to configure the credential helper:

{% tabs %}
{% tab title="Windows Server" %}

<pre class="language-powershell"><code class="lang-powershell">PS C:\> docker-credential-gcr configure-docker --registries europe-west1-docker.pkg.dev
<strong>PS C:\> docker-credential-gcr gcr-login
</strong></code></pre>

{% endtab %}

{% tab title="Linux" %}

```shell-session
$ sudo docker-credential-gcr configure-docker --registries europe-west1-docker.pkg.dev
$ docker-credential-gcr gcr-login
```

{% endtab %}
{% endtabs %}

You can now test the credential helper by pulling one of our images:

{% tabs %}
{% tab title="Windows Server" %}

<pre class="language-powershell"><code class="lang-powershell"><strong>PS C:\> docker pull europe-west1-docker.pkg.dev/elimity-general/docker/insights:v3.40.0
</strong></code></pre>

{% endtab %}

{% tab title="Linux" %}

```shell-session
$ sudo docker pull europe-west1-docker.pkg.dev/elimity-general/docker/insights:v3.40.0
```

{% endtab %}
{% endtabs %}


# Container scanning policy

We perform internal container scans for all of our officially supported images. Please read [the dedicated section in our versioning policy](/versioning-policy#support) to find out which images receive official support.

More specifically we schedule a daily job that searches for vulnerabilities using a [Trivy](https://trivy.dev/) scan with standard configuration. We process the resulting findings as follows:

1. We filter out findings that do not have a severity of 'critical', 'high' or 'medium'.
2. We also filter out findings that do not have a status of 'fixed'.
3. For the remaining findings, we look at the finding's severity as dictated by the Trivy scan to determine how urgently we need to fix it. For 'critical' vulnerabilities we publish a patch release within 3 business days. Findings with a severity of 'high' or 'medium' get a fix within 9 and 27 business days respectively.

On top of this we only publish a release if at that point in time our Trivy scan finds no 'critical', 'high' or 'medium' vulnerability that has a 'fixed' status.


# Flexible File Uploads - The Basics

Learn the basics of Flexible File Uploads. Create a custom source, define a file input and define an SQL-query to import data from a CSV into entities and relationships.

## Intro

Flexible File Uploads are a powerful way to import data from systems that do not offer technical integration options such as APIs, database access, or directory protocols. They are also ideal for sources where data changes infrequently and only needs to be updated periodically (e.g. weekly, monthly, quarterly or even yearly).

This guide explains how to configure the Flexible File Upload feature step by step.

#### **Prerequisites**

Before you start, make sure that:

* You have “**Data Source Admin**” or “**Admin**” permissions in Elimity
* You know which entities, attributes and relationships you want to model in Elimity
* You have an example file (.csv, .json, etc.) that contains the data you want to import into Elimity

For the purpose of this guide we will use a simple data source named “**HRify**” from which we will import "**Employees"** as an entity type with a few attributes.

## Step 1 - Create a custom source

You can skip this step if you already have a configured source.

In the main left navigation bar, go to "**Administration"** -> "**Sources":**

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FqnxEX2bRFAmstOpyIBuo%2Funknown.png?alt=media&amp;token=f16551a3-b496-4c82-97d7-82f3dd868e8b" alt="" width="188"><figcaption></figcaption></figure>

Click "**Add Source"**:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FLUJ469L9lMK0xKCQRsxi%2Funknown.png?alt=media&amp;token=484fa1d8-907f-4bd8-a203-8d783c47b1f0" alt="" width="563"><figcaption></figcaption></figure>

Now select the "**Custom"** data source by clicking on "**Set up"**:

<br>

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FGvMxzIh4eZnPjl6eT4Qb%2Funknown.png?alt=media&amp;token=8aed2a98-beb9-4f43-a172-4cf1b4971a45" alt="" width="327"><figcaption></figcaption></figure>

In the next screen click “**Set up**”:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FEZgHEPxrSpSks1cJEiiZ%2Funknown.png?alt=media&amp;token=c78ce8c0-e2ee-4887-b169-22c8e477d015" alt="" width="563"><figcaption></figcaption></figure>

Here, we can give a name to our new custom source. In our case this will be “**HRify**”.&#x20;

Now you can define the data model either manually or via an export file.

The easiest way is to select **"Upload Export file"** and use this file to import the data model:

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

In case you want to do it manually you can select **"Manually"** and click **"Continue"**:&#x20;

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FIKZhcwsbnSt4aVp7IEvG%2Funknown.png?alt=media&amp;token=db8becac-1df7-4a37-a102-ff03d540821f" alt=""><figcaption></figcaption></figure>

In case you chose the manual flow, we need to create at least one entity type in our source. In our case we create an entity type "**Employees**" like this:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FxS4a8Qt7fEUfD3Y0CFyn%2Funknown.png?alt=media&amp;token=9ce43e14-ad2b-4b1c-beb9-489bf0f5c9f7" alt=""><figcaption></figcaption></figure>

You need to define the singular and plural forms and add an icon representing the entity type. Of course this entity type can be anything from devices, roles, folders, users, etc. depending on the source you are planning to connect.

After clicking on confirm you’ll see that we now have set up a source with one entity type in Elimity. You can now also see this new source in your list of sources in the main left navigation bar.

If you chose the manual creation of the data model you'll have to add the correct attributes to the **"Employees"** entity type. All of the attributes are of type `String`, except for `start_date` and `active`. They are of type `Date` and `Boolean` :

* `first_name`
* `last_name`
* `email`
* `department`
* `job_title`
* `employment_type`
* `start_date` (type: date)
* `active`  (type: boolean)

## Step 2 - Create a file definition

Now that our source is configured we can start defining the file(s) and query/queries needed to import data in Elimity.

In the main left navigation bar, go to "**Sources**", select the correct source ("**HRify"** in our case) and select the "**File Uploads"** tab.&#x20;

You should see the following view:<br>

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FnfhVGuPAlsjyDlKuR7kr%2Funknown.png?alt=media&amp;token=95a13123-9cc9-4192-b342-31a8f367d5c5" alt="" width="563"><figcaption></figcaption></figure>

First we start by creating a **"definition"**. Click **"Add Definition"** to create one:<br>

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FTJFDxCGCpUnqR4g3wS2K%2Funknown.png?alt=media&amp;token=b8a900ac-3859-44a3-bca3-7a294aaac465" alt="" width="563"><figcaption></figcaption></figure>

There are a few different configuration options for ‘a definition’:

* A label is required for a specific file upload. In our case we want to import employee data so we add a definition with label: **"employees"**. This label doesn’t have to be the same as the filename.
* The **"Accept"** field allows to only highlight files of a certain type when performing the upload. Here we choose for .csv as we only want users to be able to upload a .csv file.
* You can also allow multiple files to be uploaded by enabling the **"Allow multiple files"** checkbox. This can be useful if for example the data you want to upload is divided into different files.

Click **"Confirm"**. We have now created our very first file definition, which will be used as a source for querying data (see next step):<br>

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FitLmfBJocanr0fZFufqM%2Funknown.png?alt=media&amp;token=79c3bd8b-064e-4295-bf34-df4e3178b91b" alt="" width="563"><figcaption></figcaption></figure>

## Step 3 - Define a query to import data

Now that we have created our file definition, we will create a query which will parse data from the file.&#x20;

{% hint style="info" %}
Before we dive into specific queries, let’s first explain the engine behind this feature.

Behind the scenes, Elimity uses [DuckDB](https://duckdb.org/docs/stable/data/csv/overview) (a RDBMS that supports SQL) to query uploaded data.

It can be useful to review the DuckDB [documentation](https://duckdb.org/docs/stable/data/csv/overview) to become familiar with the technology.

In particular, the section on [reading from CSV files](https://duckdb.org/docs/stable/data/csv/overview) is especially useful.
{% endhint %}

As you see in the image below there are two important things to note before we start creating our first query:

1. The file definition creates an SQL query parameter `$p0` which can be used to reference the file itself in any of the defined queries.
2. The specific queries can be configured under **"Entity queries"** (or under **"Relationship queries"** if these are part of our data model). For the purpose of this article we left out Relationship queries.

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FBAOyoukwuzLtHPhSYngO%2Funknown.png?alt=media&amp;token=397720de-47bb-46f3-baf8-f7662d1ee25a" alt="" width="563"><figcaption></figcaption></figure>

Let’s start with the minimal required query to import data into Elimity. From there we can add extra attributes to finalize the query. Let’s take the CSV below as an example:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FwMynyvnPsYxXZqKMQLD3%2Funknown.png?alt=media&amp;token=de524a9e-344d-433d-b5df-1b9362fff748" alt=""><figcaption></figcaption></figure>

Our file has data on the following columns:

* `employee_id`
* `first_name`
* `last_name`
* `email`
* `department`
* `job_title`
* `employment_type`
* `start_date`
* `active`

{% hint style="success" %}
**In Elimity we only need 2 columns to make a successful data import**, namely, `id` and `name`. These must be the first two columns in the result set of our query.
{% endhint %}

For example, the following query returns two columns. The first one containing data from the `employee_id` column and the second one containing a concatenation of both the `first_name` column and the `last_name` column:

```sql
SELECT
  employee_id,
  (first_name || ' ' || last_name)
FROM READ_CSV($p0)
```

We could have worked with aliases but this is not required or isn’t used in mapping the result set to Elimity’s attributes. Only the order in which the columns are returned is important. First the `id` column, secondly the `name` column.

When we click **"Upload and import"**, data is imported in our entity type **"Employees"**:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FyELfFjUeFoZIGZ62ugum%2Funknown.png?alt=media&amp;token=3992dad8-cf7e-4040-90d9-35bfcf2f1db1" alt=""><figcaption></figcaption></figure>

Although the entity type **"Employees"** has many different attribute types other than `id` and `name`, we only need those two to be able to create entities. All the other attributes currently have a value of `Not assigned` as can be seen in the screenshot above. This was expected and is considered a good practice to get an initial version up and running.

Now that we have our first minimal query up and running we can extend it with attributes we would like to import. We do this be both defining a correct query (with the attributes in the right order) and selecting the attributes to include:

```sql
SELECT
  employee_id AS id,
  first_name || ' ' || last_name AS name,
  CAST(active AS BOOLEAN),
  department,      
  email,
  employment_type,    
  first_name,        
  job_title,                         
  last_name,                                        
  CAST(start_date AS DATE)
FROM READ_CSV($p0)
```

{% hint style="warning" %}
As you see in the query above, the attributes (coming after `id` and `name`) are **lexicographically** sorted  (first **a**ctive, then **d**epartment, then **e**mail, then **e**mployment\_type, **f**irst\_name, etc.).

This is very important to keep in mind as the import relies on the order of the columns to import the data correctly.&#x20;
{% endhint %}

Now, the only thing we need to do is select the attributes we want to import. In the edit query screen click **"Included attribute types"**: <br>

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FLM0uyddlFAPpMPFpvq0h%2Funknown.png?alt=media&amp;token=64c8f15a-0ae8-471d-9c4f-eeddc1c66225" alt="" width="563"><figcaption></figcaption></figure>

Select all the attributes you have defined in your query which you want to import in Elimity:<br>

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FhchlB7ng7JJMsbKQEfsi%2Funknown.png?alt=media&amp;token=acfdfe59-7d1e-479a-a120-712434104cb0" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="success" %}
The amount of columns in the result set of the query should match the amount attributes you want to import into Elimity + 2 (for id and name).&#x20;

For example, in our case we have **10 columns** in our **result** **set**. **2 for id and name** and **8** for all **other** **attributes** (active, department, email, employment type, first name, job title, last name and start date).<br>
{% endhint %}

If we now look at our data we see that all other attributes have been populated:

<figure><img src="https://2067057569-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7b6iwtH0Lr9Z5pj9MCO2%2Fuploads%2FK7UIcjZjno9oFFmXVgPM%2Funknown.png?alt=media&amp;token=48c432c2-8d27-4825-90c8-cb9ac6c9ae8f" alt=""><figcaption></figcaption></figure>

## Conclusion

This article demonstrated how to set up a manual CSV import in Elimity Insights with the help of a file definition and an SQL query within a custom **"HRify"** source for the "**Employees"** entity type.

The same principles that we applied to the **"Employees"** entity type apply to importing relationships. For relationships, the query must return two entity IDs followed by optional relationship attributes. This will be covered in a future article.


# Installation

Setting up a deployment of the Elimity Insights platform typically requires provisioning the following components:

* Elimity Insights server
* PostgreSQL database
* Identity provider
* Mail server
* HTTP(S) proxy

The following pages contain detailed installation instructions for each of these components.


# Elimity Insights server

The Elimity Insights server fulfills multiple roles in a deployment of the Elimity Insights platform:

* Serving the Elimity Insights web application
* Serving the Elimity Insights REST API
* Running various scheduled background tasks
  * Performing imports for built-in sources
  * Sending daily notifications for access review reminders and failed health checks

For SaaS customers we perform the setup and maintenance of Elimity Insights servers behind the scenes. These installation instructions are mainly useful for on-prem deployments.

## Installation

We distribute all Elimity Insights releases as Docker images for both Linux and Windows Server hosts. Our recommendation for deploying these is to use your cloud provider's CaaS solution for complex applications (e.g. Google Cloud App Engine flexible environment, Azure App Service, ...). Note that we don't support deploying Elimity Insights using services like Google Cloud Run and Azure Container Apps (but we do recommend these for [gateways and import agents](/technical-guides/gateways-and-import-agents)). The main reason is that Elimity Insights servers currently do not match most cloud providers' definition of a microservice:

* Elimity Insights servers build a cache on startup which might take a while.
* Elimity Insights servers do not support horizontal scaling.
* Elimity Insights servers perform long-running tasks in the background.

Services like Google Cloud App Engine flexible environment and Azure App Service however are a perfect fit for Elimity Insights servers:

* No manual VM management
* Encrypted connections to Elimity Insights via out-of-the box HTTPS reverse proxy
* Great integration with your cloud provider's key vault for mounting secrets
* Configuration / monitoring / upgrades via your cloud provider's user-friendly UI

We also support deploying manually on e.g. Windows Server if using your cloud provider's CaaS solution is not an option. In either case please refer to [our documentation about working with containers](/technical-guides/working-with-containers) for detailed setup instructions. Visit <https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/insights> to get a list of available image tags.

## Upgrades

Upgrading an Elimity Insights deployment typically requires performing the following steps:

1. Shutting down the old server
2. Backing up your database
3. Performing database migrations (not applicable for patch upgrades)
4. Updating the server (simply bumping image version for container-based installations)
5. Starting the updated server

### Database migrations

For database migrations we also provide OCI images. As usual, we recommend using a CaaS solution like Google Cloud Run or Azure Container Apps to perform database migrations as a one-off job. You can also just run the image locally using the Docker CLI:

```shell-session
$ docker run --rm europe-west1-docker.pkg.dev/elimity-general/docker/insights-database-migrate:<tag> help
Elimity Insights Database Migration CLI
Description:
  This tool applies database migrations required for upgrading Elimity Insights. It migrates the specified Postgres
  databases in-place. Note that this tool can only migrate databases for Elimity Insights v3.x. It reads from a
  configuration file at '/app/config/config.json'.

Usage: elimity-insights-database-migrate [options]

Options:
  -h, -help      Show usage information and exit
  -print-version Print version information and exit
```

To configure your migration, mount a JSON configuration file at `/app/config/config.json` with the properties listed below. Refer to the following snippet for a starting point:

```json
{
  "pgConnStr": "postgres://<user>:<password>@<host>:5432/postgres",
  "targetVersion": "v3.44",
  "pgAzureManagedIdentity": false
}
```

The table below describes each supported configuration option in more detail:

<table data-full-width="true"><thead><tr><th width="218.96484375">Configuration option</th><th>Value type</th><th>Default value</th><th width="243.40625">Description</th></tr></thead><tbody><tr><td><code>pgConnStr</code></td><td><code>string</code></td><td></td><td>The PostgreSQL connection string (e.g., <code>"postgres://&#x3C;user>:&#x3C;password>@&#x3C;host>:5432/postgres"</code>).</td></tr><tr><td><code>targetVersion</code></td><td><code>string</code></td><td></td><td>The target release version for the migration (e.g., <code>"v3.44"</code>).</td></tr><tr><td><code>pgAzureManagedIdentity</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Set to <code>true</code> to automatically retrieve an Azure AD token from Azure for database authentication.</td></tr></tbody></table>

Visit <https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/insights-database-migrate> to get a list of available tags for this specific image.


# PostgreSQL database

The Elimity Insights server manages all of its persistent data in a PostgreSQL database. For SaaS customers we perform the setup and maintenance of PostgreSQL servers behind the scenes. These installation instructions are mainly useful for on-prem deployments. We strongly recommend using your cloud provider's DBaaS offering to set up a PostgreSQL database. More specifically, Elimity Insights servers officially support PostgreSQL 17.x. The `btree_gist`, `pgcrypto` and `plv8` extensions must also be available. If using your cloud provider's DBaaS offering is not an option, then installing PostgreSQL manually on e.g. a Linux VM is also possible.

We heavily recommend creating a dedicated database and user for Elimity Insights. More specifically, we suggest the following steps:

1. Create a dedicated PostgreSQL user with no privileges and a strong authentication mechanism
2. Create a dedicated database and assign the new user as its owner


# Identity provider

All deployments of Elimity Insights must rely on an identity provider for authentication of user accounts. We implement single sign-on (SSO) using the OpenID Connect (OIDC) protocol, both Entra ID and Google Workspace support this. More specifically, use the following Elimity Insights server configuration options to set up SSO:  `oidcClientId`, `oidcClientSecret` and `oidcIssuer`. Refer to [our dedicated documentation](/reference-manual/server-configuration) for additional details. The following sections provide more information about setting up SSO in Entra ID and Google workspace.

## Entra ID

### 1. Creating an app registration

Elimity Insights 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')
   1. Name: e.g. `elimity-insights`
   2. Redirect URI platform: 'Web'
   3. Redirect URI value: `https://{host}/api/oidc/callback`, e.g. `https://example.elimity.com/api/oidc/callback`&#x20;
   4. Click 'Register'
   5. Note down the new registration's application ID and directory ID
2. Generate a client secret for the app registration ('Certificates & secrets' > 'Client secrets' > 'New client secret') and securely note down the secret value.

### 2. Configuring Elimity Insights

Having created a new app registration, you can now set the following configuration options for the Elimity Insights server:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value</th></tr></thead><tbody><tr><td><code>oidcClientId</code></td><td>Application ID you noted down in step 1.1.e</td></tr><tr><td><code>oidcClientSecret</code></td><td>Secret value you noted down in step 1.2</td></tr><tr><td><code>oidcProvider</code></td><td><code>https://login.microsoftonline.com/{tenantId}/v2.0</code> , replace <code>{tenantId}</code> with the directory ID you noted down in step 1.1.e</td></tr></tbody></table>

## Google Workspace

### 1. Creating an OAuth2 client

Follow the steps outlined in [Google's official documentation](https://support.google.com/cloud/answer/6158849) to create an OAuth2 client. Make sure you choose 'Web application' for the application type and add `https://{host}/api/oidc/callback` as an authorized redirect URI, replacing `{host}` your Elimity Insights server host. Note down the resulting client ID and secret.

### 2. Configuring Elimity Insights

Having created a new app registration, you can now set the following configuration options for the Elimity Insights server:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value</th></tr></thead><tbody><tr><td><code>oidcClientId</code></td><td>Client ID you noted down in step 1</td></tr><tr><td><code>oidcClientSecret</code></td><td>Secret value you noted down in step 1</td></tr><tr><td><code>oidcIssuer</code></td><td><code>https://accounts.google.com</code></td></tr></tbody></table>


# Mail server

Elimity Insights servers send out emails for multiple reasons:

* to invite new user accounts
* to update subscribed users when stored query results change
* to warn subscribed connector admins when imports fail
* to request access reviews

For SaaS customers we perform the setup and maintenance of mail servers behind the scenes. These installation instructions are mainly useful for on-prem deployments.

From an Elimity Insights server's point of view, the only requirement is an SMTP server to accept the outgoing emails. In practice this means you can probably just use a mail server that is already available in your organization. We currently support the following authentication options:

* None: Elimity Insights will simply send mails to your SMTP server without prior authentication.
* Direct: Elimity Insights will try a variety of 'direct' SMTP authentication options (e.g. `PLAIN`, `LOGIN`, `CRAM-MD5`, ...) using a configured username and password.
* OAuth2: Elimity Insights will exchange configured client credentials for an access token and use it together with a configured username for `XOAUTH2` authentication at your SMTP server.

For example, many of our customers use Exchange Online as their mail server for Elimity Insights. Setting this up correctly is not easy though, so we highly recommend carefully reading through [the official documentation from Microsoft](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth). Some points that require extra attention:

* the OAuth2 token URL should have the following format: `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`
* the OAuth2 scope should be `https://outlook.office365.com/.default`
* the mailbox you want to send emails from should have a license
* you should grant your app registration full access to this mailbox using PowerShell
* you should also grant the necessary API permission to your app registration:
  * 'APIs my organization uses'
  * search for 'Office 365 Exchange Online'
  * 'Application permissions'
  * 'SMTP.SendAsApp'
* you should grant admin consent for this permission


# HTTP(S) proxy

We strongly recommend including a production-grade HTTP(S) proxy in each deployment of Elimity Insights. For our SaaS customers we include this by default.

Most cloud providers offer an HTTP(S) proxy (e.g. Google Cloud Load Balancing, Azure Load Balancer) that integrates well with their CaaS / VMaaS products. If using your cloud provider's proxy is not an option, then installing one manually on e.g. Windows Server is also possible. We suggest to take a look at [Caddy](https://caddyserver.com/), a widely-used open-source HTTPS server with excellent proxying capabilities. The remainder of this page contains some additional guidelines for setting up Caddy as an HTTP(S) proxy for Elimity Insights on Windows Server.

## Installing Caddy on Windows Server

To install Caddy as an HTTP(S) proxy for Elimity Insights on Windows Server we recommend to just deploy [their official Docker image](https://hub.docker.com/_/caddy). Refer to the snippet below as a starting point for your `docker-compose.yml` file:

```yaml
services:
  caddy:
    image: caddy
    ports:
      - 80:80
      - 443:443
    restart: always
    volumes:
      - .\caddy:C:\etc\caddy

  insights:
    image: europe-west1-docker.pkg.dev/elimity-general/docker/insights:v3.41.0-nanoserver-ltsc2022
    restart: always
    volumes:
      - .\insights:C:\app\config 
```

Of course you'll also need to configure Caddy. The official documentation includes [a great tutorial about writing `Caddyfile`s](https://caddyserver.com/docs/caddyfile-tutorial), here's a template you can build on (place it at `.\caddy\Caddyfile`):

```
elimity.example.com

reverse_proxy insights

tls cert.pem key.pem
```


# Server configuration

The Elimity Insights server supports many configuration options that it reads from different locations. Most of them reside in a configuration file, but this page also lists some environment variables that might be useful.

## HJSON configuration file

To configure your Elimity Insights server, mount a HJSON configuration file at `/app/config/config.json` with the properties listed below. Alternatively, you can pass this entire HJSON object using a single environment variable: `INSIGHTS_CONFIG_HJSON`. Refer to the following snippet for a starting point:

```hjson
{
  "baseUrl": "https://example.com:8081",
  "encryptionKey": "place-base64-encoding-of-256-bit-key-here",
  "gatewayOAuth2": {
    "clientId": "gateway-client-id",
    "clientSecret": "gateway-client-secret",
    "tokenUrl": "gateway-token-url"
  },
  "mailFrom": "noreply@elimity.com",
  "mcpJwtValidation": {
    "audience": "https://example.elimity.com",
    "issuer": "https://example.eu.auth0.com/"
  },
  "oidcClientId": "your-oidc-client-id",
  "oidcClientSecret": "your-oidc-client-secret",
  "oidcIssuer": "your-oidc-issuer",
  "organisationName": "Your company",
  "pgAzureManagedIdentity": false,
  "pgConnStr": "postgres://user:password@db.yourdomain.com:port",
  "smtpAuth": {
    "mechanism": {
      "password": "example-smtp-password",
      "type": "autoDiscover"
    },
    "username": "example-smtp-user"
  },
  "smtpHostname": "example-smtp-hostname",
  "smtpPort": 1025
}
```

The table below describes each supported configuration option in more detail:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value type</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><td><code>accessReviewToolbarBackgroundColor</code></td><td><code>string</code></td><td><code>""</code></td><td>CSS specification for the background color of toolbars in access review wizards. Use <code>""</code> to stick with the default of Elimity's primary blue color.</td></tr><tr><td><code>accessReviewToolbarLogoPath</code></td><td><code>string</code></td><td><code>""</code></td><td>File path for overriding the logo of toolbars in access review wizards. We recommend using an image with a transparent background and a height/width ratio of approximately 1/7. Use <code>""</code> to stick with the default white Elimity logo.</td></tr><tr><td><code>accessReviewToolbarTextColor</code></td><td><code>string</code></td><td><code>""</code></td><td>CSS specification for the text color of toolbars in access review wizards. Defaults to white.</td></tr><tr><td><code>baseUrl</code></td><td><code>string</code></td><td></td><td>URL indicating where the Elimity Insights server is hosted, e.g. <code>http://localhost:8080</code>.</td></tr><tr><td><code>encryptionKey</code></td><td><code>string</code></td><td></td><td>Base64-encoded AES-256 key for encrypting secrets in the configured database. We suggest using a command like <code>openssl rand -base64 32</code> to generate and encode such a key.</td></tr><tr><td><code>gatewayOAuth2</code></td><td><code>option[object]</code></td><td></td><td>Configuration object describing how Elimity Insights should use OAuth2 for gateway authentication; omit to disable this feature.</td></tr><tr><td><code>gatewayOAuth2.clientId</code></td><td><code>string</code></td><td></td><td>OAuth2 client ID to use when retrieving an access token for gateway authentication.</td></tr><tr><td><code>gatewayOAuth2.clientSecret</code></td><td><code>string</code></td><td></td><td>OAuth2 client secret to use when retrieving an access token for gateway authentication.</td></tr><tr><td><code>gatewayOAuth2.endpointParams</code></td><td><code>record[string]</code></td><td></td><td>Record mapping extra OAuth2 token endpoint parameters to <a href="https://expr-lang.org/">Expr</a> programs; refer to <a href="/reference-manual/server-configuration/oauth2-endpoint-parameters-for-gateway-authentication">our dedicated documentation</a> for additional information.</td></tr><tr><td><code>gatewayOAuth2.tokenUrl</code></td><td><code>string</code></td><td></td><td>OAuth2 token URL to use when retrieving an access token for gateway authentication.</td></tr><tr><td><code>loginPageBackgroundPath</code></td><td><code>string</code></td><td><code>""</code></td><td>File path for overriding the background image on the login page. Use <code>""</code> to stick with Elimity's default image.</td></tr><tr><td><code>mailFrom</code></td><td><code>string</code></td><td></td><td>Sender address for outgoing emails.</td></tr><tr><td><code>mcpJwtValidation</code></td><td><code>option[object]</code></td><td></td><td>Token validation settings for the MCP API; omit to disable that API.</td></tr><tr><td><code>mcpJwtValidation.audience</code></td><td><code>string</code></td><td></td><td>Expected audience of MCP tokens, as configured on your MCP server.</td></tr><tr><td><code>mcpJwtValidation.issuer</code></td><td><code>string</code></td><td></td><td>URL of the provider issuing MCP tokens, as configured on your MCP server.</td></tr><tr><td><code>oidcClientId</code></td><td><code>string</code></td><td></td><td>Client identifier to use for OIDC authentication.</td></tr><tr><td><code>oidcClientSecret</code></td><td><code>string</code></td><td></td><td>Client secret to use for OIDC authentication.</td></tr><tr><td><code>oidcIssuer</code></td><td><code>string</code></td><td></td><td>URL of the OIDC provider to use for authentication (search for the <code>issuer</code> property in your OIDC discovery document).</td></tr><tr><td><code>organisationName</code></td><td><code>string</code></td><td></td><td>The name of your organization; only affects the OIDC login button label.</td></tr><tr><td><code>pgAzureManagedIdentity</code></td><td><code>boolean</code></td><td><code>false</code></td><td>If set to <code>true</code>, then Elimity Insights will connect to PostgreSQL with Azure Managed Identity.</td></tr><tr><td><code>pgConnStr</code></td><td><code>string</code></td><td></td><td>PostgreSQL connection string that the server should use for its database connections.</td></tr><tr><td><code>queryTimeOutMinutes</code></td><td><code>integer</code></td><td><code>10</code></td><td>Maximum number of minutes the server should spend on query evaluations that are triggered by API requests.</td></tr><tr><td><code>readTimeOutMinutes</code></td><td><code>integer</code></td><td><code>5</code></td><td>Maximum number of minutes the server should spend on reading incoming requests.</td></tr><tr><td><code>smtpAuth</code></td><td><code>option[object]</code></td><td></td><td>Configuration object describing how Elimity Insights authenticates with the SMTP server; omit to skip authentication entirely. </td></tr><tr><td><code>smtpAuth.mechanism</code></td><td><code>object</code></td><td></td><td>Configuration object describing the SMTP authentication mechanism.</td></tr><tr><td><code>smtpAuth.mechanism.clientId</code></td><td><code>string</code></td><td></td><td>Client ID for OAuth2 authentication to the configured SMTP server.</td></tr><tr><td><code>smtpAuth.mechanism.clientSecret</code></td><td><code>string</code></td><td></td><td>Client secret for OAuth2 authentication.</td></tr><tr><td><code>smtpAuth.mechanism.password</code></td><td><code>string</code></td><td></td><td>Password for authentication to the configured SMTP server.</td></tr><tr><td><code>smtpAuth.mechanism.scope</code></td><td><code>string</code></td><td></td><td>Scope for OAuth2 authentication.</td></tr><tr><td><code>smtpAuth.mechanism.tokenUrl</code></td><td><code>string</code></td><td></td><td>Token URL for OAuth2 authentication.</td></tr><tr><td><code>smtpAuth.mechanism.type</code></td><td><code>string</code></td><td></td><td>Set to <code>"autoDiscover"</code> for password-based authentication, or <code>"xOAuth2"</code> for OAuth2-based authentication.</td></tr><tr><td><code>smtpAuth.username</code></td><td><code>string</code></td><td></td><td>Username for authentication to the configured SMTP server.</td></tr><tr><td><code>smtpHostname</code></td><td><code>string</code></td><td></td><td>The hostname of the SMTP server to which Elimity Insights sends emails.</td></tr><tr><td><code>smtpPort</code></td><td><code>integer</code></td><td></td><td>The port of the SMTP server to which Elimity Insights sends emails.</td></tr><tr><td><code>supportCustomMailServer</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Determines whether admins can configure a custom mail server.</td></tr><tr><td><code>supportPageUrl</code></td><td><code>string</code></td><td><code>""</code></td><td>Adds an additional support link in the UI toolbar, unless this is set to <code>""</code>.</td></tr><tr><td><code>templatesPath</code></td><td><code>string</code></td><td><code>""</code></td><td>The directory path to use for overriding various HTML and plain-text templates in Elimity Insights.</td></tr><tr><td><code>writeTimeOutMinutes</code></td><td><code>integer</code></td><td><code>15</code></td><td>Maximum number of minutes the server should spend on writing outgoing responses.</td></tr></tbody></table>

## Environment variables

For most customers the aforementioned configuration files should offer all the customization options they need; the following environment variables may be useful in more advanced deployment scenarios:

| Environment variable                    | Description                                                                                                |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `INSIGHTS_CONFIG_HJSON`                 | If set, then Elimity Insights reads this value instead of reading the `config.hjson` configuration file.   |
| `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` | Determine which proxy the server should use for outgoing HTTP(S) requests                                  |
| `GOGC`, `GOMEMLIMIT`                    | Can be used to tune memory usage                                                                           |
| `SSL_CERT_DIR`, `SSL_CERT_FILE`         | Determine where the server should look for certificates to verify SSL connections; only supported on Linux |


# OAuth2 endpoint parameters for gateway authentication

The v3.42.0 release added a new configuration option to support customization of Elimity Insights' access token retrieval for gateway authentication. By default, assuming you provided a value for `gatewayOAuth2`, Elimity Insights will perform a basic OAuth2 client credentials flow. The `gatewayOAuth2.endpointParams` configuration option allows inclusion of additional parameters in the access token request. It should be a record mapping parameter names to [Expr](https://expr-lang.org/) programs that result in the respective parameter's value.

As an example we'll explain how this feature allows us to provide out-of-the-box gateway authentication to our SaaS customers. As detailed in [our documentation about gateway-based imports](/reference-manual/advanced-topics/gateway-based-imports), we want to include `base_url`, `gateway_url` and `source_id` custom claims in the access tokens from our own OAuth2 server. To achieve this, we first need to make sure Elimity Insights provides the additional information in its token requests. For example, a token request from `https://example.elimity.com` for a gateway at `https://gateway.example.com` to import into a source with id `42` should look like this:

```http
POST /oauth/token HTTP/1.1
Host: auth.elimity.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=example-client-id&
client_secret=example-client-secret&
audience=gateway&
base_url=https%3A%2F%2Fexample.elimity.com&
gateway_url=https%3A%2F%2Fgateway.example.com&
source_id=42
```

This corresponds to the following configuration for Elimity Insights:

| Configuration option                       | Value                                    |
| ------------------------------------------ | ---------------------------------------- |
| `gatewayOAuth2.clientId`                   | `"example-client-id"`                    |
| `gatewayOAuth2.clientSecret`               | `"example-client-secret"`                |
| `gatewayOAuth2.endpointParams.audience`    | `"'gateway'"`                            |
| `gatewayOAuth2.endpointParams.base_url`    | `"baseURL"`                              |
| `gatewayOAuth2.endpointParams.gateway_url` | `"gatewayURL"`                           |
| `gatewayOAuth2.endpointParams.source_id`   | `"sourceID"`                             |
| `gatewayOAuth2.tokenUrl`                   | `"https://auth.elimity.com/oauth/token"` |

Each value in the `gatewayOAuth2.endpointParams` record must be a valid [Expr](https://expr-lang.org/) program with result type `string`. Elimity Insights will inject the following variables:

| Variable     | Type     | Description                                         |
| ------------ | -------- | --------------------------------------------------- |
| `baseURL`    | `string` | Base URL of the Elimity Insights server             |
| `gatewayURL` | `string` | URL of the gateway to import data from              |
| `sourceID`   | `string` | Unique identifier of the source to import data into |


# Template overrides

The v3.29.0 release added a new configuration option for overriding various HTML and plain-text templates in Elimity Insights. This article provides detailed information about how to use this feature. Correctly configuring `templatesPath` requires a technical background, so we recommend this feature only for advanced deployments.

The value of the `templatesPath` configuration option in `config.hjson` (if provided) must be a path to an existing directory on the Elimity Insights server.

The given directory must at least contain the following files:

* `access-review-welcome-screen.html.tmpl`
* `link.html.tmpl`
* `link.txt.tmpl`
* `link-subject.txt.tmpl`

These files should contain Go templates to customize various parts of Elimity Insights. There are multiple resources providing more information about Go templates, [the official documentation](https://pkg.go.dev/text/template) is a good place to start. You should also take a look at Elimity Insights' default templates, which we use when the \`TemplatesPath\` configuration option is not set:

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

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

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

{% file src="/files/4qCMdrcKwpWP3y452J8n" %}

The following sections will explain the role of each template in more detail.

## Customizing access review welcome screens

The `access-review-welcome-screen.html.tmpl` template allows customizing the contents of the first screen users see when opening an access review request link:

<figure><img src="https://2876268055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEDnPjX1DSBebgxMCuWjh%2Fuploads%2FPA1Gondx2D6B8M1qgLlv%2Fimage.png?alt=media&amp;token=58025daf-0348-49e8-bc67-194033005514" alt=""><figcaption></figcaption></figure>

This template has access to the following variables:

<table data-full-width="true"><thead><tr><th>Variable</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>.AssigneeName</code></td><td>Name of the access review's assignee</td><td><code>string</code></td></tr><tr><td><code>.CampaignName</code></td><td>Name of the access review's campaign</td><td><code>string</code></td></tr><tr><td><code>.CreatedAt</code></td><td>Timestamp indicating when the access review was created</td><td><code>time.Time</code></td></tr><tr><td><code>.DueDate</code></td><td>Timestamp indicating when the access review's campaign is due</td><td><code>time.Time</code></td></tr></tbody></table>

## Customizing emails

The `link.html.tmpl`, `link.txt.tmpl` and `link-subject.txt.tmpl` templates allow customizing various emails sent by Elimity Insights. They represent the email's HTML body, TXT body and subject line respectively. More specifically, we use these templates for six types of emails:

1. Invitations to new user accounts
2. Requests to fill in an access review
3. Reminders to fill in an access review
4. Notifications about missing imports
5. Requests to verify notification channels
6. Notifications about stored query subscriptions

All three templates have access to all variables listed below, but some variables will only have a meaningful value for a specific type of email.

### Common variables

The following variables always have a meaningful value regardless of the type of email:

<table data-full-width="true"><thead><tr><th>Variable</th><th>Description</th><th>Value</th></tr></thead><tbody><tr><td><code>.AccessReviewRequest</code></td><td>Indicates whether the current email is an access review request (or reminder)</td><td><code>bool</code></td></tr><tr><td><code>.Action</code></td><td>Label for the primary action button (e.g. <code>"PERFORM ACCESS REVIEW"</code> or <code>"ACCEPT INVITE"</code>)</td><td><code>string</code></td></tr><tr><td><code>.FailedHealthCheck</code></td><td>Indicates whether the current email is a notification for missing imports</td><td><code>bool</code></td></tr><tr><td><code>.Header</code></td><td>Main header for the email (e.g. <code>"Submit access review"</code> or <code>"Join Elimity Insights"</code>)</td><td><code>string</code></td></tr><tr><td><code>.NotificationChannelVerification</code></td><td>Indicates whether the current email is a notification channel verification request</td><td><code>bool</code></td></tr><tr><td><code>.NotificationTriggers</code></td><td>Lists all stored query subscriptions that triggered, empty slice if this email is not a notification about stored query subscriptions</td><td><code>[]notificationTrigger</code></td></tr><tr><td><code>.Subheader</code></td><td>Subheader for the email (e.g. <code>"Your input is needed"</code> or <code>"You have been invited"</code>)</td><td><code>string</code></td></tr><tr><td><code>.TenantName</code></td><td>The name of your organization.</td><td><code>string</code></td></tr><tr><td><code>.Title</code></td><td>Main title for the email (e.g. <code>"You have been requested to submit an access review"</code> or <code>"You are invited to Elimity Insights"</code>)</td><td><code>string</code></td></tr><tr><td><code>.URL</code></td><td>URL that the recipient should visit to perform the primary action (e.g. perform access review or accept invite)</td><td><code>string</code></td></tr><tr><td><code>renderNotificationCondition</code></td><td>Helper function to construct a textual description for the given notification trigger condition</td><td><code>func (notificationCondition) string</code></td></tr><tr><td><code>renderNotificationTriggerURL</code></td><td>Helper function to construct a link to the stored query page in Elimity Insights, for a given notification trigger</td><td><code>func (notificationTrigger) string</code></td></tr></tbody></table>

### Variables for invitations

The following variables will only have a meaningful value if the email is an invitation (if `.AccessReviewRequest` and `.FailedHealthCheck` are both `false`):

<table data-full-width="true"><thead><tr><th>Variable</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>.TenantName</code></td><td>The name of your organization</td><td><code>string</code></td></tr></tbody></table>

### Variables for access review requests and access review reminders

The following variables will only have a meaningful value if the email is an access review request or an access review reminder (if `.AccessReviewRequest` is `true`):

<table data-full-width="true"><thead><tr><th>Variable</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>.CampaignMeta</code></td><td>Map of the campaign's metadata as configured by the access review managers</td><td><code>map[string]string</code></td></tr><tr><td><code>.CampaignName</code></td><td>Name of the access review's campaign</td><td><code>string</code></td></tr><tr><td><code>.CreatorEmail</code></td><td>Email address of the access review's creator</td><td><code>string</code></td></tr><tr><td><code>.DueDate</code></td><td>Timestamp indicating when the access review's campaign is due</td><td><code>time.Time</code></td></tr><tr><td><code>.Reminder</code></td><td>Indicates whether the current email is a reminder for an access review request</td><td><code>bool</code></td></tr></tbody></table>

### Variables for missing import notifications

The following variables will only have a value if the email is a notification about a missing import (if `.FailedHealthCheck` is `true`):

<table data-full-width="true"><thead><tr><th>Variable</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>.HealthCheckSnapshotMaxAge</code></td><td>Maximum age of the snapshot in days for which imports are missing</td><td><code>int64</code></td></tr><tr><td><code>.SourceName</code></td><td>Name of the source for which the import failed</td><td><code>string</code></td></tr></tbody></table>

### Variables for notification channel verifications

The following values will only have a value if the email is a request to verify a notification channel (if `.NotificationChannelVerification` is `true`):

<table data-full-width="true"><thead><tr><th>Variable</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>.NotificationChannelDescription</code></td><td>Description of the notification channel</td><td><code>string</code></td></tr><tr><td><code>.NotificationChannelName</code></td><td>Name of the notification channel</td><td><code>string</code></td></tr></tbody></table>

### Notification triggers

The `.NotificationTriggers` template variable lists all stored queries for which at least one subscription in the notification channel has triggered. Each element in this list is a `notificationTrigger` object with the following fields:

<table data-full-width="true"><thead><tr><th>Field</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>AdditionCount</code></td><td>Number of added stored query results in the triggering history point</td><td><code>int64</code></td></tr><tr><td><code>Conditions</code></td><td>Lists all conditions that matched for this stored query</td><td><code>[]notificationCondition</code></td></tr><tr><td><code>HistoryPointID</code></td><td>Unique identifier of the history point that was added for this stored query</td><td><code>int64</code></td></tr><tr><td><code>QueryID</code></td><td>Unique identifier of this stored query</td><td><code>int64</code></td></tr><tr><td><code>QueryName</code></td><td>Name of this stored query</td><td><code>string</code></td></tr><tr><td><code>RemovalCount</code></td><td>Number of removed stored query results in the triggering history point</td><td><code>int64</code></td></tr></tbody></table>

### Notification conditions

Each notification trigger refers to a stored query for which at least one subscription has triggered. The `Conditions` field of a `notificationTrigger` object lists precisely which subscriptions matched and why. Each element in this list is a `notificationCondition` object with the following fields:

<table data-full-width="true"><thead><tr><th>Field</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>ResultsChangedAddition</code></td><td>Indicates whether the stored query subscription matched because new results were added. This field is only relevant if the <code>Type</code> field equals <code>"results_changed"</code></td><td><code>bool</code></td></tr><tr><td><code>ResultsChangedMinPct</code></td><td>Indicates the minimum percentage of change in result count (added or removed) that was exceeded. This field is only relevant if the <code>Type</code> field equals <code>"results_changed"</code></td><td><code>int64</code></td></tr><tr><td><code>ThresholdCrossedValue</code></td><td>Indicates the threshold value that was crossed (from either direction). This field is only relevant if the <code>Type</code> field equals <code>"threshold_crossed"</code></td><td><code>int64</code></td></tr><tr><td><code>Type</code></td><td><p></p><p>Indicates which type of condition matched; one of <code>"control_status_changed"</code>, <code>"history_point_added"</code>, <code>"results_changed"</code> or <code>"threshold_crossed"</code></p></td><td><code>string</code></td></tr></tbody></table>


# AWS IAM

The AWS IAM connector for Elimity Insights fetches users, groups, roles and policies for an AWS account so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated user in AWS

We recommend to create a dedicated AWS IAM user for the connector. This allows you to grant it a minimal amount of privileges:

1. Sign in to your AWS console and navigate to the IAM service by clicking on 'Services > Security, Identity & Compliance > IAM' in the top-left corner.
2. Visit the users page via the 'Access management > Users' item in the menu on the left-hand side.
3. Press the 'Add users' button in the top-right corner.
4. Provide a name for the new user, e.g. `elimity-insights`.
5. For the AWS access type, tick the checkbox next to 'Access key - Programmatic access'.
6. Click the 'Next - Permissions' button in the bottom-right corner.
7. Click the on the 'Attach existing policies directly' button, and search for the 'IAMReadOnlyAccess' policy.
8. Tick the checkbox in this table row and click on the 'Next - Tags' button in the bottom-right corner.
9. This connector does not use any tags, so you can skip ahead by clicking the 'Next - Review' button.
10. Review the configuration details and press the 'Create user' button.

Having reached the last step in AWS's user creation process, you can now note down the 'Access key ID' and 'Secret access key' values for later use.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new AWS IAM source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Access Key ID</td><td>Access key identifier you noted down in step 1.</td></tr><tr><td>Secret Access Key</td><td>Secret access key you noted down in step 1.</td></tr></tbody></table>


# Active directory

The Active Directory connector for Elimity Insights fetches users, groups and computers from Active Directory so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated read-only account in Active Directory

As usual we recommend setting up a dedicated read-only account for this connector. Make sure that authentication to Active Directory using simple bind or NTLM works as expected. Note down the username, password and (optionally) NTLM domain of the dedicated read-only account.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Active Directory source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>LDAP URL</td><td>URL indicating where the connector should contact your domain controller (e.g. <code>ldap://my-host:389</code> or <code>ldaps://my-secure-host:636</code>).</td></tr><tr><td>Username</td><td>Username to use for simple bind or NTLM authentication.</td></tr><tr><td>Password</td><td>Password to use for simple bind or NTLM authentication.</td></tr><tr><td>Domain</td><td>Domain for NTLM authentication; leave blank to use simple bind.</td></tr><tr><td>Search requests</td><td>JSON array describing which search requests to perform.</td></tr></tbody></table>


# Adobe

The Adobe connector for Elimity Insights fetches users and groups for an Adobe Enterprise organization so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up the Adobe User Management API

The first step in setting up the Adobe connector for Elimity Insights is creating a set of credentials using the Adobe Developer Console. Note that Adobe only supports this type of integration for Enterprise customers. Refer to [the official documentation](https://adobe-apiplatform.github.io/umapi-documentation/en/UM_Authentication) for detailed instructions; the steps below provide a short summary:

1. Create a new project in your Adobe Developer Console.
2. Enable the User Management API in this project.
3. Generate OAuth Server-to-Server credentials for this API.

Note down the generated client identifier and secret, we'll need it in the next step. Also note down the unique identifier for your Adobe organization. You can find this value as part of the URL path for the organization in the Admin Console or in the adobe.io console for your User Management integration. It should look like `A495E53@AdobeOrg`.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Adobe source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Organization ID</td><td>Organization identifier you noted down in step 1.</td></tr><tr><td>Client ID</td><td>Client identifier you noted down in step 1.</td></tr><tr><td>Client secret</td><td>Client secret you noted down in step 1.</td></tr></tbody></table>


# Atlassian Cloud

The Atlassian Cloud connector for Elimity Insights fetches users and groups from your Atlassian Cloud tenant so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Generating an API key in Atlassian Cloud

This connector uses an API key to authenticate with Atlassian Cloud. Please refer to [the official documentation](https://support.atlassian.com/organization-administration/docs/manage-an-organization-with-the-admin-apis) for detailed instructions on how to generate such a key. Make sure you create an API key without scopes; Atlassian does not yet support a scope with read-only access to users and groups. Note down your organization ID and the generated key for use in the next step.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Atlassian Cloud source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Organization ID</td><td>The unique identifier of your Atlassian Cloud organization which you noted down in step 1.</td></tr><tr><td>API key</td><td>The key you generated in step 1.</td></tr></tbody></table>


# Azure

The Azure connector for Elimity Insights fetches principals, roles and subscriptions from Azure so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated app registration in Entra ID

As usual we recommend creating a dedicated account for this connector. Follow the steps below to set up a new app registration in Entra ID:

1. In Azure, open the overview of your tenant's app registrations by typing 'app registrations' in the global search bar and clicking the 'App registrations' service.
2. Click the 'New registration' button.
3. Choose a name for this registration (e.g. `elimity-insights`).
4. Leave the default for 'Supported account types' and 'Redirect URI' and click 'Register'.

Note down both the client identifier and the tenant identifier for this new app registration.

## 2. Generating credentials for the new app registration

The Azure connector authenticates as the app registration using a client secret. Click "Certificates & secrets" in the menu on the left and add a new client secret. Immediately note down the value of your new secret.

## 3. Granting read access to management groups

Having created a new app registration in Entra ID, we now need to grant it read access to the relevant management groups:

1. If you want to target your tenant's root management group, then first make sure to temporarily elevate your Global Administrator access (refer to [the official documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/elevate-access-global-admin?tabs=azure-portal%2Centra-audit-logs#step-1-elevate-access-for-a-global-administrator) for detailed instructions); otherwise you can safely skip this step.
2. Open the overview of your tenant's management groups by typing 'management groups' in the global search bar and clicking the 'Management groups' service.
3. Click the management group for which you want to import and then click the 'Access control (IAM)' item in the side navigation menu.
4. Click 'Add' in the top-left corner of the main content panel, and select 'Add role assignment'.
5. Select the 'Reader' role and click 'Next'.
6. Click 'Select members', search for your newly created app registration, select it and click 'Next' again.
7. Click 'Review + assign'.
8. If you elevated your Global Administrator access in step 1: remove it again.

## 4. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Azure source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Tenant identifier</td><td>Tenant identifier you noted down in step 1.</td></tr><tr><td>Client identifier</td><td>Client identifier you noted down in step 1.</td></tr><tr><td>Client secret</td><td>Client secret you noted down in step 2.</td></tr></tbody></table>


# Delinea Secret Server Cloud

The Delinea Secret Server Cloud connector for Elimity Insights fetches users, groups, roles, folders and secrets from Delinea Secret Server Cloud so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated user in Delinea Platform

As usual, we recommend creating a dedicated service user in your Delinea Platform instance with read access to users, groups, roles, folders and secrets. Refer to [the official documentation](https://docs.delinea.com/online-help/delinea-platform/users/add-users.htm#AddServiceUsers) for detailed instructions. Note down the service user's username and password for later use.

To make sure this new service user has minimal access rights, create a custom role with only the necessary permissions. Again we point you to [the official documentation](https://docs.delinea.com/online-help/delinea-platform/roles-permissions/index.htm#CreateaNewRole) for additional information. Grant at least the following permissions:

* 'View Advanced Secret Options'
* 'View Platform Groups'
* 'View Platform Users'
* 'View Secret'
* 'View Secret Server Folders'

Now you can grant the newly created role to the dedicated service user, please consult [the official documentation](https://docs.delinea.com/online-help/delinea-platform/roles-permissions/index.htm#AddMembersGroupstoaRole) for detailed instructions.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Delinea Secret Server Cloud source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Secret server hostname</td><td>Hostname of your Delinea Secret Server Cloud instance, typically resembles <code>example.secretservercloud.eu</code>.</td></tr><tr><td>Service user username</td><td>Username of the dedicated service user you created in step 1.</td></tr><tr><td>Service user password</td><td>Password of the dedicated service user you created in step 1.</td></tr><tr><td>Platform OAuth2 token URL</td><td>OAuth2 token URL of your Delinea Platform instance, typically resembles <code>https://example.delinea.app/identity/api/oauth2/token/xpmplatform</code>.</td></tr></tbody></table>


# DocuSign

The DocuSign connector for Elimity Insights fetches users, groups and permission profiles for a DocuSign organization so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated user in DocuSign

As usual, we recommend creating a dedicated user for this connector. Make sure this user is an organization admin for the organizations you want to import. Elimity Insights will only request read-only access via this user, which we'll set up in the next step.

## 2. Delegate read-only access to the Elimity Insights app

Having set up the dedicated user in DocuSign, now we can delegate read-only access to the Elimity Insights app by visiting <https://docusign.gateways.elimity.com/login> and logging in with the new user. After granting the requested access your browser should download a `credential.json` file, which you'll need to configure the source in Elimity Insights.

## 3. Creating a source in Elimity Insights

In Elimity Insights you can now create a new DocuSign source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Credential</td><td>Credential file you downloaded in step 2.</td></tr></tbody></table>


# Entra ID

The Entra ID connector for Elimity Insights fetches principals, roles and subscriptions from Entra ID so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated app registration in Entra ID

As usual we recommend creating a dedicated account for this connector. Follow the steps below to set up a new app registration in Entra ID:

1. In Azure, open the overview of your tenant's app registrations by typing 'app registrations' in the global search bar and clicking the 'App registrations' service.
2. Click the 'New registration' button.
3. Choose a name for this registration (e.g. `elimity-insights`).
4. Leave the default for 'Supported account types' and 'Redirect URI' and click 'Register'.

Note down both the client identifier and the tenant identifier for this new app registration.

## 2. Generating credentials for the new app registration

The Entra ID connector authenticates as the app registration using a client secret. Click "Certificates & secrets" in the menu on the left and add a new client secret. Immediately note down the value of your new secret.

## 3. Granting read permissions to the Graph API

Having created a new app registration in Entra ID, we now need to grant it read access to some parts of the Microsoft Graph API:

1. Click 'API permissions' in the menu on the left and only add the 'Microsoft Graph' > 'Application permissions' > 'Directory.Read.All'. If you have an Entra ID Premium P1/P2 license and would like to import sign-in activity for users, then grant 'Microsoft Graph' > 'Application permissions' > 'AuditLog.Read.All' as well. To also include 'employee leave date' information for users, grant 'Microsoft Graph' > 'Application permissions' > 'User-LifeCycleInfo.Read.All'.
2. Grant admin consent for these permission assignments.

## 4. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Entra ID source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Tenant ID</td><td>Tenant identifier you noted down in step 1.</td></tr><tr><td>Application ID</td><td>Client identifier you noted down in step 1.</td></tr><tr><td>Application Secret</td><td>Client secret you noted down in step 2.</td></tr><tr><td>Import sign-in activity</td><td>Enable this if you want to import sign-in activity for users; requires an Entra ID Premium P1/P2 license and the additional 'AuditLog.Read.All' permission as explained in step 3.</td></tr></tbody></table>


# GitHub

The GitHub connector for Elimity Insights fetches users, roles, teams, permissions and repositories from GitHub so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a GitHub App

To ensure Elimity Insights can request the necessary information from the GitHub API, we need to provide it with a private key. GitHub only generates these keys for GitHub Apps, so we need to create a GitHub App first. To do so, follow these steps:

1. Go to the following link in your browser (filling the `{organization}` parameter) and log in with an organization administrator account: `https://github.com/organizations/{organization}/settings/apps/new?administration=read&members=read`
2. Choose a GitHub App name (e.g. `elimity-insights`) and homepage (e.g the URL of your Elimity Insights tenant); these settings are purely descriptive.
3. Untick the active checkbox under the webhooks section.
4. If you want import from multiple organizations, then select 'Any account' as the answer for 'Where can this GitHub App be installed?'.
5. Click 'Create GitHub App'.

Note down the new app's ID for later use.

## 2. Generating a private key for the app

Having created a GitHub App, now we can generate a private key for it. On the new app's settings page, scroll down to the private keys section, and click the button to generate a private key, which should download a file to your machine. Keep this file for the last step.

## 3. Installing the app for your organization(s)

Elimity Insights will only be able to use the private key you just generated if the GitHub App is effectively installed for your organization(s). For each organization you want to import, perform the following steps:

1. From the app’s settings page, click the button to install the app, which should be in the top-left menu.
2. Click the install button for the organization account.
3. Review the requested permissions and click the confirmation button.

## 4. Creating a source in Elimity Insights

In Elimity Insights you can now create a new GitHub source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>App ID</td><td>Application identifier you noted down in step 1.</td></tr><tr><td>Private key</td><td>Private key you generated in step 2.</td></tr><tr><td>Enable legacy single-org mode</td><td>Ensures backwards compatibility with older versions of this connector which did not support importing from multiple organizations, for new deployments we recommend leaving this unset.</td></tr></tbody></table>


# Google Cloud

The Google Cloud connector for Elimity Insights fetches user accounts, service accounts, roles, permissions and buckets from Google Cloud so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated service account in Google Cloud

As usual, we recommend creating a dedicated service account in Google Cloud:

1. In the Google Cloud console, open the navigation menu from the top-left corner, and click on the 'IAM & Admin > Service accounts' item.
2. Create a new service account by pressing the 'CREATE SERVICE ACCOUNT' button at the top of the page.
3. Provide a descriptive name (e.g. `elimity-insights`) and generate or choose a unique identifier for the service account.
4. Press 'CREATE AND CONTINUE'.
5. Grant the service account read rights to all information in the project by granting it the role 'Security Reviewer'.
6. Press 'CONTINUE' and skip the last optional step by pressing 'DONE'.

Note down the unique identifier of your Google Cloud project for later use. You can find it by opening the project selector in the top-left corner of your console.

## 2. Generating a key for the service account

Having created a dedicated service account, we now need to generate a private key for it:

1. Open the menu in the 'Actions' column for the newly created service account, and click on the 'Manage keys' item.
2. Click the 'ADD KEY' button and select 'Create new key'.
3. Ensure the key type is 'JSON' and press the 'CREATE' button.

Securely store the downloaded private key for later use.

## 3. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Google Cloud source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Credentials JSON</td><td>Private key you generated in step 2.</td></tr><tr><td>Project ID</td><td>Project identifier you noted down in step 1.</td></tr></tbody></table>


# Google Workspace

The Google Workspace connector for Elimity Insights fetches users and groups for a Google Workspace tenant so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated service account in Google Cloud

The Google Workspace connector for Elimity Insights authenticates as a service account. We recommend creating a dedicated service account to assign the minimal amount of permissions. Refer to [the official documentation](https://developers.google.com/workspace/guides/create-credentials#create_a_service_account) for instructions on how to create a new service account. Take note of the newly created service account's email address. Generate a secret key for the service account (again, refer to [the official documentation](https://developers.google.com/workspace/guides/create-credentials#create_credentials_for_a_service_account) for more information) and store the resulting JSON file securely; you'll need it to set up a source in Elimity Insights. Also make sure to enable the Admin SDK API in the service account's related project, refer to [the official documentation](https://developers.google.com/workspace/guides/enable-apis#admin-sdk-api) for detailed instructions.

## 2. Creating a dedicated admin role in Google Workspace

We also recommend creating a dedicated admin role for the newly created service account. This admin role should only grant the 'Admin API > Groups > Read' and 'Admin API > Users > Read' privileges. [The official documentation](https://support.google.com/a/answer/2406043) contains more information about creating a new admin role in Google Workspace. This is also a good time to note down your Google Workspace customer ID, refer to [the official documentation](https://support.google.com/a/answer/10070793) for instructions on where to find this.

## 3. Assigning the admin role in Google Workspace

Follow the instructions listed in [the official documentation](https://developers.google.com/workspace/guides/create-credentials#assign_a_role_to_a_service_account) to assign the newly created admin role to the newly created service account.

## 4. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Google Workspace source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Google Workspace customer ID</td><td>Customer identifier you noted down in step 2.</td></tr><tr><td>Group email pattern</td><td>Regular expression to filter groups by email address; leave blank to include all groups.</td></tr><tr><td>User email pattern</td><td>Regular expression to filter users by email address; leave blank to include all users.</td></tr><tr><td>Service account key</td><td>Secret key you generated in step 1.</td></tr></tbody></table>


# Jira

The Jira connector for Elimity Insights fetches users, groups and roles from Jira so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated user in Jira

As usual, we recommend creating a dedicated user in Jira for this connector. Make sure this user has sufficient rights in your organization, refer to [the official documentation](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Make-someone-an-organization-admin.1) for detailed instructions. Note down the new user's username and your organization's Atlassian URL (e.g. `https://example.atlassian.net`) for later use.

## 2. Generating an API token for the dedicated user

Having created a new user in Jira, we now need to generate an API token for authentication. Refer to [the official documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token) for detailed instructions. Note down the generated token for later use.

## 3. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Jira source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Username</td><td>Username you noted down in step 1.</td></tr><tr><td>Token</td><td>API token you generated in step 2.</td></tr><tr><td>Base URL</td><td>Your organization's Atlassian URL, which you noted down in step 1.</td></tr></tbody></table>


# Jira Data Center

The Jira Data Center connector for Elimity Insights fetches users, groups, roles and projects from Jira Data Center so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a gateway

The Elimity Insights built-in connector for Jira Data Center uses the REST API of your on-premise instance to import users, groups, roles and projects. It's not always feasible to let Elimity Insights connect directly with this API in your on-premise environment, especially for our SaaS customers. Additionally, Jira does not support fine-grained access: this connector requires both the 'Jira administrators' and 'Browse users' permissions. For these reasons we ask our customers to set up an additional point of indirection: each deployment of the Elimity Insights built-in connector for Jira Data Center should communicate with an on-prem instance of the Elimity Insights gateway for Jira Data Center. Only the on-prem gateway instance will access the Jira Data Center credentials and REST API. Refer to [the documentation about our Jira Data Center gateway](https://docs.elimity.com/gateways-jira-data-center/) for detailed setup instructions.

{% hint style="info" %}
This version of the connector is currently compatible with gateway versions matching `>=3.0.0`.
{% endhint %}

Note down your gateway's URL.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Jira Data Center source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>HTTP(S) URL of the Elimity Insights Jira Data Center gateway you set up in step 1.</td></tr><tr><td>Enable debug logging</td><td>Enable this flag if you need additional debug information in the logs.</td></tr></tbody></table>


# LDIF

The LDIF connector for Elimity Insights imports users, groups and computers from an LDIF file so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Generate an LDIF export from your Active Directory tenant

This step is typically highly customer-specific. `ldifde` is a commonly used tool to generate LDIF exports, you can use the following example command as a starting point:

```powershell
PS C:\> Ldifde -f export.ldf -s dc.example.com
```

Store the resulting export file for later use.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new LDIF source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>file</td><td>Export file you generated in step 1.</td></tr></tbody></table>


# Lansweeper

{% hint style="warning" %}
**Deprecation notice:** we no longer actively support the Lansweeper built-in connector. New users should refer to [the SQL gateway](https://docs.elimity.com/gateways-sql/v3.2.10/) instead.
{% endhint %}


# NTFS

The NTFS connector for Elimity Insights fetches trustees, access rights and files for an NTFS file system so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a gateway

The Elimity Insights built-in connector for NTFS reads permissions from a local filesystem. Of course it's often not feasible to make these filesystems actually 'local' to your Elimity Insights server. Therefore we ask our customers to set up an additional point of indirection: each deployment of the Elimity Insights built-in connector for NTFS should communicate with an on-prem instance of the Elimity Insights gateway for NTFS. Only the on-prem gateway instance has direct access to its local filesystem. Refer to [the documentation about our NTFS gateway](https://docs.elimity.com/gateways-ntfs/) for detailed setup instructions.

{% hint style="info" %}
This version of the connector is currently compatible with gateway versions matching `>=2.0.0`.
{% endhint %}

Note down your gateway's URL.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new NTFS source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>HTTP(S) URL of the Elimity Insights NTFS gateway you set up in step 1.</td></tr><tr><td>Targets</td><td>HJSON object mapping file labels to paths from which you want to start scanning; refer to <a href="/reference-manual/built-in-connectors/ntfs/targets-configuration">our documentation about targets configuration</a> for more details.</td></tr><tr><td>Max depth</td><td>Maximum level of directory nesting; use <code>0</code> to set no limit.</td></tr><tr><td>Only directories</td><td>Indicates whether to only scan directories.</td></tr><tr><td>Omit advanced access rights</td><td>Indicates whether to only import basic access rights.</td></tr><tr><td>Maximum concurrency</td><td>Maximum number of concurrent workers to use for scanning.</td></tr><tr><td>Overrides</td><td>HJSON object mapping file labels to configuration overrides; refer to <a href="/reference-manual/built-in-connectors/ntfs/overrides-configuration">our documentation about overrides configuration</a> for more details.</td></tr><tr><td>Skip patterns</td><td>Newline-delimited list of path patterns; the connector will skip files that match (cf. <a href="https://pkg.go.dev/path/filepath#Match"><code>filepath.Match</code></a>) with any of them.</td></tr></tbody></table>


# Targets configuration

The Elimity Insights built-in connector for NTFS supports a 'Targets' configuration option to determine which files it should target. Customers should provide this value as an HJSON object mapping file labels to paths from which you want to start scanning. Refer to the following snippet as an example:

```
{
  # Scan `C:\target1` and display it as `\\server\share\dir`
  \\server\share\dir: C:\target1
  
  # Scan `C:\target2` and display it as `C:\local\dir`
  "C:\\local\\dir": C:\target2
  
  # Scan `C:\` and display it as `D:\`
  "D:\\": C:\
}
```


# Overrides configuration

The Elimity Insights built-in connector for NTFS supports an 'Overrides' configuration option to override global configuration for specific files. Customers should provide this value as an HJSON object mapping file labels to configuration override objects with the following properties:

| Property   | Type      | Description                                                              |
| ---------- | --------- | ------------------------------------------------------------------------ |
| `maxDepth` | `number`  | Overrides the global 'Max depth' configuration; use `0` to set no limit. |
| `onlyDirs` | `boolean` | Overrides the global 'Only directories' configuration.                   |


# Okta

The Okta connector for Elimity Insights fetches users, groups and applications from Okta so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated read-only user in Okta

As usual, we recommend setting up a dedicated user in Okta for this connector. Make sure this user has read access to the users, groups and applications in your organization. Note down the hostname of your Okta organization (e.g. `example.okta.com`) for later use.

## 2. Generating an API token for the dedicated user

Having set up a dedicated user in Okta, we now need to generate an API token for authentication. Refer to [the official documentation](https://help.okta.com/en-us/content/topics/security/api.htm?cshid=ext-create-api-token#create-okta-api-token) for detailed instructions. Note down the generated token for later use.

## 3. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Okta source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>host</td><td>Hostname of your Okta organization, which you noted down in step 1.</td></tr><tr><td>API token</td><td>API token you generated in step 2.</td></tr></tbody></table>


# SAP SuccessFactors

The SAP SuccessFactors connector for Elimity Insights fetches users for an SAP SuccessFactors tenant so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated user in SAP SuccessFactors

The SAP SuccessFactors connector for Elimity Insights authenticates as an OAuth client application bound to a user. We recommend creating a dedicated user to assign the minimal amount of permissions. Refer to [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/534356acc0ab4b0e8977ebfb2eb432f7/02e3e0b3966c42299653b495a42b292f.html) for instructions on how to create a new user in SAP SuccesFactors. Note down the newly created user's username.

## 2. Setting up a dedicated permission role in SAP SuccessFactors

We also recommend creating a dedicated permission role for the newly created user. This permission role should only grant the 'Employee Export' permission. [The official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/b569eee64d3f4159b2b5272ba7d6b127/6d8998d9504843a58fe299ff6935a268.html) contains more information about creating a new permission role in SAP SuccessFactors.

## 3. Setting up a dedicated permission group in SAP SuccessFactors

To assign the newly created permission role to the newly created user, we recommend using a dedicated static permission group. Refer to [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/b569eee64d3f4159b2b5272ba7d6b127/c15b3696a56e4601ae110c1c37c34a3d.html) for instructions in how to create a new static permission group in SAP SuccessFactors.

## 4. Assigning the permission role in SAP SuccessFactors

Follow the instructions listed in [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/b569eee64d3f4159b2b5272ba7d6b127/fbaadf758e00485893d6f099e9f342fa.html) to assign the newly created permission role to the newly created permission group.

## 5. Setting up an OAuth client application in SAP SuccessFactors

Create a new OAuth client application as described in [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/6b3c741483de47b290d075d798163bc1.html). We recommend enabling the 'Bind to Users' option and entering the newly created user's username in the 'User IDs' field. For the 'X.509 Certificate' field, we recommend to generate your own certificate and private key; for example by using the following OpenSSL command:

```shell-session
$ openssl req -days 999 -keyout key.pem -newkey rsa -nodes -out cert.pem -subj '/CN=elimity-insights' -x509
```

Remember to strip out the beginning and ending lines from the certificate contents before pasting into the 'X.509 Certificate' field. Securely store the private key you generated, you will need it to set up the new source in Elimity Insights. Also note down the newly created application's API key.

## 6. Creating a source in Elimity Insights

In Elimity Insights you can now create a new SAP SuccessFactors source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>URL of the Elimity Insights SAP SuccessFactors gateway; SaaS customers can stick to the default of <code>https://sap-sf.gateways.elimity.com</code>. On-premise customers wishing to self-host can refer to <a href="/technical-guides/gateways-and-import-agents">our documentation about gateways and import agents </a>for more information.</td></tr><tr><td>API key</td><td>API key you noted down in step 5.</td></tr><tr><td>API URL</td><td>URL of the API server for your SAP SuccessFactors tenant; refer to <a href="https://help.sap.com/docs/successfactors-platform/sap-successfactors-api-reference-guide-odata-v2/list-of-sap-successfactors-api-servers#api-servers">the official documentation</a> for more information.</td></tr><tr><td>Company ID</td><td>Your SAP SuccessFactors company identifier, refer to <a href="https://me.sap.com/notes/0002655655">the official documentation</a> for instructions on how to find this information.</td></tr><tr><td>User ID</td><td>Username of the newly created user, which you noted down in step 1.</td></tr><tr><td>X.509 private key</td><td>Private key you stored in step 5.</td></tr></tbody></table>


# SailPoint IIQ

The SailPoint IIQ connector for Elimity Insights fetches users, accounts, entitlements, applications and roles from SailPoint IIQ so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a gateway

The Elimity Insights built-in connector for SailPoint IIQ uses the SCIM API of your on-premise instance to import users, accounts, entitlements, applications and roles. It's not always feasible to let Elimity Insights connect directly with this API in your on-premise environment, especially for our SaaS customers. Additionally, SailPoint IIQ does not support fine-grained access: this connector requires the 'SCIM Executor' capability. For these reasons we ask our customers to set up an additional point of indirection: each deployment of the Elimity Insights built-in connector for SailPoint IIQ should communicate with an on-prem instance of the Elimity Insights gateway for SailPoint IIQ. Only the on-prem gateway instance will access the SailPoint IIQ credentials and SCIM API. Refer to [the documentation about our SailPoint IIQ gateway](https://docs.elimity.com/gateways-sailpoint-iiq/) for detailed setup instructions.

{% hint style="info" %}
This version of the connector is currently compatible with gateway versions matching `>1.0.0`.
{% endhint %}

Note down your gateway's URL.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new SailPoint IIQ source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>HTTP(S) URL of the Elimity Insights gateway for SailPoint IIQ you set up in step 1.</td></tr></tbody></table>


# SCIM

The SCIM connector for Elimity Insights fetches users and groups from a SCIM server so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated read-only user

As usual, we recommend creating a dedicated read-only user for this connector. Exact instructions depend on the software serving the SCIM API, but in general this connector only requires read access to users and groups. We also recommend generating a secure password for this new user. Note down both the username and password for later use. Alternatively you can also generate a bearer token with similar permissions.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new SCIM source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Base URL</td><td>URL of your SCIM server (e.g. <code>https://api.slack.com/scim/v2</code>).</td></tr><tr><td>Username</td><td>The username you noted down in step 1, or leave empty if you want to authenticate with a bearer token.</td></tr><tr><td>Password</td><td>The password or bearer token you generated in step 1.</td></tr></tbody></table>


# Salesforce

The Salesforce connector for Elimity Insights fetches users, profiles and permissions for a Salesforce account so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated read-only user in Salesforce

As a preliminary step we recommend creating a read-only user in your Salesforce account. The Salesforce connector for Elimity Insights will authenticate as this user via a connected app. We recommend reading this post on the Salesforce Admin blog listing best practices for creating integration users: <https://admin.salesforce.com/blog/2023/best-practices-for-configuring-your-integration-user>.

## 2. Setting up a connected app in Salesforce

The Salesforce connector for Elimity Insights authenticates as a connected app in your Salesforce account. Follow these steps:

1. Create a connected app. Refer to [the official documentation](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_basics.htm) for step-by-step instructions about creating a connected app.
2. After creating the connected app, make sure the 'API > Enable OAuth settings' and 'API > Enable Client Credentials Flow' options are enabled for the app. Use a dummy value (e.g. `http://localhost`) for the callback URL and assign the 'Manage user data via APIs (api)' OAuth scope.
3. Now we still need to assign an execution user for the app. On the app's detail page, click 'Manage' and 'Edit policies'. Then set the 'Client Credentials Flow > Run As' configuration value to the dedicated integration user you previously created.
4. As a final step click the 'Manage consumer details' button on the app's detail page and note down the values for 'Consumer Key' and 'Consumer Secret'.

## 3. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Salesforce source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>URL of the Elimity Insights Salesforce gateway; SaaS customers can stick to the default of <code>https://salesforce.gateways.elimity.com</code>. On-premise customers wishing to self-host can refer to <a href="/technical-guides/gateways-and-import-agents">our documentation about gateways and import agents </a>for more information.</td></tr><tr><td>Instance URL</td><td>URL of your Salesforce instance, e.g. <code>https://example.salesforce.com</code>.</td></tr><tr><td>Connected app consumer key</td><td>Consumer key you noted down in step 2.</td></tr><tr><td>Connected app consumer secret</td><td>Consumer secret you noted down in step 2.</td></tr></tbody></table>


# ServiceNow

The ServiceNow connector for Elimity Insights fetches users, groups, and roles for a ServiceNow account so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Creating a dedicated user in ServiceNow

As usual, we recommend creating a dedicated user in ServiceNow for this connector:

1. In ServiceNow open the users overview by navigating to 'All > User Adminstration > Users' in the top left corner.
2. Press the 'New' button in the top-right corner.
3. Provide an identifier for the new user, e.g. `elimity-insights`.
4. Make sure that the 'Web service access only' checkbox is checked.
5. Leave all other fields untouched and click the 'Submit' button.

Note down the new user's identifier for later use.

## 2. Generating a password for the dedicated user

Having created a dedicated user in ServiceNow, we now need to generate a password for authentication:

1. Click on the newly created user in the overview table.
2. Now click 'Set Password' on the user detail page.
3. Click ‘Generate’ in the newly opened dialog; copy and note down the generated password for later use.
4. Click the 'Save password' button and close the dialog.

## 3. Granting read-only access for the dedicated user

Follow the steps below to grant read-only access to the dedicated ServiceNow user:

1. On the user detail page, open the 'Roles' tab and click the 'Edit…' button on the right-hand side.
2. Search and assign the `admin` and `snc_read_only` roles to the dedicated user.
3. Click 'Save' to submit the new role assignments.

## 4. Creating a source in Elimity Insights

In Elimity Insights you can now create a new ServiceNow source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Instance URL</td><td>the URL of your ServiceNow instance, e.g. <code>https://my-instance.service-now.com</code>.</td></tr><tr><td>Username</td><td>Identifier of the dedicated user, which you noted down in step 1.</td></tr><tr><td>Password</td><td>Password you generated in step 2.</td></tr></tbody></table>


# SharePoint

The Sharepoint connector for Elimity Insights fetches users, groups, and sites for a Sharepoint tenant so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a gateway

The Elimity Insights built-in connector for SharePoint requires at least full read access to the sites you want to scan; a more limited permission unfortunately just doesn't exist. Therefore we ask our customers to set up an additional layer of protection for their SharePoint credentials: each deployment of the Elimity Insights built-in connector for SharePoint should communicate with an on-prem instance of the Elimity Insights gateway for SharePoint. Only the on-prem gateway instance has direct access to the coarse-grained SharePoint tokens. Refer to [the documentation about our SharePoint gateway](https://docs.elimity.com/gateways-sharepoint/) for detailed setup instructions.

{% hint style="info" %}
This version of the connector is currently compatible with gateway versions matching `>=5.0.0`.
{% endhint %}

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new SharePoint source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>HTTP(S) URL of the Elimity Insights Sharepoint gateway you set up in step 1.</td></tr><tr><td>Target</td><td>HJSON array of objects describing which sites you want to import (use an empty array to target all sites in your tenant); refer to <a href="/reference-manual/built-in-connectors/sharepoint/target-configuration">our documentation about target configuration</a> for more details.</td></tr><tr><td>Skip files</td><td>Indicates whether to skip scanning regular files and directories for each site.</td></tr><tr><td>Skip role assignments</td><td>Indicates whether you want to skip scanning role assignments for each file; make sure you granted the gateway <code>Sites.FullControl.All</code> permission when enabling this option.</td></tr><tr><td>Skip personal sites</td><td>Indicates whether to skip scanning personal sites.</td></tr><tr><td>Include regular files</td><td>Indicates whether to also scan regular files (not only directories).</td></tr><tr><td>List item page size</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>Role assignment chunk size</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>File exclusion pattern</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>Continue on errors</td><td>Indicates whether to force continuation of the import even if the connector encounters errors while interacting with the SharePoint API. May be useful during testing, but we heavily recommend leaving this unset in production. Note that this configuration option only actually has an effect if your gateway's version matches <code>>=5.1.0</code>. Older gateways simply ignore it and always continue on errors.</td></tr></tbody></table>


# Target configuration

The Elimity Insights built-in connector for SharePoint supports a 'Target' configuration option to determine which sites it should target. Customers should provide this value as an HJSON array of objects with the following properties:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>hostname</code></td><td><code>string</code></td><td>Hostname of the SharePoint site you want to target (e.g. <code>example.sharepoint.com</code>).</td></tr><tr><td><code>path</code></td><td><code>string</code></td><td>Absolute path of the SharePoint site you want to target (e.g. <code>/sites/Example</code>).</td></tr></tbody></table>


# Vercel

The Vercel connector for Elimity Insights fetches users, projects and teams for a Vercel account so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated user in Vercel

The Vercel connector for Elimity Insights authenticates with an access token bound to a Vercel account. We recommend creating a dedicated account with minimal access rights to the teams you want to import from. For example, you could create an `elimity-insights-vercel@<your-domain>` account and add it as a billing user to the teams you want to import from. Having set up this account, you can now create an access token as described in [the official documentation](https://vercel.com/guides/how-do-i-use-a-vercel-api-access-token#creating-an-access-token); note down the token for the next step. The connector will only import teams for which you have granted access in the token.

## 2. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Vercel source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Gateway URL</td><td>URL of the Elimity Insights Vercel gateway; SaaS customers can stick to the default of <code>https://vercel.gateways.elimity.com</code>. On-premise customers wishing to self-host can refer to <a href="/technical-guides/gateways-and-import-agents">our documentation about gateways and import agents </a>for more information.</td></tr><tr><td>Access token</td><td>Token you noted down in step 1.</td></tr></tbody></table>


# Windows File Shares

{% hint style="warning" %}
**Deprecation notice:** we no longer actively support the Windows File Shares built-in connector. New users should refer to [the NTFS built-in connector](/reference-manual/built-in-connectors/ntfs) instead.
{% endhint %}


# Zendesk

The Zendesk connector for Elimity Insights fetches users and groups from Zendesk so you can keep in control of your environment. Follow the instructions below to set up the connector for your environment.

## 1. Setting up a dedicated user in Zendesk

As usual, we recommend creating a dedicated user in Zendesk for this connector. [The official documentation](https://support.zendesk.com/hc/en-us/articles/4408886939930-Adding-agents-and-admins#topic_h43_2k2_yg) contains detailed instructions.

## 2. Generating an OAuth access token for the dedicated user

Now that we have created a dedicated user in Zendesk, we need to generate an OAuth token for authentication. Refer to [the official documentation](https://developer.zendesk.com/documentation/ticketing/working-with-oauth/creating-and-using-oauth-tokens-with-the-api) for additional information on how to do this. This connector only requires the `read` scope. Note down the resulting token for later use.

## 3. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Zendesk source providing the following configuration options:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Description</th></tr></thead><tbody><tr><td>Subdomain</td><td>Subdomain of your Zendesk tenant (e.g. <code>example</code> if your Zendesk domain is <code>example.zendesk.com</code>).</td></tr><tr><td>OAuth token</td><td>OAuth token you noted down in step 1.</td></tr></tbody></table>


# Broken linking strategies

## What is a linking strategy?

Linking strategies allow connector admins to create relationships between multiple sources in Elimity Insights. Each strategy links entities of a single type in one source to entities of another type in a different source. Elimity Insights determines how to link these entities by comparing their attributes as specified in the linking strategy.

## Why do I see a warning about linking strategies referring to archived attribute types?

If at some point a linking strategy's attribute becomes archived, then Elimity Insights can no longer apply that strategy in a meaningful way. More specifically, the affected strategy will just continue using assignments for the archived attribute, which often result in no links at all. This behaviour may be unexpected, which is why connector admins will see warnings encouraging them to edit or remove the 'broken' linking strategies.


# Flexible file uploads

Elimity Insights v3.41.0 included significant improvements to data imports via file uploads. This page explains how to use this feature, and also provides some technical details about what happens behind the scenes.

We designed the 'flexible file uploads' feature for two types of users:

1. Technical experts that know how to convert application-specific export files into entities and relationships for Elimity Insights
2. Application owners that know how to get the export files and upload them in Elimity Insights

The general idea is that technical experts define which files are needed and how Elimity Insights should process them, allowing application owners to simply export and upload without the need for any knowledge about what happens behind the scenes.

<figure><img src="https://2876268055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEDnPjX1DSBebgxMCuWjh%2Fuploads%2FJH5XcA0aCipgVwr7IUZf%2Fdiagram.png?alt=media&amp;token=595add74-6422-4822-a012-1e4b75cdc457" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

## Technical expert creates file upload definitions

To start using the 'flexible file uploads' feature, a technical expert should define which export files are needed for the data import. More specifically, Elimity Insights expects a list of file upload definitions, each of which containing the following information:

* A textual label to help application owners know what to upload.
* Technical details about which file types to accept (e.g. CSV, Excel, ...).
* A flag indicating whether application owners can upload multiple files for the definition.

For example, let's say we have an HR application containing employee records that we want to review in Elimity Insights. The HR application supports exporting these employees to CSV in batches of 1000 employees per file. In this case the technical expert should create a file upload definition in Elimity Insights with the following configuration:

* A textual label of 'Employees', so the application owner knows to only upload export files containing employee records.
* Uploaded files should have a `.csv` extension.
* Multiple files are allowed, because the HR application might contain more than 1000 employees.
  {% endstep %}

{% step %}

## Technical expert configures SQL queries

Having defined which files are needed for the data import, a technical expert should now configure the business logic to convert these uploaded files into entities and relationships for Elimity Insights. More specifically, Elimity Insights expects an SQL query for each entity type and relationship type in the target source. These SQL queries can refer to named parameters (e.g. `$p0`, `$p1`, ...) which Elimity Insights will replace with glob patterns matching the uploaded files' paths. Technically this is what happens behind the scenes:

1. Application owner uploads one or more files for each definition created by the technical expert.
2. For each definition, Elimity Insights copies the uploaded content into temporary file(s). Elimity Insights also builds list containing the paths of these files.
3. For each entity type in the target source, Elimity Insights executes the SQL query configured by the technical expert, passing the file paths from step 2 as named arguments. More specifically, each file upload definition corresponds to one named argument. If the definition allows multiple files, then Elimity Insights provides a list of file paths instead of a single file path. Each of the query's resulting rows should correspond to an entity in the final data import:
   1. The number of columns must be equal to `n + 2`, where `n` is the number of included attribute types.
   2. The first column must have a textual type and represents the entity's unique identifier. This value must never be `NULL`.
   3. The second column must also have a textual type and represents the entity's human-readable name. This value must never be `NULL`.
   4. The remaining columns must follow the ordering of included attribute types, and their type has to match with the attribute's data type. A `NULL` value corresponds to an attribute that's not assigned.
4. For each relationship type in the target source, Elimity Insights follows a process that's very analogous to step 3. The main difference is that the first two columns in SQL query results should represent 'from' and 'to' entity identifiers instead of 'id' and 'name'.

It's important to know which SQL query engine we rely on behind the scenes. This version of Elimity Insights uses DuckDB v1.3.0; we highly recommend reading through [their documentation](https://duckdb.org/) before writing SQL queries.
{% endstep %}

{% step %}

## Application owner uploads export files

Having set up the file upload definitions and SQL queries, application owners can now simply upload their export files into Elimity Insights without knowledge about any processing that happens behind the scenes.
{% endstep %}
{% endstepper %}


# Gateway-based imports

Elimity Insights v3.42.0 introduced a new feature for importing data into custom sources. More specifically, it aims to avoid the out-of-band configuration management and scheduling necessary for agent-based imports. The following table compares several aspects of both agent- and gateway-based imports:

<table data-full-width="true"><thead><tr><th></th><th>Agent-based</th><th>Gateway-based</th></tr></thead><tbody><tr><td><strong>Traffic direction</strong></td><td>Agent pushes to Elimity Insights' API</td><td>Elimity Insights pulls from gateway's API</td></tr><tr><td><strong>Authentication with Elimity Insights</strong></td><td>Connector admin generates API credentials in Elimity Insights and places them in out-of-band configuration for the agent</td><td>Connector admin configures gateway URL in Elimity Insights, HTTPS by itself already provides the necessary authentication</td></tr><tr><td><strong>Authentication with underlying data source</strong></td><td>Connector admin places credentials in out-of-band configuration for the agent</td><td>Connector admin provides credentials as gateway configuration values in Elimity Insights</td></tr><tr><td><strong>Authentication with gateway</strong></td><td>Not applicable</td><td>Optional and only necessary if underlying data source requires additional protection; refer to <a href="#authenticating-with-gateways">the dedicated section below</a> for additional information</td></tr><tr><td><strong>Scheduling</strong></td><td>Connector admin configures schedule out-of-band</td><td>Connector admin configures CRON schedule in Elimity Insights</td></tr><tr><td><strong>Deployment</strong></td><td>Job in Azure Container Apps, job in Google Cloud Run, ...</td><td>App in Azure Container Apps, service in Google Cloud Run, ...</td></tr><tr><td><strong>Development</strong></td><td>Python or NodeJS script which uses an official client library for pushing to Elimity Insights' API</td><td>HTTP server in Go, NodeJS or Python which uses the official SDK for communication with Elimity Insights</td></tr></tbody></table>

In general we recommend all new customers to use gateway-based imports when possible.

## Authenticating with gateways

In most circumstances authentication for gateway-based imports is already sufficiently covered by the combination of HTTPS and credentials for the underlying data source. However, sometimes additional protection of the gateway's HTTP(S) endpoint is necessary (e.g. if the gateway itself implicitly authenticates to the underlying source). For these use cases, Elimity Insights supports including OAuth2 access tokens in its requests to gateways. More specifically, our on-prem customers can enable this feature with the `gatewayOAuth2` configuration option. For SaaS customers we can provide a fully configured setup upon request. The diagram below depicts the authentication flow in more detail:

<figure><img src="https://2876268055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEDnPjX1DSBebgxMCuWjh%2Fuploads%2FCwjYckkhITkSp1DyS6MU%2Fdiagram.png?alt=media&amp;token=8765abfa-5bb6-4e37-bec1-db026b097e49" alt=""><figcaption></figcaption></figure>

As you can see, in this case Elimity Insights includes access tokens from our own OAuth2 server at `auth.elimity.com`. More specifically, we'll make sure those tokens adhere to the JWT standard and have the following custom claims:

| Claim         | Value                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `aud`         | `"gateway"`                                                                                                        |
| `base_url`    | Base URL of the Elimity Insights tenant that requested the access token, e.g. `"https://example.elimity.com"`      |
| `gateway_url` | URL of the gateway for which Elimity Insights has requested the access token, e.g. `"https://gateway.example.com"` |
| `iss`         | `"https://auth.elimity.com/"`                                                                                      |
| `source_id`   | Unique identifier of the source for which to import into Elimity Insights, e.g. `"42"`                             |


# ITSM webhook

Elimity Insights allows users to indicate necessary changes in the IAM data, like an AD user that should be deleted. Those change requests are stored by the Elimity Insights server. In addition, you can also integrate with your IT ticketing system by triggering a webhook for every new change request.

## Configuring Elimity Insights

By default, the Elimity Insights server does not trigger any webhook when a new change request is created. To enable this feature, open the 'MISCELLANEOUS' tab on the 'Advanced settings' page and use the toggle in the 'ITSM webhook' section:

<figure><img src="https://2876268055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEDnPjX1DSBebgxMCuWjh%2Fuploads%2FnkkbBmBPoTlylKkCaOBP%2FScreenshot%202026-08-10%20at%2013.25.21.png?alt=media&amp;token=c32b4c12-a166-455d-91e4-7d522e2546c6" alt=""><figcaption></figcaption></figure>

## Request body format

The Elimity Insights server triggers your webhook by sending an HTTP `POST` request. We include detailed information about the change request in the HTTP request body. More specifically, the request body is a JSON object with the following properties:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>attributeTypeId</code></td><td><code>optional[string]</code></td><td>External identifier of the attribute type for which the assignment should change; present if and only if <code>type</code> is <code>"attributeAssignment"</code></td></tr><tr><td><code>attributeTypeName</code></td><td><code>optional[string]</code></td><td>Name of the attribute type for which the assignment should change; present if and only if <code>type</code> is <code>"attributeAssignment"</code></td></tr><tr><td><code>campaignName</code></td><td><code>optional[string]</code></td><td>Campaign name for the access review from which this change request originates; present if and only if <code>type</code> is <code>"accessReviewSubmission"</code></td></tr><tr><td><code>comment</code></td><td><code>string</code></td><td>User-provided comment for the change request or access review</td></tr><tr><td><code>entity</code></td><td><code>optional[Entity]</code></td><td>Target entity for the change request; present if and only if <code>type</code> is <code>"attributeAssignment"</code> or <code>"entityRemoval"</code></td></tr><tr><td><code>fromEntity</code></td><td><code>optional[Entity]</code></td><td>Entity from which the to-be-removed relationship starts; present if and only if <code>type</code> is <code>"relationshipRemoval"</code></td></tr><tr><td><code>relationshipChanges</code></td><td><code>optional[list[RelationshipChange]]</code></td><td>Relationship changes requested in the access review, present if and only if <code>type</code> is <code>"accessReviewSubmission"</code></td></tr><tr><td><code>requestedAt</code></td><td><code>string</code></td><td>Timestamp indicating when the change was requested</td></tr><tr><td><code>requestedBy</code></td><td><code>string</code></td><td>Email address of the change request creator</td></tr><tr><td><code>reviewCreatedBy</code></td><td><code>optional[string]</code></td><td>Email address of the access review creator; present if and only if <code>type</code> is <code>"accessReviewSubmission"</code></td></tr><tr><td><code>rowRemovals</code></td><td><code>optional[list[RowRemoval]]</code></td><td>Row removals requested in the access review, present if and only if <code>type</code> is <code>"accessReviewSubmission"</code></td></tr><tr><td><code>toEntity</code></td><td><code>optional[Entity]</code></td><td>Entity at which the to-be-removed relationship ends; present if and only if <code>type</code> is <code>"relationshipRemoval"</code></td></tr><tr><td><code>type</code></td><td><code>string</code></td><td>One of <code>"accessReviewSubmission"</code>, <code>"attributeAssignment"</code>, <code>"entityRemoval"</code> or <code>"relationshipRemoval"</code></td></tr><tr><td><code>value</code></td><td><code>optional[Value]</code></td><td>Describes current and requested values for the attribute assignment; only present if and only if <code>type</code> is <code>"attributeAssignment"</code></td></tr></tbody></table>

The table below describes all properties for `Entity` objects:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>string</code></td><td>External identifier of the entity</td></tr><tr><td><code>name</code></td><td><code>string</code></td><td>Human-readable name of the entity</td></tr><tr><td><code>sourceId</code></td><td><code>number</code></td><td>Unique identifier of the entity's source</td></tr><tr><td><code>sourceName</code></td><td><code>string</code></td><td>Human-readable name of the entity's source</td></tr><tr><td><code>type</code></td><td><code>string</code></td><td>External identifier of the entity's type</td></tr></tbody></table>

All `RelationshipChange` objects have the following properties:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>columnEntity</code></td><td><code>Entity</code></td><td>Entity corresponding to the access review column for the to-be-changed relationship</td></tr><tr><td><code>comment</code></td><td><code>string</code></td><td>User-provided comment</td></tr><tr><td><code>operation</code></td><td><code>string</code></td><td>One of <code>"add"</code> or <code>"remove"</code></td></tr><tr><td><code>rowEntity</code></td><td><code>Entity</code></td><td>Entity corresponding to the access review row for the to-be-changed relationship</td></tr></tbody></table>

The `RowRemoval` objects have a similar structure:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>comment</code></td><td><code>string</code></td><td>User-provided comment</td></tr><tr><td><code>entity</code></td><td><code>Entity</code></td><td>Entity corresponding to the to-be-removed access review row</td></tr></tbody></table>

Finally we also describe the `Value` objects:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>current</code></td><td><code>any</code></td><td>Current value of the to-be-changed assignment</td></tr><tr><td><code>requested</code></td><td><code>any</code></td><td>Requested value for the to-be-changed assignment</td></tr><tr><td><code>type</code></td><td><code>string</code></td><td>One of <code>"boolean"</code>, <code>"date"</code>, <code>"dateTime"</code>, <code>"number"</code>, <code>"string"</code> or <code>"time"</code></td></tr></tbody></table>


# Pattern matching

Elimity Insights provides several options for comparing attributes with expected values. In most cases, a simple 'equals', 'contains' or 'starts with' check is sufficient. However, from v3.24.0 onwards, users can also perform flexible pattern matching for more complex use-cases. The list below provides some example queries that were previously impossible:

* find all files with a path containing at least 2 slashes: path matches pattern `/.*/`
* find all users with an invalid phone number: phone does not match pattern `^\d{4}/(\d\d\.){2}\d\d$`
* find all groups with a name that starts with 8 digits: name matches pattern `^\d{8}`

[The Google RE2 specification](https://github.com/google/re2/wiki/Syntax) provides a technical explanation of how these patterns work exactly. For a quick overview, refer to the cheat sheet at <https://yourbasic.org/golang/regexp-cheat-sheet/#cheat-sheet>.


# SCIM provisioning

[SCIM](https://scim.cloud) is an HTTP REST API and protocol used by identity providers to manage the users across a variety of software products, including Elimity Insights. This SCIM implementation targets version 2.0 of the protocol.

{% hint style="warning" %}
Be aware that the SCIM API allows creating and deleting users at will. Hence, thoroughly protect your API keys to prevent unauthorized people from making themselves admin and accessing your data. Similarly, thoroughly test your scripts before executing them to avoid deprovisioning all users in your tenant. Of course, our support team is available should you run into any trouble.
{% endhint %}

## Authentication

The SCIM API of Elimity Insights requires authentication using a bearer token (HTTP Bearer Authentication). As such, the client must send this token in the `Authorization` header when making requests to protected resources:

```
Authorization: Bearer {token}
```

Use the 'SCIM API' tab on the 'Advanced settings' page to generate this token:

<figure><img src="https://2876268055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEDnPjX1DSBebgxMCuWjh%2Fuploads%2Fz7cj4RgnWNMyEZEOW9PF%2Fimage.png?alt=media&amp;token=3b224d61-1652-4ce0-ba2f-06a091bd07ce" alt=""><figcaption></figcaption></figure>

## Roles and access profiles

Elimity Insights works with two authorization concepts:

1. Roles like `member`, `editor`, `connectorAdmin` and `admin` determine the functionality that user can access.
2. Access profiles determine which data sources a user is permitted to see.

A user in Elimity Insights is always assigned to exactly 1 role, to the default access profile and to 0 or more custom access profiles. SCIM on the other hand works with the concept of groups and Elimity Insights models roles and access profiles as groups in the following way:

* We model roles as groups with an `id` in the format `role:{roleId}`. This list of roles currently exists:
  * `role:member`
  * `role:editor`
  * `role:changeRequestManager`
  * `role:accessReviewManager`&#x20;
  * `role:storedQueryManager`&#x20;
  * `role:connectorAdmin`
  * `role:admin`
* We model access profiles as groups with an `id` in the format of `profile:{profileId}`; `{profileId}` represents the access profile's numeric identifier. You can find this value in the URL of the access profile's details page.
* The default access profile is not available in the SCIM API and cannot be assigned or revoked explicitly.

## Supported endpoints

The table below lists the endpoints supported by the SCIM API of Elimity Insights. We intentionally don't support other related actions like deleting or creating access profiles via the SCIM API, for those you'll have to use the UI.

<table data-full-width="true"><thead><tr><th>Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><code>GET /scim/v2/ServiceProviderConfig</code></td><td>Retrieve the configuration details for the Elimity Insights SCIM API</td></tr><tr><td><code>GET /scim/v2/ResourceTypes</code></td><td>Retrieve the available resource types (users and groups)</td></tr><tr><td><code>GET /scim/v2/Schemas</code></td><td>Retrieve the schemas for users and groups</td></tr><tr><td><code>GET /scim/v2/Users</code></td><td>Retrieve the list of all users in Elimity Insights</td></tr><tr><td><code>GET /scim/v2/Users/{id}</code></td><td>Retrieve the user with the given identifier (email address)</td></tr><tr><td><code>POST /scim/v2/Users</code></td><td>Create a new user</td></tr><tr><td><code>PUT /scim/v2/Users/{id}</code></td><td>Change the name or status of the user with the given identifier (email address)</td></tr><tr><td><code>GET /scim/v2/Groups</code></td><td>Retrieve the list of all groups (roles and access profiles) in Elimity Insights</td></tr><tr><td><code>GET /scim/v2/Groups/{id}</code></td><td>Retrieve the group with the given identifier</td></tr><tr><td><code>PUT /scim/v2/Groups/{id}</code></td><td>Update the members of the group with the given identifier</td></tr></tbody></table>


# Installation

Setting up a deployment of the Elimity Insights platform typically requires provisioning the following components:

* Elimity Insights server
* PostgreSQL database
* Identity provider
* Mail server
* HTTP(S) proxy

The following pages contain detailed installation instructions for each of these components.


# Elimity Insights server

The Elimity Insights server fulfills multiple roles in a deployment of the Elimity Insights platform:

* Serving the Elimity Insights web application
* Serving the Elimity Insights REST API
* Running various scheduled background tasks
  * Performing imports for built-in sources
  * Sending daily notifications for access review reminders and failed health checks

For SaaS customers we perform the setup and maintenance of Elimity Insights servers behind the scenes. These installation instructions are mainly useful for on-prem deployments.

## Installation

We distribute all Elimity Insights releases as Docker images for both Linux and Windows Server hosts. Our recommendation for deploying these is to use your cloud provider's CaaS solution for complex applications (e.g. Google Cloud App Engine flexible environment, Azure App Service, ...). Note that we don't support deploying Elimity Insights using services like Google Cloud Run and Azure Container Apps (but we do recommend these for [gateways and import agents](/technical-guides/gateways-and-import-agents)). The main reason is that Elimity Insights servers currently do not match most cloud providers' definition of a microservice:

* Elimity Insights servers build a cache on startup which might take a while.
* Elimity Insights servers do not support horizontal scaling.
* Elimity Insights servers perform long-running tasks in the background.

Services like Google Cloud App Engine flexible environment and Azure App Service however are a perfect fit for Elimity Insights servers:

* No manual VM management
* Encrypted connections to Elimity Insights via out-of-the box HTTPS reverse proxy
* Great integration with your cloud provider's key vault for mounting secrets
* Configuration / monitoring / upgrades via your cloud provider's user-friendly UI

We also support deploying manually on e.g. Windows Server if using your cloud provider's CaaS solution is not an option. In either case please refer to [our documentation about working with containers](/technical-guides/working-with-containers) for detailed setup instructions. Visit <https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/insights> to get a list of available image tags.

## Upgrades

Upgrading an Elimity Insights deployment typically requires performing the following steps:

1. Shutting down the old server
2. Backing up your database
3. Performing database migrations (not applicable for patch upgrades)
4. Updating the server (simply bumping image version for container-based installations)
5. Starting the updated server

### Database migrations

For database migrations we also provide OCI images. As usual, we recommend using a CaaS solution like Google Cloud Run or Azure Container Apps to perform database migrations as a one-off job. You can also just run the image locally using the Docker CLI:

```shell-session
$ docker run --rm europe-west1-docker.pkg.dev/elimity-general/docker/insights-database-migrate:<tag> help
Elimity Insights Database Migration CLI
Description:
  This tool applies database migrations required for upgrading Elimity Insights. It migrates the specified Postgres
  databases in-place. Note that this tool can only migrate databases for Elimity Insights v3.x. It reads from a
  configuration file at '/app/config/config.json'.

Usage: elimity-insights-database-migrate [options]

Options:
  -h, -help      Show usage information and exit
  -print-version Print version information and exit
```

To configure your migration, mount a JSON configuration file at `/app/config/config.json` with the properties listed below. Refer to the following snippet for a starting point:

```json
{
  "pgConnStr": "postgres://<user>:<password>@<host>:5432/postgres",
  "targetVersion": "v3.44",
  "pgAzureManagedIdentity": false
}
```

The table below describes each supported configuration option in more detail:

<table data-full-width="true"><thead><tr><th width="218.96484375">Configuration option</th><th>Value type</th><th>Default value</th><th width="243.40625">Description</th></tr></thead><tbody><tr><td><code>pgConnStr</code></td><td><code>string</code></td><td></td><td>The PostgreSQL connection string (e.g., <code>"postgres://&#x3C;user>:&#x3C;password>@&#x3C;host>:5432/postgres"</code>).</td></tr><tr><td><code>targetVersion</code></td><td><code>string</code></td><td></td><td>The target release version for the migration (e.g., <code>"v3.44"</code>).</td></tr><tr><td><code>pgAzureManagedIdentity</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Set to <code>true</code> to automatically retrieve an Azure AD token from Azure for database authentication.</td></tr></tbody></table>

Visit <https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/insights-database-migrate> to get a list of available tags for this specific image.


# PostgreSQL database

The Elimity Insights server manages all of its persistent data in a PostgreSQL database. For SaaS customers we perform the setup and maintenance of PostgreSQL servers behind the scenes. These installation instructions are mainly useful for on-prem deployments. We strongly recommend using your cloud provider's DBaaS offering to set up a PostgreSQL database. More specifically, Elimity Insights servers officially support PostgreSQL 17.x. The `btree_gist`, `pgcrypto` and `plv8` extensions must also be available. If using your cloud provider's DBaaS offering is not an option, then installing PostgreSQL manually on e.g. a Linux VM is also possible.

We heavily recommend creating a dedicated database and user for Elimity Insights. More specifically, we suggest the following steps:

1. Create a dedicated PostgreSQL user with no privileges and a strong authentication mechanism
2. Create a dedicated database and assign the new user as its owner


# Identity provider

All deployments of Elimity Insights must rely on an identity provider for authentication of user accounts. We implement single sign-on (SSO) using the OpenID Connect (OIDC) protocol, both Entra ID and Google Workspace support this. More specifically, use the following Elimity Insights server configuration options to set up SSO:  `oidcClientId`, `oidcClientSecret` and `oidcIssuer`. Refer to [our dedicated documentation](/reference-manual/v3.46.6/server-configuration) for additional details. The following sections provide more information about setting up SSO in Entra ID and Google workspace.

## Entra ID

### 1. Creating an app registration

Elimity Insights 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')
   1. Name: e.g. `elimity-insights`
   2. Redirect URI platform: 'Web'
   3. Redirect URI value: `https://{host}/api/oidc/callback`, e.g. `https://example.elimity.com/api/oidc/callback`&#x20;
   4. Click 'Register'
   5. Note down the new registration's application ID and directory ID
2. Generate a client secret for the app registration ('Certificates & secrets' > 'Client secrets' > 'New client secret') and securely note down the secret value.

### 2. Configuring Elimity Insights

Having created a new app registration, you can now set the following configuration options for the Elimity Insights server:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value</th></tr></thead><tbody><tr><td><code>oidcClientId</code></td><td>Application ID you noted down in step 1.1.e</td></tr><tr><td><code>oidcClientSecret</code></td><td>Secret value you noted down in step 1.2</td></tr><tr><td><code>oidcProvider</code></td><td><code>https://login.microsoftonline.com/{tenantId}/v2.0</code> , replace <code>{tenantId}</code> with the directory ID you noted down in step 1.1.e</td></tr></tbody></table>

## Google Workspace

### 1. Creating an OAuth2 client

Follow the steps outlined in [Google's official documentation](https://support.google.com/cloud/answer/6158849) to create an OAuth2 client. Make sure you choose 'Web application' for the application type and add `https://{host}/api/oidc/callback` as an authorized redirect URI, replacing `{host}` your Elimity Insights server host. Note down the resulting client ID and secret.

### 2. Configuring Elimity Insights

Having created a new app registration, you can now set the following configuration options for the Elimity Insights server:

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value</th></tr></thead><tbody><tr><td><code>oidcClientId</code></td><td>Client ID you noted down in step 1</td></tr><tr><td><code>oidcClientSecret</code></td><td>Secret value you noted down in step 1</td></tr><tr><td><code>oidcIssuer</code></td><td><code>https://accounts.google.com</code></td></tr></tbody></table>


# Mail server

Elimity Insights servers send out emails for multiple reasons:

* to invite new user accounts
* to update subscribed users when stored query results change
* to warn subscribed connector admins when imports fail
* to request access reviews

For SaaS customers we perform the setup and maintenance of mail servers behind the scenes. These installation instructions are mainly useful for on-prem deployments.

From an Elimity Insights server's point of view, the only requirement is an SMTP server to accept the outgoing emails. In practice this means you can probably just use a mail server that is already available in your organization. We currently support the following authentication options:

* None: Elimity Insights will simply send mails to your SMTP server without prior authentication.
* Direct: Elimity Insights will try a variety of 'direct' SMTP authentication options (e.g. `PLAIN`, `LOGIN`, `CRAM-MD5`, ...) using a configured username and password.
* OAuth2: Elimity Insights will exchange configured client credentials for an access token and use it together with a configured username for `XOAUTH2` authentication at your SMTP server.

For example, many of our customers use Exchange Online as their mail server for Elimity Insights. Setting this up correctly is not easy though, so we highly recommend carefully reading through [the official documentation from Microsoft](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth). Some points that require extra attention:

* the OAuth2 token URL should have the following format: `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`
* the OAuth2 scope should be `https://outlook.office365.com/.default`
* the mailbox you want to send emails from should have a license
* you should grant your app registration full access to this mailbox using PowerShell
* you should also grant the necessary API permission to your app registration:
  * 'APIs my organization uses'
  * search for 'Office 365 Exchange Online'
  * 'Application permissions'
  * 'SMTP.SendAsApp'
* you should grant admin consent for this permission


# HTTP(S) proxy

We strongly recommend including a production-grade HTTP(S) proxy in each deployment of Elimity Insights. For our SaaS customers we include this by default.

Most cloud providers offer an HTTP(S) proxy (e.g. Google Cloud Load Balancing, Azure Load Balancer) that integrates well with their CaaS / VMaaS products. If using your cloud provider's proxy is not an option, then installing one manually on e.g. Windows Server is also possible. We suggest to take a look at [Caddy](https://caddyserver.com/), a widely-used open-source HTTPS server with excellent proxying capabilities. The remainder of this page contains some additional guidelines for setting up Caddy as an HTTP(S) proxy for Elimity Insights on Windows Server.

## Installing Caddy on Windows Server

To install Caddy as an HTTP(S) proxy for Elimity Insights on Windows Server we recommend to just deploy [their official Docker image](https://hub.docker.com/_/caddy). Refer to the snippet below as a starting point for your `docker-compose.yml` file:

```yaml
services:
  caddy:
    image: caddy
    ports:
      - 80:80
      - 443:443
    restart: always
    volumes:
      - .\caddy:C:\etc\caddy

  insights:
    image: europe-west1-docker.pkg.dev/elimity-general/docker/insights:v3.41.0-nanoserver-ltsc2022
    restart: always
    volumes:
      - .\insights:C:\app\config 
```

Of course you'll also need to configure Caddy. The official documentation includes [a great tutorial about writing `Caddyfile`s](https://caddyserver.com/docs/caddyfile-tutorial), here's a template you can build on (place it at `.\caddy\Caddyfile`):

```
elimity.example.com

reverse_proxy insights

tls cert.pem key.pem
```




---

[Next Page](https://docs.elimity.com/llms-full.txt/1)