Tax engine integration

To integrate the Tax engine (GTE) with Dynamics 365 Finance, you must implement X++ code that interacts with the Tax engine for tax calculation, and that consumes the results to show, account, and post tax for voucher and tax transactions. The tax calculation can either include or exclude tax adjustments.

Tax engine integration models

There are three models for Tax engine integration:

• Tax engine interfaces with the Tax engine service
• Tax business service
• Finance application integration:
  • Application integration
  • Accounting integration

Tax engine interfaces with the Tax engine service model

This model is part of the Finance integration framework. Therefore, partners or customers don't need to make significant changes.

The ITaxEngine interface and its implementation contain the basic operations of the Tax engine. These operations include calculating tax through the tax engine, persisting the calculated result to Finance tables, retrieving the tax document for the transaction, and deleting the tax document from both the Tax engine cache and Finance tables.

The set of ITaxDocument interfaces and implementations enables information to be read from a tax document that the Tax engine calculates and returns. This set includes ITaxDocument, ITaxDocumentLine, ITaxDocumentField, ITaxDocumentComponentLine, and ITaxDocumentMeasure.

These interfaces provide methods for retrieving a specified field value (ITaxDocumentField) from ITaxDocumentLine and an expected measure value (ITaxDocumentMeasure) from ITaxDocumentComponentLine.

• The set of ITaxDocumentMetaData interfaces enables you to read model information from a tax document. This set includes ITaxDocumentMetaData, ITaxDocumentLineMetaData, ITaxDocumentComponentLineMetaData, and ITaxDocumentMeasureMetaData.
• The set of ITaxDocumentEnumerator and ITaxDocumentMeataDataEnumerator interfaces provides an enumerator to read a list of tax document–related objects, such as ITaxDocumentLine, ITaxDocumentField, ITaxDocumentComponentLine, and ITaxDocumentMeasure.

Tax business service model

The Tax business service model is part of the Finance integration framework, and partners or customers don't need to take it up. This model supports the interactions that the Finance application has with the Tax engine for basic operations. It uses both the interface model and the application model to calculate, account, and post tax. The Tax business service model provides the following methods:

Finance application integration

Send transaction information from Finance to the Tax engine. At the same time, align the accounting and posting of tax with the Finance implementation. Create three parts in the Finance application:

• Taxable document
• Tax accounting
• Tax posting

Use the integration transit document framework to maintain the relationship between the Finance transaction and the tax document.

Application integration

Taxable document

A taxable document encapsulates transaction information by using a set of data providers. A TaxableDocument object wraps transaction information. A TaxableDocumentDescriptor object in this object describes the transaction and lists a set of data providers that bind tax model attributes with transaction data.

The TaxableDocumentDescriptor class implements a set of TaxableDocumentTypeDefinition interfaces and describes the transaction. Technically, TaxableDocumentDescriptors are the Finance table bases, whereas TaxableDocumentTypeDefinitions are more business-driven and are used mainly for tax configuration conditions.

In the following example, TaxableDocumentDescriptorPurchaseOrderParm implements three interfaces that share the same PurchParmTable table.

If you add attributes to a tax configuration for lookup, condition, formula, or other configurations, bind the attributes with transaction data. Modify the corresponding data provider classes for a transaction so that they do this type of data binding.

Transit document

A transit document is an existing framework in Finance that is used for the following two purposes:

• Maintain the relationship between a transaction and a transit document.
• Transfer the document from one transaction to another transaction.

Use this framework to easily find a transaction's document and track the transit history. For example, create a tax document from VendInvoiceInfoTable, and then the transit document maintains the relationship between VendInvoiceInfoTable and TaxDocument. When you invoice a purchase order, transfer the tax document from VendInvoiceInfoTable to VendInvoiceJour.

Transaction integration

Transaction integration occurs only on a case-by-case basis. For each transaction and scenario, call the Tax business service in the appropriate manner for tax calculation, tax assumption, and tax posting. For an example, see the Finance integration example – Purchase order invoice section later in this article.

Accounting integration

Tax accounting

The accounting of Finance transactions has two parts: source document accounting and nonsource document accounting. The same behavior applies to Tax engine tax accounting, which is integrated with the Finance implementation on both sides:

• For source document transactions, such as a purchase order or free text invoice, fetch the account information for tax when you create the tax document.
• For nonsource document transactions, such as a sales order or general journal, determine the account information when you post tax.

Tax engine tax posting

Currently, Tax engine tax posting generates TaxTrans, TaxTrans_IN (if you're running under the India country/region code), and a related voucher for TaxTrans. To fill the taxTrans field with attributes or measures from the tax document, provide the mapping via TaxAcctTaxTransTaxDocAttrMapping and TaxAcctTxTransTaxDocMeasureMapping.

The following illustration shows how TaxTrans and the voucher are created.

Example: Finance integration – Purchase order invoice

This section provides an example of how the Tax engine integrates with purchase order invoices. Related transaction tables include VendInvoiceInfoTable, VendInvoiceInfoLine, VendInvoiceJour, and VendInvoiceTrans.

Integration checklist

The following table summarizes all relevant changes related to the integration with purchase order invoices.

Define a taxable document

The classes TaxableDocumentTypeDefintionPurchaseInvoice and TaxableDocumentDescriptorPurchaseInvoice define a purchase invoice as a taxable document for the Tax engine.

TaxableDocumentTypeDefinitionPurchaseInvoice is the interface that defines a purchase invoice as a taxable document.

TaxableDocumentDescriptorPurchaseInvoice.getDataProvider() specifies the data provider class that's used for a purchase invoice.

Define data providers

The following illustration shows the data providers that send transaction data to the Tax engine for any tax-related operation.

TaxableDocPurchaseInvoiceDataProvider.buildQuery() provides a query for all related transactions, such as VendInvoiceInfoTable and VendInvoiceInfoLine. It also registers each data source with a row data provider. For example, the VendInvoiceInfoTable data source is registered with TableDocVendInvoiceInfoTableRowDP.

TaxableDocVendInvoiceInfoTableRowDP extends the TaxableDocPurchTableRowDataProvider class to set up transaction header–related information, whereas TaxableDocVendInvoiceInfoLineRowDP extends TaxableDocPurchLineRowDataProvider to set up invoice line–related information.

The following table lists the taxable document fields that Finance maps.

Add the Tax document button on a transaction

You can trigger tax calculation in the Tax engine by adding a Tax document button to a transaction. When you select this button, the transactional data is sent to the Tax engine as a predefined taxable document object, and the Tax engine starts the tax calculation. Add the button to a transaction page, such as VendEditInvoice. The tax document user interface displays the tax calculation result as soon as it's available.

Integrate with transaction totals

The Totals button displays a transaction's financial information, such as the tax amount, discount amount, and total amounts. The tax amount that appears on the total page will also be added to the invoiced amount of the journal.

For an existing implementation of Finance, a set of PurchTotals classes is created to handle this functionality. Therefore, Tax engine-related code is inserted into the class's calcTax method to help guarantee that the expected tax total amount is initiated.

For alignment with the existing logic, the existing taxTotal parameter is used to show the tax amount for the whole transaction. A new parameter that is named taxTotalGTE is used to show the tax that is posted to the vendor. In some cases, such as a reverse charge, the taxTotal value doesn't equal the taxTotalGTE value. Therefore, taxTotal will be used for journal posting, whereas taxTotalGTE will be used on Totals pages to show the total tax amount.

Integrate with a source document

A purchase invoice is a source document transaction. Therefore, the calculated tax result from the Tax engine should be integrated with the existing source document framework in Finance. The main logic is already completed and handled by the Tax engine integration framework. However, for each source document transaction, the distribution and journalization rules should still be defined for accounting purposes.

Three classes are created for a purchase invoice: AccPolicyVendPaymReqForExpensedProducts, AccDistRuleProductTaxMeasure and AccJourRuleVendPaymReqExpPurchTaxMeasure.

When you create the source document classes correctly, the distribution page shows calculated tax together with the component label, tax amount, and ledger account.

Delete a transaction

When you delete a purchase invoice, also delete the associated tax document. To delete an associated tax document, call TaxBusinessService in the delete method of VendInvoiceInfoTable.

Delete a transaction line

When you delete a transaction line, you need to recalculate the tax document. For performance reasons, GTE doesn't recalculate tax immediately after a transaction line is deleted. Instead, it updates the tax document's status to Dirty. When you retrieve a tax document so that you can view or post it, GTE checks whether the status is Dirty. Depending on the status, recalculation occurs.

Update transaction header information

Some transaction header information can affect tax calculation. Examples include the transaction date and currency. Therefore, when you update this type of information to a different value, mark the tax document as Dirty so that it can be recalculated later.

The following method lists fields that might affect tax calculation for a purchase invoice.

Update transaction line information

Similarly, updating some transaction line fields affects tax calculation.

Update tax information

The tax information of a transaction line has a major effect on tax calculation. The logic is maintained on the Application Object Tree (AOT) TransTaxInformation page. This page might not require further uptake.

Define a tax document transit rule

Define a rule to associate a purchase invoice and journal with the tax document. In TaxDocumentTransitRuleEventHandler::initTransitDocumentRuleList(), define rules for VendInvoiceInfoTable, VendInvoiceInfoLine, VendInvoiceJour, and VendInvoiceTrans to specify that the tax document or tax document row should be associated with the transaction table.

TaxDocumentTransitRuleEventHandler::initTransitDocumentRuleExtList() includes extended rule definitions of a transit action from the transaction to the journal.

Transfer a tax document

When you create a journal from a transaction, transfer the tax document to the journal. The following code transfers a tax document from a purchase invoice to a purchase invoice journal.

Post tax

Tax posting occurs when you post the purchase invoice journal. Therefore, call TaxBusinessService::PostTax() in the FormLetterJournalPost.postTax() base class to post the purchase invoice journal.

Add inventory tax

Add tax that must be posted to inventory to an inventory transaction.

The following example shows logic in the Inventory module that posts tax for inventory by using the taxEngineInventMovement().updateTaxFinancial() class method.

Post a tax document

After you post tax, update the tax document to a status that indicates the tax document is posted.

When you call the preceding method, it creates an additional record in the TaxDocumentGeneralJournalEntryLink table to maintain the relationship between GeneralJournalEntry and the journal transaction. This record helps GTE fetch the tax document at the GeneralJournalEntry level.

Debugging

Debug the Tax engine mainly by validating transaction data and the calculated tax document result. Both the transaction data and the calculated result are in JavaScript Object Notation (JSON) string format.

Debugging transaction data

Set a breakpoint in TaxEngineServiceProxy.calculate(), as shown in the following illustration.

JsonStr contains all the transaction data information that is prepared by data providers. You can use any online JSON viewer to easily identify whether data is correctly set for tax model attributes.

Debugging the tax document

If the tax engine returns errors for a calculation, the preceding method sets all the results to the RET attribute. By using the Quick Watch command on the attribute, you can easily understand the full error from the tax engine.

If the tax engine returns no issues, persist the tax document result into the following tables:

• TaxDocument
• TaxDocumentRow
• TaxDocumentJson

By querying these tables to obtain the JSON string, you can easily check the result details via any online JSON viewer.

Additional resources

• Tax engine overview
• Extend tax engine configurations