The Numeric Calculations extension enriches Rossum’s data extraction by enabling arithmetic operations on numerical data. This extension allows for the instant computation of totals, taxes, discounts, and other numeric-based logic directly within the document processing flow, ensuring efficient and accurate data handling. The extension keeps original data intact, storing any computed values in the target fields instead.

In this article, we’ll cover:

• Configuration Basics
• Simple Numerical Operations
  • Sum of two fields
  • Multiplication of two fields
  • Conditioned computation
  • Sum of line items
• Complex Numerical operations
  • Line item net unit price calculation
• Advanced Configuration

Configuration Basics

To set up the Numeric Calculations Extension, you need to activate the extension in the Rossum Store and create a JSON configuration. This includes defining your calculations array with objects that describe the calculations to be performed. Each object within the array requires an expression, using the schema field IDs in curly braces to represent the values you want to calculate, and a target_field to store the calculated result.

Here’s an example of a simple JSON configuration for the extension:

{
  "calculations": [
    {
      "expression": "{field1} + {field2}",
      "target_field": "result_field"
    }
  ]
}

The expression should be a valid Python expression using field IDs, and target_field is the ID of the schema field where the result will be saved.

Available Parameters:

• calculations: A list of the calculation definitions.
• condition: An optional Python expression containing schema IDs that must evaluate as “True” for the calculation to proceed (the condition must be met).
• expression: The Python arithmetic expression to be evaluated for the calculation.
• target_field: The schema ID where the calculation result will be stored.

Important Considerations:

• Ensure that the data types in schema fields match the expected types for arithmetic operations. For instance, when you intend to add two fields together, both fields should contain numerical data (integers, floats, or decimals).
• Target fields must be compatible with the result types (e.g., integers, floats, decimals).

Simple Examples

The Numeric Calculations extension is versatile, capable of handling a variety of numerical operations. Below, you’ll find some simple examples to help you get started.

Example 1: Sum of two fields (total cost)

Sum two extracted fields, unit_cost and shipping_cost, to calculate the total cost of an order.

Extracted values:

• Unit cost: 150
• Shipping cost: 20

Resulting total cost (calculated) value: 170

{
  "calculations": [
    {
      "expression": "{unit_cost} + {shipping_cost}",
      "target_field": "total_cost_calculated"
    }
  ]
}

Example 2: Multiplication of two fields (sales tax)

Compute the sales tax amount based on a subtotal and a tax_rate.

Extracted values:

• Subtotal: 200
• Tax rate: 5% (represented as 0.05)

Resulting tax amount (calculated) value: 10

{
  "calculations": [
    {
      "expression": "{subtotal} * {tax_rate}",
      "target_field": "tax_amount_calculated"
    }
  ]
}

Example 3: Conditioned computation (volume discount)

Determine the discounted price after applying a volume discount threshold.

Extracted values:

• Total price: 1000
• Volume discount threshold: 800
• Discount: 10% (represented as 0.10)

Resulting price after volume discount: 900

{
  "calculations": [
    {
      "condition": "{total_price} > {volume_discount_threshold}",
      "expression": "{total_price} * (1 - {discount})",
      "target_field": "price_after_volume_discount"
    }
  ]
}

Example 4: Sum of line items (total price)

An invoice contains multiple line items, each with a separate total price. The goal is to calculate the sum of all these line item totals to find the overall invoice total.

Assuming the extracted line item totals are as follows:

• Line item 1 total: $50.00
• Line item 2 total: $75.00
• Line item 3 total: $25.00

The overall invoice total should be the sum of these amounts: $150.00.

{
  "calculations": [
    {
      "expression": "sum({line_item_total})",
      "target_field": "invoice_total"
    }
  ]
}

Complex Configuration Example

In this section, we delve into a key application of the Numeric Calculations Extension to showcase how it can simplify and automate calculations, streamlining your data processing tasks.

Line item net unit price calculation

In this example, a series of calculations prioritizes determining the Net Unit Price (item_amount_base_calculated) from least to most complex. The last successful calculation produces the final Net Unit Price. If the Net Unit Price has already been extracted, it is directly copied to the target field.

{
  "calculations": [
    {
      "expression": "{item_amount_base}",
      "target_field": "item_amount_base_calculated",
      "result_decimal_points": 2
    },
    {
      "expression": "{item_total_base} / {item_quantity}",
      "target_field": "item_amount_base_calculated",
      "result_decimal_points": 2
    }, 
    {
      "expression": "({item_amount_total} - default({item_tax}, 0)) / {item_quantity}",
      "target_field": "item_amount_base_calculated",
      "result_decimal_points": 2
    }
   
  ]
}

Advanced Configuration

This section details a comprehensive list of parameters available for tailoring the Numeric Calculations Extension to your specific needs. This enables you to fine-tune your settings for more complex scenarios and precise data handling requirements.

Attribute	Type	Required	Default value	Description
calculations	list	yes	–	List of calculation definitions
condition	string	no	–	Python expression containing Rossum schema ids wrapped in the { }. The calculation will be performed only if the condition matches (expression evaluates to True).
expression	string	yes	–	A mathematical expression containing schema IDs wrapped in the { }. Supported operators and functions in the expression are: +, - , *, /, sum(), avg(), abs(), default({schema_id}, default_value)*
target_field	string	yes	–	Schema ID of the field to which the calculation result will be stored.
allow_target_update	boolean	no	false	true – Allows user update of the field calculated by the function. false – Doesn’t allow user update of the field. The value will always be changed back after edit.
result_decimal_points	number	no	2	A number of decimal points to which the calculation’s result will be rounded.
additional_user_update_triggers	list	no	–	List of schema IDs of the fields that will trigger the calculation when changed.
queues	list	no	–	Queues where the calculations should be applied (a subset of queues to which the extension is assigned). List of queue URLs. If not specified, the calculation applies to all queues to which the function is assigned.
excluded_queues	list	no	–	Queues where the action should NOT be applied (subset of queues to which the extension is assigned). List of queue URLs. If not specified, the calculation applies to all queues to which the function is assigned.

If you encounter any troubles, contact us at support@rossum.ai.