TIBCO Scribe® Online Connector for Microsoft Dynamics 365 for Finance and Operations/AX

The TIBCO Scribe® Online Connector For Microsoft Dynamics 365 for Finance and Operations/AX supports a variety of operations to multiple organizations/tenants using the OData Web Service including, query, create, update, insert, update/insert, and delete. The connector also supports authentication using Azure Active Directory and advanced functionality for configured customized HTTP requests.

Connector Specifications

This Connector supports Microsoft Dynamics 365 for Finance and Operations/AX Online and is compliant with OData version 4.

	Supported
Agent Types
On Premise	X
Cloud	X
Replication Services
Source
Target
Integration Services
Source	X
Target	X
Migration Services
Source	X
Target	X
Maps
Integration	X
Request-Reply	X
Message

Setup Considerations

• TIBCO Scribe® Online requires a Microsoft Dynamics 365 for Finance and Operations/AX Organization hosted in an Azure environment.
• TIBCO Scribe® Online can only access Dynamics 365 for Finance and Operations/AX entities and fields that are exposed to OData web services in Dynamics 365 for Finance and Operations/AX by marking them as IsPublic in the Dynamics 365 for Finance and Operations/AX Application Object Tree (AOT). Contact your Microsoft Dynamics 365 for Finance and Operations/AX Administrator for assistance.
• Company names cannot contain special characters, such as apostrophe (') or tilde (~). If you use special characters in the Company Name, the Connector generates an invalid URL when it publishes an OData Web Service, which prevents the Connector from connecting to Microsoft Dynamics 365 for Finance and Operations/AX.

Azure AD Best Practices

If you authenticate using Azure AD, there are some timing issues to consider to prevent errors.

• Avoid reauthenticating an Azure AD connection while running a Solution using the connection. There is a narrow window where this could cause the Solution to fail and may generate an exception similar to the following:

  Authorization Code already Redeemed

• Avoid reauthenticating an Azure AD connection while resetting metadata or when metadata is being loaded in a Solution or Map. There is a narrow window where this could result in an exception similar to the following:

  Key not found Exception

• Avoid hitting Cancel on the Connection dialog after successfully testing a connection: Due to the nature of this authentication type, testing credentials modifies the credentials whether you cancel or not.

Client Secret Authentication Requirements

To use Client Secret Authentication, a Connected app in the Azure portal is required. You can use the TIBCO Connected app or you can create an App Registration in the Azure portal. To create an App Registration, be sure to configure the following:

• Select single or multi-tenant based on the number of users.
• Select API Permissions > Add a permission > Select an API ->Dynamics ERP.

• Under Delegated permissions add a checkmark to the following checkboxes:

  • AX.FullAccess
  • CustomService.FullAccess
  • Odata.FullAccess

Once the App is created, you can find Tenant Id and Client Id on the User Interface.

Legacy OAuth Authentication Requirements

Azure Active Directory (Azure AD), a Microsoft multi-tenant, cloud-based directory and identity management service, provides single sign-on (SSO) access to cloud SaaS Applications, such as Office365, Salesforce.com, and DropBox. To begin, set the Client Id in the Azure AD account where the Dynamics 365 for Finance and Operations/AX application is deployed.

To set the client ID in the Azure AD account, you must:

• Register your application with Azure AD - For instructions, see Register a native application with AAD in the Service Endpoints section of the Dynamics 365 for Finance and Operations/AX online documentation.
• Obtain an authentication URL - You can either use a standard URL or specify an endpoint:
  • Standard URL - Use the standard Microsoft URL: https://login.microsoftonline.com/common.
  • Specify an endpoint - Use an endpoint specific to the user who has access to the Dynamics 365 for Finance and Operations/AX application. For example, if John Doe has access to the application, and his email address is john.doe@companyname.com, the Azure AD domain name would be companyname.com.

  For more information on authentication with Azure AD, see Basics of Registering an Application in Azure AD.

Selecting an Agent Type for Dynamics 365 for Finance and Operations/AX

Refer to TIBCO Scribe® Online Agents for information on available Agent types and how to select the best Agent for your Solution.

Connecting to Dynamics 365 for Finance and Operations/AX

Deployment Types

There are two deployment types for the Microsoft Dynamics 365 for Finance and Operations/AX Connector that provide different authentication methods. Follow the link for the deployment type you plan to use for step-by-step configuration instructions: 

• Client Secret Authentication - Select to use Client Secret Authentication with Active Directory.
• Legacy OAuth Authentication - This option is being deprecated by Microsoft. Use Client Secret Authentication instead.

Client Secret Authentication

1. Select More > Connections from the menu.
2. From the Connections page, select Add to open the Add a New Connection dialog.
3. Select the Connector from the drop-down list in the Connection Type field, and then enter the following information for this Connection:
   • Name — This can be any meaningful name, up to 25 characters.
   • Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
   • Deployment - Select Client Secret
   • OData Service URL - The address of any acceptable URL where the OData service is located. This URL must end in /data.
   • Tenant - Enter the Tenant Id, also known as the Directory ID, generated when you registered the Azure Active Directory (AAD) application. Required.
   • Client ID - GUID that identifies the client in the Dynamics 365 for Finance and Operations/AX system. This is the Application ID generated when registering the application in Azure Active Directory. Required.
   • Client Secret - Enter the Client Secret generated when you registered the Azure Active Directory (AAD) application.
   • Company Name - The company specified in Dynamics 365 for Finance and Operations/AX for this integration. Required.
4. Select Test to ensure that the Agent can connect to your database. Be sure to test the Connection against all Agents that use this Connection. See Testing Connections.
5. Select OK/Save to save the Connection.

Legacy OAuth Authentication

1. Select More > Connections from the menu.
2. From the Connections page select Add to open the Add a New Connection dialog.
3. Select the Connector from the drop-down list in the Connection Type field, and then enter the following information for this Connection:
   • Name — This can be any meaningful name, up to 25 characters.
   • Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
   • Deployment - Select Legacy OAuth
   • OData Service URL - The address of any acceptable URL where the OData service is located. This URL must end in /data.
   • User - The name of the user who has rights to access OData, if your OData service requires authentication. Required.
   • Password - The password for User, if your OData service requires authentication. For more information on OData, see your endpoint provider. Required.
   • Client ID - GUID that identifies the client in the Dynamics 365 for Finance and Operations/AX system. This is the Application ID generated when registering the application in Azure Active Directory. Required.
   • Authentication URL - The URL where the Client Id is verified in following the format. Required.

     http://login.microsoftonline.com/[domain_name]

   • Company Name - The company specified in Dynamics 365 for Finance and Operations/AX for this integration. Required.
4. Select Test to ensure that the Agent can connect to your database. Be sure to test the Connection against all Agents that use this Connection. See Testing Connections.
5. Select OK/Save to save the Connection.

Metadata Notes

Consider the following for Dynamics 365 for Finance and Operations/AX data fields and entity types.

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

Related Entities

• Using relationships in the Include tab on the Query Block or Fetch Block may require you to expose related entities and fields to the OData web services in Dynamics 365 for Finance and Operations/AX. See the note at the beginning of this document for more information on exposing entities and fields.
• Only one relationship is supported within a Map.
• Hierarchical data is not supported.

Query Timeouts

• Query operations run on an entire SQL table may cause a timeout. If a Query operation times out, reduce the number of fields selected for the Query.

  Note: Reducing the number of fields selected for the Query does not affect Preview, which selects all fields. You must run the Query operation to determine if the reduced number of fields selected resolved the timeout.

Retry Logic

When a timeout occurs, theMicrosoft Dynamics 365 for Finance and Operations/AX Connector retries three times with the following delays in between:

• Retry 1 delay = 1 second
• Retry 2 delay = 2 seconds
• Retry 3 delay = 3 seconds

When a throttle limit or request limit exceeded error is received, the Microsoft Dynamics 365 for Finance and Operations/AX Connector retries once using the delay returned by Microsoft Dynamics 365 for Finance and Operations/AX. This delay throttles or slows down the entire Map.

Filters

The "is like" and "is not like" operators are not supported. For the "is like"operator, use the "equals" operator and use an "*" as a wild card character. The "is not like" operator does not have a similar alternative.

Dynamics 365 for Finance and Operations/AX Connector As IS/MS Source

Consider the following when using the Dynamics 365 for Finance and Operations/AX Connector as an IS/MS source.

Custom Fields

• By default the creation date/time, last modified date/time, created by user and last modified by user fields are not exposed for any of the standard OData entities provided by Microsoft. If those fields are required for your integration, create similarly named fields and map the standard fields to the new fields. Different field names are required on the new fields because standard field names are reserved and cannot be exposed. See the note at the beginning of this document for more information on exposing entities and fields.

Filtering On Multiple Companies

• To return results from more than one company, you can filter for multiple companies. For example, to return records associated with either the MyTicket company or the EventsManager company, define a filter that accepts those values for the dataAreaId field.

Dynamics 365 for Finance and Operations/AX Connector As IS/MS Target

Consider the following when using the Dynamics 365 for Finance and Operations/AX Connector as an IS/MS target.

Batch Processing

• This Connector does not support Batch Processing.

Mapping Unrequired Fields

• Some unrequired fields are marked as required. Mapping an unrequired field in Dynamics 365 for Finance and Operations/AX causes an error to occur.

  The following fields are not required for the Create or Update operation, and generate an error if mapped:

  • AmountChargedNotPosted
  • DAXIntegrationId

Update And Upsert Operations

• This Connector supports the Update Patch operation.
• This Connector does not support the following operations:
  • Update Replace
  • Upsert Replace
  • Upsert Patch

  Using any of these unsupported functions may cause an error message.

• dataAreaId - When performing a target operation, such as Update Patch, if the dataAreaId value for the record you are updating is not the same as the Company Name in your Dynamics 365 for Finance and Operations/AX Connection, the record is only found and updated if you include the dataAreaId of the record in the Match Criteria of your target operation Block.

Send Operation

• The Send operation is used to make API Calls to Microsoft Dynamics 365 for Finance and Operations/AX APIs. It can be used to support custom calls to Dynamics 365 for Finance and Operations/AX REST APIs.
• The Send Block supports the Request entity used to build the HTTP calls to the API.
• The Send Block works in conjunction with the Add Block to include Headers, Cookies, or Query parameters.
• The Send and Add operations support the use of the following variables or tokens to make configuring customized API calls easy and robust:

  Name	Example Value
  [authToken]	QVNQUkFTQUQ6MTl2QWt3NOZKLmoiVnVvOWxjeVl2M3NiSERoakY0STgyVTd2WEtmenQ0az0=
  [endpointUrl]	https://<your-company-info>.axcloud.dynamics.com
  [organizationId]	Your Company Name

  • authToken - The Connector derives the value of the [authToken] variable from either the authentication token or the session ID associated with the authentication method configured in the Connection. This token is used to perform the POST, GET, and any other HTTP Verb calls using the Request entity.

    Note: When using Basic Credentials Authentication, pass the Authorization header as Basic [authToken] in Request.Headers. For Client Secret Authentication pass the Authorization header as Bearer [authToken].

    • For Basic Authentication

      

      

      • For Client Secret Authentication:

        

        

      Note: The [authToken] must be provided in the Request Header for any HTTP request.
      Note: If the Authorization Token is provided explicitly, instead of using the [authToken] variable, and the token is refreshed, an error similar to the following is generated:

      Operation failed. Label: Send Request, Name: RequestSend, Message: Forbidden: Error in calling Operation Send Http call failed with StatusCode 403 - Forbidden. Response Body: Bad_OAuth_Token.

      • endpointUrl - The Connector derives the value of the [endpointUrl] from the Microsoft Dynamics 365 for Finance and Operations/AX organization associated with the Connection configuration. This is the Custom Domain URL for your Microsoft Dynamics 365 for Finance and Operations/AX organization. Use the [endpointUrl] to construct the URI for the HTTP request. Note that the value of the variable includes "https://". The value of endpointUrl is https://<your-company-info>.axcloud.dynamics.com as shown in the above table.

        
        

        
        

      • organizationId - The Connector derives the value of the [organizationId] from the Microsoft Dynamics 365 for Finance and Operations/AX Company associated with the Connection configuration. This is the Company Name of your Microsoft Dynamics 365 for Finance and Operations/AX organization. [organizationId] is used wherever the dataAreaId is specified as a parameter in the Microsoft Dynamics 365 for Finance and Operations/AX API documentation.

        
        

        
        

        Note: You can provide [organizationId] in the Request.QueryParameters or in the Uri field of Request Entity.
  • The Send block, the Add block, and the Request entity are based on the functionality in the HTTP Connector. For more details see the HTTP Connector help.

Optimistic Concurrency

• The OData Protocol uses Entity Tags (ETag) to determine how to update or delete data. Rules for updating or deleting data are based on the ETag value and the concurrency behavior. There are three options for concurrency behavior: always overwrite, overwrite if ETag has not changed, or overwrite if ETag has changed.

  The Dynamics 365 for Finance and Operations/AX Connector exposes these ETags as fields:

  • ETag - Available as a source and target field, contains the ETag value provided by the Dynamics 365 for Finance and Operations/AX OData service.
  • ETagConcurrencyBehavior - Available as a target field, used to determine how data conflicts are handled. Possible values for this field are:
    • Always Overwrite
    • Overwrite If Match
    • Overwrite If Not Match

  If these fields are left blank and the entity provides ETag information, the default is to always overwrite the record.

• Delete operations always perform the default behavior. There is no way to map fields within a Delete Block. Therefore, if you attempt to use a Delete Block it always overwrites the existing data.
• Optimistic Concurrency is an optional OData feature and is limited to specific entities. Contact your Dynamics 365 for Finance and Operations/AX OData service administrator for additional information.

TIBCO Scribe® Online API Considerations

You must define a Connection Name and Connection Alias for each OData endpoint. For more information, see TIBCO Scribe® Online Connector For OData.

To create Connections with the TIBCO Scribe® Online API, the Dynamics 365 for Finance and Operations/AX Connector requires the following information:

Connector Name	Microsoft Dynamics 365 for Operations/AX7
Connector ID	A48234C1-BDE7-4AF0-B88E-64478168EF30

TIBCO Scribe® Online Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

Client Secret OAuth Properties

Name	Data Type	Required	Secured	Usage
DynamicsAuthenticationType	string	Yes	No
CompanyId	string	Yes	No
ClientId	string	Yes	Yes
ServiceUrl	string	Yes	No
ClientCredsTenant	string	Yes	No
ClientSecret	string	Yes	Yes

Legacy OAuth Connection Properties

Name	Data Type	Required	Secured	Usage
AuthenticationUrl	string	Yes	No
CompanyId	string	Yes	No
ClientId	string	Yes	Yes
ServiceUrl	string	Yes	No
User	string	Yes	No
Password	string	Yes	Yes
AuthenticationType	string	Yes	No	None, Basic

License Agreement

The TIBCO Scribe® Online End User License Agreement for the Dynamics 365 for Finance and Operations/AX Connector describes your and TIBCO's legal obligations and requirements. TIBCO suggests that you read the End User License Agreement.

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.