From this article you will learn:

• What is Rossum Calculations extension
• What are the common use case configurations
• How to set up Calculations extension
• What are the available configuration parameters

What is the Calculations Extension, and how does it work

We have developed Calculations extension to improve your automation while maintaining the integrity of your data. Whenever numeric data is missing from your document but can be deduced from available data, you can use our new extension to perform mathematical expressions to find the missing value. Then the extension stores the computed values to specific schema IDs. It helps ensure that the data output is congruent across all documents, regardless of what the document sender provides.

The most common use cases are:

– calculating the Net Unit Price using Quantity and Total Amount,

– calculating the VAT Amount using the VAT Rate and Total Amount.

Note that these equations can go either way. So you can calculate a Quantity using the Net Unit Price and the Total Amount or calculate the VAT Rate using the VAT Amount and the Total Amount. Usually, it involves three values, two of which are available, and the third can be calculated.

The function triggers after the AI extracts data and when a user updates one of the schema fields. Also, calculated values should always be input to their own schema fields and never be returned to overwrite extracted schema fields.

Use the Calculations extension on its own or with other extensions. You can also use the previous calculation in the next one or with a value fetched via Data Matching.

Common use case configurations for Calculations extension

Below you will find configuration examples you can copy and modify for easy setup. 

Line Item Net Unit Price Calculation

This example calculates Net Unit Price (item_amount_base_calculated) using multiple calculations. The order is from most to least complicated. The resulting value is given by the final calculation that can be finished (with values for all operands available in the data). 

As the Net Unit Price may be present and extracted directly, the last calculation copies the extracted value to the target field if it’s present in the data.

{
  "calculations": [
    {
      "expression": "({item_amount_total} - default({item_tax}, 0)) / {item_quantity}",
      "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_base}",
      "target_field": "item_amount_base_calculated",
      "result_decimal_points": 2
    }
  ]
}

Rounding of the extracted value

Another common use case is to create congruency in the number of decimal places for all numeric values extracted and exported. 

The example below rounds the Total Amount to two decimal places and inputs the result into a separate schema field.

{
  "calculations": [
    {
      "expression": "{amount_total}",
      "target_field": "amount_total_calculated",
      "result_decimal_points": 2
    }
  ]
}

How to set up the Calculations extension 

Setting up the extension itself takes a few simple steps. 

Step 1: Prepare your queues and schemas

The first step is to identify the queue(s) with the documents that require this extension. Then you need to identify the schema IDs of the fields that will contain the extracted values set to be transformed by the extension.

If you use the Dedicated Engine, make sure that you create new schema fields that will store the results of the calculations (see the info panel below). And if you use the Generic Engine, you can also store the results of the calculations in the AI-predicted fields if needed.

Please note that when using the Dedicated Engine and configuring the extension to modify the value of a particular AI extracted field, the results of the accuracy calculation for this field will be significantly lower than the actual accuracy. To avoid this, we don’t recommend manual or programmatic modification of the AI, and OCR extracted values when using the Dedicated Engine. Instead, use new extra fields to store the modified value.

Step 2: Activate Calculations in the Rossum Store

To activate Calculations, go to the Rossum application and:

1. Click on the Extensions tab at the top of the app.
2. Click on the Rossum store option to display all the available extensions.
3. Select the “Calculations” extension tile.
4. Click “Try extension.”

Step 3: Specify to which queue(s) you want to add this extension.

In the “Rossum Store Extension Settings,” scroll down to “Queues” and select the queue(s) in which you want to use the extension. Please remember to save your changes once you’ve chosen the desired queues.

Step 4: Set up the Calculations

You can set it up using the configuration field in the UI or using the settings attribute of the hook API object. The configuration is in JSON format. 

It consists of a list of calculations that work with values from different fields in the schema.

Complete list of available parameters:

Attribute	Type	Required	Default value	Description
calculations	list	yes	–	List 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 use formula default({schema_id}, default_value) and the value for the schema_id has not been extracted, the value in parameter “default_value“ is used for purposes of the calculation. The calculation is skipped if you do not use the formula and the value is not there.

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