Change Group and Optional Record Modes

Article
08/03/2018

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

You use change group and optional record modes to specify the behavior you want to occur when a parent record is created, updated, or deleted. You use the ChangeGroupMode and OptionalRecordMode properties of the form data source to specify how a record that includes joined tables is created, updated, or deleted. The following sections describe change groups and optional records.

Specifying the Behavior of Joins in a Form Data Source

If the AOT shows that the database tables in the form data source have a Relation, you can use the properties in the form data source to create an inner or outer join between the tables. For more information about joins between form data source tables, see How to: Join Data Sources for a Form.

To use joined tables in a form data source, you have to make sure that create, update, and delete operations support the following behavior:

A record that uses joined tables must include foreign key values that identify the related records.
A record in a joined table is created when it is needed. For example, the record in an outer joined table can be optional. As a result, you might not create a record in the outer joined table until a field for that table is populated.
The data changes in create, update, or delete operations are consistently applied to all the related tables for the specified record. If an error occurs, the changes are rolled back across all joined tables.

To help you efficiently implement each behavior, you can use change groups and optional records.

Change Groups

A change group is a set of joined tables in a form data source. You can use a change group when the data that appears on a form includes fields from one or more joined tables. You use a change group to simplify how you create, update, or delete a record that includes a join to another table. You use the change group to help complete the following actions:

Add and maintain the foreign key values that identify the related records.
Use a database transaction when you make a change to any of the tables in the group. If the create, update, or delete operation fails for any of the tables in the change group, the change is rolled back for all the tables in the group.

To implement a database transaction, the change group uses the UnitOfWork class on the server to create and manage the transaction. For more information about UnitOfWork class on the server, see How to: Use the UnitOfWork Class to Manage Database Transactions.

To support a change group, the Relation between the joined tables must be Normal. For information about table relations, see How to: Add a Relation to a Table.

You should use a change group when the form data source includes an inner or outer join relationship between tables. You can use a change group that has a join that includes one-to-zero, one-to-one, or one-to-many type relationships.

Important

If you have a relationship between tables that uses a dynalink, the change group does not span the dynalink. Each query is treated like a separate change group.

Setting the ChangeGroupMode property

To create a change group, you use the ChangeGroupMode property of the Data Source node of the form. However, the default behavior is not to use a change group together with a form. You can use ChangeGroupMode to create a change group for any of the following types of forms:

A new form that you create in the AOT.
A form that includes date effective data.
A form with a data source where a parent table has a join relationship to a child table where the child holds a reference to the parent table. The reference can be either mandatory or optional.

To specify whether to use a change group, you populate the ChangeGroupMode property by using one of the following values.

Value	Description
ImplicitInnerOuter	Use a change group for the tables in the form data source.
None	Do not use a change group for the tables in the form data source. This is the default value.

If you set the ChangeGroupMode to None, you might have to override the Write or Delete method of the data source table. You would override these methods when you want to how the form updates the database tables on the server. Most existing Microsoft Dynamics AX forms have the ChangeGroupMode property set to None.

Overriding of methods

When you save changes to a joined record, you might have actions that you want to perform before the write operation and after the write operation. To complete these operations you can override methods of the form data source table.

For example, you have a form with a data source table named FDS1 and a joined data source table named FDS2. You want to complete the following actions:

Validate the data for fields.
Perform a series of actions before you write the changes to the database table.
Perform actions after you write the changes to the database.

The following table shows the sequence of transactions and methods for a form where the ChangeGroupMode property is set to None. This is the same behavior that was used with Microsoft Dynamics AX 2009. Notice that each table has its own dedicated transaction.

Transaction	Method sequence	Description
Transaction 1	FDS1.ValidateWrite FDS1.write	In the write method, you add pre-write code before the call to super and post-write code after the call to super.
Transaction 2	FDS2.ValidateWrite FDS2.write	In the write method, you add pre-write code before the call to super and post-write code after the call to super.

Transaction 1

FDS1.ValidateWrite

FDS1.write

In the write method, you add pre-write code before the call to super and post-write code after the call to super.

Transaction 2

FDS2.ValidateWrite

FDS2.write

In the write method, you add pre-write code before the call to super and post-write code after the call to super.

The use of a change group alters the sequence of transactions and method calls. Now each table does not have its own dedicated transaction. The following table shows the sequence of transactions and methods that are used when the ChangeGroupMode property is set to ImplicitInnerOuter. Notice that all the pre-write, server call, and post-write actions for FDS1 and FDS2 are included in a single transaction.

Transaction	Method sequence	Description
None	FDS1.ValidateWrite FDS2.ValidateWrite	Validation on the client is completed before the transaction starts.
Transaction 1	FDS1.writing FDS2.writing The UnitOfWork class runs on the server FDS1.written FDS2.written	You use the writing methods to perform any pre-write actions. You use the written method for any post-write actions.

None

FDS1.ValidateWrite

FDS2.ValidateWrite

Validation on the client is completed before the transaction starts.

Transaction 1

FDS1.writing

FDS2.writing

The UnitOfWork class runs on the server

FDS1.written

FDS2.written

You use the writing methods to perform any pre-write actions.

You use the written method for any post-write actions.

If you change the ChangeGroupMode from None to ImplicitInnerOuter, you must refactor any code in the write methods of the data source tables.

Code that you had put in the write method before the call to super must be moved to the writing method.
Code you had in the writing method after the call to super must be moved to the written method.

There is a similar pattern for a delete operation. If you use a change group, you have to override the deleting method for any pre-delete actions and the deleted method for any post-delete actions.

Optional Records

An optional record is a child record found in an outer join table where the child record does not have to be created at the time the parent record is created. You can use the optional record mode of the form data source to specify the create behavior for the child record.

Important

To use optional records, the Relations between the database tables must be Normal.

Optional record mode enables you to use one of the following behavior to create the child record in the outer joined table.

You can specify that the record be created when a field in the child record has a value assigned to it. The assignment can be explicit or a configured default.
You can use a check box control to specify how the system treats child records during create or delete operations on the parent record of a joined table.
You can use the same behavior that was used in Microsoft Dynamics AX 2009.

To use optional record mode, you set the following values for properties in the form data source.

Property	Location	Value
ChangeGroupMode	Data Sources properties	ImplicitInnerOuter
LinkType	Form data source table properties	OuterJoin

A form data source can include more than one join relationship between tables. You can use different optional record modes to independently define the optional record behavior for each join relationship in the form data source. For example the UnitOfMeasure form in the AOT has joins that uses both implicit and explicit create behavior.

Setting the OptionalRecordMode property

To create optional records in a form data source, you set the OptionalRecordMode property on the table in the form data source where the child record is created. To control optional records, you set the OptionalRecordMode property to one of the following values.

Value	Description
ExplicitCreate	You use a check box control to explicitly specify whether to create or delete the joined record. If the check box is selected, the record is always created. If the check box is cleared, the record is always deleted.
ImplicitCreate	When you create the parent record, an empty child record is created implicitly in memory. However, if no fields in the child record are populated, the empty child record is discarded when the parent record is written to the database. This is the default value that appears when you add a table to the Data Sources node of a form.
None	The outer join behaves the same as in Microsoft Dynamics AX 2009. To add or delete a child record, you use the write or delete method for that data source table. The create method is not used to initialize the child record. Use this value when you want to use a change group but you want to retain the existing overrides of write or other methods.

ExplicitCreate

You use a check box control to explicitly specify whether to create or delete the joined record. If the check box is selected, the record is always created. If the check box is cleared, the record is always deleted.

ImplicitCreate

When you create the parent record, an empty child record is created implicitly in memory. However, if no fields in the child record are populated, the empty child record is discarded when the parent record is written to the database.

This is the default value that appears when you add a table to the Data Sources node of a form.

None

The outer join behaves the same as in Microsoft Dynamics AX 2009. To add or delete a child record, you use the write or delete method for that data source table. The create method is not used to initialize the child record.

Use this value when you want to use a change group but you want to retain the existing overrides of write or other methods.

Implicit create

An implicit create occurs when you set the OptionalRecordMode property to ImplicitCreate. When a parent record is created, the create method of the child data source is also called by the system. The create method of the child data source adds an empty record in memory. However, the write method is not called unless a change is made that populates a field in the child record. If no fields are populated, the empty record is deleted from memory.

Warning

If you initialize the child record and specify default values for one or more fields, the optional record will always be saved. The use of default values in a field will cause the implicit create behavior to write the child record to the database table.

Explicit create

An explicit create occurs when you set the OptionalRecordMode property to ExplicitCreate. When you use ExplicitCreate, you must add a check box to the Design node of the form that specifies whether to create or delete the child record. To enable the check box control to create or delete the optional child record, set the following properties of the check box control.

Property	Value
DataSource	Specify the table where you set the OptionalRecordMode property to ExplicitCreate.
OptionalRecordControl	Yes

When you set the OptionalRecordControl to Yes, the create method of the specified data source is called when you select the check box. When you save the record, the writing and written methods of the specified data source are called. If you later clear the check box, the deleting and deleted methods of the specified data source are called.

To see an example of a form that uses explicit create, review the form data source of the UnitOfMeasure form in the AOT. The data sources of that form include a join to the UnitOfMeasureInternalCode where the OptionalRecordMode is set to ExplicitCreate.