Fill primary key

See also: Save changes later

Event action – Abstract

Purpose: Returns an internal ID (as primary key) for a new or copied entity before saving (creating) it, so that it can be used immediately (e.g. as reference).

The Fill primary key event action can be used to pre-fill the primary key field 'ID' id of a new entity with a system-specified value so that it can be processed in the context of ongoing event handling before the entity is effectively stored in the database. This is necessary, for example, if references to the new entity (e.g. in the data of other entities) are also to be set up immediately in the course of event handling for the 'Create' event.

The primary key of an entity is the long value that the system automatically assigns to the 'ID' (id) field when it is saved. Until the transaction for the 'Create' event is successfully completed, the 'ID' (id) field of an entity that has been newly created or copied usually contains the value 0. It does not matter whether the entity that has not yet been saved was created by clicking 'New' or 'Copy' in the ribbon or, for example, by a Create instance event action.

►NOTE◄

  • If a transaction fails after executing the Fill primary key with an error, if it is 'rolled back' by an Abort, or if the entity is discarded by the user without saving, the ID already output for the entity type in question is 'lost'. So it will not be output again for the same entity type.

  • The Save changes later event action implies the effects of the Fill primary key immediately when the event action is executed, whereas the changes are saved 'later' (when the transaction is committed).

Configuration

images/download/attachments/69043301/image2021-3-5_9-46-46-version-1-modificationdate-1614934008234-api-v2.png

The Fill primary key event action does not use any parameters and always refers to the current reference object.

  • The reference object must be an entity, otherwise an error will occur.

  • If the reference object already has an ID (id) that is not 0, the Fill primary key event action has no effect. Whether the entity with the ID in question has already been saved is irrelevant.

  • If the Fill primary key is executed repeatedly with the same reference object, only the first call assigns an ID. The following calls have no effect.

Example

When creating a new company account with the Company type 'Forwarder' (FWD), a new address book for recipient Address book should be created automatically for this company. In this case, the owner of the address book should be the new company and not the Company of session automatically preassigned when creating an entity. The Fill primary key event action is required because when the 'Create' event is triggered (i.e. when the new company account is 'saved'), its ID (id) still has the value 0. When the new address book is created automatically, however, the owning company must be identified by its ID (id) via the 'Owner'(ownerId) field.

Configuration:

Within an event handling for the 'Create' event (see Common action event) in the context of a new company account, to which the Company type 'Forwarder' (FWD) is assigned in the field 'Company types' (types), the event actions shown on the right are configured:

  • The Fill primary key event action obtains the future ID from the server in advance for the new company account.

  • The Execute with event action creates a new address book via the Create instance_value_resolver. In the process, the new company account is stored in the newCompany variable so that characteristics of the company account can be accessed when setting up the address book in the following action block.

  • Save changes later flags the new address book to be saved in the course of the current transaction. It will be created together with the company account.

  • In a Set value event action, the ID (id) previously 'procured' via the Fill primary key is then transferred to the 'owner' (ownerId) field of the new address book. The Variable newCompany, which was set for the context of the Execute with event action, is accessed via the variable value resolver.

►NOTE◄ Below should follow further associations for the address book (e.g. name, Company type), but these will not be discussed in more detail here.

images/download/attachments/69043301/image2021-3-5_9-48-39-version-1-modificationdate-1614934121187-api-v2.png

►NOTE◄ The login used at runtime must ensure sufficient permissions to create the company account and an address book for the new company, otherwise the transaction will fail altogether with an error. Even though the Company of session will own the newly created company (by default), it may not automatically create an address book for that company. This can be achieved via Company authorizations.