> 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/8-dynamics365.md).
# Dynamics365 connector
This page describes how to use the OpenIAM Dynamics 365 connector
The Dynamics365 connector integrates the Dynamics365 environment with OpenIAM allowing the management of entities, business units and role memberships from OpenIAM. That keeps Dynamics 365 in step with the other managed systems linked to OpenIAM.
The Dynamics365 connector is open source and is shipped with basic functionality that could be extended according to your needs.
The out-of-the-box Dynamics365 connector can:
* Retrieve information about system user objects in a Dynamics365 environment
* Retrieve information about roles in a Dynamics365 environment
* Assign/revoke system roles from system users
* Assign/revoke business unit affiliation for system users
* Set and modify basic system user information
* Add and remove team membership
* Add and remove queue membership
The Dynamics365 connector contains a .NET PowerShell module that helps you to run requests to the Dynamics365 API. Use of cmdlets from that module will be described later in this document.
| Operation | Supported |
| ------------------------ | --------------------------------------------------------------------------------------- |
| Create / update (Save) | ✅ |
| Search | ✅ |
| Suspend / resume | ✅ — writes the `isdisabled` property |
| Delete | ✅ for **Contact** — refused for system users, which the Dynamics 365 API does not allow |
| Reset password | ❌ — not implemented |
| Check a password (Login) | ✅ |
| Test connection | ❌ — see the note below |
## Use cases
* **Provisioning system users into Dynamics 365** as part of joining, with the business unit and security roles their job requires.
* **Keeping team and queue membership in step** with role changes, which Dynamics holds separately from the user record.
* **Managing contacts** alongside system users, which is the one entity type this connector can also delete.
* **Reading Dynamics back into OpenIAM** for reconciliation and certification.
## Versions and compatibility
The connector talks to the Dynamics 365 Web API over HTTP, so what matters is the **API version** in the endpoint it builds, not a product version of its own.
The endpoint is your resource address — the **Host URL** on the managed system — with a base API path appended. That path defaults to `api/data/v9.2/` and can be overridden in `Connector.ps1` in the connector folder.
## Prerequisites
* The connector host can reach your Dynamics 365 tenant address.
* An application registration whose **client ID**, **tenant ID** and **client secret** the connector can use — see [Configuring the managed system](#configuring-the-managed-system) for how they are entered.
## Installing the connector
All PowerShell connectors are installed in the same way which is described at this link: [PowerShell connector installation](/connector-configuration/microsoft/1-powershellconnectorinstallation.md)
Only requirement specific to this connector is being able to connect to your Dynamics365 tenant address.
## Starting, stopping, and restarting
The installer registers a pair of Windows services 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
All PowerShell connectors are used in the same way which is described at this link: [PowerShell connector usage](/connector-configuration/microsoft/2-powershellconnectorsusage.md)
The one connector-specific value that lives in a file rather than on the managed system is the **base API path**, in `Connector.ps1`. Everything else — queues, concurrency, logging, simulation mode — is `Connector.config`, documented 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 a search — `Get-Dynamics365Roles` is a cheap one — to prove the path end to end.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
This connector does not support **Test Connection** — it refuses the request rather than answering it. OpenIAM's periodic health check against the managed system therefore fails permanently until you set `DisableManSysHealthcheckRequests` to `True` in the connector's `Connector.config`. The installer also offers this as the end-to-end managed system check, which you can leave unticked.
{% endhint %}
## Troubleshooting
Troubleshooting for the whole family is in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md). The errors below are the ones most often hit with this connector.
| Symptom | Likely cause | Resolution |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Got API response status code - '500'. ErrorMessage - 'Server returned 'InternalServerError'` | User can be in a broken state. For example, you can set the `isdisabled` property to NULL using the API. But when you try to change it to `true` or `false` you would be able to see such an error. | You can try to figure out which attribute `breaks` the request by turning them off. When you find this attribute you can try to understand why this happens by comparing the user with `normal` ones. |
| `Unable to retrieve attribute=businessunitid for entityLogicalName=systemuser` | No businessunitid was specified for the create operation. | Specify `businessunitid`, or find out why the connector is not receiving it. |
| `Login for managed system should be like clientID@tenantID. Operation is stopped` | The managed system's **Login Id** is not in the required form. | It is the two values joined by an `@`, not a user name — see [Configuring the managed system](#configuring-the-managed-system). |
| `Could not get bearer token for further operations` | The connector authenticated and got nothing back. | Check the Login Id, the client secret in **Password**, and the **Host URL**. |
| `No Systemuserid is set for ADD operation`, `No contactid is set for ADD operation`, `No ExternalId is set for ADD operation` | A create arrived without the identifier the entity is keyed by. | This is a deliberate stop: the connector refuses rather than creating an object it could not then find again. Check the policy map supplies the key for the entity type in use. |
| `Could not find newly created user for further operations` | The create succeeded but the user could not be read back, so the steps after it were abandoned. | Usually a permissions problem on read, or replication lag in the tenant. |
| `Removing systemusers is not supported by Dynamics365 API` | A delete arrived for a system user. | The API allows deleting contacts only. Suspend the system user instead. |
| `Reset-IdentityPassword is not implemented` | A password reset arrived. | Dynamics 365 accounts authenticate through Entra ID; reset the password there. |
| `This connector does not support end-to-end validation of the managed system` | Test Connection was attempted. | Expected — set `DisableManSysHealthcheckRequests` to `True`, as described above. |
| `Unable to find case sensitive value of identity name` | The identity value does not match once case is taken into account. | Check the principal attribute's value in OpenIAM against the record in Dynamics. |
## 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
While configuring the managed system you should have the following properties set:
* Host URL - should be set to your resource address like:
* Login Id - uses format client\_id\@tenant\_id that is used to access your API
* Password - should be set to client\_secret value
### Choosing the entity type
The connector provisions more than system users. The **`EntityType`** attribute on the managed system selects which object a request acts on:
| Value | What it provisions |
| ------------------------- | ---------------------------------------------------------------------------- |
| `SystemUser` | Dynamics 365 system users. **The default** when the attribute is not set |
| `Contact` | Dynamics 365 contacts. This is the entity type for which delete is supported |
| `Dot_mdm_externalaccount` | Recognized but not implemented — a request against it is refused |
### 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.
## Attribute mapping and policy map
To be able to run requests to the Dynamics365 API, one needs to have the base API location that is appended to your resource address (which you set at the Host URL parameter of the Managed System configuration page). The Dynamics365 connector contains the following value by default: `api/data/v9.2/`. This value could be overridden in the Connector.ps1 script that is located inside the connector folder.
| Property | Description | Required |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| systemuserid | Unique identifier of system user in Dynamics365 | Yes |
| businessunitid | Unique identifier of business unit in Dynamics365. | Yes (for adding user) |
| internalemailaddress | Internal email address for the user. | Yes (required for creating user) |
| domainname | Could be used to set the `domainname` parameter of the system user. This parameter can be applied only for the create systemuser operation and is ignored for update operations because the Dynamics365 API does not allow us to change it after creation. | No |
| roleid | Unique identifier of role in Dynamics365. Used for assigning roles to system users | No |
| firstname | First name of the user. | No |
| lastname | Last name of the user. | No |
| isdisabled | Information about whether the user is enabled or not. | No |
| photourl | URL for the website on which a photo of the user is located. | No |
| employeeid | Employee identifier for the user. | No |
| governmentid | Government identifier for the user. | No |
| homephone | Home phone for the user. | No |
| jobtitle | Job title of the user. | No |
| middlename | Middle name of the user. | No |
| mobilephone | Mobile phone of the user. | No |
| nickname | Nickname of the user. | No |
| salutation | Salutation for correspondence with the user. | No |
| skills | Skill set of the user. | No |
| title | Title of the user. | No |
### Team and queue membership
Two attributes are handled apart from the property table above, because they are memberships rather than fields on the user:
| Attribute | Effect |
| --------- | -------------------------------------------------------------------------------------------- |
| `Teams` | Each value is a team ID. An add or update joins the user to that team; a delete removes them |
| `Queues` | Each value is a queue ID, handled the same way |
### Add vs Update operations difference
Due to Dynamics365 limitations, not every attribute can be set during update process. Some attributes are only allowed when you add a new user.
**Attributes allowed for ADD operation:** `systemuserid`,`domainname`,`firstname`,`lastname`,`businessunitid`, `isdisabled`,`internalemailaddress`,`photourl`, `employeeid`,`governmentid`,`homephone`,`jobtitle`,`middlename`, `mobilephone`,`nickname`,`salutation`,`skills`,`title`
**Attributes allowed for UPDATE operation:** `firstname`,`lastname`,`businessunitid`,`isdisabled`,`internalemailaddress`, `photourl`,`employeeid`,`governmentid`,`homephone`,`jobtitle`,`middlename`, `mobilephone`,`nickname`,`salutation`,`skills`,`title`
### Suspend and resume operations
When OpenIAM sends a Suspend operation, the connector modifies the `isdisabled` property of a given user. The Resume operation sets the same property back to a `false` state.
### Deleting users
Deleting users is not supported by Dynamics365 API. You can disable a user instead.
Delete is supported for the **Contact** entity type. For system users the connector refuses the request rather than failing silently, reporting that removing system users is not supported by the Dynamics 365 API.
## Reconciliation and synchronization
The Dynamics365 connector can synchronize Systemusers and Roles objects. It can synchrinize all of them or a single record by a given identifier.
Search query for synchronizing all systemusers:
```powershell
Get-Dynamics365Systemusers
```
Search query for synchronizing single systemuser:
```powershell
Get-Dynamics365Systemusers(e5f759c2-cde2-4396-a153-53a53d2cf172)
```
Search query for synchronizing all roles:
```powershell
Get-Dynamics365Roles
```
Search query for synchronizing single role:
```powershell
Get-Dynamics365Roles(e5f759c2-cde2-4396-a153-53a53d2cf172)
```
Those two are the object types most deployments synchronize, but they are not the only ones the connector can read. It also ships cmdlets for business units, contacts, entities, metadata, organizations, owner teams, positions, queues, teams, team templates and incidents, each following the same `Get-Dynamics365