Operating the Lerian SISBAJUD executor

This page describes how to set up and run the executor. Operating Lerian SISBAJUD describes the Mensageria. How the Lerian SISBAJUD executor runs orders describes what the executor does with each order.

Institution setup

Register each institution on the Mensageria and on the executor, with the same institutionId. Operating Lerian SISBAJUD describes the Mensageria request. POST /v1/institutions registers an institution on the executor. The body has these fields:

Field	Meaning
`institutionId`	The UUID of the institution. Use the same value as on the Mensageria.
`connectorType`	The ledger connector. Set it to `midaz`.
`institutionCode`	The CNPJ root of the institution, 8 digits.
`enabled`	Whether the institution is active. Send `true`.
`connectorMetadata`	The Midaz configuration of the institution. The tables below describe it.
`retryPolicyConfig`	Optional. The retry policy, as JSON.
`branchFormat`	Optional. A Go RE2 regular expression, at most 64 characters, for the branch number that a court can name in a block restriction.
`accountFormat`	Optional. A Go RE2 regular expression, at most 64 characters, for the account number that a court can name in a block restriction.

The request also creates the tokenization keyset and the audit keyset of the institution. A second request with the same institutionId returns 409. The executor records itself as the owner of the institution, from its own M2M identity (EXECUTOR_M2M_SUBJECT). No request field sets the owner, and a PATCH does not change it.

Connector metadata

Key	Required	Meaning
`organizations`	Yes	A list of `{organizationId, ledgers}` entries: the Midaz organizations that the executor searches for the accounts of a subject. Without `ledgers`, the executor searches every ledger of the organization.
`baseUrl`	Yes	The base URL of the Midaz ledger of the institution.
`authAddress`	When credentials are stored	The Access Manager address that issues the Midaz token of the institution.
`blockableBalances`	Yes	The Midaz balance keys that a block can use, for example `default`. These are balance keys, not the `available` or `onHold` amounts.
`blockableAccountTypes`	Yes	The account types that a block can use.
`salaryAccountTypes`	Yes	The account types that are salary accounts. Send `["NONE"]` when the institution has no salary account type.
`crmMode`	No	`legacy` or `embedded`. Without a value, the institution uses `MIDAZ_CRM_MODE`.
`crmBaseUrl`	No	The base URL of the standalone Midaz CRM, for `legacy`. With `embedded`, leave it empty: the executor reads the CRM through `baseUrl`.
`executorLedger`	To run orders	The ledger where the executor writes. The next table describes it.

Executor ledger

Key	Meaning
`organizationId`	The Midaz organization of the writes.
`ledgerId`	The Midaz ledger of the writes.
`asset`	Set it to `BRL`, exactly.
`judicialDepositAccountAlias`	The alias of the judicial deposit account. It must follow the Midaz alias rule.

The executor refuses an institution request whose executorLedger is present and not valid, with 400. At startup, the executor leaves out of its ledger routing an institution that has no valid executorLedger.

Connector credentials

PUT /v1/institutions/{institutionId}/connector-credentials writes the Midaz credentials of the institution:

ledger_client_id and ledger_client_secret are always required.
crm_client_id and crm_client_secret are required with crmMode legacy. With embedded, do not send them.

The executor encrypts the credentials before it stores them. PATCH /v1/institutions/{institutionId} refuses a body with credentials. A new credential does not revoke the previous one at the Access Manager, so revoke it there. The executor gets the Midaz token of the institution from {authAddress}/v1/login/oauth/access_token. When the institution has no stored credentials, the executor sends no Authorization header to Midaz.

Change the configuration

PATCH /v1/institutions/{institutionId} changes the fields of the institution. A connectorMetadata in the body replaces the whole bag, except the stored credentials.
PUT /v1/institutions/{institutionId}/connector-config replaces connectorType and connectorMetadata. It keeps the stored credentials, and it refuses a body with credentials.
GET /v1/institutions/{institutionId} returns the configuration without the credentials.

The executor reads the configuration of its institutions at startup. After you create an institution or change its configuration, restart the executor.

Ledger routing

With SYSTEMPLANE_ENABLED on, the executor serves the tenant documents of its accounting routes under /tenant-system. The executor reads two of them: routing.organizations turns on accounting routes for each organization, and routing.ledger_bindings holds the routes. With SYSTEMPLANE_ENABLED off, the executor writes without routes. GET /v1/admin/ledger-routing/preflight checks the routing configuration against the ledger of the institution. It writes nothing. A single-tenant executor needs the institutionId query parameter. The report covers these checks:

The transaction routes and the operation routes exist, and they match the writes of the executor.
A ledger that validates account types has sisbajud_block registered.
The judicial deposit account in executorLedger exists in the ledger and is not blocked.

The ready field reports whether the configuration is ready. The report shows the stored executorLedger. The running executor uses the configuration that it read at startup.

Orders that need attention

Operation	What it returns
`GET /v1/institutions/{institutionId}/executor/failed-orders`	The order revisions that the executor failed or abandoned. Each item has the order ID, the revision, a reason token, and the ID of its journal entry. It does not list the revisions whose outcome is not known yet.
`GET /v1/institutions/{institutionId}/executor/human-decisions`	The order revisions that the executor stopped on a human decision.

Each human decision has a humanDisposition:

GAVE_UP: the executor attempted no ledger write and answered EXECUTOR_GAVE_UP.
HELD_MONEY_MOVED: the executor attempted a write. Money can have moved, and the executor posted no answer.

The Mensageria also lists the orders that the executor gave up on. Operating Lerian SISBAJUD describes that list.

Credential key rotation

POST /v1/institutions/{institutionId}/security/credential-kek:rotate rotates the key that wraps the stored Midaz credentials of the institution. This key is not the institution-data key that the Mensageria rotates.

The rotation moves the stored credentials to the new key version. The credential values do not change. To replace a credential, use PUT /v1/institutions/{institutionId}/connector-credentials.
The response shows the previous and the new key version.
An institution with no stored credentials returns 404.
While another rotation of the same institution runs, a rotation returns 409.
With HashiCorp Vault as the key provider and STREAMING_ENABLED on, the rotation publishes a kek.rotated event with keyPurpose CREDENTIALS.

With PLUGIN_AUTH_ENABLED off, the executor does not serve this operation.

Audit verification

GET /v1/admin/audit/verify checks a range of the audit log of the institution, from fromIndex to toIndex. It does not decrypt any payload. It reports tampering and deleted entries.

Roles

Each operation needs one permission:

Operation	Permission
Create or update an institution, its connector configuration, or its credentials	`institution_config:write`
Read an institution, the failed orders, the human decisions, or the audit verification	`admin:read`
Credential key rotation	`credential_kek:rotate`
Ledger-routing preflight, and reads under `/tenant-system`	`tenant_policy:read`
Writes under `/tenant-system`	`tenant_policy:write`

The admin role holds every permission in this table. The operator, investigator, and compliance-officer roles hold admin:read. The systemplane permissions of /system go to the M2M role editor, and to no business role.

The executor on the Mensageria

The executor calls the execution API of the Mensageria with its own M2M client. Set the client in MENSAGERIA_CLIENT_ID and MENSAGERIA_CLIENT_SECRET. The executor gets its token from the Access Manager at PLUGIN_AUTH_HOST. On the Mensageria, the client holds the role br-sisbajud-executor-role. Integrating with Lerian SISBAJUD describes its permissions.

Listeners

The executor has two listeners:

Main API, at SERVER_ADDRESS. Set it to :4029, the port that the image exposes. It serves the operations of the API reference. It also serves /health, /readyz, and /version. With SYSTEMPLANE_ENABLED on, it serves /system and /tenant-system. With SWAGGER_ENABLED on, it serves /swagger.
Webhook listener, at EXECUTOR_HUB_WEBHOOK_ADDRESS. The default is :9082. It has one route, POST at EXECUTOR_HUB_WEBHOOK_PATH, whose default is /v1/webhooks/hub. Expose this port to the Streaming Hub, and use your ingress address plus this path as the subscription URL.

The webhook listener has no application authentication. It accepts a delivery only when the HMAC signature verifies with the subscription secret or with the previous secret. Outside DEPLOYMENT_MODE=local, the listener needs its own TLS certificate. As an alternative, terminate TLS in front of it and set EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED=true. /readyz includes two executor checks:

hub_webhook: the webhook listener.
executor_institutions: the number of institutions that the executor owns, and how many of them have ledger routing. This check does not fail readiness.

Deploy constraints

One tenant for each process. The executor does not start when its tenant list holds more than one tenant.
Its own database. The executor runs on its own empty PostgreSQL database. Its migrations refuse a database that already holds another migration history.
Restart after configuration changes. The executor reads its institutions at startup.
Termination grace period. Set the terminationGracePeriodSeconds of the pod to at least 90.

​Institution setup

​Connector metadata

​Executor ledger

​Connector credentials

​Change the configuration

​Ledger routing

​Orders that need attention

​Credential key rotation

​Audit verification

​Roles

​The executor on the Mensageria

​Listeners

​Deploy constraints