TIBCO Scribe® Online Connector For Microsoft Dynamics 365 Business Central / NAV

The TIBCO Scribe® Online Connector for Microsoft Dynamics 365 Business Central / NAV supports both REST and OData endpoints for Dynamics 365 Business Central, and OData Web Services for Dynamics NAV. The connector supports a variety of operations 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.

Use the TIBCO Scribe® Connector for Dynamics 365 Business Central / NAV to create source or target Connections in Integration or Migration Solutions using the Open Data Protocol (OData) standard.

Connector Specifications

This Connector supports Microsoft Dynamics NAV and Microsoft Dynamics 365 Business Central / NAV using OData v4 web services or REST APIs. For more information, contact your System Administrator.

	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

Supported Entities

The Dynamics 365 Business Central / NAV Connector supports any entities that you have exposed to the OData service in Dynamics 365 Business Central / NAV.

Supported Operations

Standard operations for Dynamics 365 Business Central / NAV entities include:

• Query
• Create
• Update
• Update/Insert
• Delete

Update Operations

• If you try to use an operation that is not implemented in your Dynamics 365 Business Central / NAV OData endpoint, you may see an error message.
• The success of Update operations is affected by ETag usage. Refer to Optimistic Concurrency below for additional information.
• Update/Insert — If your Dynamics 365 Business Central / NAV OData service is implemented to support more than one Update operation, TIBCO Scribe® Online cannot anticipate which of these Update operations to use in a Block.

  Note: Best practice is to use separate UpdateMerge, UpdateReplace, or UpdatePatch, not the Update/Insert Block.

Special Operations

Supported special operations are based on the version of the OData service used. Operations include:

• UpdateMerge — Overwrites fields in the existing record with the data provided from the source. All other fields remain unchanged.
• UpdateReplace — Overwrites the entire record except for the fields with data provided from the source. If any mapped source fields are empty, target fields with data are overwritten with the default value for that field.

  Note: If you plan to use UpdateReplace, refer to Knowledge Base article Dynamics NAV OData Service UpdateReplace Operation Issue.

• UpdatePatch — Overwrites fields in the existing record with the data provided from the source. All other fields remain unchanged.
• Send — Makes API calls to Microsoft Dynamics 365 Business Central / NAV APIs. See Send Operation for more information.

Supported special operations for collections include:

• CreateWith — Container Block used with hierarchical data to add a parent record that may contain one or more child records. This Block collects all of the data for a single record before writing the entire record to the target. See CreateWith Block.
• UpdateWith — Container Block used with hierarchical data. Use this Block to update a parent record that may contain one or more child records. This Block collects all of the data for a single parent record before writing the record to the target. See UpdateWith Block.

  Note: Operation results from an UpdateWith Block are not available for use in subsequent Blocks.

• Add — Used for hierarchical data to add child records to the parent selected in a CreateWith or UpdateWith Block. See Add Block.

Setup Considerations

• OData services must be enabled in Dynamics 365 Business Central / NAV.
• Company names cannot contain special characters, such as apostrophe (') or tilde (~). If you use special characters in the Company name, an invalid URL is generated when publishing an OData web service, which prevents the Connector from connecting to Dynamics 365 Business Central / NAV.

Client Secret Authentication

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 a new App Registration in the Azure portal. To create a new App Registration, be sure to enable the following:

• Select single or multi-tenant based on the number of users.
• Select API Permissions > Add a permission > Dynamics 365 Business Central.
• Under Delegated permissions enable the following checkboxes:
  • user_impersonation
  • Financials.ReadWrite.All

• Under Application permissions enable the following checkboxes:

  • app_access
  • API.ReadWrite.All
  • Automation.ReadWrite.All

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

 

Selecting An Agent Type For Dynamics 365 Business Central / NAV

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 Business Central / NAV

There are two deployment types for the Microsoft Dynamics 365 Business Central / NAV Connector that provides different authentication methods. Follow the link for the authentication method you plan to use for step-by-step configuration instructions:

• Basic Authentication — Select if you do not want to authenticate using Active Directory.
• Client Secret Authentication — Select to use Client Secret authentication with Active Directory.

Basic 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.
   • OData Service URL — The address of any acceptable URL where the Dynamics 365 Business Central / NAV OData service is located.
   • User — The name of the user who has rights to access Dynamics 365 Business Central / NAV OData, if your Dynamics 365 Business Central / NAV OData service requires authentication.
   • Password — The password, if your Dynamics NAV OData service requires authentication.

     Note: If you are connecting to Dynamics 365 Business Central, you must enter your Web Service Access Key in the Password field NOT your password.

   • Company Name — Name of the Dynamics 365 Business Central / NAV Company to access. This field is optional. If left blank, Dynamics 365 Business Central / NAV returns the default company.
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.

Azure AD Best Practices

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

• Avoid re-authenticating 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 re-authenticating 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

The Microsoft Dynamics 365 Business Central / NAV Connector supports connecting to your Microsoft Dynamics 365 Business Central / NAV instance using Client Secret authentication. This authentication method requires a separate configuration to establish a connection from TIBCO Cloud ™ Integration - Connect.

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.
   • In the Deployment field select Client Secret.
   • OData Service URL — The address of any acceptable URL where the Dynamics 365 Business Central / NAVOData service is located.
   • Tenant ID — Enter the tenant ID, also known as the Directory ID, generated when you registered the Azure Active Directory (AAD) App.
   • Client ID — Enter the Client ID, also known as the Application ID, generated when you registered the Azure Active Directory (AAD) App.
   • Client Secret — Enter the Client Secret generated when you registered the Azure Active Directory (AAD) App.
   • Company Name — Name of the Dynamics 365 Business Central / NAV Company to access. This field is mandatory.
     

   Note: If you enter incorrect company name, the connection is made but maps using that connections generate errors.

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

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.

Endpoint Support

The Connector does not currently support the FunctionImport or ActionImport OData features.

Data Types

The Connector converts DateTime data types on the OData V4 protocol as follows:

• Edm.DateTime — DateTime
• Edm.DateTimeOffset — String

Filter, Match Criteria, Or Lookup

The Dynamics 365 Business Central / NAV Connector supports the following operators, based on the operators supported by your Dynamics 365 Business Central / NAV OData service:

• ANDs
• ORs — Multiple OR operators can be used to apply different filters on the same field. Multiple filters on different fields are not supported.

Retry Logic

When a timeout or an exception occurs or the API indicates that too many requests are being sent the Connector retries three times. Each time a retry fails, the time between retries increases by 12 seconds.

Dynamics 365 Business Central / NAV Connection As IS/MS Source

Consider the following when using the Dynamics 365 Business Central / NAV Connector as an Integration Solution or Migration Solution source.

Filtering

When a datetime is configured on the Query Block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Scribe® Online builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.

Some Connectors for TIBCO Scribe® Online only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

• Entities returned using the OData service URL contain Date fields. The Connector converts the Date fields into DateTime fields where the time defaults to midnight. This causes some records to be reprocessed the next time the Map runs. Your Maps should be designed to check for duplicate records. You may want to consider using the OData Service URL for the REST version of the API, which has more support for DateTime fields.
• Net Change uses Date and DateTime fields to locate new and updated records and stores the Date and DateTime value of the last record processed. The next time the Solution runs, the Query Block requests records with:
  • A Date that is greater than the Date value of the last record processed.

  • A DateTime that is greater than or equal to the DateTime value of the last record processed.

  Dynamics 365 Business Central / NAV timestamps in datetime values are always set to midnight or 00:00:00. When using Net Change with this type of datetime fields, running a Solution another time on the same day causes new and updated records for that day to be processed again. For example, if you run a Solution on 10/15/2020 at 10 AM and the last record processed has a date of 10/15/2020 00:00:00:, when the Solution runs again on 10/15/2020 at 9 PM, any records updated or created before 10 AM are processed again because Net Change is requesting records with a datetime greater than or equal to 10/15/2020 at midnight.

  Best practice is to schedule the Solution to run once a day after all records have been created or modified for the day to process all of the records for that day. For example, if your business day ends at 6 PM, schedule the Solution to run after 6 PM to ensure all records for the day are processed only once.

• If you are using the TIBCO Scribe® Online Net Change feature to filter records by date with Microsoft Dynamics NAV 2016, Dynamics NAV Cumulative Update 3 must be installed.
• For some entities the datetime fields available for Net Change generate errors similar to the following: 

  OData V4 Error

  The following error has occurred in the Dynamics NAV Connector: Error: status code = NotImplemented

  Select another datetime field for use with Net Change or do not enable Net Change for entities that generate these errors.

• If you create a Map that queries a large number of fields, the URL that is generated may be very long. Some services, cannot process long URLs even though the URLs are valid. An error is returned when you attempt to run the Map. To work around this issue, create multiple Maps with fewer fields in each Map.

Query Objects

Use Dynamics 365 Business Central / NAV Query Objects to access the results of a Dynamics 365 Business Central / NAV custom query and use those results in a TIBCO Scribe® Online Query. Expose Query Objects to the OData service within Dynamics 365 Business Central / NAV to make them accessible by TIBCO Scribe® Online.

Query Objects are available in metadata for both source and target operations, however, only source operations are supported. If you use a Query Object in a target operation, all records fail with the following error: An error occurred while processing this request.

Relationships

• Inner join operations are not supported with related entities.
• Collections are supported.
• Hierarchical relationships, such as grandparent, parent, grandchild relationships are supported. See Hierarchical Data for examples.

• Note: Single parent/child relationships do not display on the Include tab.

Dynamics 365 Business Central / NAV Connection As IS/MS Target

Consider the following when using the Dynamics 365 Business Central / NAV Connector as an Integration Solution or Migration Solution target.

Batch Processing

• The Dynamics 365 Business Central / NAV Connector supports batch processing for Create, Update, and Delete operations if the Dynamics 365 Business Central / NAV OData V4 service also supports Batch Processing for those operations. The maximum number of records allowed per batch is 100.

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 Business Central / NAV Connector exposes these ETags as fields:

  • ETag — Available as a source and target field, contains the ETag value provided by the Dynamics 365 Business Central / NAV 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.

• Update operations generate errors and are not successful when the ETagConcurrencyBehavior option selected is Overwrite If Not Match and the ETag value of the source record does not match the target 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 operation it always overwrites the existing data.
• Optimistic Concurrency is an optional OData feature and is limited to specific entities. Contact your Dynamics 365 Business Central / NAV OData service administrator for additional information.

Conditional Success

When you Insert or Update a record, some services may indicate success, but return error information in the response. When this occurs, refer to your Dynamics 365 Business Central / NAV OData service documentation for further information, and review the record for accuracy.

For example, if a record is inserted without providing a required field, an OData service may return a successful status code but the response has error information stating that the field is required. The OData service has committed the record but it could be inaccurate and possibly unusable. In this case, the TIBCO Scribe® Online Solution execution yields a record error. The corresponding records in the actual application may still need values for the required fields.

Send Operation

• The Send operation is used to make API Calls to Microsoft Dynamics 365 Business Central / NAV APIs. It can be used to support custom calls to Microsoft Dynamics 365 Business Central / NAV 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://api.businesscentral.dynamics.com
  [organizationId]	ced1fa95-abb3-8921-be01-2443c892cbda

  Note: In some cases, when using an Client Secret Connection to make request calls, the Company Name is expected by the Microsoft Dynamics 365 Business Central / NAV API as a queryparameter. When making request calls, pass Company Name in the Request.QueryParameter entity as shown in the following example.

  

  If you do not include the Company Name in the request, errors similar to the following are generated:

  Error : Http call failed with StatusCode 404 - Not Found. Response Body: {"error":{"code":"Internal_CompanyNotFound","message":"Cannot process the request because the default company cannot be found. You can specify a default company in the service configuration file, or specify one for each tenant, or you can add a query string in the form of \"company=[name]\". You can see the available companies by accessing the default OData web service, Company. For more information, see \"OData Web Services\" in Help. CorrelationId: 2b0cd7c3-2dba-49e5-b4f4-819d34c355ae."}}.

• 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 HTTPVerb calls using the Request entity.

  Note: When using Basic Credentials Authentication, pass the Authorization header as Basic [authToken] in Request.Headers. For Client Secret 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.

  • 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 Business Central / NAV associated with the Connection configuration. This is the Custom Domain URL for your Microsoft Dynamics 365 Business Central / NAV 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://api.businesscentral.dynamics.com as shown in the table above.

    

    
    

  • organizationId — The Connector derives the value of the [organizationId] from the Microsoft Dynamics 365 Business Central / NAV Tenant associated with the Connection configuration. This is the TenantId of your Microsoft Dynamics 365 Business Central / NAV organization. [organizationId] is used wherever the Company Id is specified as a parameter in the Microsoft Dynamics 365 Business Central / NAV 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.

Troubleshooting

Prior versions of the Dynamics 365 Business Central / NAV Connector supported relationships. If you have Solutions configured with relationships and you are seeing errors, refer to the Errors In Scribe Online Dynamics NAV Solutions With Relationships Knowledge Base article for additional information.

TIBCO Scribe® Online API Considerations

You must define a Connection Name and Connection Alias for each OData endpoint.

To create Connections with the TIBCO Scribe® Online API, the Dynamics 365 Business Central / NAV Connector requires the following information:

Connector Name	Microsoft Dynamics 365 Business Central/NAV
Connector ID	DD5C2188-316A-41FA-8415-A14C1CACD59E

TIBCO Scribe® Online Connection Properties

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

Client Secret Authentication

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

Basic Authentication

Name	Data Type	Required	Secured	Usage
DynamicsAuthenticationType	string	Yes	No	Basic Authentication
ServiceUrl	string	Yes	No
User	string	Yes	No
Password	string	Yes	Yes
CompanyId	string	No	No

License Agreement

The TIBCO Scribe® Online End User License Agreement for the Dynamics 365 Business Central / NAV Connector describes TIBCO and your 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.