Events and scripts

Event scripts let you add your own logic to the operator screens without changing DocView itself. A script is a short piece of JavaScript that runs when something happens while an operator works on a batch: a batch or document opens, a field gets or loses the cursor, a value changes, a button is pressed, a document is completed or the batch is released.

If you have written validation scripts in Kofax/Tungsten Capture or rules and actions in IBM Datacap, the idea is the same, but scripts here are plain JavaScript and each one is small and focused.

Where to edit event scripts

You can edit the same scripts in three places:

• The Events tab of the Batch Setup lists all of them.
• The field editor shows Scripts on this field.
• The screen designer has a Scripts panel for the document class you are designing.

Add an event script

1. Open the Batch Setup and go to the Events tab. Create a draft first if the version is released.
2. Click Add next to Batch, Document, Field or Field groups.
3. Fill in the settings:

4. Under Try it, enter field values, one per line as Name = value, and click Try.
5. Click Save events.

Click Help on the Events tab for a full reference with examples.

Events

Batch

Document

Field

Field groups (several fields together, such as net, VAT and total)

Browser or server

In the browser scripts run instantly on the operator's PC, in a sandbox without network access. They are best for BeforeFocus, LostFocus and Change: formatting values, filling one field from another, or moving the cursor.

On the server scripts run in DocView's sandbox. Use them for AfterRelease and for checks that must not be bypassed. Server Validate scripts run wherever documents are checked: after extraction, on every save and when completing. They count as validation rules, so they also stop straight-through processing when they fail.

Important: Anything a browser script checks could, in theory, be bypassed on the operator's PC. Put checks that protect your downstream systems in server scripts or in validation rules.

What a script can use

What a script returns

Examples

Field · Change (browser): upper case and no spaces

return { set: { [field.name]: (field.value || '').toUpperCase().replace(/\s+/g, '') } };

Field group · Change (browser): fill the total

if (!fields.TotalAmount && fields.NetAmount && fields.VatAmount) {
    return { set: { TotalAmount: round(num(fields.NetAmount) + num(fields.VatAmount), 2).toFixed(2) } };
}

Field · LostFocus (browser): ask for a PO number

if (field.value && !fields.PoNumber) {
    return { focus: 'PoNumber', message: 'This supplier needs a PO number.', severity: 'warning' };
}

Document · BeforeComplete (server): credit notes need a reference

if (document.className === 'credit_note' && !fields.PoNumber) {
    return 'A credit note needs the original invoice or PO reference.';
}

Batch · BeforeRelease (server): at least one document

return batch.documentCount > 0 || 'The batch has no documents.';

Form buttons with Click scripts

A Click script runs when an operator presses a button on a designed form. Buttons are added in the screen designer (Workflow tab → Design screens), and each button names the Click script it runs.

1. Add a Document script with the event Click, for the right document class.
2. In the screen designer, click Add button in a section, type the Button text and choose the script under Runs.
3. Save the form.

This Click script adds a delivery line, copies the supplier to a batch field and completes the document:

const lines = (tables.LineItems || []).concat([{ Description: 'Delivery', Quantity: '1', Amount: '25.00' }]);
return {
    set: { Currency: 'GBP' },
    setBatch: { Reference: fields.Supplier },
    setTables: { LineItems: lines },
    message: 'Delivery added.',
    action: 'complete'
};

Route the batch

A Route script decides where a batch goes after a workflow step. Normally a batch moves to the next step of the workflow. A Route script can send it somewhere else instead: a second validation step, a quality check sample, or straight to export.

Add it as a Batch script with the event Route. It always runs on the server, every time a step is completed. If you have several Route scripts, they run in order and the first one that names a step wins.

What a Route script can use

What a Route script returns

The module keys are scan, qc, recognition, classification-review, extraction, correction, index, verify and export.

If the script fails, or names a step that is not in the workflow, the error is recorded in the batch history and the batch goes to the normal next step.

Batch · Route (server): a second check when needed

After "Validation 1", batches where any document has the field NeedsSecondCheck set to Y go to "Validation 2". The others go to quality check.

if (step.completed !== 'Validation 1') return;
if (documents.some(d => d.fields.NeedsSecondCheck === 'Y')) {
    return { to: 'Validation 2', reason: 'A document needs a second check' };
}
return 'qc';

Batch · Route (server): a 10 % sample to quality check

if (step.module === 'index' && sample(10)) return 'qc';

Tip: Always check step.completed or step.module first. A Route script runs after every step, including the step it sent the batch to, so without that check it could send the batch back to the same step again and again.

Tips for reliable scripts

• Keep each script small and give it a clear name.
• Always handle empty values: (field.value || '').
• Use num() for amounts; it copes with currency symbols and thousands separators.
• Try every script with sample values before saving.
• For checks that are the same on every Batch Setup, such as a VAT check digit, prefer a ready-made validator over a script.

For a deeper guide to the scripting model, see JavaScript event scripts. For scripts that run during export, see C# export scripts.