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: bptl.tasks.models.BaseTask)¶

Close the ZAAK by setting the final STATUS.

A ZAAK is required to have a RESULTAAT.

Required process variables

zaakUrl: full URL of 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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables

resultaattype: full URL of the RESULTAATTYPE to set. If provided the RESULTAAT is created before the ZAAK is closed

Optional process variables (Camunda exclusive)

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

Sets the process variables

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

class bptl.work_units.zgw.tasks.zaak.CreateZaakTask(task: bptl.tasks.models.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

zaaktype: the full URL of the ZAAKTYPE
organisatieRSIN: RSIN of the organisation
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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables

NLXProcessId: a process id for purpose registration (“doelbinding”)
NLXSubjectIdentifier: a subject identifier for purpose registration (“doelbinding”)
zaakDetails: 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.
initialStatusRemarks: a text to use for the remarks field on the initial status. Must be maximum 1000 characters.
initiator: 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.

Optional process variables (Camunda exclusive)

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

Sets the process variables

zaak: the JSON response of the created ZAAK
zaakUrl: the full URL of the created ZAAK
zaakIdentificatie: the identificatie of the created ZAAK

class bptl.work_units.zgw.tasks.zaak.LookupZaak(task: bptl.tasks.models.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: identification of the zaak, commonly known as “zaaknummer”
bronorganisatie: RSIN of the source organization for the zaak. The combination
of identificatie and bronorganisatie uniquely identifies a 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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables (Camunda exclusive)

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

Sets the process variables

zaakUrl: the 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: bptl.tasks.models.BaseTask)¶

Create a new STATUS for the ZAAK in the process.

Required process variables

zaakUrl: full URL of the ZAAK to create a new status for
statusVolgnummer: volgnummer of the status type as it occurs in the catalogus OR
statustype: full URL of the STATUSTYPE to set
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.
services: DEPRECATED - support will be removed in 1.1

Note that either statusVolgnummer or statustype are sufficient.

Optional process variables

toelichting: description of the STATUS

Optional process variables (Camunda exclusive)

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

Sets the process variables

statusUrl: the full URL of the created STATUS

class bptl.work_units.zgw.tasks.resultaat.CreateResultaatTask(task: bptl.tasks.models.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: full URL of the ZAAK to set the RESULTAAT for
resultaattype: full URL of the RESULTAATTYPE to set
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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables

toelichting

Optional process variables (Camunda exclusive)

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

Sets the process variables

resultaatUrl: the full URL of the created RESULTAAT

class bptl.work_units.zgw.tasks.zaak_relations.CreateEigenschap(task: bptl.tasks.models.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: URL reference to a ZAAK in a Zaken API. The eigenschap is created for this zaak.

eigenschap: a JSON Object containing the name and value:

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

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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables

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

Optional process variables (Camunda exclusive)

callbackUrl: 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: bptl.tasks.models.BaseTask)¶

Create a new ZAAKOBJECT for the ZAAK in the process.

Required process variables

zaakUrl: full URL of the ZAAK to create a new ZaakObject for
objectUrl: full URL of the OBJECT to set
objectType: type of the OBJECT
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.
services: DEPRECATED - support will be removed in 1.1

If zaakUrl is not given - returns empty dictionary.

Optional process variables

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

Optional process variables (Camunda exclusive)

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

Sets the process variables

zaakObjectUrl: the full URL of the created ZAAKOBJECT

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

Create relations between ZAAK and INFORMATIEOBJECT

Required process variables

zaakUrl: full URL of the ZAAK
informatieobject: full URL of the INFORMATIEOBJECT. If empty, no relation
will be created.
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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables (Camunda exclusive)

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

Sets the process variables

zaakinformatieobject: full URL of ZAAKINFORMATIEOBJECT

class bptl.work_units.zgw.tasks.zaak_relations.RelatePand(task: bptl.tasks.models.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: URL reference to a ZAAK in a Zaken API. The PANDen are related to this.
panden: list of URL references to PANDen in BAG API.
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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables

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

Optional process variables (Camunda exclusive)

callbackUrl: 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: bptl.tasks.models.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: URL reference to a ZAAK in a Zaken API. This zaak receives the relations.
zaakUrl: URL reference to another ZAAK in a Zaken API, to be related to zaakUrl.
bijdrageAard: the type of relation. One of vervolg, onderwerp or bijdrage.
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.
services: DEPRECATED - support will be removed in 1.1

Optional process variables

NLXProcessId: a process id for purpose registration (“doelbinding”)
NLXSubjectIdentifier: a subject identifier for purpose registration (“doelbinding”)
bijdrageAardOmgekeerdeRichting: 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: 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: bptl.tasks.models.BaseTask)¶

Lock a Documenten API document.

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

Required process variables

informatieobject: String, API URL 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: the application ID of the app that caused this task to be executed. The app-specific credentials will be used for the API calls.
services: DEPRECATED - support will be removed in 1.1

Sets the process variables

lockId: String, Lock ID for the locked document. Required to unlock or mutate the document.

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

Unlock a Documenten API document.

Required process variables

informatieobject: String, API URL 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: String, Lock ID for the locked DRC document, obtained from locking the document.
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.
services: DEPRECATED - support will be removed in 1.1

Sets no process variables

BRP¶

class bptl.work_units.brp.tasks.DegreeOfKinship(task: bptl.tasks.models.BaseTask)¶

Retrieve the degree of kinship from the BRP API.

Required process variables

burgerservicenummer1: BSN of the first person
burgerservicenummer2: BSN of the second person

Optional process variables

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, if provided.

Sets the process variables

kinship: integer, which represents the degree of kinship (blood relations). Values can be in
range [1..4] or Null if the BSNs are identical.

class bptl.work_units.brp.tasks.IsAboveAge(task: bptl.tasks.models.BaseTask)¶

Fetches BRP API and returns whether a person is exactly, or older than, a certain age.

Required process variables

burgerservicenummer: BSN of the person
age: integer, which represents the number of years

Optional process variables

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, if provided.

The task sets the process variables

isAboveAge: boolean, which indicate if the requested person is equal or above a certain age. If the information about person’s age is not found, isAboveAge will be set as none

Kadaster¶

bptl.work_units.kadaster.tasks.retrieve_openbare_ruimten(task: bptl.tasks.models.BaseTask) → Dict[str, Any]¶

Given a bounding box (or other polygon), retrieve the ‘public space’ objects contained/overlapping.

This consumes the BRT API to fetch relevant objects, which are returned so that they can be drawn/selected on maps as GeoJSON.

Checked resources:

Wegdeel
Terrein (in development)
Inrichtingselement (in development)

Required process variables

geometry: A GeoJSON geometry that is checked for overlap.

Optional process variables

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, if provided.

Sets the following return/process variables

features: a list of GeoJSON features, in EPSG:4258 CRS. Properties contain feature-specific keys/values.

Note

The kadaster geo query APIs have long response times (up to 40s) - this work unit takes a considerable time to execute.

Camunda¶

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

Start subprocess in Camunda

Required process variables

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

Optional process variables

subprocessDefinitionVersion: 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 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: instance id of the created subprocess

ValidSign¶

class bptl.work_units.valid_sign.tasks.CreateValidSignPackageTask(task: bptl.tasks.models.BaseTask)¶

Create a ValidSign package with signers and documents and send a signing request to the signers.

Required process variables

documents: List of strings. List of API URLs where the documents to be signed can be retrieved.
The API must comply with the Documenten API 1.0.x ( https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index).

signers: JSON list with signers information. For ValidSign, the first name, the last name and the

email address of each signer are required. Example signers:

[{
    "email": "example.signer@example.com",
    "firstName": "ExampleFirstName",
    "lastName": "ExampleLastName"
},
{
    "email": "another.signer@example.com",
    "firstName": "AnotherFirstName",
    "lastName": "AnotherLastName"
}]

packageName: string. Name of the ValidSign package that contains the documents to sign and the signers.
This name appears in the notification-email that is sent to the signers.

services: JSON Object of connection details for ZGW services:

{
    "<drc alias1>": {"jwt": "Bearer <JWT value>"},
    "<drc alias2>": {"jwt": "Bearer <JWT value>"}
}

Optional process variables

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, if provided.
messageId: string. The message ID to send back into the process when the
package is signed by everyone. You can use this to continue process execution. If left empty, then no message will be sent.

Sets the process variables

packageId: string. ID of the ValidSign package created by the task.

add_documents_and_approvals_to_package(package: dict) → List[dict]¶: Add documents and approvals to the package.

create_package() → dict¶: Create a ValidSign package with the name specified by the process variable and add the signers to it.

format_signers(signers: List[dict]) → List[dict]¶: Format the signer information into an array of JSON objects as needed by ValidSign.

send_package(package: dict)¶

Change the status of the package to ‘SENT’

When the status of the package is changed, an email is automatically sent to all the signers with a link where they can sign the documents.

exception bptl.work_units.valid_sign.tasks.DoesNotExist¶

exception bptl.work_units.valid_sign.tasks.NoAuth¶

exception bptl.work_units.valid_sign.tasks.NoService¶

class bptl.work_units.valid_sign.tasks.ValidSignReminderTask(task: bptl.tasks.models.BaseTask)¶

Email a reminder (with links) to signers that they need to sign documents through ValidSign.

Required process variables

packageId: string with the ValidSign Id of a package
email: the email address of the signer who needs a reminder

Optional process variables

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, if provided.

Sets no process variables

Email¶

class bptl.work_units.email.tasks.SendEmailTask(task: bptl.tasks.models.BaseTask)¶

This task sends an email to receiver signed by sender.

Required process variables

sender: JSON with required fields email and name of sender.

{
  "email": "kees@example.com",
  "name": "Kees Koos"
}

receiver: JSON with required fields email and name of receiver.

{
  "email": "jan@example.com",
  "name": "Jan Janssen"
}

email: JSON with required fields email subject and email content:

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

template: string with template name. Valid choices are:

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

context: JSON with optional fields:

{
  "kownslFrontendUrl": "https://kownsl.utrechtproeftuin.nl/kownsl/<uuid>/",
  "deadline`": "2020-04-20"
}

Kownsl¶

bptl.work_units.kownsl.tasks.get_approval_status(task: bptl.tasks.models.BaseTask) → dict¶

Get the result of an approval review request.

Once all reviewers have submitted their approval or rejection, derive the end-result from the review session. If all reviewers approve, the result is positive. If any rejections are present, the result is negative.

In the task binding, the service with alias kownsl must be connected, so that this task knows which endpoints to contact.

Required process variables

kownslReviewRequestId: the identifier of the Kownsl review request.

Optional process variables

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, if provided.

Sets the process variables

approvalResult: a JSON-object containing meta-data about the result:

{
   "approved": true,
   "num_approved": 3,
   "num_rejected": 0,
   "approvers": ["mpet001", "will002", "jozz001"]
}

bptl.work_units.kownsl.tasks.get_approval_toelichtingen(task: bptl.tasks.models.BaseTask) → dict¶

Get the “toelichtingen” of all reviewers that responded to the review request.

Required process variables

kownslReviewRequestId: the identifier of the Kownsl review request.

Optional process variables

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, if provided.

Sets the process variables

toelichtingen: a string containing the “toelichtingen” of all reviewers.

bptl.work_units.kownsl.tasks.get_email_details(task: bptl.tasks.models.BaseTask) → dict¶

Get email details required to build the email that is sent from the accordeer/adviseer sub processes in Camunda.

Required process variables

kownslReviewRequestId: the identifier of the Kownsl review request.
deadline: deadline of the review request.
kownslFrontendUrl: URL that takes you to the review request.

Optional process variables

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, if provided.

Sets the process variables

email: a JSON that holds the email content and subject.

{
    "subject": "Email subject",
    "content": "Email content",
}

context: a JSON that holds data relevant to the email:

{
    "deadline": "2020-12-31",
    "kownslFrontendUrl": "somekownslurl",
}

template: a string that determines which template will be used for the email.
senderUsername: a list that holds a string of the review requester’s username. This is used to determine the email’s sender’s details.

bptl.work_units.kownsl.tasks.get_review_request_reminder_date(task: bptl.tasks.models.BaseTask) → dict¶

Get the reminder for the set of reviewers who are requested. The returned value is the deadline minus one day.

In the task binding, the service with alias kownsl must be connected, so that this task knows which endpoints to contact.

Required process variables

kownslReviewRequestId: the identifier of the Kownsl review request.
kownslUsers: list of usernames that have been configured in the review request configuration.

Optional process variables

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, if provided.

Sets the process variables

reminderDate: a string containing the reminder date: “2020-02-29”.
deadline: a string containing the deadline date: “2020-03-01”.

bptl.work_units.kownsl.tasks.get_review_response_status(task: bptl.tasks.models.BaseTask) → dict¶

Get the reviewers who have not yet responded to a review request so that a reminder email can be sent to them if they exist.

In the task binding, the service with alias kownsl must be connected, so that this task knows which endpoints to contact.

Required process variables

kownslReviewRequestId: the identifier of the Kownsl review request.
kownslUsers: list of usernames that have been configured in the review request configuration.

Optional process variables

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, if provided.

Sets the process variables

remindThese: a JSON-object containing a list of usernames who need reminding:
```
[
    "user1",
    "user2",
]
```

bptl.work_units.kownsl.tasks.set_review_request_metadata(task: bptl.tasks.models.BaseTask) → dict¶

Set the metadata for a Kownsl review request.

Metadata is a set of arbitrary key-value labels, allowing you to attach extra data required for your process routing/handling.

Required process variables

kownslReviewRequestId: the identifier of the Kownsl review request.
metadata: a JSON structure holding key-values of the metadata. This will be set directly on the matching review request. Example:
```
{
    "processInstanceId": "aProcessInstanceId"
}
```

Optional process variables

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, if provided.

Sets no process variables

Xential¶

bptl.work_units.xential.tasks.start_xential_template(task: bptl.tasks.models.BaseTask) → dict¶

Run Xential template with requested variables.

If the interactive task variable is:

True: it returns a URL in bptlDocumentUrl for building a document interactively
False: it returns an empty string in bptlDocumentUrl

In the task binding, the service with alias xential must be connected, so that this task knows which endpoints to contact.

Required process variables

bptlAppId: the application ID in the BPTL credential store
templateUuid: the id of the template which should be started
interactive: bool, whether the process will be interactive or not
templateVariables: a JSON-object containing the data to fill the template. In an interactive flow, this can be an empty object {}:
```
{
   "variable1": "String",
   "variable2": "String"
}
```
documentMetadata: a JSON-object containing the fields required to create a document in the Documenten API. The fields shown below are required. The property ‘creatiedatum’ defaults to the day in which the document is sent to the Documenten API and the property ‘taal’ defaults to ‘nld’ (dutch).
```
{
   "bronorganisatie": "string",
   "titel": "string",
   "auteur": "string",
   "informatieobjecttype": "url"
}
```

Optional process variable

messageId: string. The message ID to send back into the process when the document is sent to the Documenten API. You can use this to continue process execution. If left empty, then no message will be sent.

Sets the process variable

bptlDocumentUrl: BPTL specific URL for interactive documents. If the document creation is not interactive, this will be empty.

ZAC¶

class bptl.work_units.zac.tasks.UserDetailsTask(task: bptl.tasks.models.BaseTask)¶

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

Required process variables

usernames: JSON with usernames.

[
    "user1",
    "user2",
    "user3"
]

OR

emailaddresses: JSON with email addresses.

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

Optional process variables

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, if provided.

Sets the process variables

userData: a JSON-object containing a list of user names and emails:

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

Camunda tasks¶

Module for Camunda API interaction.

bptl.camunda.utils.complete_task(task: bptl.camunda.models.ExternalTask, variables: Optional[Dict[str, Union[str, int, bool]]] = 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: bptl.camunda.models.ExternalTask, 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/