Implementing an integration — Part 1

Integration Core help · for the implementation consultant · graded against Core v1.0.0-rc.5 · written 2026-10-06 · re-read against rc.8's screens 2026-10-09 · where a newer Core words a screen differently, see the Glossary's "Changed in newer releases"

This is the route through an implementation, from the first conversation with the customer to the end of the first two weeks live. Part 1 is the same for every integration. Part 2 is the connector's own Connect your … page, and this guide tells you when to switch to it.

⚠ This route has not yet been followed end to end at a customer. It is written from what has been measured on benches and walks. Where a step has not been done by someone outside the integration team, it says so.

What this page restates, and from where. Every fact below is owned by one of Integration Core's papers, kept in the integration team's workspace; each section ends with its source line (paper · date). Where this page and a paper disagree, report it; a section that read a newer build than its paper says so. The papers: Implementing an iVendNext integration — the order of operations (the methodology, 2026-09-13, release lines re-derived 2026-10-02) · Installing it, and knowing what a site is running (the install guide, re-derived 2026-10-02) · Setting up an integration — the screens, in order (the setup guide, screens re-derived 2026-09-27) · What Integration Core gives you today (2026-09-13, release rows 2026-10-02) · the support runbook (2026-09-13, re-looked-up 2026-10-02) · Integration Core v1.0.0-rc.8 — known issues (2026-10-02; its Upgrading from rc.6 and Upgrading from rc.7 blocks 2026-10-06 and 2026-10-09).

Qualify the customer before anything is promised

Ask these first. Each one decides the shape of the project.

Write the names down — operator, System Manager, and an Administrator where the connector asks for one — in the project record. Every hand-off below resolves to one of them; a nameless hand-off is the commonest cause of a stalled setup.

Source: the methodology §0 (2026-09-13).

Prepare the site before you arrive

• On the other system: whatever the connector's own page lists — usually an account, a key with the right permissions, and a reachable address with a valid certificate.
• In iVendNext: the master data the connection maps to — price lists, warehouses, accounts, payment methods — must already exist. ⛔ Creating them is not part of setting up the integration; doing it under time pressure during a cut-over is where mistakes happen.
• A user for the operator, with the Integration Manager role and Is Desk User ticked.
• The site's scheduled jobs running. ⛔ Without them nothing is alerted and nothing is retried, and the screens still look calm. Every alert is itself a scheduled job, so for this one case have an outside uptime monitor poll Integration Core's health address, GET /api/method/ivendnext_integration_core.business_logic.lifecycle.integration_health_feed (with the API key of a user who can read the Connections; at most once a minute; alert when it fails or reports connections_checked = 0).
• The database's binary-log format. Run SELECT @@log_bin, @@binlog_format. With binary logging on and binlog_format = STATEMENT, every sync start fails loudly. MIXED (the default) or ROW is fine.

Source: the methodology §1 (2026-09-13); the install guide §8 (2026-10-02); the setup guide, Getting alerts by email (2026-09-27); the support runbook §6 (2026-10-02); the known issues §5, IC-HEARD-B8 (2026-10-02).

Install, in order, and pin the versions

Order: engine → Integration Core → connector. Each app must already be on the bench before the next one installs. Integration Core is never installed on its own; it arrives because a connector requires it.

Pin Integration Core by its tag — and where the connector's own version matrix names a Core, the connector's matrix wins: an untested combination is untested whether or not one side has a tag. Pin three things, not one: Core, the connector and the engine.

⭐ For the beta today (2026-10-09), the connectors' matrices differ: WooCommerce's v1.0.0-beta.3 passed its own gate on Core v1.0.0-rc.5 only (its gate reads RED on rc.8, their BUG-WC-409); Acumatica's v1.0.0-beta.3 passed its gate on v1.0.0-rc.8. Ask the connector's team before moving a site past the Core their matrix names.

⚠ Nothing checks versions for you. An app's list of required apps checks only that the others are present and installs them in order; it checks no version. Write down what you installed.

⚠ The repository is private. Installing it needs credentials that can read ivendnext/ivendnext_integration_core.

Upgrades: roll forward — stepping back to an older Core brings back money defects the newer release closes. Before any upgrade, read the known issues' Upgrading from … block for the release you are leaving. (From rc.8 to build 2.0.0.157, the first build under the new numbering, the main things are: the six long help pages are replaced by short answer cards, opened by What does this mean? and What is this list? on every Core screen; a person fenced Integration Activity-only to some connections no longer sees or closes other connections' Differences; every scheduled email of a Core report other than Connection Health is switched off, with a comment on it — use Email me a daily summary; and the first hourly checks may move up to 1,000 records per connection an hour to Failed — records already past their last try — so the Failed count can jump — Upgrading from rc.8. From rc.7 to rc.8 the main things are: the upgrade adds the read-only Help pages and a Help link on Getting started; a connection's alert and the daily summary email now reach only the people who may see that connection — a connection no Manager may see alerts the System Managers — and the upgrade stamps each existing daily summary with its own person; the Differences list names each row by its kind, so look up the other system's number with the ID in Connected System filter; a new alert rings for a money record nobody re-tries; and rolling back to rc.7 brings back an S1 security hole in page titles, refuses a connector that declares one of the eight new erp record types, and needs the Hub's Help link removed by hand — Upgrading from rc.7, which lists all eight. From rc.6 to rc.7 it owes two: records already waiting carry no cause and group as No cause recorded, and duplicate waiting rows made on rc.6 are kept — Upgrading from rc.6.) From rc.5 to rc.6 it owes four things:

1. A link written onto a document that was already cancelled gets no difference if it was written before the upgrade. Once, after the upgrade: list the documents of the connector's record types cancelled since go-live, look each up on Record Links, and reverse by hand any that crossed to the other system.
2. The report Waiting on Connected System becomes In progress. A saved daily email or custom role on it is moved; a link to it you added anywhere else (another Workspace, a Number Card, a Dashboard Chart) is not — make it again.
3. A copy of the alert email you switched on keeps its old Subject and Condition. Copy both from the shipped iVendNext Integration Alert by Email into your copy.
4. Core can no longer be uninstalled while it holds record links. The site-config key that lets it through, integration_core_allow_uninstall, is set per site — ⛔ never bench-wide with -g — and removed straight after.

Source: the install guide §1, §2, §2.1, §2.2 and §6 (2026-10-02); the methodology §2 (re-derived 2026-10-02); the known issues, Upgrading from rc.5 items 1, 2, 4 and 6 (2026-10-02).

Check the install — six things, in order

1. The roles exist: Integration Manager and Integration Viewer. The install creates both and grants them to nobody.
2. The page opens: the left-hand menu → Integrations Hub. On rc.5 it shows six count tiles and five cards. You may see more than one menu entry starting with "Integration"; yours is Integrations Hub.
3. The connector's card is on that page. No card means the app is not installed, or it declares no setup page, or its declaration was refused — the refusal is in the Error Log.
4. The scheduled jobs are enabled.
5. No test record exists: Integration Activity is empty on a fresh site. A row marked Test record is a certification run, not customer work.
6. Run the connector's own post-install checks, from its own page.

Then write down what each app is at, on the site itself: bench --site <site> list-apps (what is installed — ⚠ it can leave out an app installed since the site's last migrate; run bench --site <site> migrate first, or cross-check with bench --site <site> execute frappe.get_installed_apps), git -C apps/<app> rev-parse --short HEAD (each app's commit) and bench version (the framework and engine).

⭐ And read the Error Log after every migrate and every connector install — not only at the end of the first week. A step that could not complete is logged and alerted and the migrate carries on, so a green migrate is not proof every step ran. If an Integration Core "Upgrade: … NOT …" notice names a deadlock, run the migrate once more.

Source: the install guide §3 and §4 (2026-10-02); the support runbook §7 (2026-09-13); the known issues §1, IC-R83, and §2, IC-IDENTITY-TAIL-B3 (2026-10-02).

Grant the roles — a System Manager's job

Installing Integration Core gives no person any access to it. For each person who will operate the integrations, a System Manager opens their User, adds Integration Manager (or Integration Viewer for read-only), and ticks Is Desk User.

• Integration Manager is the operator: every button, including switching a connection on — except Link manually and Make inactive, which also need permission to change the iVendNext record (for products, Item Manager), and Erase personal data, which is a System Manager's.
• Integration Viewer sees the same Hub and the same states, and presses nothing.
• ⚠ Fixing a cause needs the iVendNext roles for that document too. A record's Open … button appears only for someone who can read the document it is about, and fixing a price, a warehouse or an invoice needs the role that maintains it. Give the operator those as well, or name who fixes what.
• ⚠ Every desk user is also given the engine's Workspace Manager role automatically, so a Viewer can edit the layout of the Integrations Hub page itself. It changes no record.

How to tell it worked: open Connections and check you can see a Switch on or Switch off button on a connection. Seeing the Hub is not the test — a Viewer sees it too.

Source: the install guide §5 (2026-10-02); the setup guide, Before you start (2026-09-27); the support runbook §9 and §10 (2026-09-13).

Name the hand-offs that are not the operator's

Three steps in every setup are not the operator's, and no screen says so. Assign each now.

1. Credentials — restricted to a System Manager, by design.
2. Registering the connection — the connector's own button; on at least one connector it is refused for anyone but a System Manager.
3. Mapping price lists, warehouses, accounts and payment methods — needs someone who can both edit the connection and read all four. No standard role has both; check the connector's own page for who grants that read.

And one optional step: alert email, if the customer wants it — a System Manager sets up an outgoing email account and switches on a copy of the shipped Notification. Since rc.8 an alert and its email reach only the Integration Managers who may see that connection (and the System Managers if that is nobody).

Several storefronts, each with its own operator? Fence each operator with a User Permission on the Connection — for every document type (leave Applicable For empty) or for Integration Activity. Since rc.8 the bell, the alert email, Connection Health on the desk and the daily summary email respect either; since build 2.0.0.157 so do the Differences — the list, its Hub tile and the form, and Mark resolved, Accept and Erase personal data on another connection's row. ⚠ On rc.7 and older the daily summary honours only the first (a fence for every document type); on rc.8 and older an Integration Activity fence does not reach the Differences at all. What each shape hides: either one hides other connections' activity, Differences and alerts; ⛔ only the first also hides their Incoming Records (with the stored order message — customer names and emails), Record Links and Sync Positions, the Link manually / Make inactive actions on their links, and their name and state on the Connections list, its Hub tile and the six connection reports (measured at build 2.0.0.157, IC-RELEASE-RC9-B2). ⇒ To limit a person to some connections, leave Applicable For empty. Grant the framework's Report Manager role only to people who may see every connection.

Source: the methodology §2 (2026-10-02 re-derivation); the known issues §5, IC-RELEASE-RC4-B1, IC-HEARD-B1 and the Report Manager row (2026-10-02); the alert fence, IC-DESK-HEADERS (2026-10-07); the daily summary's fence, IC-MONITOR-GAPS (2026-10-09); the Differences' fence, IC-READER-FENCE (2026-10-09).

Open the Integrations Hub with the customer

Left-hand menu → Integrations Hub. The Getting started card lists the whole setup in five links, in order (from rc.8 a sixth, Help; from build 2.0.0.157 it opens the list of short answer cards — these long pages live in the repository's docs/): 1. Add an Integration Manager · 2. Connect a system · 3. Test it (on its setup page) · 4. Switch it on · 5. Watch the first run.

Walk the operator through the six tiles — each a count of something that needs a person — and the cards of links. On the desk, What does this mean? and What is this list? open the answer for each one; the long How Integration Core works and Glossary in the repository's docs/ explain them in full.

Source: the setup guide, Step 1 (2026-09-27; Hub layout rc.5's).

Add a connection, then switch to Part 2

Connections → Connect a system. One of three things happens:

• A list to choose from: pick the system and press Start; you land on that connector's own setup page. Give the connection a short, clear name and treat it as permanent — on the connectors documented today it cannot be changed afterwards.
• You are told who to ask (for example "Acumatica: ask someone with the System Manager role to start this connection."). That is not an error: some systems are set up by a System Manager because the first screen holds credentials.
• You are told nothing can be connected yet: no installed connector offers a setup page. Go back to the install.

➡ Now follow the connector's own guide — Part 2 — for its setup page, field by field, its test and its registration. It is in that connector's repository: Acumatica's Connect your Acumatica (docs/guides/ in ivendnext/ivendnext_acumatica); WooCommerce's Connect your WooCommerce store (docs/guides/ in ivendnext/iVendNext_WooCommerce).

⛔⛔ Before anyone presses Register, agree the date from which past history is brought in. On WooCommerce it is fixed once registration has run. Get it wrong and the customer imports years of history, or misses a week. Read the connector's page and decide it deliberately.

Source: the setup guide, Steps 2 and 3 (2026-09-27); the methodology §4 item 1.

Read what the connection still needs

When registration succeeds, a line for the connection appears under Connections. Open it. At the top:

• Still needed: what is not yet configured, each with its reason. A bullet in bold is one the connector says loses records while it stays unmet, and it comes first. Most bullets link to the screen that fixes them; under a bullet you may see Open the fix or Ask a System Manager.
• Ready: what is already done.
• "This connection does not report what it still needs…" means the connector publishes no checklist — not that nothing is missing.
• "The connector's own readiness check could not run…" is worse: the check itself failed. Raise a ticket.
• "This connection has not passed certification (…)" is information, not a restriction. You may switch it on.

Work the Still needed list to empty before switching on. You can switch on with items outstanding; the records that arrive will wait until you fix them.

One field to know by name: Check Every (minutes) — how often the other system is checked for changes. It also sets how long Core waits before warning you about a record whose outcome it cannot confirm, so a long interval means a late warning.

Source: the setup guide, Step 4 (2026-09-27).

Switch it on — the operator presses it

Same screen, top right: Switch on. ⭐ The operator presses it, not you — it is their system. The confirmation lists anything still needed and says "You can switch it on anyway — these are things to finish, not a block."

• It can be refused: "This connection cannot be switched on" — usually another connection of the same kind is already running and only one is allowed (one ERP per company). Switch that one off first.
• Changes kept while it was off are re-queued: one batch straight away, then 500 records an hour. A backlog of twenty thousand takes roughly forty hours. That is normal.
• The operator's name and the time are recorded on the connection.

⛔⛔ Nothing runs until the connector's own scheduled check runs for the first time. Until then the connection reads Not reported yet — blue for its Check Every (minutes) value plus an hour, then grey. Grey means overdue.

Source: the setup guide, Step 5 (2026-09-27).

The first sync — wait for a real record

⛔⛔ Do not leave on the strength of the green word. At cut-over it is the least reliable thing on the screen. A connection whose connector has never run reads Not reported yet, never Live — and no alert will ever fire for that case.

⇒ The exit criterion is a real record reaching Applied in Integration Activity. If none has, stay, and check the site's scheduler and the connector's own scheduled job.

Then look at the Connections list once more, later: a never-started connection turns grey only after its own check interval plus an hour (5 minutes by default ⇒ about 65 minutes; a connection set to poll daily or weekly turns grey after about 25 hours). ⛔ Do not promise "an hour" — read the field, say when, and agree who does that second check.

Source: the methodology §4 items 4–5 (2026-09-13, corrected 2026-09-24); the setup guide, Step 5.

Rehearse on a copy, never on production

Before production, take a copy of the customer's site and a test instance of the other system, and run the whole setup on it with the customer's own people pressing the buttons. You learn three things you cannot learn any other way:

• whether their staff can follow the guide — hand it over and do not help; note every place they had to ask;
• what their real data does to the mapping — an unmapped payment method or a missing warehouse shows up as waiting records, not as an error, and is far cheaper to find here;
• how long their catalogue and history take, and how many records the first load produces.

⛔ Never rehearse against the live other system: a test order posted into a customer's real ERP or store is a real order. ⛔ And do not run the conformance kit on the customer's site — certify on a copy.

Exit criterion: one record of each kind the customer cares about crosses, and the operator can explain what every row on the Hub means.

Source: the methodology §2 and §3 (2026-09-13, corrected 2026-09-25).

Cut over to production

1. Agree the start point for history (above), before registering. ⛔⛔ Never point an existing connection at a different system — from the rehearsal's test system to the customer's real one, or from one store or tenant to another. Create a new connection. Re-running setup against another system keeps every record link, so money documents can be matched to the wrong system's IDs with no refusal and no notice.
2. Install and configure on production, following the rehearsal's notes.
3. The operator switches on.
4. Watch the first records cross in Integration Activity, together.
5. Stay until a real record reaches Applied — and book the later look at the Connections list.

Source: the methodology §4 (2026-09-13); the known issues §2, IC-DP7-B5 (2026-10-02).

Hypercare — the first two weeks

The methodology defines the first week:

For the second week, the operator keeps the daily habit (the help page Daily operations) and you repeat the end-of-week check. Hand over on a fact, not a feeling: N records crossed this week, M needed a person, and here is what each of the M was.

Source: the methodology §5 (2026-09-13; rc.5 names re-derived 2026-10-02). The second-week line is this guide's own advice, not a measured step.

Hand over to support

Give the customer, in writing:

• who their operator is, and that the Hub is a daily habit;
• the setup guide and the connector's own pages;
• the names from qualification — the roles they will need again for credentials and mapping;
• the Integration Core tag, and the commit each other app is at — a support ticket without them cannot be reproduced;
• the support runbook, for whoever answers their call;
• the bounds, said out loud: Integration Core does nothing alone; a connection that has never run raises no alert; alerts depend on the scheduled jobs; one company per site; several connections of one kind are built but not proven together on live systems; the 30-day retention does not cover everything stored; on an engine branch without the count fix (iVend-POS PR #2670 — ask which branch the site runs), any user who can sign in can, slowly, learn what the integration records hold, by counting; and certification means a connector declares itself correctly — ⛔ never that its money handling has been tested. A customer who meets a limit for the first time during an incident has been mis-sold.

Fill in where tickets go — who to contact, how, and what to always send (the connection name, the record's ID and what it says, when it started, and the version each app is at). The setup guide leaves a blank for it; fill it before go-live.

Source: the methodology §6 (2026-09-13); What Integration Core gives you today, The bounds (2026-09-13, release rows 2026-10-02); the known issues §4, INT-GH-SYNC-B2 (2026-10-02; fixed in the engine by branch, 2026-10-07); the setup guide, Where to raise a ticket.

The five things that go wrong

1. Nobody was given the operator role, so the money alerts land on a System Manager who is not watching for them.
2. The scheduler is off. Same symptom, different cause. Check it at install and again at cut-over.
3. The master data was created during the cut-over instead of before it.
4. The history start point was chosen by accident, and it is fixed after registration.
5. The hand-offs were never named, so setup stalls waiting for a System Manager nobody identified.

Four of the five are prevented before anything is installed.

Source: the methodology, The five things that go wrong (2026-09-13).