> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/microsoft/9-sqlserver.md).

# Microsoft SQL Server connector

This page describes how to enable provisioning to a database table

MSSQL connector works only with user accounts on the MSSQL server level or MSSQL database level, manages logins and database users, manages login roles for database user. It is not intended for reading or writing data to database tables or other database objects.

| Operation                     | Supported |
| ----------------------------- | --------- |
| Create / update a user (Save) | ✅         |
| Delete a user                 | ✅         |
| Suspend / resume              | ✅         |
| Reset password                | ✅         |
| Check a password (Login)      | ✅         |
| Search users and databases    | ✅         |
| Test connection               | ✅         |

## Use cases

* **Giving a joiner the database access their role entitles them to** — a login on the server, a user in each database they need, and the database and server roles that go with it.
* **Keeping SQL Server access in step** as people move, including adding and removing database users across many databases in one request.
* **Leavers** — disabling the login, then removing the user and the login when the retention period ends.
* **Reconciling what is actually on the server** — reading back logins, database users and their role membership.

## Versions and compatibility

The connector does not talk to SQL Server directly. It drives the **SQL Server PowerShell provider** and the **SMO** object model, so what it supports is what those support rather than a version range of its own.

| Property            | Value                                                                                                                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SQL Server**      | Whatever the installed SqlServer PowerShell module supports                                                                                                                                                                                                                        |
| **Required module** | `SqlServer`, which the connector imports at startup and fails without. See [SQL Server PowerShell](https://docs.microsoft.com/en-us/sql/powershell/sql-server-powershell) and the [module download](https://docs.microsoft.com/en-us/sql/powershell/download-sql-server-ps-module) |
| **Object model**    | [SMO](https://docs.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo), which is what the attribute names below come from                                                                                                                                           |

## Prerequisites

* The **SqlServer PowerShell module** installed on the connector host. The connector imports it at startup and cannot run without it.
* A SQL Server account with rights over the logins, users and roles you intend to manage — or a Windows account, if you use Windows authentication.
* Network access from the connector host to the SQL Server instance.

## Installing the connector

All PowerShell connectors are installed in the same way, which is described in the document: [PowerShell connector installation](/connector-configuration/microsoft/1-powershellconnectorinstallation.md)

The connector uses the [SQL Server PowerShell provider](https://docs.microsoft.com/en-us/sql/powershell/sql-server-powershell) to communicate with MSSQL server. Before installing the MSSQL connector, the SQL Server PowerShell module should be installed. You can install the SQL Server PowerShell module using this [link](https://docs.microsoft.com/en-us/sql/powershell/download-sql-server-ps-module).

## Starting, stopping, and restarting

The connector runs as a pair of Windows services registered by the installer, named after the connector name you supply. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#starting-stopping-and-restarting).

## Command-line parameters and properties

The connector takes no command-line parameters. Queue names, concurrency, logging, simulation mode and the RabbitMQ settings all live in `Connector.config`, which is documented once for the whole family in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md#working-with-the-connector-configuration).

## Verifying the connector is running

{% stepper %}
{% step %}
Confirm the connector's Windows services are running on the host.
{% endstep %}

{% step %}
Check the connector's request queue in RabbitMQ has a consumer.
{% endstep %}

{% step %}
Run **Test Connection** on the managed system.
{% endstep %}

{% step %}
Run a search — `Get-Databases` is the cheapest — to prove the path end to end.
{% endstep %}
{% endstepper %}

## Troubleshooting

Troubleshooting for the whole family, including where the logs are and how to replay a request, is in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md). What is specific to this connector is that almost everything it does runs through the `SqlServer` PowerShell module and the PSDrive built from the **Host URL**, so a failure is usually one of those two.

The table below covers both: the behaviour you observe, and the messages the connector itself raises — which are distinct from anything SQL Server returns, and each points at one piece of configuration.

| Symptom                                                                 | Likely cause                                                                                                                      | Resolution                                                                                                                              |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing works, and the connector log mentions the module                | The `SqlServer` module is not installed on the connector host. The connector imports it at startup                                | Install the module on the connector host                                                                                                |
| The connection fails before any operation                               | The PSDrive root is wrong                                                                                                         | Check the `SQLSERVER:\SQL\ComputerName\InstanceName` shape of the Host URL, including the `\default` ending on a single-instance server |
| Operations fail with permission errors                                  | Under Windows authentication the connector acts as the account its Windows service runs as, not as anything configured in OpenIAM | Check that account's rights on the server                                                                                               |
| `Test connection - hostUrl cannot be empty`                             | The managed system has no **Host URL**                                                                                            | Set it to the PSDrive root, not a server name on its own                                                                                |
| `Unable to connect to MSSQLServer …`                                    | The drive root is reachable but the connection failed                                                                             | Verify the instance name, the port and the credentials — or, under Windows authentication, the service account                          |
| `Database path not set`, `Wrong database path`                          | `baseDN` is missing or is not in the `Databases\DatabaseName` form                                                                | Correct `baseDN`, or set `DATABASE_NAME` instead and avoid the path entirely                                                            |
| `Could not get domain name`                                             | Provisioning a Windows-authentication user needs `DOMAIN_NAME`                                                                    | Add `DOMAIN_NAME` to the metaData attributes                                                                                            |
| `Could not find login`, `Could not get login from attributes`           | The policy map supplies no `Login`, or the login does not exist                                                                   | Map `Login`, or set `CreateLoginIfNotExist` — which then makes `LoginType` and a `Password` required                                    |
| `Could not change password, login was not found`                        | A password reset arrived for a login that is not on the server                                                                    | Create the login, or correct the identity                                                                                               |
| `Could not get database role`, `Could not get server role`              | A name in `DataBaseRoles` or `ServerRoles` does not exist on the target. Roles are not created for you                            | Create the role on the server, or correct the name                                                                                      |
| `Both IdentityName and Identity value should be set for AddUser`        | The request carries no principal                                                                                                  | Check the managed system's principal attribute                                                                                          |
| `Password property should not be null or empty for Reset-LoginPassword` | A reset password request arrived with no password in the attribute map                                                            | Map the password attribute                                                                                                              |
| `validatePassword function can be called for USER object only`          | A password check arrived for something other than a user                                                                          | Send password checks for USER objects only                                                                                              |

## Registering the connector in OpenIAM

The connector's request queue name in OpenIAM has to match the queue in the connector's own `Connector.config` exactly. Getting the connection parameters out of OpenIAM and into the installer is covered in [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#getting-connection-parameters-with-openiam).

## Configuring the managed system

Follow the standard steps in [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md). The **Host URL** is the one field with a shape specific to this connector.

For establishing a connection with MSSQL server, the connector uses PSDrive that has its own path pattern: `SQLSERVER:\SQL\ComputerName\InstanceName`.\
Example: `SQLSERVER:\SQL\10.50.41.50,1433\default`\
If the standalone server hosts only one MSSQL Server, the connection path should have the `\default` ending.\
If the standalone server hosts more than one MSSQL server instances, connection path should end with the name of MSSQL Server instance.

For example:\
`SQLSERVER:\SQL\10.50.41.50,1433\Instance1`\
`SQLSERVER:\SQL\10.50.41.50,1433\Instance2`

See more at: [SQL Server PowerShell Provider](https://docs.microsoft.com/en-us/sql/powershell/sql-server-powershell-provider)

The connector supports the following MSSQL server authentications:

1. **MSSQL server authentication** – the connector uses MSSQL credentials that are set inside the OpenIAM Managed System configuration.
2. **Windows authentication** – the connector service should run as a Windows user which has permissions inside MSSQL server.

{% hint style="info" %}
Which authentication applies is decided by whether the managed system carries a login and password. With them, the connector opens the drive with those credentials; without them, it falls back to the identity of the Windows service — so Windows authentication is configured by leaving the OpenIAM credentials empty and setting the service account instead.
{% endhint %}

### Custom handlers

Search, delete, password, suspend and resume can each be routed to a script of your own instead of the connector's built-in path, by setting `SEARCH_HANDLER`, `DELETE_HANDLER`, `PASSWORD_HANDLER`, `SUSPEND_HANDLER` or `RESUME_HANDLER` on the managed system. A handler takes over that operation entirely. There is no hook for the create or update halves of save, which this connector does not split.

## Attribute mapping and policy map

The connector works in two modes:

1. With all databases in one MSSQL server (system databases will be ignored). It is the default mode.
2. With particular databases in one MSSQL server.

For provisioning database users in specific databases, the connector supports two approaches:

1. Set the **Databases** attribute in the user policy map. This approach allows adding or removing database users for particular databases.
2. Set `baseDN` or `DATABASE_NAME` attributes in metaData attributes. This approach allows for provisioning database users in one database. If both parameters are set, the connector will choose the `DATABASE_NAME` attribute.

| Attribute       | What it holds                | Example                  |
| --------------- | ---------------------------- | ------------------------ |
| `baseDN`        | The database path            | `Databases\DatabaseName` |
| `DATABASE_NAME` | The database name on its own | `DatabaseName`           |

Provisioning a user with Windows authentication additionally requires **`DOMAIN_NAME`** in the metaData attributes — the domain or server instance name, for example `OpenIAMDomain`.

The connector uses SMO objects for managing MSSQL objects. More info can be found at this [Link](https://docs.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo)

### ADD

| Attribute name                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Type                   |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| Name                                                  | <p>Specifies the user name in a database.<br><strong>Required</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | string                 |
| UserType                                              | <p>Specifies the type of user in a database.<br><strong>Required</strong><br><br><code>AsymmetricKey</code> - Specifies that the user login for the database is based on an asymmetric key.<br><code>Certificate</code> - Specifies that the user login for the database is based on a certificate.<br><code>External</code> - Specifies that the user is based on external authentication<br><code>NoLogin</code> - Specifies that the user does not have a login for the database.<br><code>SqlLogin</code> - Specifies a SQLLogin user. This is deprecated, use SQLUser instead.<br><code>SqlUser</code> - Specifies that the user is either a SQLLogin user or a user with password.<br></p> | enum                   |
| Login                                                 | <p>Specifies a name for the Login object. The case sensitivity is the same as that of the instance of the SQL Server.<br><strong>Required if <code>UserType</code> is SqlLogin</strong><br><strong>Required if <code>CreateLoginIfNotExist</code> is True</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                           | string                 |
| LoginType                                             | <p>Specifies the type of the Login object as a <code>Microsoft.SqlServer.Management.Smo.LoginType</code> value.<br><strong>Required if <code>CreateLoginIfNotExist</code> is True</strong><br><br><code>SqlLogin</code> - Login is based on the SQL login.<br><code>WindowsGroup</code> - Login is based on the Windows Group.<br><code>WindowsUser</code> - Login is based on the Windows User.<br></p>                                                                                                                                                                                                                                                                                         | enum                   |
| <p>CreateLoginIfNotExist<br>(Custom attribute)</p>    | <p>True – Create login if login does not exist<br>False – Do not create login</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | bool                   |
| <p>DataBaseRoles<br>(Custom attribute)</p>            | Contains database roles                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | <p>string<br>array</p> |
| <p>Databases<br>(Custom attribute)</p>                | <p>List of database names in which the user should be added.<br><code>baseDN</code> and <code>DATABASE\_NAME</code> attributes will be ignored</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | <p>string<br>array</p> |
| <p>ExcludeDatabasesByStatus<br>(Custom attribute)</p> | <p>List of database statuses which should be ignored.<br>Prevent provisioning the database user in databases which have status other than normal.<br><br><strong>In case only if connector works with all databases.</strong><br><br>Common statuses:<br>"Offline",<br>"Shutdown"<br><a href="https://docs.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo.databasestatus">More statuses</a></p>                                                                                                                                                                                                                                                                               | <p>string<br>array</p> |
|                                                       | **Login attributes**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                        |
| <p>Password<br>(Custom attribute)</p>                 | <p>Set password for login.<br><strong>Required if <code>CreateLoginIfNotExist</code> is True and <code>LoginType</code> is SqlLogin</strong></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | string                 |
| GrantConnectSql                                       | Indicates that the Login object is not denied permissions to connect to the database engine. By default, Login objects are denied permissions to connect to the database engine.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | bool                   |
| Enable                                                | Indicates that the Login object is enabled. By default, Login objects are disabled `WindowsGroup` type objects are always enabled. This parameter does not affect them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | bool                   |
| <p>ServerRoles<br>(Custom attribute)</p>              | Contains server roles                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | <p>string<br>array</p> |
| DefaultDatabase                                       | Specify the default database for the Login object. The default value is master.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | string                 |
| EnforcePasswordPolicy                                 | Indicates that the password policy is enforced for the Login object. This parameter applies only `SqlLogin` type objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | bool                   |
| EnforcePasswordExpiration                             | Indicates that the password expiration policy is enforced for the Login object. This parameter applies only `SqlLogin` type objects. This parameter implies the `EnforcePasswordPolicy` parameter. You do not have to specify both.                                                                                                                                                                                                                                                                                                                                                                                                                                                              | bool                   |
| MustChangePasswordAtNextLogin                         | Indicates that the user must change the password at the next login. This parameter applies only `SqlLogin` type objects. This parameter implies the `EnforcePasswordExpiration` parameter. You do not have to specify both.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | bool                   |

### MODIFY

| Attribute name                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                        | Type                   |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| Name                                                  | Only if `LoginType` is `SqlLogin` or UserType is `NoLogin`                                                                                                                                                                                                                                                                                                                                                         | string                 |
| <p>Password<br>(Custom attribute)</p>                 | Change password for Login, from the `Login` attribute                                                                                                                                                                                                                                                                                                                                                              | string                 |
| <p>DataBaseRoles<br>(Custom attribute)</p>            | Add and remove database roles for user `Name` attribute                                                                                                                                                                                                                                                                                                                                                            | <p>string<br>array</p> |
| GrantConnectSql                                       | <p>True – grant connect permission for the <code>Login</code> attribute<br>False – deny connect permission for the <code>Login</code> attribute</p>                                                                                                                                                                                                                                                                | bool                   |
| Enable                                                | <p>True – Enable user<br>False – Disable user<br><br>Note: Does not works for the <code>LoginType</code> = "WindowsGroup"</p>                                                                                                                                                                                                                                                                                      | bool                   |
| <p>ServerRoles<br>(Custom attribute)</p>              | Add and remove server roles for the `Login` attribute                                                                                                                                                                                                                                                                                                                                                              | <p>string<br>array</p> |
| DefaultDatabase                                       | Set default database for the `Login` attribute                                                                                                                                                                                                                                                                                                                                                                     | string                 |
| EnforcePasswordPolicy                                 | <p>Set enforce policy for the <code>Login</code> attribute<br><br>Note: For <code>LoginType</code> = <code>SqlLogin</code></p>                                                                                                                                                                                                                                                                                     | bool                   |
| EnforcePasswordExpiration                             | <p>Set enforce password expiration for the <code>Login</code> attribute<br><br>Note: For <code>LoginType</code> = <code>SqlLogin</code></p>                                                                                                                                                                                                                                                                        | bool                   |
| MustChangePasswordAtNextLogin                         | <p>Set user must change the password at the next login.<br><br>Note: Only for changing password for <code>LoginType</code> = <code>SqlLogin</code></p>                                                                                                                                                                                                                                                             | bool                   |
| <p>Databases<br>(Custom attribute)</p>                | <p>List of database names in which the user should be added or removed.<br><code>baseDN</code> and <code>DATABASE\_NAME</code> attributes will be ignored</p>                                                                                                                                                                                                                                                      | <p>string<br>array</p> |
| <p>ExcludeDatabasesByStatus<br>(Custom attribute)</p> | <p>List of database statuses which should be ignored.<br>Prevent provisioning the database user in databases which have a status another than normal.<br><br><strong>only if connector works with all the databases.</strong><br><br>Common statuses:<br>"Offline",<br>"Shutdown"<br><a href="https://docs.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo.databasestatus">More statuses</a></p> | <p>string<br>array</p> |

### RESET PASSWORD

Password can be changed only for `LoginType` = `SqlLogin`

| Attribute name                        | Description                                                          | Type   |
| ------------------------------------- | -------------------------------------------------------------------- | ------ |
| Login                                 | <p>Login name for user<br><strong>Required</strong></p>              | string |
| <p>Password<br>(Custom attribute)</p> | <p>New password for Login attribute<br><strong>Required</strong></p> | string |
| MustChangePasswordAtNextLogin         | Set if user must change the password at the next login.              | bool   |

### SUSPEND

Disable login. If login has windows authentication, then the `DATABASE_NAME` attribute should contain the domain or instance name.

| Attribute name | Description                                                                                                                        | Type   |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Login          | <p>Login name which will be disabled.<br><strong>Required</strong></p>                                                             | string |
| LoginType      | <p>Login’s type<br><strong>Required</strong><br><br>Note: Does not work for <code>LoginType</code> = <code>WindowsGroup</code></p> | enum   |

### RESUME

Enable login. If login has Windows authentication, then the `DATABASE_NAME` attribute should contain the domain or instance name.

| Attribute name | Description                                                                                                                        | Type   |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Login          | <p>Login name which will be enabled.<br><strong>Required</strong></p>                                                              | string |
| LoginType      | <p>Login’s type<br><strong>Required</strong><br><br>Note: Does not work for <code>LoginType</code> = <code>WindowsGroup</code></p> | enum   |

### DELETE

Deletes database user from the database. The database should be set in `baseDN` (database path) or the `DATABASE_NAME` attribute in metaData attributes. If the login uses Windows authentication, then the `DATABASE_NAME` attribute should contain the domain of the instance.

| Attribute name                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                      | Type                   |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| Name                                                  | <p>Database user name which will be deleted<br><strong>Required</strong></p>                                                                                                                                                                                                                                                                                                                                     | string                 |
| UserType                                              | <p>User’s type<br><strong>Required</strong></p>                                                                                                                                                                                                                                                                                                                                                                  | enum                   |
| <p>DropLoginIfNotUsed<br>(Custom attribute)</p>       | <p>True – After the user is deleted, the connector will check if the mapped login does not have any mapped users to other databases, and then the mapped login will be deleted.<br>False – After the user is deleted, the connector will not check the login to any user's mapping</p>                                                                                                                           | bool                   |
| LoginType                                             | <p>Login’s type<br>Required if login has windows authentication and <code>UserType</code> is not <code>NoLogin</code></p>                                                                                                                                                                                                                                                                                        | enum                   |
| <p>Databases<br>(Custom attribute)</p>                | <p>List of database names in which the user should be removed.<br><code>baseDN</code> and <code>DATABASE\_NAME</code> attributes will be ignored</p>                                                                                                                                                                                                                                                             | <p>string<br>array</p> |
| <p>ExcludeDatabasesByStatus<br>(Custom attribute)</p> | <p>List of database statuses which should be ignored.<br>Prevent provisioning the database user in databases which have a status other than normal.<br><br><strong>only if the connector works with all databases.</strong><br><br>Common statuses:<br>"Offline",<br>"Shutdown"<br><a href="https://docs.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo.databasestatus">More statuses</a></p> | <p>string<br>array</p> |

## Reconciliation and synchronization

How synchronization and reconciliation work in general is covered in the Administration guide — see [*Synchronize and import data*](/administration-guide/lifecycle/synchronize-and-import-data.md) and [*Configure reconciliation*](/administration-guide/lifecycle/configure-reconciliation.md). This section covers what the connector returns.

### User object

**Get-DBUsers** – return users from databases\
\[-Database \<array>] - array of database names or \* -all databases\
\[-UserName \<string>] - database user name\
\[-UsersFilter \<string>] - query for search\
\[-SkipSystemObject] – skip system databases (like master) and system users (like guest)

If `-Database` parameter is not set then the connector will use `baseDN` or `DATABASE_NAME` attributes. If the attributes do not exist the connector will return users from all databases.

| Attribute name     | Description                        | Response type |
| ------------------ | ---------------------------------- | ------------- |
| Id                 | User’s id                          | int           |
| Name               | User’s name                        | string        |
| Database           | User’s database                    | string        |
| DatabaseRole       | Granted database roles             | array         |
| UserType           | User’s type                        | string        |
| Login              | User’s login name                  | string        |
| LoginType          | Login’s type                       | string        |
| AuthenticationType | User’s authentication type         | string        |
| CreateDate         | User’s creation date               | string        |
| DateLastModified   | The last date of user modification | string        |

### Database object

**Get-Databases** – return databases\
\[-Database \<array>] - array of database names or \* - return all databases\
\[-SkipSystemObject] - skip system databases (like master)<br>

If the `-Database` parameter is not set then the connector will use `baseDN` or `DATABASE_NAME` attributes. If attributes do not exist the connector will return all databases.

| Attribute name  | Description              | Response type |
| --------------- | ------------------------ | ------------- |
| Id              | Id’s database            | int           |
| Name            | Database name            | string        |
| FixedRole       | Default database’s roles | array         |
| UserDefinedRole | Custom roles             | array         |


---

# 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 by asking a question.

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

```
GET https://docs.openiam.com/connector-configuration/microsoft/9-sqlserver.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.

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.