Public API

Tasks and task registry

Expose the public API to manage tasks.

exception bptl.tasks.api.NoCallback

exception bptl.tasks.api.TaskExpired

exception bptl.tasks.api.TaskPerformed

bptl.tasks.api.execute(task: ~bptl.tasks.models.BaseTask, registry: ~bptl.tasks.registry.WorkUnitRegistry = <bptl.tasks.registry.WorkUnitRegistry object>) → dict

Execute the appropriate task for a fetched external task.

This function takes care of looking up the appropriate handler for a task from the registry, and then calls it, passing the fetched task argument.

Parameters:

task – A BaseTask instance, that may not have expired yet.
registry – A bptl.tasks.registry.TaskRegistry instance. This is the registry that will be used to find the corresponding callback for the topic name. Defaults to the default sentinel registry, mostly useful for tests.

Raises:

TaskExpired if the task is already expired, this exception is raised. You will need to re-fetch and lock the task before you can process it.

Raises:

NoCallback if no callback could be determined for the topic.

Raises:

TaskPerformed if the task is already completed, this exception is raised.

Work units

Work units are python callbacks which process tasks from external engines. They are engine independent and can be python functions or classes. Work units are registered in the registry.

API’s voor Zaakgericht Werken

class bptl.work_units.zgw.tasks.zaak.CloseZaakTask(task: BaseTask)

Close the ZAAK by setting the final STATUS.

A ZAAK is required to have a RESULTAAT.

Required process variables

zaakUrl [str]: URL-reference to the ZAAK.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Optional process variables

omschrijving [str]: description of the RESULTAATTYPE. RESULTAATTYPE takes priority.
resultaattype [str]: URL-reference to the RESULTAATTYPE to set.
statustoelichting [str]: description of the STATUS. If provided the RESULTAAT is created before the ZAAK is closed.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

einddatum [str]: date of closing the zaak.
archiefnominatie [str]: shows if the zaak should be destroyed or stored permanently.
archiefactiedatum [str]: date when the archived zaak should be destroyed or transferred to the archive.

class bptl.work_units.zgw.tasks.zaak.CreateZaakTask(task: BaseTask)

Create a ZAAK in the configured Zaken API and set the initial status.

The initial status is the STATUSTYPE with volgnummer equal to 1 for the ZAAKTYPE.

By default, the registratiedatum and startdatum are set to todays date.

Required process variables

organisatieRSIN [str]: RSIN of the organisation.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.
catalogusDomein [str]: abbrevation for the domain of the catalogus of the ZAAKTYPEn.
zaaktypeIdentificatie: ID of ZAAKTYPE.

Optional process variables

NLXProcessId [str]: a process id for purpose registration (“doelbinding”).
NLXSubjectIdentifier [str]: a subject identifier for purpose registration (“doelbinding”).
initialStatusRemarks [str]: a text to use for the remarks field on the initial status. Must be maximum 1000 characters.
catalogusRSIN [str]: RSIN of catalogus where zaaktype can be found. Defaults to organisatieRSIN.
initiator [str]: a JSON object with data used to create a rol for a particular zaak. See https://zaken-api.vng.cloud/api/v1/schema/#operation/rol_create for the properties available.
zaakDetails [json]: a JSON object with extra properties for zaak creation. See https://zaken-api.vng.cloud/api/v1/schema/#operation/zaak_create for the available properties. Note that you can use these to override zaaktype, bronorganisatie, verantwoordelijkeOrganisatie, registratiedatum and startdatum if you’d require so.
zaaktype [str]: URL-reference to the ZAAKTYPE.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

zaak [json]: the JSON response of the created ZAAK.
zaakUrl [str]: URL-reference to the created ZAAK.
zaakIdentificatie [str]: the identificatie of the created ZAAK.

class bptl.work_units.zgw.tasks.zaak.LookupZaak(task: BaseTask)

Look up a single ZAAK by identificatie and bronorganisatie.

This task looks up the referenced zaak, and if found sets the zaakUrl as a process variable. If not found, the variable will be empty.

You can use this to check if the referenced ZAAK does indeed exist, and relate it to other objects.

Required process variables

identificatie [str]: identification of the zaak, commonly known as “zaaknummer”.
bronorganisatie [str]: RSIN of the source organization for the zaak. The combination of identificatie and bronorganisatie uniquely identifies a zaak.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

zaakUrl [str]: URL-reference of the retrieved zaak, if retrieved at all. If the zaak was not found, the value will be Null.

class bptl.work_units.zgw.tasks.status.CreateStatusTask(task: BaseTask)

Create a new STATUS for the ZAAK in the process.

Required process variables

zaakUrl [str]: URL-reference to the ZAAK to create a new status for
statusVolgnummer [int]: volgnummer of the status type as it occurs in the catalogus OR
statustype [str]: URL-reference to the STATUSTYPE to set
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Note that either statusVolgnummer or statustype are sufficient.

Optional process variables

toelichting [str]: description of the STATUS.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

statusUrl [str]: URL-reference to the created STATUS.

class bptl.work_units.zgw.tasks.resultaat.CreateResultaatTask(task: BaseTask)

Set the RESULTAAT for the ZAAK in the process.

A resultaat is required to be able to close a zaak. A zaak can only have one resultaat.

Required process variables

zaakUrl [str]: URL-reference to the ZAAK to set the RESULTAAT for.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.
resultaattype [str]: URL-reference to the RESULTAATTYPE to set.

OR

omschrijving [str]: description of RESULTAAT.

Optional process variables

toelichting [str]: comment of RESULTAAT.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

resultaatUrl [str]: URL-reference to the created RESULTAAT.

class bptl.work_units.zgw.tasks.zaak_relations.CreateEigenschap(task: BaseTask)

Set a particular EIGENSCHAP value for a given zaak.

Unique eigenschappen can be defined for a given zaaktype. This task looks up the eigenschap reference for the given zaak and will set the provided value.

Required process variables

zaakUrl [str]: URL-reference to a ZAAK in a Zaken API. The eigenschap is created for this zaak.

eigenschap [json]: a JSON Object containing the name and value:

{
    "naam": "eigenschapnaam as in zaaktypecatalogus",
    "waarde": "<value to set>"
}

bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Optional process variables

NLXProcessId [str]: a process id for purpose registration (“doelbinding”)
NLXSubjectIdentifier [str]: a subject identifier for purpose registration (“doelbinding”)

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion

Sets no process variables

class bptl.work_units.zgw.tasks.zaak_relations.CreateZaakObject(task: BaseTask)

Create a new ZAAKOBJECT for the ZAAK in the process.

Required process variables

zaakUrl [str]: URL-reference to the ZAAK to create a new ZaakObject for.
objectUrl [str]: URL-reference to the OBJECT to set.
objectType [str]: URL-reference to the type of the OBJECT.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

If zaakUrl is not given - returns empty dictionary.

Optional process variables

objectTypeOverige [str]: description of the OBJECT type if objectType == ‘overige’.
relatieomschrijving [str]: description of relationship between ZAAK and OBJECT.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

zaakObjectUrl [str]: URL-reference to the created ZAAKOBJECT.

class bptl.work_units.zgw.tasks.zaak_relations.FetchZaakObjects(task: BaseTask)

Fetch all ZAAKOBJECTs for ZAAK.

Required process variables

hoofdZaakUrl [str]: URL-reference of ZAAK.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Sets the process variables
zaakObjects list[dict[str,str]]: A list of ZAAKOBJECTs, with their objecttypes and objectTypeOverige and relatieomschrijving attributes.

class bptl.work_units.zgw.tasks.zaak_relations.FetchZaakRelaties(task: BaseTask)

Fetch relevanteAndereZaken for ZAAK.

Required process variables

zaakUrl [str]: URL-reference of ZAAK.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Sets the process variables
relatieZaken list[dict[str, str]]: A dictionary of URL-references of ZAAKen and their aardRelatie.

class bptl.work_units.zgw.tasks.zaak_relations.RelateDocumentToZaakTask(task: BaseTask)

Create relations between ZAAK and INFORMATIEOBJECT

Required process variables

zaakUrl [str]: URL-reference to the ZAAK.
informatieobject [str]: URL-reference to the INFORMATIEOBJECT. If empty, no relation will be created.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets the process variables

zaakinformatieobject [str]: URL-reference to ZAAKINFORMATIEOBJECT.

class bptl.work_units.zgw.tasks.zaak_relations.RelatePand(task: BaseTask)

Relate Pand objects from the BAG to a ZAAK as ZAAKOBJECTs.

One or more PANDen are related to the ZAAK in the process as ZAAKOBJECT.

Required process variables

zaakUrl [str]: URL-reference to a ZAAK in a Zaken API. The PANDen are related to this.
panden [list[str]]: URL-references to PANDen in BAG API.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Optional process variables

NLXProcessId [str]: a process id for purpose registration (“doelbinding”).
NLXSubjectIdentifier [str]: a subject identifier for purpose registration (“doelbinding”).

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion

Sets no process variables

class bptl.work_units.zgw.tasks.zaak_relations.RelateerZaak(task: BaseTask)

Relate a zaak to another zaak.

Different kinds of relations are possible, specifying the relation type will ensure this is done correctly. Existing relations are not affected - if there are any, they are retained and the new relation is added.

Required process variables

hoofdZaakUrl [str]: URL-reference to a ZAAK in a Zaken API. This zaak receives the relations.
zaakUrl [str]: URL-reference to another ZAAK in a Zaken API, to be related to zaakUrl.
aardRelatie [str]: the type of relation. One of vervolg, onderwerp or bijdrage.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Optional process variables

NLXProcessId [str]: a process id for purpose registration (“doelbinding”).
NLXSubjectIdentifier [str]: a subject identifier for purpose registration (“doelbinding”).
aardRelatieOmgekeerdeRichting [str]: the type of reverse relation. One of vervolg, onderwerp, bijdrage or empty (""). Default is onderwerp if the process variable isn’t given.

Optional process variables (Camunda exclusive)

callbackUrl [str]: send an empty POST request to this URL to signal completion.

Sets no process variables

class bptl.work_units.zgw.tasks.documents.GetDRCMixin

Temp workaround to get credentials for the relevant DRC.

The services var should contain a DRC alias key with credentials, but that’s currently a massive spaghetti. So, we’ll allow for the time being that DRCs are all configured in BPTL, and we grab the right one from the document URL.

class bptl.work_units.zgw.tasks.documents.LockDocument(task: BaseTask)

Lock a Documenten API document.

A locked document cannot be mutated without having the lock ID.

Required process variables

informatieobject [str]: URL-reference of the document to lock. The API must comply with the Documenten API 1.0.x (https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index).
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Sets the process variables

lockId [str]: Lock ID for the locked document. Required to unlock or mutate the document.

class bptl.work_units.zgw.tasks.documents.SetIndicatieGebruiksrecht(task: BaseTask)

Set the indicatieGebruiksrecht to False of all INFORMATIEOBJECTen related to the ZAAK. The INFORMATIEOBJECTen in ZAAKINFORMATIEOBJECTen must point to INFORMATIEOBJECTen in an API that complies with the Documenten API 1.0.x (https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index).

From the API documentation:

Indicatie of er beperkingen gelden aangaande het gebruik van het informatieobject
anders dan raadpleging. Dit veld mag ``Null`` zijn om aan te geven dat de
indicatie nog niet bekend is. Als de indicatie gezet is, dan kan je de
gebruiksrechten die van toepassing zijn raadplegen via de GEBRUIKSRECHTen
resource.

-- Documenten API documentation

This task essentially switches the value from Null to False, implying re-use other than “consulting” is not allowed.

required process variables

zaakUrl [str]: URL-reference to the ZAAK.
bptlAppId: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Sets no process variables

class bptl.work_units.zgw.tasks.documents.UnlockDocument(task: BaseTask)

Unlock a Documenten API document.

Required process variables

informatieobject [str]: URL-reference of the document to lock. The API must comply with the Documenten API 1.0.x (https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index).
lockId [str]: Lock ID for the locked DRC document, obtained from locking the document.
bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.

Sets no process variables

class bptl.work_units.zgw.tasks.zaakprocess.CreatedProcessInstanceSerializer(*args, **kwargs)

class bptl.work_units.zgw.tasks.zaakprocess.StartCamundaProcessTask(task: BaseTask)

Starts the related camunda business process for a ZAAK if its ZAAKTYPE is associated to a configured StartCamundaProcessForm in the OBJECTS API.

Required process variables * zaakUrl [str]: URL-reference of a ZAAK in Open Zaak. * bptlAppId [str]: the application ID of the app that caused this task to be executed.

Sets the process variables

Does not set any process variables.

class bptl.work_units.zgw.zac.tasks.UserDetailsTask(task: BaseTask)

Requests email and name data from usernames from the zac and feeds them back to the camunda process.

Required process variables

usernames [list[str]]: usernames.

[
    "user:user1",
    "user:user2",
    "group:group1"
]

OR

emailaddresses [list[str]]: user email addresses.

[
    "user1@email",
    "user2@email"
]

Optional process variables

bptlAppId [str]: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls, if provided.
emailNotificationList: JSON with email notification flags per “user”.

Sets the process variables

userData [list[json]]: a list of user names and emails:

[
    {
        "name": "FirstName LastName",
        "username": "username",
        "email": "test@test.nl"
    }
]

class bptl.work_units.zgw.zac.tasks.ZaakDetailURLTask(task: BaseTask)

Requests the URL to the zaak detail page of a ZAAK in open zaak.

Required process variables * zaakUrl [str]: URL-reference of a ZAAK in Open Zaak.

Sets the process variables

zaakDetailUrl [str]: URL-reference to the ZAC ZAAK detail page.

class bptl.work_units.zgw.zac.tasks.ZacEmailVGUReports(task: BaseTask)

Requests the VGU reports from the ZAC and sends them via email to the recipients. If startPeriod and endPeriod are provided, the reports will be filtered by these dates, otherwise by default the last month.

Required task variables * recipientList [List[str]]: List of email addresses to send email to.

Optional task variables * startPeriod [date]: the start of the logging period. * endPeriod [date]: the end start of the logging period.

Camunda

class bptl.work_units.camunda_api.tasks.CallActivity(task: BaseTask)

Start subprocess in Camunda.

Required process variables

subprocessDefinition [str]: process definition key for the target subprocess to start.

Optional process variables

subprocessDefinitionVersion [str]: a specific version of the deployed subprocess. defaults to latest if not set, which means the process will be kicked off by definition key.
variablesMapping [json]: JSON object to map variables from the parent process to be sent into the new subprocess. If renaming is not needed, use the same name as a key and a value. If variablesMapping is empty, the all parent variables are sent to subprocess unchanged.
{ "<source variable name>": "<target variable name>", }

Sets the process variables

processInstanceId [str]: instance id of the created subprocess

Email

class bptl.work_units.mail.tasks.SendEmailTask(task: BaseTask)

This task sends an email to receiver signed by sender.

Required process variables

sender [json]: required fields email and name of sender.

{
  "email": "voornaam.achternaam@example.com",
  "name": "Voornaam Achternaam"
}

receiver [json]: required fields email and name of receiver.

{
  "email": "voornaam.achternaam@example.com",
  "name": "Voornaam Achternaam"
}

email [json]: required fields email subject and email content:

{
  "subject": "This is an example subject.",
  "content": "This is an example body."
}

template [str]: template name. Valid choices are:

[
  "generiek",
  "accordering",
  "advies",
  "nen2580",
  "verzoek_afgehandeld"
]

context [json]: JSON with fields depending on the template:

{
  "reviewType": "accordering/advies",
  "doReviewUrl": "https://kownsl.cg-intern.*.utrecht.nl/kownsl/<uuid>/",
  "deadline`": "2020-04-20"
}

Camunda tasks

Module for Camunda API interaction.

bptl.camunda.utils.complete_task(task: ExternalTask, variables: Dict[str, str | int | bool] | None = None) → None

Complete an External Task, while optionally setting process variables.

API reference: https://docs.camunda.org/manual/7.12/reference/rest/external-task/post-complete/

If a task variable callbackUrl is available, a post request is made to it.

Note that we currently only support setting process variables and not local task variables.

Camunda performs optimistic table locking, see the docs. This results in HTTP 500 exceptions being thrown when concurrent mutations to the process instance happen. The recommended way to deal with this by Camunda is to retry the operation to reach eventual consistency, which is why the @retry decorator applies.

bptl.camunda.utils.fail_task(task: ExternalTask | str, reason: str = '') → None

Mark an external task as failed.

See https://docs.camunda.org/manual/7.11/reference/rest/external-task/post-failure/

When the number of retries becomes 0, an incident is created in Camunda.

bptl.camunda.utils.fetch_and_lock(max_tasks: int, long_polling_timeout=None) → Tuple[str, int, list]: Fetch and lock a number of external tasks. API reference: https://docs.camunda.org/manual/7.12/reference/rest/external-task/fetch/