# Key and assignment

Three keys pass back and forth between your backend system and the MACO APP.
Here you find for each of them who assigns it, where it is and when it is
mandatory. You find the values in the catalogues *Process triggers LF, NB,
MSB* (response 201) and *Backend write LF, NB, MSB* (field `zusatzdaten`).

## The three keys

| Field | Meaning | Who assigns | Where the value is |
|---|---|---|---|
| `businessKey` | The identifier of the process instance in the MACO APP | The MACO APP | In the response **201** of every trigger; when writing to your backend, in `zusatzdaten.businessKey` |
| `prozessId` | Your document number: the id of the document or record in your backend | Your backend | When triggering, in `zusatzdaten.prozessId`; returned in the callback in `zusatzdaten.prozessId` |
| `targetBusinessKey` | The `businessKey` of the initial process this call refers to | The MACO APP | When writing to your backend, in `zusatzdaten.targetBusinessKey` |

### Which one identifies the transaction in the MACO APP?

The **`businessKey`**. It is the identifier of the process instance and the only one of the
three that the MACO APP assigns itself. Your `prozessId` remains your document number;
the MACO APP carries it along and returns it, but does not make it the
process identifier.

The `targetBusinessKey` does not identify this transaction but the one it
responds to. Chain the transactions that belong together via the
`targetBusinessKey`, and do not rely on the
`businessKey` staying the same across them.

## Does the MACO APP take over your key?

**No.** The trigger returns its own `businessKey`; your
`prozessId` does not become the process identifier. You send your document number and
get back the identifier of the MACO process instance.

| Direction | You send | You receive |
|---|---|---|
| **Trigger** (`POST /inbound`) | `zusatzdaten.prozessId`, mandatory in every event | **201** with `businessKey` (uuid) and `message`, both mandatory |
| **Callback** (`createProcessData` / `updateProcessData`) | — | `zusatzdaten` with `businessKey`, `prozessId` and `targetBusinessKey` |

### When each key is mandatory

| Operation | `businessKey` | `targetBusinessKey` | `prozessId` (do not use for assignment) |
|---|---|---|---|
| `createProcessData` (LF, MSB, NB) | **Mandatory** | optional | optional |
| `updateProcessData` (LF, MSB, NB) | **Mandatory** | **Mandatory** | optional |
| `updateProcessData` — MaloIdent 03002 / 03003 (only LF) | not in the schema | **Mandatory** | **Mandatory** |

The MaloIdent responses follow a rule of their own: there your `prozessId` is
mandatory, and the `businessKey` does not occur.

:::caution{title="Do not assign a callback via the prozessId"}

In the callback, `zusatzdaten.prozessId` is optional, except for MaloIdent. Assign
incoming callbacks via the `businessKey` you received in the response 201.

:::

## The body of the callback

Send `updateProcessData` and `createProcessData`

```json
{ "stammdaten": { }, "transaktionsdaten": { }, "zusatzdaten": { } }
```

without an envelope. There is no `Process` object around the payload, no
list and no `data`. The `businessKey` is in `zusatzdaten`, not on the
body.

## The MaloIdent chain

The only flow in which the keys are chained across several
calls:

1. **Anfrage.** The `vorgangsnummer` corresponds to the header field `transactionId`;
   on a retry, the `idempodenzschluessel` carries the
   `initialTransactionId`.
2. **Response 03002 / 03003.** The `vorgangsreferenznummer` corresponds to the
   query parameter `referenceID` and thus to the `transactionId` from step 1.
   The response carries its own `vorgangsnummer`; `prozessId` and
   `targetBusinessKey` are mandatory.

:::caution{title="Do not equate the transaction number of the response with that of the request"}

Request and response each carry their own `vorgangsnummer`. Assign the
response via the `vorgangsreferenznummer`.

:::

## Opening a transaction in the user interface

| Address | What it shows |
|---|---|
| `<Backoffice>/transaction/<businessKey>` | The detail page of this transaction |
| `<Backoffice>/transaction/<targetBusinessKey>` | The detail page of the initial transaction (information from operations) |

The detail page is not in the menu; you reach it via this address or
from the monitors. You need to sign in, and what you see
depends on your role. Your operations team knows the host of your installation.