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.
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
Code
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:
- Anfrage. The
vorgangsnummercorresponds to the header fieldtransactionId; on a retry, theidempodenzschluesselcarries theinitialTransactionId. - Response 03002 / 03003. The
vorgangsreferenznummercorresponds to the query parameterreferenceIDand thus to thetransactionIdfrom step 1. The response carries its ownvorgangsnummer;prozessIdandtargetBusinessKeyare mandatory.
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.