Subiekt nexo Sfera: a developer's guide, and what changes if you came from GT

The Question That Opens Every nexo Project

I wrote the developer's guide to Sfera for Subiekt GT a few weeks ago and the word nexo doesn't appear in it once. That was a mistake, and I've been paying for it in phone calls ever since. Everyone on the newer InsERT line opens with some version of the same sentence: we have Sfera too, so it's the same integration, right?

It isn't. The name carries across. Almost nothing underneath it does. Sfera in Subiekt GT and Sfera in Subiekt nexo are two different technologies, sold two different ways, and they fail on the first day for two entirely different reasons.

This is the nexo half of that guide. It sits alongside the Optima API guide, the enova365 WebAPI guide and the three-way comparison for integrators. Same rule as in all of those: every technical claim below comes from InsERT's own materials or from code you can read yourself. In this corner of the market, an invented assembly name costs somebody a working day.

"Sfera" Is Three Products, Not One

Start here. Getting this wrong isn't a technical error — it's a commercial one.

Sfera dla Subiekta GT is an add-on. You own Subiekt GT, you buy Sfera separately, you get COM access to the running application. Roughly a thousand złoty net for the first workstation on InsERT's published list, more for each additional one.

Sfera dla Subiekta nexo isn't sold that way at all. It's a capability of Subiekt nexo PRO — InsERT lists it among the PRO features next to advanced custom fields and user-defined reports. There's no version of the standard Subiekt nexo with Sfera in it, and no add-on that puts it there.

Sfera PRO+ is a third thing again, and the one people conflate with the second. It's the event layer — Sfera zdarzeniowa, which lets your code run in response to what a user does inside the program (block a field, reject a save, react to a value changing, refuse a deletion), plus the spherical menu, which puts your own operations into the program's own menus. InsERT documents eleven main events plus thirteen more specific to Subiekt. It lives only in nexo PRO+, the top tier.

Now the consequence, which is why this section comes first.

On GT, acquiring an API is a purchase: one line item, an IT decision, signed off by whoever signs off on software. On nexo, acquiring an API is a tier upgrade of the entire installation, priced per workstation. A company with ten seats doesn't buy one licence to unlock an integration — it moves ten seats up a tier. And if the requirement turns out to need event hooks rather than an external process, it moves them up two.

Different meeting, different person at the table. Find out which tier the client is on in the first conversation, not the fourth. I've watched a perfectly reasonable two-week integration die because the licensing answer arrived after the estimate did, and the estimate was suddenly the smaller number on the page.

The Connection Model Is Inverted

In GT, the architecture is drive the application. You create a COM object with the ProgID InsERT.GT, hand it two sets of credentials, call Uruchom with a running mode, and from then on your integration is bound to a live subiekt.exe process. Mode 4 hides the window. Nothing hides the dependency: if that process ends, your object handle is dead and won't heal itself.

In nexo, the architecture is load the business logic. You add references to InsERT's own .NET assemblies — InsERT.Moria.API.dll, InsERT.Moria.ModelDanych.dll, InsERT.Moria.Sfera.dll, InsERT.Moria.BibliotekaDokumentow.dll, InsERT.Mox.Core.dll and friends — point the code at a server and a podmiot, authenticate, and work through the object model in your own process. No window. No application to attach to. No RPC server to lose overnight.

If you came from GT, that removes your single most familiar failure. The service that ran happily for six weeks and then went quiet because somebody closed a window isn't a nexo problem.

It's replaced by a subtler one.

You Are Referencing the Client's Installation, Not a Package

There's no NuGet feed here. The assemblies you reference are the ones sitting in the Subiekt nexo installation directory on that machine — an absolute path into the podmiot's binaries. Your build output is bound to the version of nexo that was installed when you compiled it.

InsERT ships templates for this. Since version 40.0.0 of the SDK there's a Visual Studio extension (nexoSDKSzablony_VS2019.vsix) with console and WPF project templates that set up Sfera initialisation for you, and the guidance is explicit about the target platform: .NET Framework 4.6.1, chosen for compatibility with the Entity Framework version nexo itself uses. Take both facts literally. You don't get to pick a runtime here — you're loading somebody else's object graph into your process.

So the day-one failure on nexo is an assembly load error. The classic is a flat refusal to load InsERT.Moria.Sfera — a message that says nothing about versions, nothing about updates, and points you straight at your own project configuration, where the problem usually isn't.

Compare the equivalent moment on GT: a .NET project built as AnyCPU on a 64-bit machine throwing Klasa niezarejestrowana against a COM object that's registered perfectly well, just not for a 64-bit process. Different platform, different message, identical lesson. On both InsERT lines the first error message points somewhere other than the cause, and on both it costs half a day to anyone who hasn't seen it before.

Three rules follow, and all three are cheap to adopt:

Pin the version you built against, in writing, in the deployment. Not in someone's memory.

Treat a client-side nexo update as a redeploy of your component. Not as something that happens to the ERP and might affect you. The update is a deploy; plan the window jointly. Same discipline I argued for around unwatched scheduled jobs, and for the same reason: the thing that breaks quietly is the thing nobody assigned to anyone.

Log the loaded assembly versions and the podmiot version at every startup. One line in your log, and version drift announces itself with a name instead of arriving as a stack trace nobody can date.

The Service Account Question, Again

A Sfera connection in nexo authenticates as a nexo user, configured for the purpose — that is what the Sfera configuration screen is for. The permissions that user holds are the permissions your integration holds.

I've written before about what read-only actually means for a service account, and the nexo case is cleaner than GT's, where two separate credential sets — a SQL login and a Subiekt operator — both get called "the integration account" in the same sentence. That particular ambiguity is gone here. What remains is the ordinary one, and ask it out loud in the kickoff: which named account will this run as, who created it, what can it do, and what happens to it when that person leaves.

The other half of the same question is custom fields. Subiekt nexo PRO carries advanced custom fields on system objects, and everything I found out the hard way about custom fields as an undocumented schema change applies here without amendment: a field added by an administrator after go-live is a breaking change performed by somebody with no obligation to tell you, and your integration is the only party that will ever notice.

Where the Documentation Is

On GT, the reference is a CHM file inside the installation directory and there's no public copy. People lose hours hunting for one that doesn't exist.

On nexo, the documentation is a deliberate download: nexoSDK.exe, published by InsERT on their public FTP, covering Subiekt, Rachmistrz, Rewizor, Gratyfikant and Gestor nexo PRO alongside Sello NX and Biuro nexo. It carries the database structure, the object and method reference, and several dozen categories of worked examples — import and export plugins for e-invoices and bank statements, spherical menu operations on documents and stock, custom fields including SQL-backed dictionaries, scheduled tasks, custom reports.

Read the examples before you design anything. Not for the code — for the shape of the extension points. That's what decides whether the thing you've been asked for is an external process, a menu operation or an event handler. And that decision, as we established above, sets the licence tier.

What I Would Build First

The same shape I recommend on GT, for the same reasons.

Put a thin HTTP service on the Windows host that owns the nexo installation, and let it be the only component in your system that knows Sfera exists. Your application talks to it over JSON. That shim absorbs the assembly coupling, the .NET Framework constraint, the credentials and the version discipline — so all of it stays one small, replaceable component instead of becoming a property of your entire architecture.

Then start with reads. Stock, contractors, prices, exposed read-only, with a heartbeat and that startup version log. A week of work, and it earns you the right to talk about writing documents.

One nexo-specific piece of advice on top. If the client is anywhere near a GT-to-nexo migration, build the shim's interface first and the Sfera half second. The interface survives the migration. The Sfera half doesn't — none of it carries across. A team that built the interface first replaces one component; a team that didn't rewrites the integration. The order-intake work I described for Subiekt GT is exactly this: the part that reads email and decides what a document should contain is worth more than the part that writes it, and it doesn't care which InsERT line sits underneath.

Trying to work out whether a Subiekt nexo integration is worth building — or whether the licence tier kills it? Get in touch. An hour with your installation, your tier and your real document flow settles more than any estimate written from a feature list.