Skip to main content

Extension Configuration

When configuring your Rossum Extension there are a few options you can tweak to adjust the invoice 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 invoiceDocumentTypes and erpVersion. If any other parameters are not specified then we will use our defaults.

The only other exception to this is the ei02Variant which is required IF you are using the ERP7 / ERPCR version of the connector.

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.

transactionType​

string

{ "transactionType": "T1" }

This is the ERP Transaction Type code which we will pass through to your ERP when submitting the invoice, either directly in the JSON for ERPx or as the incoming invoice transaction type parameter on the EI02 for ERP7 / CR

ei02Variant​

number

{ "ei02Variant": 0 }

This is required for milestone seven, this is the EI02 report variant which will be run when the invoice is posted.

invoiceDocumentTypes:​

string[]

{ "invoiceDocumentTypes": ["IINV", "XYZ"] }

This is the list of document types that we will accept as invoices. If there is only one type we will enforce it, if not we will use the first as a default but allow the user to change it in the UI.

For fully-automated processes, this means that the docType will ALWAYS be the first in the list. If you require manual control, ensure that automatic processing is disabled.

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.

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"
    }
}

Document Processing​

manualTaxCodeIds​

string[]

{ "manualTaxCodeIds": ["0", "1", "11"] }

If specified we will restrict tax-codes for non-PO lines (AP / extra PO lines / non PO invoice lines) to only those listed here.

Invoice lines matched to a purchase order line will still use the tax-codes from the purchase order as specified.

allowedTaxRates​

number[]

{ "allowedTaxRates": [0.2, 0.05] }

If specified we will restrict tax-rates to only those listed here. If we round near to one of these, we will "snap" to it. If we round to a rate not in this list we will ignore it and assume it's an OCR or invoice error.

noPurchaseOrder​

{ base: 'allow' | 'reject'; perSupplier: 'allow' | 'reject' | null; }

{
    "noPurchaseOrder": {
        "base": "allow",
        "perSupplier": "supppoctrl/no_po_no_pay_fx"
    }
}

This is used to determine if we can raise invoices without PO. If base is 'reject' then we will reject any invoice without a PO. If base is 'allow' then we will allow invoices without a PO.

If perSupplier is specified, we will look for a customField (flexifield) on the supplier and if found we will treat the value as the base value for that supplier. This value should be either allow or reject (or not present) so the flexifield should be configured with these options An example value for the perSupplier field would be something like supppoctrl/no_po_no_pay_fx If not found, we will use the base value.

apDefaultDims​

{ dim1?: string|number, dim3?: string|number, dim3?: string|number, dim4?: string|number, dim5?: string|number, dim6?: string|number, dim7?: string|number }

{
   "apDefaultDims": {
        "dim1": 3000,
        "dim2": "ABC",
        "dim4": "Custom value"
   }
}

We use these defaults to enable automated submission.

On the AP line, we pull account from the supplier group and then fill in any valid dimensions with the dimensions from here.

If not provided these will need to be filled manually in the UI.

glDefaultDims​

{ account?: string, dim1?: string|number, dim3?: string|number, dim3?: string|number, dim4?: string|number, dim5?: string|number, dim6?: string|number, dim7?: string|number }

{
    "glDefaultDims": {
        "dim1": 3001,
        "dim2": "ABC",
        "dim6": "Custom value",
        "account": "3000"
    }
}

For invoices without a PO, we will use these defaults to enable automated submission.

If not provided these will need to be filled manually in the UI.

defaultQuantity​

number

{ "defaultQuantity": 1 }

If we can't read a quantity for a line item we will fall back to this value.

defaultSupplierId​

string

{ "defaultSupplierId": "1000" }

If we can't determine a supplier we will fall back to this value.

Before using this we will check the purchase order for a supplier, then search the company-number, vat-number fields and bank details for a supplier. If we can match on any of those, we will. If not we will use this value when set.

defaultAccountable​

string

{ "defaultAccountable": "101" }

We try to match the active Rossum user to an ERP user. If successful we will set that ERP-user to be the accountable person for this invoice.

If we do not succeed in matching the user, we will fall back to this value when set.

This value will eventually appear in the ext_ref field on the invoice transaction

ignoreTax​

boolean

{ "ignoreTax": false }

This one makes no major changes to the UI, but when submitting the invoice to ERP we will only submit gross values and set all the tax to zero.

This is a rarely used setting for special types of organisation who never handle VAT or other tax rates and only manage gross values internally. We maintain the tax in the UI even when set to ensure that the invoice lines balance to the header, but we will not submit the tax to ERP.

ignoreZeroRows​

boolean

{ "ignoreZeroRows": true }

If true a zero-row should will show an info notice, but then be filtered out before sending to ERP.

If false a zero-row will show an error and block submission until manually corrected in the UI.

ignoreDueDate​

boolean

{ "ignoreDueDate": true }

Ignore the due date on the invoice and allow Unit4 to calculate it using standard setup.

firstLineAsDescription​

boolean

{ "firstLineAsDescription": true }

If set to true, the first invoice line description will be used as the overall invoice description (this is the description on the AP line). If not present or false, a timestamp will be entered as the description.

payRecipientCheck​

boolean

{ "payRecipientCheck": true }

If this is set to true the system will flag an INFO message against the matched supplier, if a pay recipient (Factor company) is identified as set on the supplier record. This will be upgraded to a WARNING message if the pay recipient is not status N.

payRecipientBankCheck​

boolean

{ "payRecipientBankCheck": true }

If this is set to true, the system will match the bank details AND currency from the invoice to those from the pay-recipient (instead of those on the supplier masterfile).

Caching​

cacheTime​

number

{ "cacheTime": true }

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": true }

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.

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",
    "erpConnectionSettings" :{
        "unit4ApiUrl": "https://example.unit4cloud.com",
        "unit4SoapUrl": "https://example.unit4cloud.com" ,
        "erpxHost": "https://example.unit4cloud.com",
        "erpIdsHost": "https://example.unit4cloud.com"
    },
    "transactionType": "T1",
    "ei02Variant": 0,
    "invoiceDocumentTypes": ["IINV", "XYZ"],
    "manualTaxCodeIds": ["0", "1", "11"],
    "allowedTaxRates": [0.2, 0.05],
    "noPurchaseOrder": {
        "base": "allow",
        "perSupplier": "xocrconfig/nopurchaseorder"
    },
    "apDefaultDims": {
        "dim1": 3000,
        "dim2": "ABC",
        "dim4": "Custom value"
    },
    "glDefaultDims": {
        "dim1": 3001,
        "dim2": "ABC",
        "dim6": "Custom value",
        "account": "3000"
    },
    "defaultQuantity": 1,
    "defaultSupplierId": "1000",
    "defaultAccountable": "101",
    "payRecipientCheck" : true,
    "payRecipientBankCheck" : true,
    "ignoreTax": false,
    "ignoreZeroRows": true,
    "ignoreDueDate": true,
    "firstLineAsDescription": true,
    "cacheTime": 3600,
    "cacheSuffix": "",
    "locale": "en",
    "erpHeaders": {
        "X-ACME-RequestOrigin": "ERP Apps OCR",
        "X-ACME-UUID": "0c12f153-36f7-4b76-962c-e97c82a491e8"
    }
}