Functions

Functional Documentation

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

Functions

set_field_value()

Sets the value of a field in the document data.

po_number = get_field_value(fields_dict, 'purchase_order', None)
if not po_number:
    po_number = ''
    
if po_number:
    set_field_value(fields_dict, "invoice_sub_type", 'Purchase Invoice')
else:
    set_field_value(fields_dict, "invoice_sub_type", 'Cost Invoice')

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
value*	any	The value to set for the field
remove_link (optional)	bool	Remove the "coords" key from the field.

set_date_value()

Sets the value of a date field in the document data.

invoice_date = get_field_value(document_data, 'invoice_date', None)
    
if not document_json.get("script_executed", False):
    if invoice_date:
        set_date_value(document_data, "accounting_date", invoice_date)
        document_json["script_executed"] = True

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
value*	string	The date value to set in ISO format (e.g., "2020-12-31").
add_days (optional)	int	Add additional days to the given date Default is 0
skip_weekend (optional)	bool	Skips the date if it falls on the weekend Default is False
remove link (optional)	bool	Remove the "coords" key from the field.
exclude_final_days (optional)	either string or int	Specifies the days to exclude (0-6 or Sunday to Saturday)

set_amount_value()

Sets the value of an amount field in the document data.

total_amount = get_field_value(document_data, "net_amount")
lines_total = 0.0
set_amount_value(document_data, "net_amount",str(lines_total))

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
value*	string	The value to set for the field (pass a number as string e.g., "123456"
remove link (optional)	bool	Remove the "coords" key from the field.

get_field_value()

Gets the value of a field from the document data.

total_amount = get_field_value(document_data, "net_amount")
lines_total = 0.0
set_amount_value(document_data, "net_amount", str(lines_total))

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
default_value (optional)	any	Returns default_value if no field value is found Default is None
is_clean (optional)	bool	Converts the value to uppercase and removes any extra spaces Default is False

Returns:

• Value of the specified field

create_new_field()

Creates a new field with the specified name and value.

currency = get_field_value(document_data, 'currency', None)

if not currency:
    if 'currency' not in fields_dict:
        new_field = create_new_field('currency','')
        fields_dict['currency'] = new_field
        document_json['fields'].append(new_field)
    set_field_value(document_data, "currency", "USD")

Parameters:

Name	Type	Description
field_name*	str	The document data containing field information
value (optional)	any	The initial value for the field Default is ""

Returns:

• Dictionary of the new created field

delete_field()

Deletes a field from the document data

field_amount = get_field_value(document_data, field_name)
    if not field_amount:
        delete_field(document_data, fields_dict, field_name)
    else:
        field_amount = float(field_amount)
        if field_amount == 0:
            delete_field(document_data, fields_dict, field_name)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to delete

Returns:

• Document_data as json and as dict after field got deleted

set_is_required()

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

net_amount = get_field_value(document_data, "net_amount", None)
if net_amount:
    set_is_required(document_data, "tax_country", True)
    set_is_required(document_data, "tax_code_without_country", True)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
value*	bool	The value to set for the field

set_force_validation()

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

if supplier_id in supplier_to_check:
    set_force_validation(document_data, 'purchase_order', True, reset_validation=reset_validation)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
value*	bool	The value to set for the field
reset_validation (optional)	bool	Sets the "is_validated" attribute to the specified value Default is False

set_field_as_invalid()

Marks a field in the validation screen as invalid and highlights it.

if not document_date:
    set_field_as_invalid(document_data, "document_date", "Es ist kein Datum vorhanden", "INVALID_VALUE")

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to mark as invalid
message*	string	The validation message for the field
code (optional)	string	Error code for the validation Default is None

set_field_attribute()

Sets a custom attribute of a field in the document data.

if purchase_order:
    if po_supplier_id != invoice_supplier_id:
        set_field_as_invalid(document_data, "supplier_name", "Supplier is different from PO supplier")
    else:
        set_field_attribute(document_data, "supplier_name", "is_valid", True)
        set_field_attribute(document_data, "supplier_name", "validation_message","")

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
field_name*	string	The name of the field to set
attribute_name*	string	The name of the attribute to set. List of supported attributes can be found here.
value*	any	The value to set for the attribute

is_supplier_valid()

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

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

Parameters:

Name	Type	Description
user*	UserAuthentication	The authenticated user
filter_data_json*	json	Filter criteria for validating the supplier
sub_org_id (optional)	string	Optional sub-organization ID for filtering Default is None

Returns:

• True, if the user is valid

• False if the user isn’t valid

get_document_content()

Decodes document data and returns it as a string.

document_content = get_document_content(doc)
if document_content:
    document_content = document_content.lower()

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information

Returns:

• Document data as a string.

update_document_status_with_doc_id()

Updates the status of a document with a specific ID to the given status.

genehmigung_user_1 = get_field_value(document_data, 'genehmigung_user_1', None)

if genehmigung_user_1 != "LEER":
    update_document_status_with_doc_id(document_json['doc_id'], user, document_json['org_id'], "validated_pending_approval")

Parameters:

Name	Type	Description
doc_id*	string	The ID of the document to update
user*	either user ID or UserAuthentication object	The user performing the update
org_id*	string	The ID of the organization to which the document belongs
status*	string	The new status of the document
message (optional)	string	Optional message associated with the status update Default is None
doc_classification_class (optional)	string	Optional document classification class Default is None

get_lov_values()

Gets the LOV values from a specific org_id and key.

reverse_charge_to_check = get_lov_values(org_id, 'Kosten', return_type="list_of_values")

Parameters:

Name	Type	Description
org_id*	string	The ID of the organization to which the document belongs
key*	string	The key of the required List Of Values
return_type (optional)	string	The type in which the data should be returned Default is 'list_of_objects'
sub_org_id (optional)	string	Optional sub-organization ID for filtering Default is None
language_code (optional)	string	This parameter sets the language in which the values will be returned. It accepts language codes, such as "en" for English or "fr" for French. Default is ""

Returns:

• LOV-Values as a list of objects or as a list.

format_decimal_to_locale()

Formats a decimal value to en_US.UTF-8 format.

standard_value = "{0:.2f}".format(total)
formatted_value = format_decimal_to_locale(
    standard_value, document_json['amount_format_locale']
)

Parameters:

Name	Type	Description
value*	float, decimal.Decimal, str	The ID of the organization to which the document belongs
to_locale (optional)	string	The type in which the data should be returned Default is 'en_US.UTF-8'
max_decimal_places (optional)	int	Optional sub-organization ID for filtering Default is 4
min_decimal_places (optional)	int	The minimum of decimal places which should be considered Default is 2

• value: The value which should be formatted.

• to_locale (optional): The format in which the value gets transformed.

• max_decimal_places (optional): The maximum of decimal places which should be considered.

• min_decimal_places (optional): The minimum of decimal places which should be considered.

Returns:

• The formatted value.

compare_values()

Compares two values for equality, handling various data types.

result = compare_values(10, "10")

Parameters:

Name	Type	Description
value1*	any	The first value to compare
value2*	any	The second value to compare

Returns:

• True if the values are equal and False if they differ

create_document_task()

Creates a task, assigns it to a user or group, sets priority, and optionally sends an email.

if not is_task_created:
            create_document_task(user, document_data, "Herkunftsland außerhalb der EU", "Die Gelangensbestätigung kommt von einem Land außerhalb der EU. Bitte das MRN-Dokument anhängen.", "high", 1007, None, False)
            document_data["document_json"]["country_check_task_created"] = True

Parameters:

Name	Type	Description
user*	either user ID or UserAuthentication object	The user performing the update
document_data*	dictionary	The document data containing field information
title*	string	The title of the task
description*	string	The description of the task
priority*	string	The priority of the task
assigned_to_user_id*	int	The id of the user to which the task should assigned to
assigned_to_group_id*	int	The id of the group to which the task should assigned to
send_email*	bool	Determine if an email should be send or not

Returns:

• Dict which is indicating if the process was successful or not

set_document_sub_org_id()

Sets the sub_org_id of the specified document_data.

if sub_org_id != current_sub_org_id:
    document_data["document_json"]["sub_org_id4"] = sub_org_id
    set_document_sub_org_id(document_data, sub_org_id)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
sub_org_id*	string	Optional sub-organization ID for filtering

get_user_by_id()

Gets the user with the corresponding user ID.

requester_mail = str(get_user_by_id(str(requester)).email.lower())

Parameters:

Name	Type	Description
user_id*	string	The ID of the user

Returns:

• The user with the corresponding user ID

get_group_by_id()

Gets the group with the corresponding group ID.

group_name  = str(get_group_by_id(assigned_to_group_id))

Parameters:

Name	Type	Description
group_id*	string	The ID of the group

Returns:

• The group with the corresponding group ID

get_user_by_email()

Gets the group with the corresponding group ID.

user_name = str(get_user_by_email(email)

Parameters:

Name	Type	Description
email*	any	The email of the user

Returns:

• The user with the corresponding email

add_table_column()

Adds a column to the specified table.

table = tables_dict.get("ORDER_CONFIRMATION_TABLE")

if table:
    add_table_column(table, "PROMISED_DELIVERY_DATE")

Parameters:

Name	Type	Description
table*	string	The table where the column should be added
col_name*	string	The name of the column
default_value (optional)	any	The initial value for the field Default is None

get_column_value()

Gets the value of a specified column.

for row in table['rows']:
        unit = get_column_value(row, "UNIT")

Parameters:

Name	Type	Description
row*	string	The row where the value is located
col_name*	string	The name of the column
default_value (optional)	any	The initial value for the field Default is None
is_clean (optional)	bool	Converts the value to uppercase and removes any extra spaces Default is False

Returns

• Returns the value of the specified column if it exists; otherwise, it returns None

set_column_value()

Sets the value of the specified column. If the column does not exist, it will be created.

supplier_id = get_field_value(document_data, "supplier_id", "")

quote_table = tables_dict["QUOTE_TABLE"]

for row in quote_table.get('rows', []):
    set_column_value(row,"SUPPLIER_ID", supplier_id)

Parameters:

Name	Type	Description
row*	string	The row where the value is located
col_name*	string	The name of the column
value*	any	The value that will be set at the specified location

Returns:

• True if the change was successful

set_column_date_value()

Sets the date value of a specified column.

set_column_date_value(document_data, row, "DELIVERY_DATE", "2020-12-31", add_days=2)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
row*	string	The row where the value is located
col_name*	string	The name of the column
value*	string	The date value to set in ISO format (e.g., "2020-12-31")
add_days (optional)	int	Add additional days to the given date Default is 2
skip_weekend (optional)	bool	Skips the date if it falls on the weekend Default is False
exclude_final_days (optional)	either string or int	Specifies the days to exclude (0-6 or Sunday to Saturday)

set_column_amount_value()

• Convert value to string and set the value for the column

• Set column content to the value

• Format value according to the locale

quantity = float(quantity) / 1000
set_column_amount_value(document_data, row, "QUANTITY", str(quantity))

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
row*	string	The row where the value is located
column_name*	string	The name of the column
value*	string	The value to set for the field (pass a number as string e.g., "123456")

delete_tables()

This function deletes the tables from the document data.

delete_tables(document_data)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information

restore_tables()

This function restores the tables in the document data.

restore_tables(document_data)

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information

remove_rows_from_table()

Removes rows from the specified table.

count = 1
start = 1
remove_rows_from_table(document_data,"INVOICE_TABLE",count,start) 

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
table_name*	string	The name of the table
count*	int	How many lines should be deleted
start*	int	The starting point

remove_all_rows_except_one_from_table()

Removes all rows except one from the specified table

count = 1
start = 1
remove_rows_from_table(document_data,"INVOICE_TABLE",count,start) 

Parameters:

Name	Type	Description
document_data*	dictionary	The document data containing field information
line_number*	int	The number of the line which should not be removed

Supported Attributes

Core Field Attributes

Attribute	Type	Description
value	any	The raw field value
formatted_value	string	Display-formatted value
content	string	Original extracted content
is_required	bool	Whether field is mandatory
is_valid	bool	Validation status
is_validated	bool	Whether field has been validated by user
force_validation	bool	Force user to validate this field
highlight_field	bool	Highlight field in UI
extraction_method	string	How value was extracted (e.g., "SCRIPT")

Validation Attributes

Attribute	Type	Description
validation_message	string	Error message shown to user
validation_code	string	Error code (e.g., "FORCED_VALIDATION", "INVALID_VALUE")
invalidated_by_script	bool	Marks field as invalidated by script

Extraction/OCR Attributes

Attribute	Type	Description
coords	object	Bounding box coordinates on document
confidence	float	OCR/extraction confidence score
score	float	Match/validation score
score_description	string	Description of the score
page	int	Page number where field was found
rule	string	Extraction rule that was applied

Python Built-in Functions

You can also utilize some of the python in-build functions:

• abs(): Returns the absolute value of a number.

• len(): Returns the length (number of items) of an object, like a list or string.

• isinstance(): Checks if an object is an instance of a particular class or type.

• print(): Prints output to the console.

• round(): Rounds a floating-point number to a specified number of decimal places.

• str_to_bool(): Converts a string to a boolean value (True or False).

• type(): Returns the type of an object.

• dict(): Creates a dictionary object.

• list(): Creates a list object.

• str(): Converts a value to a string.

• float(): Converts a value to a floating-point number.

• int(): Converts a value to an integer.

For more details, visit the official Python documentation: Built-in Functions.

String Class Functions

You can also use these functions specifically for working with strings:

• lower(): Converts all characters in a string to lowercase.

• upper(): Converts all characters in a string to uppercase.

• split(): Splits a string into a list based on a delimiter (e.g., space or comma).

• startswith(): Checks if a string starts with a specified prefix.

• endswith(): Checks if a string ends with a specified suffix.

• strip(): Removes any leading or trailing whitespace from a string.

Functions from the Python Math Module

These functions are part of the math module and are useful for mathematical operations:

• floor(): Returns the largest integer less than or equal to a given number.

• ceil(): Returns the smallest integer greater than or equal to a given number.

For more information, check out the official Python documentation: Math Module Functions.

Regular Expression Function

• re.search(): Searches for a pattern within a string and returns the first match.

See more details here: re.search Documentation.

External Functions

Here are some useful functions from external libraries:

• deepcopy(): Creates a copy of an object, including nested objects (from the copy module). Deepcopy Documentation.

• levenshtein_distance(): Calculates the number of edits (insertions, deletions, substitutions) required to change one string into another. This function is available in the Jellyfish library.

Date and Time Functions

You can use the following functions for working with dates and times:

• strptime(): Converts a string into a datetime object based on a specified format.

• strftime(): Formats a datetime object into a string based on a specified format.

For more information, check the official documentation: Date and Time Functions.