Map flexible fields from Vertex to billing response
This section discusses how the Vertex O Series Tax Connector app handles flexible fields in specific situations.
In certain scenarios, the Vertex response may include flexible fields such as flexible_code_field, flexible_numeric_field, and flexible_date_field. These fields need to be mapped into the billing response as custom fields. This document outlines the logic and process for mapping these flexible fields.
Mapping logic
The mapping of flexible fields from the Vertex response to the billing response follows a predefined logic. Each flexible field is mapped to a corresponding custom field in the billing response. The naming convention for these custom fields follows a specific pattern:
def process_flexible_fields(flexible_field_type, field_prefix, flex_fields, extracted_flexible_fields)
flexible_field_objects = extracted_flexible_fields[flexible_field_type]
return unless flexible_field_objects.present?
flexible_field_objects = [flexible_field_objects] if flexible_field_objects.is_a?(Hash)
flexible_field_objects.each do |flex_field_object|
next unless flex_field_object['__content__'].present?
flex_fields["tax_vertex_#{field_prefix}_#{flex_field_object["fieldId"]}_c"] = flex_field_object["__content__"]
end
end
- {type of field}: Indicates the type of flexible field (numeric, date, or code).
- {fieldId}: Refers to the unique identifier of the field from the Vertex response.
The value of each flexible field in the Vertex response is then mapped to its corresponding custom field in the billing response.
Example mapping 1
Let's illustrate the mapping process with an example using a flexible numeric field:
Vertex response
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<VertexEnvelope xmlns="urn:vertexinc:o-series:tps:7:0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Login>
<TrustedId>******</TrustedId>
<Password>******</Password>
</Login>
<QuotationResponse documentDate="2023-03-23" documentNumber="PREVIEW-INV-8adcd6298417a66a0184195871877308" returnGeneratedLineItemsIndicator="true" transactionId="PREVIEW-INV-8adcd6298417a66a0184195871877308" transactionType="SALE">
<Currency isoCurrencyCodeAlpha="EUR" isoCurrencyCodeNum="978" isoCurrencyName="Euro"/>
<OriginalCurrency isoCurrencyCodeAlpha="EUR" isoCurrencyCodeNum="978" isoCurrencyName="Euro"/>
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
<Destination taxAreaId="803800000">
<StreetAddress1>Via Scuderlando 31</StreetAddress1>
<City>Cologna Spiaggia</City>
<MainDivision>TE</MainDivision>
<PostalCode>64020</PostalCode>
<Country>IT</Country>
</Destination>
</Customer>
<SubTotal>0.0</SubTotal>
<Total>0.0</Total>
<TotalTax>0.0</TotalTax>
<LineItem lineItemId="8adca6528707a79701870d7b0ad03f67" taxDate="2022-10-27">
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
</Customer>
<Product productClass="ALL"/>
<Quantity>1.0</Quantity>
<ExtendedPrice>0.0</ExtendedPrice>
<Taxes inputOutputType="OUTPUT" rateClassification="Standard Rate" situs="DESTINATION" taxCollectedFromParty="BUYER" taxResult="TAXABLE" taxStructure="SINGLE_RATE" taxType="VAT">
<Jurisdiction jurisdictionId="78286" jurisdictionLevel="COUNTRY">ITALY</Jurisdiction>
<CalculatedTax>0.0</CalculatedTax>
<EffectiveRate>0.0</EffectiveRate>
<Taxable>0.0</Taxable>
<Imposition impositionId="1">VAT</Imposition>
<ImpositionType impositionTypeId="19">VAT</ImpositionType>
<TaxRuleId>549448</TaxRuleId>
<SellerRegistrationId>DK33368771</SellerRegistrationId>
<InvoiceTextCode>21</InvoiceTextCode>
</Taxes>
<TotalTax>0.0</TotalTax>
<FlexibleFields>
<FlexibleNumericField fieldId="1">124082</FlexibleNumericField>
</FlexibleFields>
</LineItem>
<LineItem lineItemId="8adca6528707a79701870d7b0ad13f68" taxDate="2022-10-27">
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
</Customer>
<Product productClass="ALL"/>
<Quantity>1.0</Quantity>
<ExtendedPrice>0.0</ExtendedPrice>
<Taxes inputOutputType="OUTPUT" rateClassification="Standard Rate" situs="DESTINATION" taxCollectedFromParty="BUYER" taxResult="TAXABLE" taxStructure="SINGLE_RATE" taxType="VAT">
<Jurisdiction jurisdictionId="78286" jurisdictionLevel="COUNTRY">ITALY</Jurisdiction>
<CalculatedTax>0.0</CalculatedTax>
<EffectiveRate>0.0</EffectiveRate>
<Taxable>0.0</Taxable>
<Imposition impositionId="1">VAT</Imposition>
<ImpositionType impositionTypeId="19">VAT</ImpositionType>
<TaxRuleId>549448</TaxRuleId>
<SellerRegistrationId>DK33368771</SellerRegistrationId>
<InvoiceTextCode>21</InvoiceTextCode>
</Taxes>
<TotalTax>0.0</TotalTax>
<FlexibleFields>
<FlexibleNumericField fieldId="1">124082</FlexibleNumericField>
<FlexibleNumericField fieldId="2">124067</FlexibleNumericField>
</FlexibleFields>
</LineItem>
</QuotationResponse>
<ApplicationData>
<ResponseTimeMS>1.5</ResponseTimeMS>
</ApplicationData>
</VertexEnvelope>
</soapenv:Body>
</soapenv:Envelope>
Billing response
{
"taxationItems":
[
{
"invoiceItemId": "8adca6528707a79701870d7b0ad03f67",
"taxAmount": 0.0,
"taxAmountUnRounded": 0.0,
"exemptAmount": 0.0,
"name": "ITALY",
"jurisdiction": "COUNTRY",
"locationCode": "78286",
"taxCode": "Sales Tax for Communications",
"taxDate": "2022-08-24",
"taxMode": 0,
"taxRate": 0.0,
"taxRateType": "Percentage",
"taxCodeDescription": "VAT",
"taxRateDescription": "VAT",
"country": "",
"taxRuleId": "549448",
"customerCode": "124082",
"tax_vertex_flexible_numeric_field_1__c": "124082"
},
{
"invoiceItemId": "8adca6528707a79701870d7b0ad13f68",
"taxAmount": 0.0,
"taxAmountUnRounded": 0.0,
"exemptAmount": 0.0,
"name": "ITALY",
"jurisdiction": "COUNTRY",
"locationCode": "78286",
"taxCode": "",
"taxDate": "",
"taxMode": "",
"taxRate": 0.0,
"taxRateType": "Percentage",
"taxCodeDescription": "VAT",
"taxRateDescription": "VAT",
"country": "",
"taxRuleId": "549448",
"customerCode": "124082",
"tax_vertex_flexible_numeric_field_1__c": "124082",
"tax_vertex_flexible_numeric_field_2__c": "124067"
}
]
}
In this example, the flexible numeric field with fieldId 1 from the Vertex response is mapped to the custom field tax_vertex_flexible_numeric_field_1__c in the billing response, with the value 124082.
Example mapping 2
Let's illustrate the mapping process with an example using other fields:
Vertex response
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<VertexEnvelope xmlns="urn:vertexinc:o-series:tps:7:0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Login>
<TrustedId>******</TrustedId>
<Password>******</Password>
</Login>
<QuotationResponse documentDate="2023-03-23" documentNumber="PREVIEW-INV-8adcd6298417a66a0184195871877308" returnGeneratedLineItemsIndicator="true" transactionId="PREVIEW-INV-8adcd6298417a66a0184195871877308" transactionType="SALE">
<Currency isoCurrencyCodeAlpha="EUR" isoCurrencyCodeNum="978" isoCurrencyName="Euro"/>
<OriginalCurrency isoCurrencyCodeAlpha="EUR" isoCurrencyCodeNum="978" isoCurrencyName="Euro"/>
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
<Destination taxAreaId="803800000">
<StreetAddress1>Via Scuderlando 31</StreetAddress1>
<City>Cologna Spiaggia</City>
<MainDivision>TE</MainDivision>
<PostalCode>64020</PostalCode>
<Country>IT</Country>
</Destination>
</Customer>
<SubTotal>0.0</SubTotal>
<Total>0.0</Total>
<TotalTax>0.0</TotalTax>
<LineItem lineItemId="8adca6528707a79701870d7b0ad03f67" taxDate="2022-10-27">
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
</Customer>
<Product productClass="ALL"/>
<Quantity>1.0</Quantity>
<ExtendedPrice>0.0</ExtendedPrice>
<Taxes inputOutputType="OUTPUT" rateClassification="Standard Rate" situs="DESTINATION" taxCollectedFromParty="BUYER" taxResult="TAXABLE" taxStructure="SINGLE_RATE" taxType="VAT">
<Jurisdiction jurisdictionId="78286" jurisdictionLevel="COUNTRY">ITALY</Jurisdiction>
<CalculatedTax>0.0</CalculatedTax>
<EffectiveRate>0.0</EffectiveRate>
<Taxable>0.0</Taxable>
<Imposition impositionId="1">VAT</Imposition>
<ImpositionType impositionTypeId="19">VAT</ImpositionType>
<TaxRuleId>549448</TaxRuleId>
<SellerRegistrationId>DK33368771</SellerRegistrationId>
<InvoiceTextCode>21</InvoiceTextCode>
</Taxes>
<TotalTax>0.0</TotalTax>
<FlexibleFields>
<FlexibleNumericField fieldId="1">124082</FlexibleNumericField>
</FlexibleFields>
</LineItem>
<LineItem lineItemId="8adca6528707a79701870d7b0ad13f68" taxDate="2022-10-27">
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
</Customer>
<Product productClass="ALL"/>
<Quantity>1.0</Quantity>
<ExtendedPrice>0.0</ExtendedPrice>
<Taxes inputOutputType="OUTPUT" rateClassification="Standard Rate" situs="DESTINATION" taxCollectedFromParty="BUYER" taxResult="TAXABLE" taxStructure="SINGLE_RATE" taxType="VAT">
<Jurisdiction jurisdictionId="78286" jurisdictionLevel="COUNTRY">ITALY</Jurisdiction>
<CalculatedTax>0.0</CalculatedTax>
<EffectiveRate>0.0</EffectiveRate>
<Taxable>0.0</Taxable>
<Imposition impositionId="1">VAT</Imposition>
<ImpositionType impositionTypeId="19">VAT</ImpositionType>
<TaxRuleId>549448</TaxRuleId>
<SellerRegistrationId>DK33368771</SellerRegistrationId>
<InvoiceTextCode>21</InvoiceTextCode>
</Taxes>
<TotalTax>0.0</TotalTax>
<FlexibleFields>
<FlexibleDateField fieldId="1">12-03-2023</FlexibleDateField>
</FlexibleFields>
</LineItem>
</QuotationResponse>
<ApplicationData>
<ResponseTimeMS>1.5</ResponseTimeMS>
</ApplicationData>
</VertexEnvelope>
</soapenv:Body>
</soapenv:
Billing response
In this example, the flexible numeric field with fieldId 1 from the Vertex response is mapped to the custom field tax_vertex_flexible_numeric_field_1__c in the billing response, with the value 124082.
Other fields
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<VertexEnvelope xmlns="urn:vertexinc:o-series:tps:7:0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Login>
<TrustedId>******</TrustedId>
<Password>******</Password>
</Login>
<QuotationResponse documentDate="2023-03-23" documentNumber="PREVIEW-INV-8adcd6298417a66a0184195871877308" returnGeneratedLineItemsIndicator="true" transactionId="PREVIEW-INV-8adcd6298417a66a0184195871877308" transactionType="SALE">
<Currency isoCurrencyCodeAlpha="EUR" isoCurrencyCodeNum="978" isoCurrencyName="Euro"/>
<OriginalCurrency isoCurrencyCodeAlpha="EUR" isoCurrencyCodeNum="978" isoCurrencyName="Euro"/>
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
<Destination taxAreaId="803800000">
<StreetAddress1>Via Scuderlando 31</StreetAddress1>
<City>Cologna Spiaggia</City>
<MainDivision>TE</MainDivision>
<PostalCode>64020</PostalCode>
<Country>IT</Country>
</Destination>
</Customer>
<SubTotal>0.0</SubTotal>
<Total>0.0</Total>
<TotalTax>0.0</TotalTax>
<LineItem lineItemId="8adca6528707a79701870d7b0ad03f67" taxDate="2022-10-27">
<Seller>
<Company>TR</Company>
</Seller>
<Customer>
<CustomerCode>124082</CustomerCode>
</Customer>
<Prod