Dynamics365 connector
General information
The Dynamics365 connector integrates the Dynamics365 environment with OpenIAM allowing the managemenet of entities, business units and role memberships from OpenIAM. It allows us to use Dynamics365 in sync with other manged systems that are 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
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.
Installation and connection to OpenIAM
All PowerShell connectors are installed in the same way which is described at this link: PowerShell connector installation
Only requirement specific to this connector is being able to connect to your Dynamics365 tenant address.
General usage
All PowerShell connectors are used in the same way which is described at this link: PowerShell connector usage
Configuring managed system
While configuring the managed system you should have the following properties set:
- Host URL - should be set to your resource address like: https://yourcompany.api.crm4.dynamics.com/
- Login Id - uses format client_id@tenant_id that is used to access your API
- Password - should be set to client_secret value
Configuring 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.1/'. 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 |
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.
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:
Get-Dynamics365Systemusers
Search query for synchronizing single systemuser:
Get-Dynamics365Systemusers(e5f759c2-cde2-4396-a153-53a53d2cf172)
Search query for synchronizing all roles:
Get-Dynamics365Roles
Search query for synchronizing single role:
Get-Dynamics365Roles(e5f759c2-cde2-4396-a153-53a53d2cf172)
Possible errors
Errors in the table below contain most frequent and/or tricky errors could be encountered during connector operation.
| Error | Possible cause | How to fix |
|---|---|---|
| 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 usde operation. | Need to specify businessunitid or figure out why the connector does not receive this value. |