From this article you will learn:

• What is a Rossum Value Transformations extension
• Common use case configurations for Value Transformations
• How to set up Value Transformations extension
• What are the available configuration parameters

What is a Rossum Value Transformations extension

Values on documents are often not in the desired format or may contain unwanted characters such as spaces, commas, colons, etc. Given this, you might want to convert the AI-extracted values rather than using the original ones from the document. The most common example is removing non-alphanumerical characters from values such as the VAT, IBAN, and account number.

This function can help with this process by providing powerful, configurable string manipulation options that use regular expressions to replace selected string patterns automatically. Please remember that this extension cannot perform any arithmetic or date operations.

Advanced users can also chain defined transformations to cover more complex cases when one regular expression is insufficient. They can also chain multiple actions where the results of one are projected into the input of another. However, you don’t have to have the advanced technical expertise to use the function.

Common use case configurations for Value Transformations

You may find it difficult to define transformation rules simply by using the description of the available parameters. That’s why we prepared some configuration examples you can copy and modify for an easier time setting up the extension.

Please note that backslashes in regular expressions must be escaped (doubled) in the extension configuration of the Rossum UI. The example configuration below already contains escaped regular expressions. Also, you need to enclose any string in action condition expression in single quotes (see examples for more details).

The examples below demonstrate only a subset of the capabilities of regular expressions and Python expressions used by this extension to define transformations and conditions. You can find complete documentation of Python regular expressions here, and expression documentation is available here.

1. Removal of non-alphanumeric characters

The Value Transformations extension with the configuration below removes all non-alphanumeric characters from the Vendor VAT Number and IBAN fields.

Example:

• Input: DE 12345-6789
• Output: DE123456789

{
  "actions": [
    {
      "transformations": [
        {
          "pattern_to_replace": "[^a-zA-Z\\d]",
          "value_to_replace_with": "",
          "replace_if_this_pattern_matches": "[^a-zA-Z\\d]"
        }
      ],
      "source_target_mappings": [
        {
          "source": "sender_vat_id",
          "target": "sender_vat_id_normalized"
        },
        {
          "source": "iban",
          "target": "iban_normalized"
        }
      ]
    }
  ]
}

2. Extracting and normalizing part of the line item description

This configuration uses two chained transformations to extract and normalize item code from the item description.

The first transformation removes everything after the first space character in the string. The second one removes all hyphens from the result of the first transformation.

Notice also that there is an action condition defined in this configuration. The function will perform this action only when the Vendor Name is “Great Company “. The condition is optional.

Example:

• Input: 1234-567-89 This is a line item description with the code at the beginning.
• Output: 123456789

{
  "actions": [
    {
      "transformations": [
        {
          "pattern_to_replace": " ([\\s\\S]*)$",
          "value_to_replace_with": "",
          "replace_if_this_pattern_matches": " ([\\s\\S]*)$"
        },
        {
          "pattern_to_replace": "-",
          "value_to_replace_with": "",
          "replace_if_this_pattern_matches": "-"
        }
      ],      
      "action_condition": "{sender_name} == 'Great Company'",
      "source_target_mappings": [
        {
          "source": "item_description",
          "target": "item_code"
        }
      ]
    }
  ]
}

3. Copying item code to another field for specific line items

This configuration uses an action condition to check if the document_type header field has the value ‘tax_invoice’ and checks all line items if attribute item_code is either ‘M0061’ or ‘M0062’. The transformation is applied to line items that meet this condition.
Then the transformation removes all characters different than numerical characters and stores the transformed values in a separate field called item_other for each matched line item.

Example:

• Input: ‘tax_invoice’ and [M006, M0062]
• Output: [0061, 0062]

{
  "actions": [
      {
        "queue_ids": ["123"],
        "action_condition": "{document_type} == 'tax_invoice' and {item_code} in ['M0061','M0062']",
        "transformations": [
            {
             "pattern_to_replace": "[^0-9]",
             "value_to_replace_with": "",
             "replace_if_this_pattern_matches": ".+",
            }
         ],
         "source_target_mappings": [
            {
             "source": "item_code",
             "target": "item_other"
            }
         ]
      }
   ]
}

How to set up Value Transformations

Setting up the extension itself takes a few simple steps:

Step 1: Prepare your queues and schemas

To begin, you must identify the queue(s) that have the documents that require Value Transformations. After that, find the schema IDs of the fields that will contain the extracted values set that the function will change.

If you’re using the Dedicated Engine, add new schema fields to store the results of the transformations (see the info panel below). If you have the Generic Engine, set up the function to modify the field’s value “in-place” (same source and target field).

Please keep in mind that if you use the Dedicated Engine and configure the extension to change the value of a specific field, the results of the accuracy calculation for that field will be significantly lower than the real accuracy. When using the Dedicated Engine, it is not recommended to manually or programmatically modify the values extracted by the AI and OCR.

Step 2: Activate Value Transformations in the Rossum Store

To enable Document Splitting, 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 Transformations” 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 the queue(s) in which you want to use the Value Transformations. Please remember to save your changes once you’ve chosen the desired queues.

Step 4: Set up the actions and transformations

You can set up the function through the Configuration field in the UI or by using the settings attribute of the hook API object. The configuration is in JSON format (see the description of the available parameters below).

This configuration consists of a list of actions that can work with values from different fields in the schema. Each action has a set of transformations, source/target field definitions, and the condition under which the action will be performed.

You can copy and paste the code from the examples above if there is a matching use case. Then, the only thing left to do is replace the fields whose values the function will change.

What are the available configuration parameters

Below you will find the complete list of available settings parameters.

Root	Param name	Description
	actions	List of actions to be performed. See a description of the action parameters below.
actions	source_target_mappings	List of source and target field schema IDs.
source_target_mappings	source	Source schema_id of the initial value to be transformed.
source_target_mappings	target	Target field’s schema_id where the extension will store the transformed value.
actions	transformations	List of transformations to perform on the value of the source field. See a description of the transformation parameters below.
actions	queue_ids	Queue IDs where the extension should perform the particular action. You can assign the extension to multiple queues and specify numerous actions for different queues in one instance. It’s optional. If not present, the extension will act on all the queues to which it is assigned unless excluded_queue_ids is set.
actions	excluded_queue_ids	Queue IDs where the function won’t perform the action. This parameter cannot be set along with queue_ids. It’s optional.
actions	action_condition	Condition’s definition for a particular action. Condition needs to evaluate to bool (True or False). When defined, the action will be evaluated. If True, the extension will apply the action’s transformation; otherwise, it won’t. It’s a Python condition where schema fields are referenced by their schema_id enclosed in {}. Example: {item_code} != '' and {document_type} == 'invoice' Python expressions documentation.
actions	additional_user_update_trigger	Additional list of schema_ids that will trigger the action if a user modified a field with such name.
actions	allow_target_update	If set to true, it prevents the action from overwriting the target value when the user updates it manually. Default false.
transformations	pattern_to_replace	The regular expression defines a pattern in the value to be found and replaced. Python regular expressions.
transformations	value_to_replace_with	This value will replace all pattern occurrences matching the regular expression defined in the pattern_to_replace parameter.
transformations	replace_if_this_pattern_matches	Regular expression defines the condition for a transformation to be applied. Extension will apply the transformation if the value matches the expression. Python regular expressions.