Skip to main content

Rossum Formulas

This section covers both the Rossum Formula Fields and the Serverless Functions (Formula Fields flavor in custom extensions).

Installation​

Formula Fields or Serverless Functions do not require any installation. They are both available as a native Rossum functionality.

Formula Fields are available in the queue schema as a formula field type. In serverless functions, you can import TxScript library which is a wrapper introducing the same functionality into serverless functions. Both flavors are fundamentally similar and differ only in how they are used with minimal syntax differences.

In case you want to use the TxScript within pre-existing serverless functions, you need to enable following setting:

  1. Go to the settings of the Webhook (Serverless function)
  2. Scroll to Additional notification metadata
  3. Enable the Schemas option
  4. Save it, and now you can work with the TxScript in your serverless function

Basic usage​

To start with Formula Fields, follow these steps:

  1. Create a new order_id_normalized field in the queue schema.
  2. Select the formula field type of the field.
  3. Write the formula in the formula field.

Your first formula can be as simple as (no returns, no imports):

field.order_id

This formula copies the order_id field into your newly created Formula Field.

Alternatively, you can create a new serverless (Python) function with the following boilerplate code that does the same thing:

from txscript import TxScript

def rossum_hook_request_handler(payload):
    t = TxScript.from_payload(payload)

    t.field.order_id_normalized = t.field.order_id  # Copies `order_id` value into `order_id_normalized`

    return t.hook_response()

Notice that it is a little bit more verbose, but it is still very similar. The main differences are that we need to wrap the functionality into rossum_hook_request_handler function and that we need to explicitly write into the order_id_normalized field.

This is an illustrative example. In case you only need to modify an existing field value, always prefer making it a formula field.

For backward compatibility, you can also use the following import which works the same way as TxScript:

from rossum_python import RossumPython

# …

Available functions and features​

Here is a list of available functions and features and their comparison between Formula Fields and Serverless Functions. Note that serverless functions examples always assume that the code is wrapped in rossum_hook_request_handler function like so:

from txscript import TxScript

def rossum_hook_request_handler(payload):
    t = TxScript.from_payload(payload)

    # INSERT THE EXAMPLES HERE

    return t.hook_response()

Formula field examples do not require any further modification.

Working with datapoints​

Getting values (or meta information):

field.amount                            # Get datapoint value
field.amount.id                         # Get datapoint system ID
field.amount.attr.rir_confidence        # Get confidence score
field.amount.attr.ocr_raw_text          # Get raw value extracted by OCR, if applicable
field.amount.attr.rir_raw_text          # Get raw extracted text by RIR
warning

Formula fields cannot write into any other fields. They simply return the value into the formula field itself.

Working with annotation data​

annotation.id                                       # Get annotation ID
annotation.metadata                                 # Get annotation metadata
annotation.document.original_file_name              # Get document original file name
annotation.email.subject                            # Get email subject

Check whether datapoint is set or not​

is_set(field.amount)        # Returns `true` if datapoint is set (has value)
is_empty(field.amount)      # Opposite of `is_set`

Defaulting values​

Use the default value if the field is empty.

default_to(field.amount, 0)

Substitute​

Substitute is an alias for re.sub function (for convenience).

substitute(r"[^0-9]", r"", field.document_id)  # Remove non-digit characters

Could also be written as (re is imported automatically):

re.sub(r"[^0-9]", r"", field.document_id)

Show info/warning/error messages​

note

Messages do not affect the automation behavior and, therefore, automation blockers must be set explicitly (see how to set automation blockers). The only exception is show_error which always blocks the automation.

show_info("…")                          # Show global info message
show_info("…", field.amount)            # Show info message on the specified field

show_warning("…")                       # Show global warning message
show_warning("…", field.amount)         # Show warning message on the specified field

show_error("…")                         # Show global error message
show_error("…", field.amount)           # Show error message on the specified field

Set automation blockers​

note

Automation blockers must be set independently of the info/warning messages. Error messages block the automation by default (cannot be disabled).

automation_blocker("message", field.amount)

Create multivalue field values​

warning

Multivalue formula fields are currently not supported (only serverless functions).

Create enum field options​

warning

Changing enum field options is currently not supported in formula fields (only serverless functions).