Trade Agreement Evaluation Policies In Microsoft Dynamics AX 2012

Microsoft Dynamics® AX 2012

Trade agreement evaluation policies in Microsoft Dynamics AX 2012

Implementation Considerations

TAE-Policies are an out-of-box feature of Microsoft Dynamics AX 2012 that prevents unintentional overwriting of prices and discounts that are manually entered, or that originate from sources other than the built-in trade agreement system. This document explains the architecture, and also provides hints for extending and debugging TAE-Policies. It assumes familiarity with the concepts of sales orders, sales quotations, and purchase orders, how they are created, and how they interact with trade agreements. Conceptual knowledge of the Microsoft Dynamics AX 2012 agreement feature will also be useful. March 2012

www.microsoft.com/dynamics/ax

Lars David Jørgensen, Software Development Engineer

Send suggestions and comments about this document to [email protected]. Please include the title with your feedback.

CCAX2012IC3001

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Table of Contents

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012

1. TAE-Policies overview

Purchase order lines, sales quotation lines, and sales order lines all include fields (trade agreement result fields: see the Glossary of terms section) that can be:

Entered by trade agreements.

Entered by manual input.

Set from external sources, such as sales quotations, project quotations, purchase requisitions, requests for quotation (RFQs), agreements, projects, Application Integration Framework (AIF), and Enterprise Portal for Microsoft Dynamics® AX (EP).

The lines also include the Net amount field, which can be either calculated based on trade agreements or entered from one of the external sources.

The TAE-Policies feature prevents Microsoft Dynamics AX from accidentally evaluating the trade agreements and overwriting fields populated by manual input or a system source (see the Glossary of terms section).

Note: The TAE-Policies feature is used only in the context of price and discount fields on sales quotations, sales orders, and purchase orders. It is related neither to the policy framework used for designing and enforcing business rules, nor to the framework that creates extensible data security, both of which are being introduced in Microsoft Dynamics AX 2012.

Also, the TAE-Policies feature is not implemented in intercompany scenarios.

2. Scenarios that support TAE-Policies with Microsoft Dynamics AX

This section describes some core concepts and some of the most common scenarios in which TAE- Policies are implemented within Microsoft Dynamics AX.

For sales orders, purchase orders, and sales quotations, two main steps are performed:

When a trade agreement result field is populated from a system source or updated manually, a TAE-Policy is created, and a reference to the TAE-Policy is added to the document.

Changing a trade agreement condition field triggers a recalculation of the trade agreement result fields. The user is prompted for permission to overwrite the field values entered in this step.

When a line amount field is overwritten manually, and changes to a trade agreement condition trigger a recalculation of the trade agreement result fields, the user is prompted for permission to change the manually entered value.

Whether the different types of field entries (manually entered or entered from different system sources) should be subject to TAE-Policies is controlled by new sets of customer and vendor parameters.

Sources – What are they?

The trade agreement result fields are populated from different sources, depending on the scenario. In this context, we divide the sources into several groups, some of which can be guarded by policies.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Trade agreements This is the legacy price discount setup that has been present in Microsoft Dynamics AX since version 1 and is considered the default source in the default scenario: the user creates or updates a document directly from the UI.

In this scenario, no TAE-Policies are applied.

Manual input The user enters a value in one of the trade agreement result fields.

A manual-type TAE-Policy is applied to prevent the user input from being overwritten by the trade agreements.

System sources Documents are created or updated by means other than the default scenario—that is, they are imported via AIF or copied from other documents.

A system-type TAE-Policy is applied to prevent one or more trade agreement result fields from being overwritten by the trade agreements.

For the complete list of system sources, see the Glossary of terms section.

Sales and purchase agreements The agreement feature that is replacing blanket orders in Microsoft Dynamics AX 2012 can be considered a source for prices and discounts, along with the legacy trade agreement feature.

Depending on the specific agreement configuration, a subset of the price and discount values that previously came from the trade agreement setup now comes from agreements.

The agreement feature serves as a source in two ways:

As long as a document is linked to an agreement, the agreement is considered a system source. To control the mix of agreements and trade agreements, a set of fixed TAE-Policies is implemented in the price discount policy feature. The purpose is to prevent price and discount values that originate from agreements from being overwritten by trade agreements. More details on the fixed TAE-Policies are provided later in this document.

When a document is unlinked from an agreement, prices and discounts that originate from the agreement can be preserved. In that scenario, the agreement is considered a system source, and a policy is applied accordingly.

TAE-Policies – More details

As has been mentioned, TAE-Policies come in two “flavors.” One is dynamic, and includes the manual and system types, and the other is static, and includes the fixed type.

Dynamic policies A dynamic TAE-Policy is represented by a record in the PriceDiscChangePolicy table that is related to one or more records in the PriceDiscPolicyFields table.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Depending on the source, the ID of the record is populated in either the ManualEntryChangepolicy field or the SystemlEntryChangepolicy field of the document. In the latter scenario, the SystemEntrySource field is also is populated to identify the type of system source. The following are some characteristics of dynamic policies:

The application is parameter-controlled.

The policies are created on the fly.

The policies are immutable, and they are reused.

One document can have both a manual policy and a system policy applied at the same time, but a specific field can only be controlled by only one type of policy at a time. For more details on combined policies, see the Manual and system TAE-Policies applied to the same document header and line section.

More implementation details are provided later in this document.

Fixed policies Policies of this type are hard-coded in the PriceDiscPolicyFixed class. They are sets of rules that are applied to documents, depending on document attributes. In Microsoft Dynamics AX 2012 RTM, fixed policies are used in two scenarios:

Document lines are attached to agreements. This scenario has two sets of rules:

For quantity-based agreements, the Price, Line discount, Line discount pct., and Price unit fields are controlled by fixed policies.

For volume-based agreements, the Line discount pct. field is controlled by a fixed policy.

On category-based document lines, the Price and Markup fields are controlled by fixed policies.

Summary In summary, the TAE-Policies feature implements two different sets of TAE-Policies:

The parameter-controlled dynamic type (manual and system policies) – These policies are attached and detached on the fly, based on user actions and dialog boxes.

The hard-coded static type (fixed policies) – These policies control how agreements and trade agreements interact.

Manual TAE-Policy applied to a document header or line record

A manual policy is applied to a document when the user overwrites one or more of the trade agreement result fields.

Example: Manually overwrite the unit price For this example, a document line has a stocked product, a quantity, and a unit price. No sales or purchase agreement is attached.

The unit price is then changed, and the flow illustrated in Figure 1 is executed. In this case, a policy indicating that the unit price was changed is applied to the document line.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Next, the quantity is changed, triggering a recalculation of the trade agreement fields. The flow illustrated in Figure 2 is executed, and three outcomes are possible:

OK is clicked:

3. The unit price is recalculated in accordance with the trade agreement setup.

4. The TAE-Policy is removed from the record.

The Unit price check box is cleared, and OK is clicked:

1. The manually entered unit price is kept.

5. The TAE-Policy remains on the record.

Cancel is clicked:

1. Update of the record is canceled, rolling back the quantity change.

2. The TAE-Policy remains on the record.

Even though the appearance of the dialog box differs in different scenarios, the flow and outcomes are similar.

System TAE-Policy applied to a document header and line

A system policy is applied to a document when it is created from sources other than manual input by a user.

Example: System policy originating from a sales quotation For this example, a sales quotation has one or more lines. The line items are all stocked products, and no sales agreements are involved.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 The confirmation process is started to create a sales order based on the sales quotation. As part of that process, the price discount policy functionality is called to apply system policies to the new sales order, as illustrated in Figure 3.

Fig.3 : S y ste m p o licy o rig ina tin g from a sa le s q u o tation

New record created in New record created in Creation of the PriceDiscChangePolicy PriceDiscChangePolicyFields docum ent header record N o

The source type and Does a The policy is selected in docum ent header reuseable policy Yes PriceDiscChangePolicy policy is determ ined exists?

The source type and The docum ent is docum ent line updated w ith the policy is determ ined policy ID

Yes: Are Creation of the docum ent line docum ent line record(s) records pending creation?

At the latest after first docum ent line No is processed, this is true for rem aining lines.

Manual and system TAE-Policies applied to the same document header and line

As has been mentioned, a document can be controlled or protected by both a manual policy and a system policy at the same time. However, a particular field can be subject to control by only one policy at a time. Nevertheless, the type of policy that controls a particular field can shift from manual to system, and from system to manual.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Example: Manually overwrite system policies originating from a sales quotation For this example, a sales order is created based on a sales quotation, as described in the previous example. Both the header and the line records have system policies applied that indicate the origin.

Triggering a recalculation of the trade agreement opens a dialog box, and the steps that are executed are similar to the steps in Figure 2.

First, we describe the appearance of the dialog box when only the system policies are applied.

On the document header, the calculation of multiline discounts is started, and the following dialog box appears.

This dialog box indicates that multiline discounts come from the sales quotation.

As has been mentioned, we can accept or cancel the dialog box. For now, assume that Cancel is clicked.

Still on the document header, the calculation of the total discount is started, and the following dialog box appears.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 This dialog box indicates that the total discount comes from the sales quotation.

Again, assume that Cancel is clicked.

Now one of the trade condition fields on the document line is changed, and the following dialog box appears.

This dialog box indicates that a system policy of type SalesQuotation that includes all five trade agreement result fields for the document line exists on the document line.

Assume that Cancel is clicked. In this case, the Discount and Discount percent fields are overwritten.

For each overwritten field, the flow illustrated in Figure 4 is executed.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Fig 4: M an ually overw rite a trade agreem ent resu lt field . (M ore detailed )

Is the field ID subject to a fixed policy or already included Yes in a m anual policy applied to the docum ent?

Is a m anual policy already No Yes applied to the docum ent? A new m anual policy w ith A new m anual policy only the new field ID m erging the new field ID should should be applied. and the existing policy, should be applied.

Does a Yes reuseable policy N o exists?

The policy is selected in the A new record is created in the PriceDiscChangePolicy table PriceDiscChangePolicy table.

O ne or m ore new records are created in the PriceDiscChangePolicyFields table.

Applying a System m anual or M anual system policy?

The docum ent field The docum ent field ”System EntryChangePolicy” ”M anualEntryChangePolicy” is updated w itht the policy ID and is updated w itht the policy ID the ”System EntrySource” field is updated w ith the system source in question. Is a system policy applied to the docum ent? No A new system policy Yes w ithout the field ID should replace the existing one. Is the field ID part of the N o Yes existing system policy?

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Again, one of the trade condition fields on the document line is changed, and the following dialog box appears.

Now the dialog box indicates that both a manual policy and a system policy are applied to the document line.

Manual changes to the price discount result fields for the document header follow the same pattern: fields are “moved” from the system policies to the manual policies.

6. Architecture of TAE-Policies in Microsoft Dynamics AX

Some design highlights

The following information supports the diagrams in this section:

The implementation can be seen as divided into two major parts: the core functionality common to all documents and the document-specific integration.

Whereas the integration part is tailored to the specific document scenarios, the core part consists of three subsystems of functionality and several common supporting elements.

The subsystems are as follows:

Make policy – Enables a given trade agreement result field to be included in a price discount policy, or if no price discount policy exists, enables a new one to be created.

Prompt user – Enables a dialog box to be opened, providing the user with field-level information about applied policies and also letting the user decide whether each field should continue to be subject to policy control.

Check policy – For a given table, record, or field, answers the following question: “Is this field blocked by a policy?”

The subsystems are marked with different colors in the core functionality class diagram.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 A TAE-Policy is a list of table field IDs.

In the database, a TAE-Policy is stored as one record in the PriceDiscChangePolicy table, and each table field ID belonging to a TAE-Policy is stored as a separate record in the PriceDiscPolicyFields table.

Both tables, PriceDiscChangePolicy and PriceDiscPolicyFields, are immutable: after records have been created, they are never updated or deleted.

When records are created in the PriceDiscPolicyFields table, the field IDs representing the policy are converted to the corresponding field IDs from the PriceDiscResultFields table map.

When policy field IDs are retrieved from the PriceDiscPolicyFields table, they are converted back to the appropriate table field IDs.

ER diagram

Class diagrams

As has been mentioned, the core part of the implementation consists of three subsystems and several supporting elements. The following diagram is color-coded to group the elements by subsystem, and the integration with the document-specific integration is also shown.

As has been mentioned, the document-specific integration part of the implementation is tailored to each document. The following diagram shows the purchase order part. The diagrams covering sales orders and sales quotations are located in the appendix of this document.

7. Glossary of terms

Term Definition Trade agreements The legacy Microsoft Dynamics AX price and discount feature used to set up price and discount rules for specific customers and products, groups of customers and products, or all customers and products.

Agreements The new Microsoft Dynamics AX 2012 feature that replaces the legacy blanket order feature.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 Term Definition

Trade agreement condition field A field for which the value can be used as a requirement for a trade agreement rule before the trade agreement can be applied. The trade agreement conditions are as follows: Item number Configuration Size Color Site Warehouse Batch number Serial number Quantity Unit

Trade agreement result field A field that can be directly set by trade agreements.

Location Field Document header > Price/Discount tab Total discount % Document line details > Price/Discount tab Unit price Discount Disc. pct. Multiline discount Multiline discount % Markup

These fields can all be found in the Purchase order details, Sales quotation details, and Sales order details forms.

System source When sales orders, sales quotations, and purchase orders are not created from the details forms, their origination is considered a system source.

System source Description PurchaseAgreement A purchase order line is attached to a purchase agreement. CopyFromPurchaseOrder A purchase order line is copied from another purchase order line. PurchaseReq A purchase order is created based on a purchase requisition. RequestForQuote A purchase order is created based on a request for quotation. SalesAgreement A sales order line is attached to a sales agreement. CopyFromSalesOrder A sales order line is copied from another sales order line. CopyfromSalesQuotation A sales order line is copied from a sales quotation line. ProjectQuotation A sales order is created based on a project quotation. SalesQuotation A sales order is created based on a sales quotation. AIF A document is created by importing an XML file. Project A sales order is created based on a project. Product configurator A sales price or purchase price is generated by the product configurator.

Manual-type TAE-Policy A TAE-Policy that is created based on a manual update of a trade agreement result field. Example: On a sales line, the user has overwritten the default sales price.

System-type TAE-Policy A TAE-Policy that is created based on entries from external sources. Example: A sales line was created by a sales quotation, and the sales price was “inherited” from a sales quotation line. For Microsoft Dynamics AX 2012 RTM, all system policy types for the document header are the same, whereas system policy types for the document lines come in different “flavors.” The latter types are coded in Classes\PriceDiscPolicyFindOrCreate\systemLinePolicyFields.

Fixed-type TAE-Policy A hard-coded TAE-Policy that is used to control the mixture of prices and discounts originating from agreements and trade agreements.

Document In this context, a sales quotation, sales order, or purchase order.

Document header A record in the SalesQuotationTable, SalesTable, or PurchTable table.

Document line A record in the SalesQuotationLine, SalesLine, or PurchLine table.

Core functionality The parts of the implementation that are common to all documents. For more details, see the Some design highlights section.

Document-specific integration Integration points in the legacy code. For more details, see the Some design highlights section.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 8. Appendix

Sequence diagrams

Class diagrams

Showcase – Extending TAE-Policies

Adding another system source to be policy-controlled requires only a few changes. The following walkthrough shows how the product configurator was added as another system source.

First, the new source should be named and parameterized by adding new outcomes to the three policy enumerations.

DataDictionary/Base Enums/PriceDiscPurchasePromptSystemSource

#ProductConfig PROPERTIES Name #ProductConfig Label #@SYS344213 EnumValue #7 ENDPROPERTIES DataDictionary/Base Enums/PriceDiscSalesPromptSystemSource

#ProductConfig PROPERTIES Name #ProductConfig Label #@SYS344213 EnumValue #8 ENDPROPERTIES DataDictionary/Base Enums/PriceDiscSystemSource

#ProductConfig PROPERTIES Name #ProductConfig Label #@SYS344213 EnumValue #11

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 ENDPROPERTIES Next, the policy classes should implement the required parameter checks and the definition of which fields are controlled for the new source. For the product configurator implementation in this example, only the price should be controlled, because discounts are coming from the trade agreements.

Classes/PriceDiscFindORCreate/systemLinePolicyFields

..... case PriceDiscSystemSource::ProductConfig : ret += [fieldNum(PriceDiscResultFields, Price)]; break; ..... Classes/PriceDiscPolicyMakePolicy checkPolicyParmSetup

Starting at line 52:

..... case PriceDiscSystemSource::ProductConfig ret = PriceDiscSalesPolicyParameters::isSourceEnabled(PriceDiscSalesPromptSystemSource::ProductConfig); break; ..... Starting at line 94:

..... case PriceDiscSystemSource::ProductConfig : ret = PriceDiscPurchPolicyParameters::isSourceEnabled(PriceDiscPurchasePromptSystemSource::ProductConfi g); break; ..... Finally, a call to the .setPriceDiscChangePolicy(…) method should be made at the point where the new source is creating or updating the document. For the product configurator, this happens in the PCSourceDocumentLineUtility class when the price is transferred.

Classes/ PCSourceDocumentLineUtility /updateSalesLineDetails

..... _salesLine.setPriceDiscChangePolicy(PriceDiscSystemSource::ProductConfig); ..... Classes/ PCSourceDocumentLineUtility /updatePurchaseLineDetails

..... _salesQuotationLine.setPriceDiscChangePolicy(PriceDiscSystemSource::ProductConfig); ..... Classes/ PCSourceDocumentLineUtility /updateSalesQuotationLineDetails

..... _purchaseLine.setPriceDiscChangePolicy(PriceDiscSystemSource::ProductConfig); .....

Installation and upgrade

By default, all TAE-Policy parameters are enabled.

For new installations, this is done along with the default generation of vendor and customer parameters.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012 In upgrade scenarios, it is done as part of the upgrade in the following locations:

\Classes\ReleaseUpdateDB60_Cust\initiatePriceDiscPolicyParameter

\Classes\ReleaseUpdateDB60_Vend\initPriceDiscPolicyParameter

Performance considerations

Obviously, the TAE-Policy feature has the potential to affect performance, and several design decisions were made with that in mind:

The affected document tables are denormalized by adding the policy columns directly to the document tables.

With regard to the PriceDiscChangePolicy and PriceDiscPolicyFields tables:

Caching of the entire table is enabled.

The tables are immutable. After records are created, they are never updated or deleted, because they are reused across all documents and legal entities.

The number of possible records is finite and kept at a minimum by storing the field IDs of the PriceDiscResultFields table map instead of the document table field IDs.

The mapping of the document field IDs and the PriceDiscResultFields field IDs is globally cached in the PriceDiscPolicyFieldMappingCache class.

Debugging hints

As was mentioned in the Some design highlights section, the implementation is divided into two major logical parts: the new core elements and the document-specific integration points.

The document-specific part is detailed in the Class diagrams section, where all new and changed methods are included.

As has been mentioned, the core element part consists of three subsystems, and debugging hints for each are provided here.

The make policy subsystem creates policies and applies them to documents.

Placing a break point in the PriceDiscResultFields.createPriceDiscChangePolicy() table map method is a good starting point for debugging sessions, because all documents call that method.

The prompt user subsystem handles the user dialog box.

Placing a break point in the PriceDiscResultFields.runPriceDiscPolicyDialog() table map method is once again a good starting point for debugging sessions, because all documents call that method.

The get policy subsystem determines whether a specific field is blocked.

Debug by placing a break point in the \Classes\PriceDiscPolicyCheckPolicy\mustUpdateField area, because proceeding from here, the debugger will step through both the dynamic and fixed policies.

TRADE AGREEMENT EVALUATION POLICIES IN MICROSOFT DYNAMICS AX 2012