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® Online Connector for Dynamics 365 Business Central / NAV to create source or target Connections in On schedule or On event apps 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.

Note: Options and features identified in this document may vary depending on the version of the Dynamics 365 Business Central / NAV OData service you are using.
  Supported

Agent Types

Connect on-premise X
Connect cloud X

Data Replication Apps

Source  
Target  

On Schedule Apps

Source X
Target X

On Event Apps

Source X
Target X

Flows

Integration X
Request-Reply X
Message  
Note: This Connector is available from the TIBCO Cloud™ Integration Marketplace. See Marketplace Connectors for more information.

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:

Update Operations

Special Operations

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

Supported special operations for collections include:

Setup Considerations

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:

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

Note: To create a Client secret click Client Credentials > New Client Secret. Add the client secret description and select the expiration period. Save the generated client secret value.

Selecting An Agent Type For Dynamics 365 Business Central / NAV

Refer to TIBCO Cloud™ Integration - Connect Agents for information on available agent types and how to select the best agent for your app.

Connecting To Dynamics 365 Business Central / NAV

Note: Best practice is to create Connections with credentials that limit permissions in the target system, following the principle of least privilege. Using Administrator level credentials in a Connection provides Administrator level access to the target system for TIBCO Cloud™ Integration - Connect users. Depending on the entities supported, a TIBCO Cloud™ Integration - Connect user could alter user accounts in the target system.

Deployment Types

Note: For information about which deployment to use, see your System Administrator.

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

Basic Authentication

  1. Select Connections from the menu.
  2. From the Connections page select Create to open the Create a connection dialog.
  3. Select the Connector from the list to open the Connection dialog, 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.

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 Connections from the menu.
  2. From the Connections page select Create to open the Create a connection dialog.
  3. Select the Connector from the list to open the Connection dialog.  
    • 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 / NAV OData 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 an incorrect company name, the connection is made but flows using that connection 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:

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:

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 An App Source

Consider the following when using the Dynamics 365 Business Central / NAV Connector as an On schedule or On event app 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 Cloud™ Integration - Connect 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 Cloud™ Integration - Connect only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

Note: The Net Change date is ignored when previewing data on the Preview tab. Filters on the Block Properties Filters tab are used to filter the data on the Preview tab.

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 Cloud™ Integration - Connect Query. Expose Query Objects to the OData service within Dynamics 365 Business Central / NAV to make them accessible by TIBCO Cloud™ Integration - Connect.

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.

Note: For on premise versions of Dynamics 365 Business Central / NAV, Query Objects may fail with an error similar to the following:

When writing a JSON response, a user model must be specified and the entity set and entity type must be passed to the ODataMessageWriter.CreateODataEntryWriter method or the ODataFeedAndEntrySerializationInfo must be set on the ODataEntry or ODataFeed that is being written.

Try querying a similar Page Object.

Relationships

Dynamics 365 Business Central / NAV Connection As An App Target

Consider the following when using the Dynamics 365 Business Central / NAV Connector as an app target.

Batch Processing

Optimistic Concurrency

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 Cloud™ Integration - Connect app execution yields a record error. The corresponding records in the actual application may still need values for the required fields.

Send Operation

Query parameter as Compony Name

Note: If you do not include the Company Name in the request, errors similar to the following are generated:
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.

Troubleshooting

Prior versions of the Dynamics 365 Business Central / NAV Connector supported relationships. If you have apps 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 Cloud™ Integration - Connect API Considerations

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

To create Connections with the TIBCO Cloud™ Integration - Connect 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 Cloud™ Integration - Connect Connection Properties

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

Note: Connection property names are case-sensitive.

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 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.