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.

[joeribekker]

Refinement: We discussed this and #262 and find that the API becomes a little messy this way. If we follow these issues, the retrieval of Partij+PartijIdentificatoren (PI)is done via "expand" and the creation is done via a POST. We think this should be more the same, and thus make the retrieval of Partij+PI work with a GET-operation as well.

While at it, we then also want to support PUT/PATCH for this nested resource. To that end, we also discussed how this behaviour should work, resulting in a very simple description (and also matches the current behaviour :)): PUT works like PATCH, with 1 difference. For PUT required fields are validated to be present in the request. For PATCH, this validation is not done. This allows us to update nested resources as you would update main resources.

Behaviour of PUT and PATCH for nested resources:

Current:
{
    "foo": [
        {
            "id": 1,
            "bar": "abc"
        }
    ]
}


Scenario A
----------


PUT content:
{
    "foo": []
}

Result:
{
    "foo": []
}


Scenario B
----------

PUT
{
    "foo": [
        {
            "id": 2
            "bar": "klm"
        }
    ]
}

Result:

Error: Because ID is generated and doesnt exist.

Scenario C
----------

PUT
{
    "foo": [
        {
            "bar": "klm"
        }
    ]
}

Result:

{
    "foo": [
        {
            "id": 2,
            "bar": "klm"
        }
    ]
}

Scenario D
----------

PUT
{
}

Result:

{
    "foo": [
        {
            "id": 1,
            "bar": "abc"
        }
    ]
}

Scenario E
----------

PUT
{
    "foo": [
        {
            "id": 1,
            "bar": "klm"
        }
    ]
}

Result:

{
    "foo": [
        {
            "id": 1,
            "bar": "klm"
        }
    ]
}

Scenario F
----------

PUT
{
    "foo": [
        {
            "id": 1,
            "bar": "klm"
        },
        {
            "bar": "xyz"
        }
    ]
}

Result:

{
    "foo": [
        {
            "id": 1,
            "bar": "klm"
        },
        {
            "id": 2,
            "bar": "xyz"
        }

    ]
}

Scenario G
----------

Assume "bar" is optional. In this case PUT works as PATCH.
If "bar" is required, in the case of PUT it would throw a 400 error. In case of PATCH it would succeed.

PUT
{
    "foo": [
        {
            "id": 1,
        },
        {
            "bar": "xyz"
        }
    ]
}

Result:

{
    "foo": [
        {
            "id": 1,
            "bar": "klm"
        },
        {
            "id": 2,
            "bar": "xyz"
        }

    ]
}