Dynamics 365 for Customer Engagement Adapter Limitations

This operation uses Microsoft Dynamics 365 for Customer Engagement Web API. For more details on API specifications, refer to the following page.

“Use the Dynamics 365 for Customer Engagement Web API” (https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/use-microsoft-dynamics-365-web-api)

This operation uses Azure Active Directory as authentication. For more details on Azure Active Directory configuration, refer to the following pages.

“Azure Active Directory developer's guide”(http://go.microsoft.com/fwlink/?LinkId=290817)
“Authorize access to web applications using OAuth 2.0 and Azure Active Directory” (https://msdn.microsoft.com/en-us/library/azure/dn645542.aspx)

Common to all operations

Setting method of service root URL in [Destination]

Enter “Service root URL” which is in "Settings" - "Customize" - “Developer resources” in Dynamics 365 for Customer Engagement.

URL is “https://<Host name>/api/data/<API version>” format.

Setting method of global resource of [Authentication]

For details about how to configure global resource of Authentication, refer to the following page.

Global Resource Properties (OpenID Connect 1.0)

You need a user with a security role which has permissions to each operation target. For more details about permissions, refer to the following page.

“Security model of Customer Engagement”(https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/security-dev/security-model)

You need to specify following parameters in [Additional parameters] of global resource.

[Additional parameters/Key]	[Additional parameters/Value]	Remarks
resource	<Scheme and host name of [Service root URL] set in [Destination]>	Parameter value is “https://<Host name>” format. “/api/data/<API version>” part is not needed.

[Resource path]

For more details about [Resource path], refer to the following page.

“OData Version 4.0. Part 2: URL Conventions Plus Errata 03” (http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html)

Notes

HTTPS is used in the communication between Dynamics 365 for Customer Engagement and this adapter.

This specifications is susceptible to change without any prior notification depending on the changes in Dynamics 365 for Customer Engagement specifications.

Refresh token has expiration date in Azure Active Directory authentication. When the token cannot be renewed, you need to reissue a token in the specified [Authentication] global resource.

Specification Limits

None.

Read Entity

Field definition

Entity type (Navigation property) is displayed only when the key is specified in [Resource path] and the entity is unique.

Example of [Resource path]	Whether or not to display Entity type (Navigation property)
accounts	Does not display.
accounts(00000000-0000-0000-0000-000000000001)	Displays.
accounts(accountid=00000000-0000-0000-0000-000000000001)	Displays.
accounts(00000000-0000-0000-0000-000000000001)/contact_customer_accounts	Does not display.

Query set in [Filter]

For more details on query set in [Filter], refer to the following page.

“Query Data using the Web API” (https://msdn.microsoft.com/library/gg334767.aspx#bkmk_filter)

Notes

Some entity sets got in [Update entity set name list] might not be able to be read.

Some fields got in [Update field definition] might not be able to be read.

Write Entity

Specification Limits

When all of the following conditions are satisfied, an error occurs in the operation of associating entities.
- [Create or update] or [Create only] is selected in [Processing method when the key is specified]
- The field defined with alternate key is selected in [Associated key fields] of [Associated key settings]
- A value containing the following characters is mapped with the field selected in [Associated key fields] of [Associated key settings]
  
  Character : * & +
When the operation to be associated with the entity field of N:1 entity relationship is performed, creating and updating the entity set in [Resource path] fail if the following conditions are satisfied.
- [Update only] is specified as the setting value for [Processing method when the key is specified]
- The entity whose setting value is the key does not exist in the related entity set

Character	:	*	&	+

Notes

If you specify a key in [Resource path], it is ignored.

Some entity sets got in [Update entity set name list] might not be able to be written.

Some fields got in [Update field definition] might not be able to be written.

When all of the following conditions are satisfied, the associated entity will not be created.
- Associated entity set is systemusers or teams
- There is no entity for the specified ownerid in the associated entity set
- The settings value of [Processing method when the key is specified] is [Create or update] or [Create only]

When the following operations are performed by using the alternate key, there are some characters that cannot be used as the key field.

Character Update operation Operation to associate entities

: No Yes

? No No

' No No

* No Yes

/ No No

\ No No

& No Yes

# Yes No

% No No

+ No Yes

< No Yes

> No Yes
- Yes: It can be used.
- No: It cannot be used.

Character	Update operation	Operation to associate entities
:	No	Yes
?	No	No
'	No	No
*	No	Yes
/	No	No
\	No	No
&	No	Yes
#	Yes	No
%	No	No
+	No	Yes
<	No	Yes
>	No	Yes

Delete Entity

Notes

If you specify a key in [Resource path], it is ignored.

Some entity sets got in [Update entity set name list] might not be able to be deleted.

Main Exceptions

Exception name	Cause	Solution
HttpClientException java.lang.IllegalStateException: Target host must not be null, or set in parameters.	[Service root URL] is invalid.	Check [Service root URL].
HttpClientException org.apache.http.client.ClientProtocolException: Scheme '<protocol>' not registered.	It is not supported protocol.	Check [Service root URL].
HttpClientException java.net.UnknownHostException: <Host name>	The host is not found.	Check [Service root URL].
EdmException Cannot find EntitySet, entitySetName=<Entity set name>	The entity set does not exist.	Check whether the entity set in [Resource path] exists.
EdmException Cannot find EntityType, path=<entity name>/<field name>	The field does not exist in entity.	Check whether the field of entity set in [Resource path] exists.
ODataClientErrorException (401) Unauthorized [HTTP/1.1 401 Unauthorized]	Authentication is failed.	Check [Service root URL]. Check [Authentication]. Confirm that a token can be issued in global resource of the specified [Authentication]. Confirm that the user is which security role which has authority to the target.
ODataClientErrorException <Error message> [<HTTP status>]	Failed to process.	Check the contents of the error message. For more details about HTTP status, refer to the following page. “Compose HTTP requests and handle errors”(https://msdn.microsoft.com/library/gg334391.aspx) Measure to all operations Check whether the entity exists in [Resource path]. Check whether the filed of entity set in [Resource path] exists. Check whether [Field definition] corresponds to [Resource path]. Measure which is particular to Read Entity operation Check the condition set in [Filter]. Check whether the entity set in [Resource path] can be read. Check the field set in [Field definition] can be read. Uncheck the field which cannot be read. Measure which is particular to Write Entity operation Check [Skip entity which the system failed to process]. Check [Processing method when the key is specified]. Check whether the entity set in [Resource path] can be written. Check whether the field set in [Field definition] can be written. Uncheck the field which cannot be written. Check whether the key field set to [Key field of resource path] exists in the entity set to [Resource path]. Check whether the key field set to [Associated key fields] of [Associated key settings] exists in the entity shown in [Associated entity] of the same row. Measure which is particular to Delete Entity operation Check [Skip entity which the system failed to process]. Check entity set in [Resource path] can be deleted.

Character	Update operation	Operation to associate entities
:	No	Yes
?	No	No
'	No	No
*	No	Yes
/	No	No
\	No	No
&	No	Yes
#	Yes	No
%	No	No
+	No	Yes
<	No	Yes
>	No	Yes

Character	Update operation	Operation to associate entities
:	No	Yes
?	No	No
'	No	No
*	No	Yes
/	No	No
\	No	No
&	No	Yes
#	Yes	No
%	No	No
+	No	Yes
<	No	Yes
>	No	Yes

Character	Update operation	Operation to associate entities
:	No	Yes
?	No	No
'	No	No
*	No	Yes
/	No	No
\	No	No
&	No	Yes
#	Yes	No
%	No	No
+	No	Yes
<	No	Yes
>	No	Yes