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

# Step-by-step deployment guide

## 1. Configuring the agent

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

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

This example configuration will simply mimic the import functionality of Elimity Insights' built-in connector for Active Directory. Edit the following properties in your file to configure the import agent to your needs:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>cronPattern</code></td><td><code>string</code></td><td>Optional CRON pattern describing when the import agent should run (refer to <a href="https://crontab.guru">https://crontab.guru</a> for example patterns); omit if you just want to run the agent once</td></tr><tr><td><code>entityTypes</code></td><td><code>list[object]</code></td><td>Describes how to import entities of a specific type into Elimity Insights</td></tr><tr><td><code>entityTypes[].attributes</code></td><td><code>list[object]</code></td><td>Describes how to import attributes of this entity type's entities</td></tr><tr><td><code>entityTypes[].attributes[].attribute</code></td><td><code>string</code></td><td>Identifier of the attribute to read from the LDAP server</td></tr><tr><td><code>entityTypes[].attributes[].id</code></td><td><code>string</code></td><td>Unique identifier of the attribute type for which the agent should import assignments</td></tr><tr><td><code>entityTypes[].attributes[].description</code><sup>*</sup></td><td><code>string</code></td><td>Description of the attribute type</td></tr><tr><td><code>entityTypes[].attributes[].name</code><sup>*</sup></td><td><code>string</code></td><td>Human-readable name of the attribute type</td></tr><tr><td><code>entityTypes[].attributes[].syntax</code></td><td><code>object</code></td><td>Describes how to parse the LDAP attribute</td></tr><tr><td><code>entityTypes[].attributes[].syntax.cmp</code></td><td><code>boolean</code></td><td>Value to compare with masking result; only applicable if <code>syntax.type</code> is <code>"flag"</code></td></tr><tr><td><code>entityTypes[].attributes[].syntax.default</code></td><td><code>string</code></td><td>Fallback value if none of the configured bitmasks match; only applicable if <code>syntax.type</code> is <code>"enum"</code></td></tr><tr><td><code>entityTypes[].attributes[].syntax.delimiter</code></td><td><code>string</code></td><td>Delimiter to use for joining the attribute values into a single string; only applicable if <code>syntax.type</code> is <code>"multiString</code>"</td></tr><tr><td><code>entityTypes[].attributes[].syntax.mask</code></td><td><code>number</code></td><td>Mask to apply before comparing with <code>syntax.type.cmp</code>; only applicable if <code>syntax.type</code> is <code>"flag"</code></td></tr><tr><td><code>entityTypes[].attributes[].syntax.options</code></td><td><code>record[number]</code></td><td>Record mapping enum member names to bitmasks for matching; only applicable if <code>syntax.type</code> is <code>"enum"</code></td></tr><tr><td><code>entityTypes[].attributes[].syntax.type</code></td><td><code>string</code></td><td>LDAP syntax for the attribute type, one of <code>boolean</code>, <code>enum</code>, <code>flag</code>, <code>generalizedTime</code>, <code>integer</code>, <code>interval</code>, <code>multiString</code>, <code>sid</code> or <code>string</code></td></tr><tr><td><code>entityTypes[].icon</code><sup>*</sup></td><td><code>string</code></td><td>Icon of the entity type</td></tr><tr><td><code>entityTypes[].id</code></td><td><code>string</code></td><td>Unique identifier of the entity type for which the agent should import entities</td></tr><tr><td><code>entityTypes[].plural</code><sup>*</sup></td><td><code>string</code></td><td>Plural form of the entity type's name</td></tr><tr><td><code>entityTypes[].searchRequests</code></td><td><code>list[object]</code></td><td>Requests that the import agent should send to the configured LDAP server, each resulting entry corresponds to an entity of this type</td></tr><tr><td><code>entityTypes[].searchRequests[].baseDn</code></td><td><code>string</code></td><td>Specified the base of the subtree in which the search is to be constrained</td></tr><tr><td><code>entityTypes[].searchRequests[].filter</code></td><td><code>string</code></td><td>Specified criteria to identify which entries within the scope should be returned</td></tr><tr><td><code>entityTypes[].searchRequests[].scope</code></td><td><code>string</code></td><td>One of <code>"base"</code>, <code>"oneLevel"</code> or <code>"subtree"</code></td></tr><tr><td><code>entityTypes[].singular</code><sup>*</sup></td><td><code>string</code></td><td>Singular form of the entity type's name</td></tr><tr><td><code>insightsSourceId</code></td><td><code>number</code></td><td>Elimity Insights source identifier; we'll create one in step 2</td></tr><tr><td><code>insightsSourceToken</code></td><td><code>string</code></td><td>Elimity Insights source token; we'll generate one in step 2</td></tr><tr><td><code>insightsUrl</code></td><td><code>string</code></td><td>URL of your Elimity Insights server</td></tr><tr><td><code>ldapUrl</code></td><td><code>string</code></td><td>URL of your LDAP server, e.g. <code>ldap://my-host:389</code> or <code>ldaps://my-secure-host:636</code></td></tr><tr><td><code>ldapUsername</code></td><td><code>string</code></td><td>Username for authentication with the LDAP server</td></tr><tr><td><code>ldapPassword</code></td><td><code>string</code></td><td>Password for authentication with the LDAP server</td></tr><tr><td><code>relationshipTypes</code></td><td><code>list[object]</code></td><td>Describes how to import relationships between entities of two specific types into Elimity Insights</td></tr><tr><td><code>relationshipTypes[].from</code></td><td><code>string</code></td><td>Unique identifier of the entity type from which the relationships start</td></tr><tr><td><code>relationshipTypes[].targetAttribute</code></td><td><code>string</code></td><td>LDAP attribute to filter on when searching <code>to</code> entities (e.g. <code>"memberOf"</code> when searching relationships from users to groups)</td></tr><tr><td><code>relationshipTypes[].to</code></td><td><code>string</code></td><td>Unique identifier of the entity type where the relationships end</td></tr></tbody></table>

<sup>\*</sup>These properties do not affect the importing functionality, they are only necessary to generate a data model export file when running the import agent with the `-print-data-model-export` flag.

## 2. Creating a source in Elimity Insights

The import agent also includes some functionality to help you with creating a source in Elimity Insights. Assuming you correctly configured the agent as explained in the previous step, the following command will write a data model export file to `data-model-export.json`:

```
$ docker run -v ./config:/app/config --rm europe-west1-docker.pkg.dev/elimity-general/docker/ldap-import-agent:<tag> -print-data-model-export > data-model-export.json
```

You can now upload this file to Elimity Insights when creating a new custom source. Copy the resulting source's identifier and token to the `insightsSourceId` and `insightsSourceToken` properties in the agent's configuration file.

## 3. Deploying the agent

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

## 4. Following up on the import

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


---

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

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

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

```
GET https://docs.elimity.com/import-agents-ldap/v1.2.x/step-by-step-deployment-guide.md?ask=<question>&goal=<endgoal>
```

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

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

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