Skip to main content

Statement Extension Configuration

When configuring your Rossum Extension there are a few options you can tweak to adjust the statement matching flow to better suit your organisation. These configuration options are set in the extension settings via your Rossum UI.

These should be written in JSON format.

info

Most parameters here are optional, with the exception of statementDocumentType and erpVersion. If any other parameters are not specified then we will use our defaults.

Parameter Definitions and Usage​

System Setup​

clientId​

string

{ "clientId": "ABC" }

If specified ALL ERP-queries will be restricted to this client ID.

if not specified, we will attempt to read this per-document from the data in the Rossum UI. If that is not specified then some attempt will be made to determine the client ID from the uncovered PO details.

Most subsequent lookups will fail if we cannot determine a client ID and so we recommend specifying this in the config wherever possible as it makes a big difference to the system reliability.

erpVersion​

'erpx' | 'erp7' | 'erpcr'

{ "erpVersion": "erp7" }

The ERP version, this is important so we know what endpoints to use to retrieve data from and send data to.

  • ERPx Unit4's ERPx system
  • ERPCR Unit4's ERP CR system, you are likely on this system if you are using Unit4 cloud.
  • ERP7 This is most likely the version you are on if your servers are not hosted by Unit4.

locale​

'en' | 'no' | 'sv' | 'es' | 'fr' | 'cy'

{ "locale": "en" }

Only these exact strings will be accepted as valid locales. If not specified, we will use en

Some messages may not be translated, as we need to decode and validate the event before we can use the locale. So if we fail prior to that, error messages will be in English.

erpHeaders​

Record<string, string>

{
    "erpHeaders": {
        "X-ACME-RequestOrigin": "ERP Apps OCR",
        "X-ACME-UUID": "0c12f153-36f7-4b76-962c-e97c82a491e8"
    }
}

If set we will forward these headers along to the ERP system.

This may be useful, for example, if you have a self hosted ERP system to which you wish to control access.

You can use this to set a pre-defined header which can be used on a load balancer or reverse proxy to control access to the ERP system.

If a request is made to the ERP system without this header, it can be rejected by the load balancer or reverse proxy without hitting the server itself.

You may also wish to use this for analytics or logging purposes.

attachMessagesDocument​

none | warning | all

{ "attachMessagesDocument": "all" }

Which messages should be attached to the transaction in ERP as a secondary document. (This will be attached as zzzz_messages....) These are copies of the messages we send to the Rossum UI, so that ERP users have long-term access to the same messages.

  • none will never attach messages.
  • warning will attach messages of warning-level or above.
  • all will attach all messages including info

If not specified, the default behaviour is all.

statementDocumentType​

{ "statementDocumentType": "STATREP" }

The document type that the report will be written back to. Must be a valid document type attached to supplier.

statementReportFormat​

**pdf | spreadsheet | both **

{ "statementReportFormat": "pdf" }

The format that the report will be written back in. If not set, the system will set this to pdf.

ERP Connection Configuration​

warning

Note that these connection settings can now be set in extension secrets (where they were historically) OR here in settings (for better visibility).

If any of these values are set in both places, the one here in settings will take precedence.

erpConnectionSettings​

{ unit4ApiUrl?: string, unit4SoapUrl?: string, erpxHost?: string, erpIdsHost?: string

{
    "erpConnectionSettings" :{
    "unit4ApiUrl": "https://example.unit4cloud.com",
    "unit4SoapUrl": "https://example.unit4cloud.com",
    "erpxHost": "https://example.unit4cloud.com",
    "erpIdsHost": "https://example.unit4cloud.com"
    }
}

unit4ApiUrl and unit4SoapUrl are required for ERP7 / ERPCR systems.

erpxHost is required on an ERPx system

erpIdsHost is required on any system using IDS for authentication.

Document Processing​

elevateWarnings​

string[]

{ "elevateWarnings": ["SM_004"] }

An array of codes which usually generate warnings, but the organisation wishes to elevate to errors.

Adding items in here will cause the schema field override_warnings to error if there are warning messages present which are in the elevated list. For more information please see the warnings documentation

Please see the list of warnings that can be elevated

Matching Configuration​

The matching configuration are the rules by which the lines from the statement can be matched to the supplier transactions

The rules are defined as matchCodes and the matchCodes are then defined in a matchSequence

This allows you to create a hierarchy of matching options from most controlled to least controlled in order to try and get a match.

Match sequences can also be applied to a specific apar id in the case that a particular supplier / customer needs some specific matching logic

There are a couple of system level settings which can be useful to reduce the amount of data that the system is having to retrieve:

maxHistoricalDays​

number

{ "maxHistoricalDays": 180 }

How many days to pull from historical invoices matchedSupplierInvoices (C status) based on the invoiceDate from the API. Note registeredItems (A status) and unmatchedSupplierInvoices (B status) invoices are always pulled.

If this value is not set, it will default to 180.

ignoreTransactionTypes​

string[]

{ "ignoreTransactionTypes": ["MM","SM"] }

These transaction types will be excluded from the API request. This should be filled in with any transaction types you do not wish to match to the statement lines.

validSupplierStatus​

string[]

{ "validSupplierStatus": ["N","P","C","T"] }

If this setting is not set in the configuration, our default filter of status = N will be applied

Some customers have requested that non-active suppliers be matched in the OCR, but an error raised if this is the case. E.g. they wish to know the supplier exists and was the best match, but that it is closed.

To avoid changing our original behaviour, this new status allows you to set valid status for suppliers which will be used when retrieving suppliers from the ERP API.

You may receive error SU_017 if the supplier is not at N or P status and warning SU_018 if the supplier is at P status. SU_018 can also be elevated to an error.

matchCodes​

{ "matchCodes" : [{ "matchCodeId" : "CODE1",
  "description" : "Default code",
  "amountTolerance" : 1,
  "invNo" : "withinAny",
  "transDate" : "either",
  "toleranceDays" : 7,
  "historicDays" : 180,
  "cleanText" : "SIN-|INV|INV #|A/R Invoices -|SI[rx]^00"
  }]
}

These are the rules by which the lines from the statement can be matched to the supplier transactions.

The above example can be used as the default setup on your system and covers the most common matching scenarios

They are made up of the following properties

matchCodeId​

string

{ "matchCodeId" : "CODE1"}

A unique code for the match, this MUST be unique in your configuration and the system will throw a QSET_006 error if they are not.

description​

string | null

{ "description" : "Optional Description"}

Freetext description to help document what the code is for.

amountTolerance​

number

{ "amountTolerance" : 0.01}

the absolute allowable difference between the statement amount and the transaction amount. This will be checked to the transactions currency amount.

If not set, this will default to 0.01

invNo​

off | withinAny | exactAny | withinInvoiceNumber | exactInvoiceNumber

{ "invNo" : "off"}

Used to control how statement invoice references are matched to transaction invoice references. Possible options are:

  • off: Ignore: only use date and amount
  • withinAny: ERP Invoice number (ext inv ref) must be WITHIN any field (Int / Trans number, description, reference)
  • exactAny: Match ERP Invoice number (ext inv ref) to any statement field (Int / Trans number, description, reference)
  • withinInvoiceNumber: Statement Inv / Trans number must be WITHIN ERP Invoice Number (ext inv ref)
  • exactInvoiceNumber: Statement Inv / Trans number must match ERP Invoice Number (ext inv ref)

If not set, this will default to off

transDate​

either | voucherDate | transDate

{ "transDate" : "either"}

Used to define which ERP field to match the statement transaction date to.

Possible options are:

  • either: Try either date
  • voucherDate: Use voucher date
  • transDate: Use trans date

If not set, this will default to either

toleranceDays​

number

{ "toleranceDays" : 7}

Linked to the trans date, defines how many days difference there can be between the statement date from field and the date field(s) defined by the above Trans Date setting.

If not set, this will default to 0

historicDays​

number

{ "historicDays" : 180}

The number of days for which matchedSupplierInvoices (status C transactions) should be loaded, note if this field is set to 0 then the queue level value maxhistoricaldays will be used.

Any other value will over-ride the system setup value but please note this value can not be MORE than the system setup value.

cleanText​

string | null

{ "cleanText" : "SIN-|INV|INV #|A/R Invoices -|SI|[rx]^00"}

Thus works in combination with the Inv No setting above.

These can be used to clean specific text out of statement fields (Invoice Number, Reference, Description) to improve matching against transactions.

For example a supplier may add some specific text to an invoice number to the statement but not on the original invoice. This should be a pipe separated list of values and you may also use regular expressions in this field which should be preceded with [rx] so we know it is a regular expression.

Please note that regular expressions are "pre-cleaned" for security so if you find a particular pattern that does not work then please let us know via the usual support channels.

Regex patterns may also not use the pipe | symbol as this is the separator for the list, if you need this then please let us know via the usual support channels.

In the given example if our statement invoice number had any of the following formats:

  • SIN-1234599A
  • INV1234599A
  • 1234599AINV
  • INV #1234599A
  • A/R Invoices -1234599A
  • SI1234599A
  • 001234599A

It would be matched to the ERP transaction with the (Invoice Number, Reference, Description) set as 1234599A

matchSequences​

These are used to group match codes and tell the system which order to run them in.

This allows you to create a hierarchy of matching options from most controlled to least controlled in order to try and get a match.

{"matchSequences" : [{ "matchSequenceId" : "RUN1",
  "description" : "Default sequence",
  "supplierId" : null,
   "matchingConfiguration": [
        {
            "matchOrder": 1,
            "matchCodeId": "CODE1"
        },
        {
            "matchOrder": 2,
            "matchCodeId": "CODE2"
        }
    ]
  }]
}

matchSequenceId​

string

{ "matchSequenceId" : "RUN1"}

A unique code for the sequence, this MUST be unique in your configuration and the system will throw a QSET_007 error if they are not.

description​

string | null

{ "description" : "Optional Description"}

Freetext description to help document what the code is for.

supplierId​

string

{ "supplierId" : "12399"}

If included this match sequence will only run when the statement is matched to the set supplier id.

If not included the match sequence will run against all suppliers.

matchingConfiguration​

{  "matchingConfiguration": [
        {
            "matchOrder": 1,
            "matchCodeId": "CODE1"
        },
        {
            "matchOrder": 2,
            "matchCodeId": "CODE2"
        }
    ]
  }

Is an array of objects with each object containing:

matchOrder​

number

{ "matchOrder" : "12399"}

The order in which the included match code should be run in the sequence.

matchCodeId​

string

{ "matchCodeId" : "12399"}

A valid match code id to be used. The system will throw a QSET_010 error error if the included match code has not been defined in the match codes setting.

Caching​

cacheTime​

number

{ "cacheTime": 3600 }

If no value is given, the default of 3600 seconds (one hour) will be applied.

The amount of time (in seconds) that data (such as suppliers, purchase orders, accounting information) from Unit4 will be held by the cache. The longer this is, the fewer API requests need to be made and the faster the service will run. The offset against a longer cache time is that data will take longer to "appear" in the OCR system.

cacheSuffix​

string

{ "cacheSuffix": "custom-suffix" }

A random string which can be applied to the end of the cache keys in the system. If no value is supplied then default is used. You may wish to define a value in here to force a cache refresh in the system sooner than your cacheTime. Any time this value is changed, old cached values will no longer be used and data will be retrieved fresh. It should not be necessary to do this regularly, doing so may indicate your cacheTime is too long.

testExtensionSettings​

Please see the test extension documentation

Example Configuration​

As JSON syntax and the type definitions used above may not be familiar to everyone, here is an example configuration.

warning

This MUST be edited / reduced to only the keys and options which you require.

{
 "clientId": "ABC",
 "erpVersion": "erp7",
 "locale": "en",
 "attachMessagesDocument": "all",
"erpConnectionSettings" :{
    "unit4ApiUrl": "https://example.unit4cloud.com",
    "unit4SoapUrl": "https://example.unit4cloud.com",
    "erpxHost": "https://example.unit4cloud.com",
    "erpIdsHost": "https://example.unit4cloud.com"
    },
 "statementDocumentType": "STATREP",
 "statementReportFormat": "pdf",
 "elevateWarnings": ["SM_004"],
 "maxHistoricalDays": 180,
 "ignoreTransactionTypes": ["MM","SM"],
 "validSupplierStatus": ["N","P","C","T"],
 "matchCodes" : [
    { "matchCodeId" : "CODE1",
  "description" : "Default code",
  "amountTolerance" : 1,
  "invNo" : "withinAny",
  "transDate" : "either",
  "toleranceDays" : 7,
  "historicDays" : 180,
  "cleanText" : "SIN-|INV|INV #|A/R Invoices -|SI[rx]^00"
  }
  ],
"matchSequences" : [{ "matchSequenceId" : "RUN1",
  "description" : "Default sequence",
  "supplierId" : null,
   "matchingConfiguration": [
        {
            "matchOrder": 1,
            "matchCodeId": "CODE1"
        }
    ]
  }
  ],

"cacheTime": 3600,
"cacheSuffix": "custom-suffix"
}