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
Note: This document describes the new, improved version of the Value Transformations function. You will find the documentation for the old version of this function here.
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:
- Click on the Extensions tab at the top of the app.
- Click on the Rossum store option to display all the available extensions.
- Select the “Value Transformations” extension tile.
- 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_id s | 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. |