Accept Partij Identificatoren as part of Partij creation

[swrichards]

Thema / Theme

Klantinteracties API

Omschrijving / Description

Update the partijenCreate payload to accept one or more partij identificatoren, e.g.:

// POST /partijen
{
  "indicatieGeheimhouding": false,
  "indicatieActief": true,
  "soortPartij": "persoon",
  "partijIdentificatie": { /* ... */ },
   // ...   

   // New field
   "partijIdentificatoren": [
     {
        // "identificeerdePartij" will be automatically set to the created party
        "partijIdentificator": {
			"codeObjecttype": "bsn",
			"codeSoortObjectId": "inp",
			"objectId": "123456789",
			"codeRegister": "brp",
	},
	"anderePartijIdentificator": "optional_identifier_123",
     }        
   ]
}

Toegevoegde waarde / Added value

A common pattern emerging in Open Inwoner Platform is (1) creating a Partij and immediately subsequent to that (2) creating a PartijIdentificator. We canonically identify parties in OK through the usual suspects from the basisregistraties: bsn, kvk, and so on.

Although the bare Partij has the nummer field, its intent is not very clear when it is client provided: OIP might choose to use the nummer to build its own scheme (e.g. setting it to our internal user ID, or some pseudonymised version thereof), but this might not play well with other clients reading and writing from OK. We would in any case like to avoid having to maintain our internal mapping between a Partij.{uuid|nummer}.

TLDR: we would like to canonically identify a Partij through a Partij Identificator, and this would be eased by being able to create the Partij with its Identificator atomically. The added value is thus it facilitates our use-case, in at least two ways:

1. One rather than two requests
2. It improves atomicity, as having to use two requests creates a transactionality problem: the Partij creation could succeed by the PartijIdentificator could fail. This forces clients to maintain a retry/compensating transaction queue, which is a nuisance. But also, it runs the risk of orphaned Partij objects lacking a clear identificator due to such a failed transaction.

Our assumption is that this is probably a common use-case, but that is just a hunch.

Aanvullende opmerkingen / Additional context

No response

[alextreme]

@Hugo-ter-Doest

[danielmursa-dev]

I can take this ticket because it is related to this: #267.

[swrichards]

@Hugo-ter-Doest while implementing this, @danielmursa-dev hit upon a question we might want to consider from an architectural perspective.

The PartijIdentificator -> Partij mapping is currently one-to-one (where PartijIdentificator has a foreign key to Partij, while a Partij can have multiple PartijIdentificators).

This is I think problematic because PartijIdentificator should behave like a value object. The combination of:

• codeObjecttype
• codeSoortObjectId
• objectId
• codeRegister

should function as a natural key and be unique.

For example, a single PartijIdentificator should be able to identify multiple Partijen. For instance, a kvkNummer can identify both:

• The rechtspersoon itself
• The rechtspersoon + vestiging combination (as discussed in Enforce uniqueness of Partij #267)

I would proposed the following changes:

1. Make PartijIdentificator entries unique based on the four main fields listed above
2. Change the relationship to allow a PartijIdentificator to point to multiple Partijen

This would, among other things, make this current feature more cogent, because creating a Partij where all the substantive fields of a PartijIdentificator match an existing row would be re-used, rather than re-created as we are forced to do now. Also, it means searching by a PartijIdentificator's uuid to return multiple associated parties, which to me seems like logical behaviour (I would expect to find all Partijen that match the identificators susbtantive fields, but currently, if I use uuid, there may be another Identificator with identical fields that I would miss).

[joeribekker]

Refinement:

There is some discussion about this. I see the PartijIdentificator as a group-attribute of Partij, similar to Actor-group. Basically, meaning, we can have duplicate values of KvK-number in the database. The only downside is that if you search directly on PartijIdenticatoren, it can return more than 1. the benefit is that you can delete and change these Partijidenticatoren without worrying that you change another party.

[joeribekker]

@swrichards please reply (without bobby knowing)

[swrichards]

The only downside is that if you search directly on PartijIdenticatoren, it can return more than 1.

In my view this is a very significant downside, but that might be due to incorrect assumptions. Although this is more to do with #267, in my understanding the critical problem that we wish to solve is ambiguity around which Partij to select for a well-known identifier (kvk, bsn, etc.). If OIP and KISS both wish to append klantcontacten for bsn=1234, the API should do as much as possible to avoid those two clients writing their information to two different Partijen (because they each have bsn=1234 attached to a different Partij resource).

Simply put, in my understanding the whole point of PartijIdenticator is to help different clients coordinate and converge on the same Partij, to avoid fragmentation. This objective is harder to reach if a PartijIdentificator is not unique.