File by a field

After the approval, the script files an incoming invoice into its vendor’s file, which it finds by the vendor number. Without a number, it notifies accounting to file the invoice by hand. The workflow adds the vendor number field itself. With a card it needs no script: File into the vendor’s file finds the file by a unique key field and creates a missing one.

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: file-by-field
name: In Akte nach Feld ablegen
template: custom
trigger:
  documentType: incoming-invoice
fields:
  - key: vendorNumber
    kind: text
    labelDe: Lieferantennummer
    labelEn: Vendor number
    documentTypes:
      - incoming-invoice
start: approve
steps:
  - 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: file
    onRejected: rejected
  - kind: script
    name: file
    label: In die Lieferantenakte ablegen
    script: file.ts
    hook: onApproved
    inputs:
      - kind: field
        key: vendorNumber
        type: text
      - kind: field
        key: invoiceNumber
        type: text
    returns: []
    exits: []
    next: approved
  - kind: end
    name: approved
    label: Freigegeben
    outcome: approved
  - kind: end
    name: rejected
    label: Zurückgewiesen
    outcome: rejected

The script file.ts

Hook: onApproved · Inputs: vendorNumber, invoiceNumber · Return values: none

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

export default defineScript({
  hook: 'onApproved',
  run(ctx) {
    const { vendorNumber, invoiceNumber } = ctx.document.fields;
    const number = vendorNumber?.trim();
    if (!number) {
      ctx.notify({
        to: [{ role: 'Buchhaltung' }],
        text: `Die freigegebene Rechnung ${invoiceNumber ?? 'ohne Nummer'} hat keine Lieferantennummer. Bitte legen Sie sie von Hand in die Akte des Lieferanten.`,
      });
      return;
    }
    // Already in the vendor's Akte, for example filed by hand: nothing to do.
    if (ctx.document.files.some((file) => file.type === 'vendor' && file.number === number)) return;
    ctx.fileInto({ type: 'vendor', number });
  },
});

What it does

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

An invoice already in the file

• Input: vendorNumber 70012, invoiceNumber RE-2026-1034, last task outcome Approved
• Exit: the default next step
• Changes: none

An invoice without a vendor number

• Input: vendorNumber null, invoiceNumber RE-2026-1035, last task outcome Approved
• Exit: the default next step
• Changes: notification to the role Buchhaltung: “Die freigegebene Rechnung RE-2026-1035 hat keine Lieferantennummer. Bitte legen Sie sie von Hand in die Akte des Lieferanten.”

An invoice with a vendor number

• Input: vendorNumber 70012, invoiceNumber RE-2026-1033, last task outcome Approved
• Exit: the default next step
• Changes: filed into the file vendor 70012