Normalize vendor names

The same vendor often appears differently on invoices: once as “TELEKOM DEUTSCHLAND GMBH”, once as “Telekom Deutschland GmbH”. The script writes the name without its legal form, double spaces and all-capitals into a field of its own that you can search and sort by. It doesn’t change the recognized vendor itself.

The workflow

The workflow starts for every document of the type incoming-invoice. Its file workflow.yaml:

$schema: 'https://docs.acriva.de/schemas/workflow.schema.json'
format: 1
schemaVersion: 4
sdk: '1.0.0'
key: normalize-vendor-names
name: Lieferantennamen vereinheitlichen
template: custom
trigger:
  documentType: incoming-invoice
fields:
  - key: vendorShortName
    kind: text
    labelDe: Lieferant (einheitlich)
    labelEn: Vendor (normalized)
    documentTypes:
      - incoming-invoice
start: normalize
steps:
  - kind: script
    name: normalize
    label: Lieferantennamen vereinheitlichen
    script: normalize.ts
    hook: onDocumentArrived
    inputs:
      - kind: field
        key: vendorName
        type: text
    returns: []
    exits: []
    next: approve
  - kind: humanTask
    name: approve
    label: Freigabe
    taskKind: approve
    assignees:
      - when: null
        assignee:
          kind: costCenterResponsible
    fallback:
      kind: role
      role: Buchhaltung
    options:
      excludeRequester: true
      excludeActorsOfSteps: []
      pickFile: false
    next: approved
    onRejected: rejected
  - kind: end
    name: approved
    label: Freigegeben
    outcome: approved
  - kind: end
    name: rejected
    label: Zurückgewiesen
    outcome: rejected

The script normalize.ts

Hook: onDocumentArrived · Inputs: vendorName · Return values: none

import { defineScript } from '@acriva/workflow-sdk';

/**
 * A legal form at the end of a name, after a space or a comma: the combined forms (GmbH & Co. KG) come before their
 * parts, so the whole form goes.
 */
const LEGAL_FORM =
  /[\s,]+(?:(?:gmbh|ag|se|ug)\s*&\s*co\.?\s*(?:kgaa|kg|ohg)|ug\s*\(haftungsbeschränkt\)|ggmbh|gmbh|mbh|kgaa|ag|se|kg|ohg|gbr|ug|e\.\s?k\.|e\.\s?v\.|ltd\.?|inc\.?)\.?$/i;

/** "TELEKOM DEUTSCHLAND" becomes "Telekom Deutschland"; a name in mixed case keeps its spelling (such as "IBM Deutschland"). */
const capitalize = (name: string) =>
  name === name.toUpperCase()
    ? name
        .toLowerCase()
        .split(' ')
        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
        .join(' ')
    : name;

export default defineScript({
  hook: 'onDocumentArrived',
  run(ctx) {
    const vendor = ctx.document.fields.vendorName;
    if (vendor == null) return;
    // One space between words, then without the legal form, then in one way of writing.
    const spaced = vendor.replace(/\s+/g, ' ').trim();
    const withoutForm = spaced.replace(LEGAL_FORM, '').trim();
    const normalized = capitalize(withoutForm === '' ? spaced : withoutForm);
    ctx.log(`"${vendor}" becomes "${normalized}"`);
    // The standard field vendorName is Finance's: the script writes the declared field next to it.
    ctx.setField('vendorShortName', normalized);
  },
});

What it does

A test runs each of these cases in the sandbox and compares the result.

A name in capitals

• Input: vendorName TELEKOM DEUTSCHLAND GMBH
• Exit: the default next step
• Changes: field vendorShortName = Telekom Deutschland

A name with GmbH & Co. KG and double spaces

• Input: vendorName Bürobedarf Schmidt GmbH & Co. KG
• Exit: the default next step
• Changes: field vendorShortName = Bürobedarf Schmidt

An invoice without a vendor

• Input: vendorName null
• Exit: the default next step
• Changes: none