Business Integration Solutions Documentation

About: Record Change Event

In Business Integration Solutions, the Record Change Event triggers a pipeline, based on changes in the Microsoft Dynamics BC database.

Usage

Use this event if you want to trigger an export based on record changes in Microsoft Dynamics BC. You can configure a Record Change Event for a table by:

• Defining an internal document
• Providing table and field filters and
• Specifying the logging mechanism for record changes, such as insert, modify, delete or rename

Use the Job Queue to process the Record Change Event automatically. On the Job Queue Entry card you can define the recurrence and interval of the Job Queue.

To be able to determine the type of change (insert, modify, delete or rename), the NAVRecordChangeType property of the the message at the receiving end is updated with relevant information. See Determine Transaction Type for more information.

Concept

When you insert, modify, delete or rename a record in Microsoft Dynamics BC, the Record Change Event generates a record set and all relevant record changes are captioned and stored in a change log table, namely N108 Record Set Member. This record set is the input for the first activity in the Pipeline, most likely the XML Generator Activity.

Details

Each Record Change Event will enable the Change log to keep track on the changes based on the Internal Document. E.g. If you change a field on the Item table and this field is monitored on more than one Internal Document on multiple Record Change Events, this will result in a new entry in the Change Log for each Record Change Event (Connection).

How to: Setup the Recordchange Event

Document

An Internal Document definition describes what Tables and/or Fields need to be triggered.

Using multiple Tables, incurs the functionality to trigger on each Table individually.

 

Filters

On each table it is possible to set filters for specific fields. This is restricted to constant values. Keep in mind that although filters are applied, the Change Log functionality is triggered upon every record change that is requested to be monitored. The filters will eventually determine which changes are inserted into the Record Set/Member table.

 

 

Event Setup

The Event Setup allows you to determine on which triggers the change log should monitor:

Insert: all new entries in the table are monitored and stored as a change log.

Modify: All the included fields in the Internal Document are a trigger for this type and will result in an entry in the change log. If a Table is included, but no fields are listed, all fields will be monitored! Fields that are part of the Primary Key will not be monitored in this trigger.

Include XRec: Consider the previous record state when the current record doesn't match the filters set on the table.

Before the release of April 2024, the default behaviour was that XRec monitoring was enabled by default, going forward new configurations will have this setting disabled by default.

Delete: all deleted entries in the table are monitored and stored as a change log.

Rename: All changes to fields that belong to the primary key will result in a rename. These are monitored and stored as a change log.

Log changes incrementally: When enabled, only changed records are processed. This behaviour only applies in a multi-table monitoring setup, when one record is updated one line is updated the header will be sent including the updated line only. The remaining unchanged lines will not be processed. When disabled all records will be processed based on a single line change.

Process changes separately: For each logged record a separate message will be created.

The two triggering fields "Triggering Record ID" and "Triggering Action" hold information about what created the change log line. If a trigger occurs on a child node, the parent of the child node will also be flagged as modified, see entries 60 and 65 in screenshot below.

 

Monitor changes

Before changes are processed by the Record Change Event, the system will collect and store the changes into the N108 Record Set and N108 Record Set Member tables. To quickly access the changes, it is possible to view the entries from the Record Change Event Element, by clicking in the ribbon on Navigate à Details.

After the record change event has run, processed entries will be deleted.

Change log Filter

The change log filter was introduced to avoid monitoring inaccessable tables. Tables defined here will automatically be excluded from the record change event, even when they are defined in the monitoring document. When installing the app, it will automatically add all system tables to be excluded from monitoring.

Optional Setup

Solution Center Setup is only available in search via "Solution Center Setup".

Changeloghandler v2

The Enable change log Handler V2 was introduced to adress performance issues. The record change event code has been updated and this feature can be enabled in Solution Center Setup. When enabled record changes will be logged via new handler which improves performance. This feature will become a standard feature in the future.

AutoReloadRecordset

It can occur that recordchanges get processed before the transaction of capturing the event has completed. This can result in the following error message

The related recordset for this message could not be retrieved. Please retry.

To avoid this, a retry option is set globally to retry retrieving the recordset before triggering this error. Initially this will be set to 3 attempts, with an increasing delay between attempts.

This setting can be modified between 1 and 9 load attempts.

Recommendations

• Limit to one table

Every Table included in the Internal Document will be monitored. This has an impact on performance. It is recommended to only include one table to be monitored.

• Specify fields

Specify the fields that need to be monitored. Try to minimize the number of fields when using the Modify in the Event setup.

This will minimize the number of entries in the change log and activity on the change log functionality.

• Use a "trigger" Document

Create two Internal Documents. The first Internal Document can be used for triggering/monitoring and the second can include multiple table model with relations and filters. Make sure that the both Documents contains the same Root Element (E.g. the Customer Table). The Record ID is passed in the Message through the Pipeline to communicate between the two documents.

If a different table in the Root Element of the second Document is used, then there will be no reference to the changed record, only filters will then be able to limit the number of records processed.

• Beware of the combination Log changes incrementally and Process changes separately

Process changes separately will create a separate message for each record set member, if multiple tables are monitored, this will create messages with different record and possibly different tables.

A warning is generated when this configuration is detected during the configuration check.

• Beware of the usage of subscribers that handle records being monitored by Record Change Events

Subscribers that hook into record triggers could change the values of certain fields that might be monitored by your Record Change Events. If that happens the record change details logging will fail with the following error "A Subscriber changed field values during an Insert(false) on table 'TableName', this conflicts with configuration in 'BIS Product':'BIS Connection'. Please contact your partner.".