Introduction

This document provides a detailed guide on the "Calculating Total Charges" script within the Docbits platform. The script is designed to automatically calculate the total amount charged on an invoice by summing up various individual charges. This automation enhances accuracy and efficiency in document processing.

Objective

The aim of this script is to streamline the calculation process for total charges on invoices. By automatically adding up specified charges, such as base charges, taxes, and additional fees, the script ensures that the total charges reflected on each invoice are accurate and comprehensive.

Script Details

Code Implementation

The "Calculating Total Charges" script automates the process of summing up various charges and additional amounts within invoice documents. This guide walks you through the script setup, logic, and application to ensure accurate total charge calculations across your documents.

Purpose

This script aims to provide a dynamic way to calculate the total charges on an invoice by adding up different charge types, such as base charges, freight (Fracht), and packaging (Verpackung). It then updates the invoice's total charges field with the calculated sum, ensuring accurate billing information.

Script Overview

The script retrieves values from specified fields, converts them to floats, sums them up, and then updates the total_charges field with the result. If the total_charges field doesn't exist, the script creates this field and sets its value accordingly.

Code Snippet

total_charges = get_field_value(fields_dict, 'total_charges', None)
fracht = get_field_value(fields_dict, 'additional_amount_2', None)
verpackung = get_field_value(fields_dict, 'additional_amount', None)

# Initialize total to 0
total = 0

# Add fracht to total if it exists
if fracht:
    fracht = float(fracht)
    total += fracht

# Add verpackung to total if it exists
if verpackung:
    verpackung = float(verpackung)
    total += verpackung

# Formatting the total to two decimal places
formatted_total = "{0:.2f}".format(total)

# Checking if the total_charges field exists and updating or creating accordingly
if 'total_charges' not in fields_dict:
    new_field = create_new_field('total_charges', formatted_total)
    fields_dict['total_charges'] = new_field
    document_json['fields'].append(new_field)
else:
    set_field_value(fields_dict, 'total_charges', formatted_total)

This document outlines the "Formatting Export Certificate Reference Numbers" script, aimed at standardizing reference numbers across export certificates in Docbits. Proper formatting ensures that reference numbers comply with external systems or regulatory requirements.

Purpose

The script's primary goal is to format reference numbers on export certificates, ensuring they meet a predefined length requirement by padding them with leading zeros. This consistency aids in maintaining a standardized format for all export documents processed through Docbits.

Script Overview

The script identifies the reference_number field in an export certificate, checks its length, and if necessary, pads the number with leading zeros to ensure it meets the minimum length requirement.

Code Snippet

ref_number = get_field_value(fields_dict, 'reference_number')
# Ensure the reference number meets a minimum length of 10 characters
if len(ref_number) < 10:
    ref_number = ref_number.zfill(10)
    set_field_value(fields_dict, 'reference_number', ref_number)

Guia de Scripting do Docbits

Bem-vindo ao guia de scripting do Docbits! Aqui, você aprenderá a usar scripts para automatizar e aprimorar o processamento de documentos dentro do Docbits. Scripts permitem a manipulação personalizada de campos, transformação de dados e implementação de lógica em vários tipos de documentos.

Introdução

Os scripts no Docbits são escritos em Python. Eles interagem com campos de documentos e metadados para realizar uma ampla gama de operações, desde formatação simples de dados até lógica complexa.

Funções Principais

• get_field_value(fields_dict, field_name, default=None): Recupera o valor de um campo especificado.

• set_field_value(fields_dict, field_name, value): Define o valor de um campo especificado.

• create_new_field(field_name, value): Cria um novo campo com um nome e valor especificados.

• format_decimal_to_locale(value, locale): Formata um valor decimal de acordo com um local especificado.

Exemplos de Scripts

Abaixo estão vários exemplos que demonstram tarefas comuns de scripting.

Exemplo 1: Mapeamento de Moeda para Faturas

Padronize símbolos ou texto de moeda para códigos de moeda ISO.

currency_map = {
    "€": "EUR",
    "EURO": "EUR",
    "$": "USD",
    "£": "GBP"
}
currency_value = get_field_value(fields_dict, "currency", None)
if currency_value:
    currency_value = currency_value.upper()
    if currency_value in currency_map:
        currency_value = currency_map[currency_value]
    set_field_value(fields_dict, "currency", currency_value)

This document details the "Generating Extended Invoice Numbers" script, which automates the creation of extended invoice numbers in Docbits. Extended invoice numbers combine multiple document identifiers, such as the invoice ID and the purchase order number, into a single, comprehensive identifier. This script enhances document traceability and simplifies record-keeping.

Purpose

The purpose of this script is to streamline the process of generating extended invoice numbers by automatically concatenating the invoice ID and purchase order number, thereby providing a unified and unique identifier for each invoice document.

Script Overview

The script checks for the presence of invoice ID and purchase order number fields within the document, concatenates their values if both are present (separated by a hyphen), and updates or creates a new field to store the combined value.

Code Snippet

invoice_id = get_field_value(fields_dict, 'invoice_id')
purchase_order = get_field_value(fields_dict, 'purchase_order')

# Combining invoice ID and purchase order number with a hyphen separator
extended_number = '-'.join(filter(None, [invoice_id, purchase_order]))

# Check if there is an extended number to set
if extended_number:
    # Updating the 'invoice_extended_number' field with the combined value
    if not 'invoice_extended_number' in fields_dict:
        new_field = create_new_field('invoice_extended_number', extended_number)
        fields_dict['invoice_extended_number'] = new_field
        document_json['fields'].append(new_field)
    else:
        set_field_value(fields_dict, 'invoice_extended_number', extended_number)

Part 1: Delete Lines with Empty Quantity and Amount

This section of the script processes an invoice table to remove any lines where both the quantity and the total amount are zero or not provided.

• Check for INVOICE_TABLE: It starts by checking if the INVOICE_TABLE key exists in the tables_dict dictionary.

• Iterate Over Rows: For each row in the table, the script initializes flags and variables to determine if the TOTAL_AMOUNT and QUANTITY columns exist and to capture their values.

• Check Column Names: As it iterates through each column in a row, it looks for columns named TOTAL_AMOUNT and QUANTITY.

  • If TOTAL_AMOUNT is found, it captures the value. If this value is non-zero, it converts it to a float.

  • Similarly for QUANTITY, capturing and converting the value if it is non-zero.

• Mark Row for Deletion: After checking both columns in a row, if both the total amount and quantity are effectively zero (either by being zero or not existing), the row is marked for deletion by setting row['is_deleted'] to True.

Part 2: Validate Line Total Against Invoice Total

This section calculates the total amount from all lines in an invoice and compares it to the invoice’s reported total to validate their consistency.

• Initialize Line Total: Starts by setting a variable lines_total to 0.0 to accumulate the total amount from all lines.

• Sum Line Amounts: Iterates over each row in the INVOICE_TABLE, extracting the TOTAL_AMOUNT from each and adding it to lines_total.

• Retrieve and Convert Invoice Total: Fetches the total invoice amount using a helper function get_field_value and converts it to a float.

• Compare Totals: Finally, it checks if the absolute difference between the calculated line total (lines_total) and the reported invoice total (total_amount) exceeds a threshold of 0.05. If so, it marks the invoice total field as invalid using another helper function set_field_as_invalid, citing a mismatch.

##################################################
# Delete lines with empty quantity and amount 
##################################################


if tables_dict.get('INVOICE_TABLE'):
    for row in tables_dict['INVOICE_TABLE']['rows']:
        amount_col_found = False
        quantity_col_found = False
        line_amount = 0.0
        line_quantity = 0.0
        for col in row['columns']:
            if col['name'] == 'TOTAL_AMOUNT':
                amount_col_found = True
                line_amount = col.get('value', 0)
                if line_amount:
                    line_amount = float(line_amount)
            if col['name'] == 'QUANTITY':
                quantity_col_found = True
                line_quantity = col.get('value', 0)
                if line_quantity:
                    line_quantity = float(line_quantity)
            if amount_col_found and quantity_col_found:
                break
        if amount_col_found and quantity_col_found and (not line_amount and not line_quantity or (line_amount + line_quantity) == 0):
            row['is_deleted'] = True
        
##################################################
# End: Delete lines with empty quantity and amount 
##################################################

##################################################
# Validating Line total againg invoice total
##################################################
lines_total = 0.0
# Getting Lines Total
if tables_dict.get('INVOICE_TABLE'):
    for row in tables_dict['INVOICE_TABLE']['rows']:
        line_amount = 0.0
        for col in row['columns']:
            if col['name'] == 'TOTAL_AMOUNT':
                line_amount = col.get('value', 0)
                if line_amount:
                    line_amount = float(line_amount)
                break
        lines_total += line_amount

# Getting Invoice total
total_amount = get_field_value(fields_dict, "net_amount", "0.0")
if total_amount:
    total_amount = float(total_amount)

# Comparing lines total with invoice total    
if abs(total_amount - lines_total) > 0.05:
    set_field_as_invalid(fields_dict, "net_amount", "Invoice total mismatches lines total", "AMOUNTS_MISMATCH")

##################################################
# End: Validating Line total againg invoice total
##################################################






    

Summary

The script effectively ensures data integrity by:

1. Removing data rows that do not contribute to the invoice’s financial total due to lacking quantities or amounts.

2. Validating the consistency between the sum of individual line amounts and the overall invoice total, highlighting discrepancies for further action.

This automation helps maintain accurate financial records and can be crucial for systems like ERP that require precise data for accounting and financial reporting.

Functional Documentation

This module contains functions for manipulating document data and performing various operations related to document fields.

Functions

1. set_field_value(document_data, field_name, value)

   • Description: Sets the value of a field in the document data.

   • Parameters:

     • document_data (dict): The document data containing field information.

     • field_name (str): The name of the field to set.

     • value: The value to set for the field.

   • Example:

     set_field_value(document_data, "name", "John Doe")

2. set_date_value(document_data, field_name, value)

   • Description: Sets the value of a date field in the document data.

   • Parameters:

     • document_data (dict): The document data containing field information.

     • field_name (str): The name of the date field to set.

     • value: The date value to set in ISO format (e.g., "2020-12-31").

   • Example:

     set_date_value(document_data, "date_of_birth", "1990-05-15")

3. set_amount_value(document_data, field_name, value)

   • Description: Sets the value of an amount field in the document data.

   • Parameters and example usage similar to set_field_value.

4. set_is_required(document_data, field_name, value)

   • Description: Sets the 'is_required' attribute of a field in the document data.

   • Parameters and example usage similar to set_field_value.

5. set_force_validation(document_data, field_name, value)

   • Description: Sets the 'force_validation' attribute of a field in the document data.

   • Parameters and example usage similar to set_field_value.

6. set_field_attribute(document_data, field_name, attribute_name, value)

   • Description: Sets a custom attribute of a field in the document data.

   • Parameters:

     • attribute_name (str): The name of the attribute to set.

     • value: The value to set for the attribute.

   • Example:

     set_field_attribute(document_data, "address", "is_verified", True)

7. get_field_value(document_data, field_name, default_value=None, is_clean=False)

   • Description: Gets the value of a field from the document data.

   • Parameters and example usage similar to set_field_value.

8. create_new_field(field_name, value="")

   • Description: Creates a new field with the specified name and value.

   • Parameters:

     • field_name (str): The name of the field to create.

     • value: The initial value for the field (default is an empty string).

   • Example:

     create_new_field("address", "123 Main St")

9. delete_field(document_data, field_name)

   • Description: Deletes a field from the document data.

   • Parameters and example usage similar to set_field_value.

10. update_document_status_with_doc_id(doc_id, user, org_id, status, message=None, doc_classification_class=None)

    • Description: Updates the status of a document with the specified ID.

    • Parameters:

      • doc_id (str): The ID of the document to update.

      • user: The user performing the update (either user ID or UserAuthentication object).

      • org_id: The ID of the organization to which the document belongs.

      • status (str): The new status of the document.

      • message: Optional message associated with the status update.

      • doc_classification_class: Optional document classification class.

    • Example:

      update_document_status_with_doc_id("123456", user, org_id, "approved", "Document approved")

11. is_supplier_valid(user: UserAuthentication, filter_data_json, sub_org_id=None)

    • Description: Checks if a supplier is valid based on the provided criteria.

    • Parameters:

      • user (UserAuthentication): The authenticated user.

      • filter_data_json: Filter criteria for validating the supplier.

      • sub_org_id: Optional sub-organization ID for filtering.

    • Example:

      is_supplier_valid(user, {"name": "Supplier Inc."})

12. set_field_as_invalid(document_data, field_name, message, code=None)

    • Description: Marks a field as invalid in the document data.

    • Parameters:

      • document_data (dict): The document data containing field information.

      • field_name (str): The name of the field to mark as invalid.

      • message (str): The validation message for the field.

      • code (optional): Error code for the validation (default is None).

    • Example:

      set_field_as_invalid(document_data, "email", "Invalid email format", "EMAIL_FORMAT_INVALID")

13. compare_values(value1, value2)

    • Description: Compares two values for equality, handling various data types.

    • Parameters:

      • value1: The first value to compare.

      • value2: The second value to compare.

    • Example:

      compare_values(10, "10")

\

Overview

This guide focuses on automating the creation of extended invoice numbers in Docbits, a crucial feature for improving invoice management and tracking. The "Generating Extended Invoice Numbers" script concatenates various document identifiers, such as invoice ID and purchase order number, to create a comprehensive and unique identifier for each invoice.

Objective

The primary goal of this script is to automate the generation of extended invoice numbers, facilitating easier tracking and management of invoices by combining multiple identifiers into a single, unique number.

Script Implementation

Code Snippet