Breadcrumbs

2 · Setup and Configuration

Installation

Ventoo Address Validation is an extension for Microsoft Dynamics 365 Business Central (SaaS, BC 28 / runtime 17.0).

  1. Install the app from the AppSource marketplace or upload the .app file via Extension Management › Manage › Upload Extension.

  2. After installation the app automatically creates the setup record with sensible defaults – so the app is ready to use as soon as the connection is configured.

  3. Assign users the Ventoo Address Validation permission set (AddressValidUserVTO), and the person who configures the service Ventoo Address Validation - Setup (AddressValidAdminVTO) – see Administration Reference › Permissions. No permission set is required for the automatic flows.

Prerequisite: A Swiss Post technical user for the address web service. You obtain it from the Swiss Post developer portal.

Connecting to the Swiss Post web service

Open the Address Validation Setup page (search: Address Validation Setup).

  1. Environment – choose Test (integration environment) or Production. The base URLs are pre-filled; they can be adjusted if needed.

  2. User Name – enter the bare technical user, e.g. TU_1234567_0001 – without the @service.post.ch suffix.

  3. Password – store the technical user's password. It is kept encrypted in Isolated Storage and is never stored in clear text on the setup record.

  4. Test Connection – performs a test call to verify that credentials and endpoint are correct.

Timeout: Timeout (ms) controls how long Business Central waits for a Swiss Post response (default 10,000 ms).

In the setup, click Apply Recommended Defaults. This sets the proven baseline configuration:

  • Validation active everywhere but non-blocking (notification only) on cards, documents, on release, document print, reminders and on the print/send of posted invoices.

  • Hard block only at the posting gate – the last point where the address can still be corrected on the document.

  • Block on Address Not Found (PSTAT 7) enabled; block on partly confirmed (PSTAT 6) and not unique (PSTAT 8) disabled.

  • Background queue active for all master tables, batch size 50, interval 30 minutes, re-check of unchanged addresses every 90 days.

You can then fine-tune every setting individually.

Configuring the validation triggers

The app validates at several points. Each point has an on/off switch and – where relevant – a mode:

  • Suggest – informs / warns and lets you continue.

  • Block – stops the action so the address is corrected first.

The triggers from early (most correctable) to late (last safety net):

#

Trigger

Setting

Mode

Recommendation

1

Manual button

Enable Manual Button

Button Mode

Suggest

2

Automatic validation on cards

Auto-Validate on Cards

– (always non-blocking)

On

3

Document check

Check Addresses on Documents

– (always non-blocking)

On

4

Release gate

Enable Release Gate

Release Gate Mode

Suggest

5

Document print gate (unposted)

Enable Document Print Gate

Document Print Gate Mode

Suggest

6

Reminder gate

Enable Reminder Gate

Reminder Gate Mode

Suggest

7

Posting gate

Enable Posting Gate

Posting Gate Mode

Block

8

Print gate (posted invoice)

Enable Print Gate

Print Gate Mode

Suggest

9

Send gate (posted invoice)

Enable Send Gate

Send Gate Mode

Suggest

Why block only at the posting gate? On cards and during document entry the check should not get in the way – a notification is enough. At posting it is the last moment the address can still be corrected on the document; afterwards (posted invoice) a correction is no longer possible, so Suggest there.

Behaviour in difficult cases (Block mode only)

Setting

Effect

Block: Partly Confirmed (PSTAT 6)

Stops when Swiss Post can only partially confirm the address. Default: off.

Block: Address Not Found (PSTAT 7)

Stops when the address is not found at all. Default: on.

Block: Ambiguous Address (PSTAT 8)

Stops when several matches are possible. Default: off.

Block When Swiss Post Unreachable

Stops on timeout/technical error. Default: off (warn and continue).

Block: Correction Available

Stops when a correction/completion was offered but not applied. Default: off (warning only).

Reviewed addresses are exempt. These blocking rules never fire for an address a person has already handled in the worklist (set to Done or Deferred), as long as the address is unchanged. This is automatic – there is no setting for it.

E-mail dispatch

By default e-mail dispatch is not validated, because the postal address is not relevant for e-mail delivery (it still appears on the PDF). Enable Also Check on E-Mail if you want a check here as well.

Configuring the background queue

The queue validates the existing address base automatically (see Business Functions › Background queue).

Setting

Meaning

Default

Queue: Customers / Ship-to Addresses / Contacts / Vendors / Order Addresses

Which master tables the queue validates.

all on

Batch Size Per Run

Max. number of Swiss Post calls per run (stays within the per-minute limit).

50

Run Interval (Minutes)

How often the job queue runs.

30

Re-Sweep Interval (Days)

After how many days an unchanged address is validated again (0 = off).

90

List House Numbers on Wrong/Missing No.

Automatically fetches the valid house numbers of the street (≈ 9 extra calls, once).

on

Keep Log History (Days)

After how many days superseded log entries are deleted (0 = keep forever).

0

Recall to the worklist

Setting

Meaning

Default

Re-open When Result Worsens

Puts a done/deferred address back to Open when the result gets worse.

on

Re-open Deferred After (Days)

Time-based recall of deferred addresses (0 = off).

30

Re-open Done After (Days)

Time-based recall of handled addresses (0 = off).

0