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.

PropertyDescriptionRequired
systemuseridUnique identifier of system user in Dynamics365Yes
businessunitidUnique identifier of business unit in Dynamics365.Yes (for adding user)
internalemailaddressInternal email address for the user.Yes (required for creating user)
domainnameCould 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
roleidUnique identifier of role in Dynamics365. Used for assigning roles to system usersNo
firstnameFirst name of the user.No
lastnameLast name of the user.No
isdisabledInformation about whether the user is enabled or not.No
photourlURL for the website on which a photo of the user is located.No
employeeidEmployee identifier for the user.No
governmentidGovernment identifier for the user.No
homephoneHome phone for the user.No
jobtitleJob title of the user.No
middlenameMiddle name of the user.No
mobilephoneMobile phone of the user.No
nicknameNickname of the user.No
salutationSalutation for correspondence with the user.No
skillsSkill set of the user.No
titleTitle 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.

ErrorPossible causeHow 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=systemuserNo businessunitid was specified for the create usde operation.Need to specify businessunitid or figure out why the connector does not receive this value.