This tutorial explains the concept of mapping primary keys (PKs) between Pigello and other systems, and how to use Integration Service ID connections in Pigello to store and use those mappings.
When you integrate Pigello with another system (e.g. your own ERP system, Bookkeeping system, or tenant portal), you often need to correlate entities between the two:
- A tenant in Pigello might correspond to one or many user(s) or account(s) in your portal.
- Multiple verifications in Pigello might correspond to one invoice in your portal.
Each system has its own primary keys. To avoid duplicate syncs, to look up the right record on each side during update/delete, or to support other workflows that span both systems, you oftan want a mapping between Pigello Pks and external PKs.
Pigello offers a generic way to store these mappings: Integration Service ID connections (integrations.integrationserviceidconnection).
For each mapping you create a connection that links:
- Pigello side:
content_type(e.g.accounting.verification) andobject_id(the UUIDpkof the entity in Pigello). - External side:
external_id(thepkof the entity in your other system—stored as a string, so it can be a UUID, numeric ID, or any type of identifier that the external system uses).
So: this Pigello entity (content_type + object_id) corresponds to this external entity (external_id).
The model supports M:N (many-to-many) mappings:
- One Pigello entity → many external IDs: One item in Pigello can be linked to multiple items in other systems (e.g. one tenant in pigello corresponding to multiple tenants in another system).
- Many Pigello entities → one external ID: Multiple Pigello items can point to the same external ID if your use case requires it.
You create one connection row per (Pigello entity, external entity) pair you want to track.
There is a unique constraint on (external_id, content_type, object_id) per application service. So for a given application's service:
- You cannot create two connections with the same
external_id,content_type, andobject_id. - This prevents duplicate mappings and allows you to use the connection as a lock: for example, "this external ID is already linked to this Pigello object," so you can avoid creating a second link or double-syncing.
All services under the same application can view each other's Integration Service ID connections. So if your application has multiple services (e.g. "Bookkeeping sync" and "Reporting"), they can all read (and, where allowed, create) the same set of connections. That way you can share PK mappings across services within one application.
- Create connections when you sync or link an entity: after creating or identifying the entity in the other system, POST a new integrations.integrationserviceidconnection with the right
content_type,object_id, andexternal_id. - List connections to resolve "what Pigello ID goes with this external ID?" or "what external ID goes with this Pigello ID?" Use the list endpoint with filters (e.g. by
content_type,object_id, orexternal_id) as needed. See the API Reference for the list endpoint and filters. - Respect the unique constraint when creating: if a connection already exists for the triple (external_id, content_type, object_id), you will get an error; use that to avoid duplicates and to implement locking if needed.
For a concrete example of creating connections (e.g. "mark verifications as synced"), see the Bookkeeping Data implementation example, which uses Integration Service ID connections to record synced verifications.
- PK mapping links Pigello entities to entities in other systems.
- Integration Service ID connection stores:
content_type+object_id(Pigello) andexternal_id(your system). - M:N is supported: one Pigello item can map to many external IDs, and vice versa.
- Unique per application service on (
external_id,content_type,object_id)—no duplicates, usable as a lock. - All services under one application can see each other's connections.
- Create connections when you sync or link; list and filter them to resolve IDs on either side.