As a developer I want to be able to PATCH or PUT rollen in the Zaken API

[damm89]

Summary:
To reduce the number of requests it would be great if we can PATCH or PUT rollen (and other resources).

Context:
In some cases a rol is created at a time where more information on the rol is unknown. In our particular implementation we're using a BPMN modeler (Camunda) so that (non-)developers can create resources such as rollen at particular points in time in automated processes. The BPMN modeler is naive in the sense that it doesn't hold all information of every user and polluting it with that data is undesirable. Currently a rol gets created in the BPMN modeler but with sparse data (only the username is added to the betrokkeneIdentificatie).

Current implementation:
A rol resource can be created or destroyed.

Current inefficiencies:
A notification from the NRC alerts our Zaakafhandelcomponent that a rol is created. This sets in motion the processes to complete the information in the betrokkeneIdentificatie by:

1. getting the rol
2. temporarily storing the rol information
3. marrying other data to the rol if other data exists
4. destroying the rol (alerts the NRC)
5. creating a new rol (alerts the NRC) with updated data

Benefits:
The number of requests related to "editing" these resources would be halved.

[edgarvonk]

We are working on the development of ZAC and we would also very much like to be able to change (zaak)rollen with just one ZGW ZRC API request (PUT or possibly PATCH) instead of the two we now need to do (DELETE, followed by a CREATE).

In ZAC users can (re-)assign ('verdelen') batches of up to 100 zaken in one go. This action results in a lot of ZGW API traffic to the zaakregister (OpenZaak in our case) and this is for a large part because we need to first delete and then create these zaakrollen for every zaak. And also, in the ZGW architecture this currently means that we receive and need to handle two notifications (from OpenNotificaties in our case): one for the zaakrol delete and one for the zaakrol create while we really are only interested in a single notificatie: zaakrole update.

In other words: we find that the current ZGW ZRC API is too low-level for this (and possibly other) use case and we (and I think other zaakafhandelcomponents) would greatly benefit from an addition to this API to be able to update zaakrollen in one request.

The following JIRA issue contains some more information specific for ZAC: https://dimpact.atlassian.net/browse/PZ-4371

[Hugo-ter-Doest]

Thanks Edgar!
@joeridiederen this aligns very well with the G4 initiative to create handelinggedreven API's in addition to the CRUD API's.

[edgarvonk]

@Hugo-ter-Doest there may well be more places than just this where ZAC (and other components) would greatly benefit from higher-level handelinggedreven API's as compared to the current CRUD ones. Might be worthwhile to do an investigation at some point?

[HenriKorver]

@edgarvonk Do you really have an urgent (performance) problem right now? If so, does it solve the problem for you if we only add the PUT-operation to the /rollen resource and not the PATCH?

[edgarvonk]

@edgarvonk Do you really have an urgent (performance) problem right now? If so, does it solve the problem for you if we only add the PUT-operation to the /rollen resource and not the PATCH?

Only the PUT would be fine! Actually I would prefer that even just to keep things simple. No, we don't have an urgent performance problem. Our main driver for this change is more to reduce complexity and improve reliability of our solution. But performance gains are always welcome for sure. :-)

[HenriKorver]

See PR #2489. You can view the addition of the PUT-operation to the /rollen endpoint here with Redoc Viewer.

@edgarvonk Does this satisfy your needs?

[HenriKorver]

Note that in this definition you can not change the attributes: zaak, betrokkene and brokkeneType.

[marnixdessing]

Is there any reason why the betrokkene field is not updatable? As it is a non-required attribute is would be nice to set it at a later point in time. At Gemeente Nijmegen we have a use case for doing so. We use this field to store a URL reference (to an external system), however the object to be referenced is created after the role is created. Hence, we need to update the betrokkene field.

[HenriKorver]

The reason was that I wanted to be consistent with the existing PUT-operation at the /zaakobjecten endpoint:

But if you want to update the betrokkene field I can change the specification.

[HenriKorver]

@marnixdessing In commit 7492f1a of the PR I have relaxed on the validation such that you can update the betrokkene field. Is this to your liking?

[marnixdessing]

@HenriKorver thanks! This will work for us :)