This feature is available in our Business plan and all higher tiers for new customers. Existing customers who are interested in accessing this feature should reach out to our support team for assistance – support@rossum.ai
Formula fields in Rossum let you easily transform your data right within the app. You can create formulas to set field values, whether it’s for normalizing data, performing calculations, or doing text operations. This guide will show you how to get the most out of this feature. You will learn the basics of using formula fields, including how to use the recommended Copilot method and how to manually define the logic with code.
How to create a formula field
To add formula fields in your queue, use the schema editor in the “Fields” tab of your queue settings.
Click on “Settings” in the queue, then go to the “Fields” section.
Select “Add Field”.
In the field properties, set the “Value source” to “Formula”. You can also specify whether users should be able to edit the value calculated or added by the formula. We recommend keeping editing disabled. For more details, click here.
Enter a label and ID of your field.
Ask Copilot to help you create your formula, or add it manually.
Click “Save” to create the field.
How to use the Copilot
Copilot can help you create your formula based on the instructions you give it. Just click the “Copilot edit” button to start. A box will appear where you can describe what you want to do in plain language.
For example, you might type, “Remove any spaces from the IBAN.”
Copilot will then generate the rule and the right code for you based on your description. You can check the code by clicking on “Show source code” button.
If you need to change your formula, you can open Copilot and ask for help again. Copilot will take your feedback and update the formula accordingly—like a virtual assistant that makes all the necessary adjustments. There’s no need to rebuild the entire formula from scratch.
You can also edit the code.
Any changes you make (even if you edit the code directly) will show up in the visual representation of the rule on the purple background.
How to write Copilot prompts
Describe the complete transformation, covering all the details you need.
Be clear and concise. Make sure your instructions are specific and easy to understand.
If the transformation depends on certain conditions, state them clearly. For example, you could say, “If the total amount is greater than 20000, apply a 20% discount; otherwise, no discount.”
How to test your formula
In the “Formula” section, click the “Test formula” button to see how the transformation works on your documents.
In the table, the first column (green text) shows the results of your transformation on the latest documents in your queue.
The table also displays the actual document values for all relevant fields and includes a link to each document in the right column.
Check the preview to make sure your formula works as expected. Adjust the formula if needed.
If used, info, warning, and error messages will also appear in the table.
To see results for more documents, click the “Show more” button in the bottom-right corner.
How to create a formula manually
If you prefer to write the transformation logic manually, you can do so and still use our preview for testing. Go to the “Formula” and create your formula directly there.
Rossum formulas use TxScript that is based on Python, in addition including a variety of additional predefined functions and variables. More information here.
You can refer to any fields in the queue using field.SCHEMA_ID_OF_THE_FIELD, such as field.iban.
Make sure the last line of your code represents the desired output.
Formula code that can be used in example we mentioned before – if the total amount is greater than 20000, apply a 20% discount; otherwise, no discount:
field.total_amount * 0.2 if field.total_amount > 20000 else field.total_amount
For additional examples, explore this comprehensive guide.
Editing value of a formula field
Like other fields, you can choose whether users can edit the value of the formula field manually. When normal, the icon is the classic one:
If editing is allowed and a user changes the value, the formula field marker will change, now with a pencil icon appearing next to it.
When edited:
The calculation for that field stops. Even if the source field changes, the manual value will stay the same.
If there are other formula fields or extensions using the edited field as a source, they will treat the manually added value as correct and use it.
You can restart calculations for the edited formula field by hovering over the formula symbol, revealing 3 dots, and clicking in them. You will see the option to “Restore value”. This will reset the edited value to its original state and resume calculations for the field.
If editing is allowed and a user makes changes but doesn’t confirm the document (leaving it in ‘to_review’ status), and then editing is disabled in the field configuration, the manually changed values will go back to the values calculated by the formula.
We recommend disabling editing for formula fields, unless it’s needed for testing. It’s better to adjust the transformation logic instead of allowing users to edit the value.