From this article you will learn:

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

What is the Value Operations extension, and how does it help you

The values Rossum extracts from the processed document are not always available in the structure you need for the export on integration with the downstream system.

Some values may only be available in the header, but you need them to be present on all line items. Or a case when your target system requires document type to be marked with a special code. And that code that does not correspond to Rossum document type values, so you need to create a mapping table. You might also want to export the account number and fall back to IBAN if the account number is not available within the same exported field.

In conclusion, Value Operations is a configurable extension that can help with many different issues as it offers configurable operations with extracted values.

Common use case configurations for Value Operations

You can copy and modify the following examples for easy setup.

1. Distribution of the PO number to the line items

The Value Operations extension with the configuration below distributes the Order Number from the header field to the line item field with the following logic.
If the order number is annotated and extracted both on the header level and line item level, the line item value has priority and is copied to the target Item PO number (calculated) field.
However, if no value is extracted on the line item level, the header level value is copied to the target field on the line item.

In this case, we have two operations in the configuration. So the first operation distributes the header level value to all line items where item_order_id was not extracted. Then the second operation copies the values from the item_order_id column for line items where the value was extracted.
As a result we have the item_order_id_calculated column containing PO number information from the document.

Example:

• PO number (order_id): PO-123
• PO numbers line items (item_order_id):
  • 1: PO-345
  • 2:
  • 3:
  • 4: PO-678
• Output: PO numbers line items calculated (item_order_id_calculated):
  • 1: PO-345
  • 2: PO-123
  • 3: PO-123
  • 4: PO-678

{
  "operations": [
    {
      "condition": "len({line_items}) > 0 and {item_order_id} == ''",
      "source_field": "order_id",
      "target_field": "item_order_id_calculated"
    },
    {
      "condition": "len({line_items}) > 0 and {item_order_id} != ''",
      "source_field": "item_order_id",
      "target_field": "item_order_id_calculated"
    }
  ]
}

Notice the len({line_items}) > 0 part of the conditions in the operations. It ensures that the operation is only applied on documents with some line items in the annotation and avoids warning about incorrect configuration when no line items are present.

2. Mapping of the document types

Of course, Rossum can recognize basic document types of documents it processes (see documentation here). However, when you are exporting the document to the target system, it might not understand the document type values that Rossum extracts, and you might want to map the Rossum values to document type codes that are defined in the target system.

In this case, we use the Value Operations extension to map the tax_invoice and credit_note document types to the required codes.

So the source field is document_type, a default enumerator (list of specific options) defined in the Rossum schema. And the target field document_type_calculated is another enumerator with the custom values corresponding to the desired document types to be exported.

Having a target field set to a line item type field (distributing mapped value to each line item field) can be achieved by two chained operations in the following order. The first operation will define the actual mapping and save the value to a hidden field. Then there has to be a second operation that will distribute the value into desired line item field.

Example:

If the tax_invoice document type is set in the document_type field, the document_type_calculated will be set to value “10“ by the extension and to value “20“ if the credit_note is set in the document_type field.

{
  "operations": [
    {
      "source_field": "document_type",
      "target_field": "document_type_calculated",
      "values_mapping": {
        "tax_invoice": "10",
        "credit_note": "20"
      }
    }
  ]
}

How to set up the Value Operations extension

Although the Value Operations extension can do many different things, setting it up takes a few simple steps.

Step 1: Prepare your queues and schemas

So first, you need to identify the queue(s) with the documents that require Value Operations. Then identify the schema IDs of the fields that the extension will use.

If you use the Dedicated Engine, create new schema fields that will store the results of the operations (see the info panel below). In case you have the Generic Engine, the extension can rewrite AI predicted value if needed.

Please remember that if you configure the function to modify the value of a specific AI-extracted field in the Dedicated Engine, the accuracy calculation will be lower than the actual accuracy. To avoid this, we do not recommend changing the AI and OCR extracted values manually or programmatically. Instead, store the modified value in new schema fields.

Step 2: Activate Value Operations in the Rossum Store

Secondly, you need to activate Value Operations, 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 “Value Operations” extension tile.
4. Click “Try extension.”

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

Once in the “Rossum Store Extension Settings,” scroll down to “Queues” and select those where you want to use the Value Operations. Please remember to save your changes once you’ve chosen the desired queues.

Step 4: Set up the operations

As a last step, you can set up the extension through the configuration field in the UI or by using the settings attribute of the hook API object. Also, the configuration is in JSON format (see the description of the available parameters below).

In this case, the configuration consists of a list of operations that can work with values from different fields in the schema, source/target field definitions, and the condition under which the extension will perform the action.

Configuration parameters

Attribute	Type	Required	Default value	Description
operations	list	yes	–	List of definitions of operations
condition	string	no	–	Python expression containing schema ids wrapped in the {}. The calculation is performed only if the condition matches (expression evaluates to True). Condition expression supports len() usage with multivalue schema fields to define condition based on number of items in the multivalue.
source_field	string	no	–	Schema ID of the field which is the source for the value (optional field). The function can work with no source, only with default values.
condition_false_source_field	string	no	–	Schema ID of the field, which is the source for the value when the condition is evaluated to false (optional field). The function can also work without any source, only with default values. The parameter has no effect if no condition is defined for the operation.
target_field	string	yes	–	Schema ID of the field to which the result of the operation will be written.
value_conversion	string	no	–	Conversion applied to the transferred value. Possible options: upper – Convert value to upper case. lower – Convert value to lower case. capitalize – Convert the first letter of each word in the value to upper case.
default_value	string/ number/ date	no	–	Default value to be put into the field when value of the source_field is empty or not defined.
condition_false_default_value	string/ number/ date	no	–	Default value to be put into the field when the value of the condition_false_source_field is empty or not defined. This parameter has no effect if no condition is defined for the operation.
values_mapping	dict	no	–	A dictionary containing a mapping of the values to be put to the target_field to the values of the source_field. If the value of the source_field equals one of the keys defined in this parameter, the value corresponding to the key is put into the target_field. If source_field has no value or if the value of the source_field is not present in the dictionary’s keys, the default_value is used. The values_mapping is not applied when the condition is evaluated to false. Only condition_false_default_value can be used in such cases. Note that mapping can only be applied to a field of the same cardinality (line item field or header field). Therefore having a header field as source_field and a line item field as target_field (or vice versa) is an invalid configuration. You can resolve the mentioned case by setting up 2 operations chained together, the first saving mapped value into a hidden field and the second distributing the value in the hidden field to line item fields.
queues	list	no	–	Queues where the operations should be applied (a subset of queues to which the extension is assigned). List of queue URLs. If not specified, the operation 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 operation applies to all queues to which the function is assigned.
allow_target_update	boolean	no	false	true – allows user update of the field filled out by the function. false – doesn’t allow user update of the field. The value will always be changed back after edit.