Dynamics365 connector

General information

Dynamics365 connector integrates Dynamics365 environment with OpenIAM allowing to manage entities, business units and roles memberships from OpenIAM. It allows to use Dynamics365 in sync with other manged systems that are linked to OpenIAM.

Dynamics365 connector is open sourced and is shiped with basic functionality that could be extended according to your needs.

Out of the box Dynamics365 connector can:

  • Retrieve information about system user objects in Dynamics365 environment
  • Retrieve information about roles in Dynamics365 environment
  • Assign/revoke system roles from system users
  • Assign/revoke business unit affiliation for system users
  • Set and modify basic system user information

Dynamics365 connector conains .NET PowerShell module that help you to run requests towards Dynamics365 API. Using 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 in the document: 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 in the document: PowerShell connector usage

Configuring managed system

While configuring managed system you should have 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 Dynamics365 API, one needs to have base API location that is appended to your resource address (which you set at Host URL parameter of the Managed system configuration page). Dynamics365 connector contains following value by default: 'api/data/v9.1/'. This value could be overriden in Connector.ps1 script that is located inside connector folder.

PropertyDescriptionRequired
systemuseridUnique identifier of system user in Dynamics365Yes
businessunitidUnique identifier of business init in Dynamics365.Yes (for adding user)
internalemailaddressInternal email address for the user.Yes (required for creating user)
domainnameCould be used to set 'domainname' parameter of system user. This parameter could be applied only for create systemuser operation and is ignored for update operations, because Dynamics365 API does not allow 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 could be set during update process. Some attributes are only allowed while you add 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 Suspend operation, connector modified 'isdisabled' property of a given user. Resume operation sets the same proparty back to 'false' state.

Deleting users

Deleting users is not supported by Dynamics365 API. You can disable user instead.

Synchronization

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 'isdisabled' property to NULL using API. But when you try to change it to 'true' or 'false' value back - you would be able to see such error.You can try to figure out which attribute 'breaks' request by turning them off. When you find this attribute you can try to understand why this happens by comparing user with 'normal' ones.
Unable to retrieve attribute=businessunitid for entityLogicalName=systemuserNo businessunitid was specified for create usde operation.Need to specify businessunitid or figure out why connector does not receive this value.