ImportTechnicalAssetsFromCSVExecutor

Long Running Task (LRT) that bulk-creates or updates Technical Assets in CzechIdM by reading a semicolon-separated CSV file. Each CSV row represents one technical asset. Besides the scalar attributes of the asset the task imports its guarantors and holders and its extended (EAV) attributes. It validates the whole row before it writes anything and supports dry-run mode.

@since 16.1.0

The task is the writing counterpart of the generic generic-entity-report export: there is no other bulk write path for technical assets, because the standard IdM export and import does not cover them and they cannot be synchronised from a target system.

• The task reads the attached CSV file line by line (first line = header).
• For each data row it looks up an existing Technical Asset by the value in the code column (matched against code, which is globally unique).
• Depending on whether the asset exists and which behaviour flags are set, the asset is created, updated or skipped.
• Before anything is written, the whole row is validated in one gate. Every problem found in the row is reported together and the row is aborted without a partial write.
• Optional columns assign guarantors and holders, and pairs of prefixed columns import extended attributes.
• All item-level results are written to the LRT task log.

The recommended column names follow the asset attributes of the generic report export, so an export can be edited and fed back in: `code`, `name`, `description`, `externalId`, `externalCode`, `validFrom`, `validTill`, `disabled`, `pam`, `zone`.

Each of the column parameters below is the exact name of a column in the CSV header (case-sensitive).

All flags are of type Boolean and default to false.

The value is trimmed first, so a cell containing only spaces behaves as empty.

• An unmapped column means the value is not touched.
• An empty cell of a mapped column clears the value, and it clears it to null, not to an empty string.

There are three deliberate exceptions.

read code from codecolumn; empty  ->  row fails
find the asset by code
  |- NOT FOUND + cancreate = false   ->  log CSV_IMPORT_ASSET_SKIPPED (NOT_EXECUTED), stop
  |- FOUND + canoverwrite = false    ->  log CSV_IMPORT_ASSET_SKIPPED (NOT_EXECUTED), stop

validatePreSave - one gate, nothing is written yet
  |- lengths of code, name, zone and the external identifiers; description
  |- name present for a new asset, not cleared for an existing one
  |- validFrom and validTill parsable, validity not inverted
  |- externalId / externalCode free, both in the database and within the file
  |- disabled and pam recognised boolean values
  |- transition to disabled = true on an existing asset requires candisable
  |     and the number of accounts the cascade will disable is counted here
  |- zone change requires canchangezone; with validatezone also a code list lookup
  |- every guarantor and holder username and role code resolved
  |- every extended attribute code present in the main form definition
  |- for an existing asset with linked accounts: the assignment check script
  |- any problem  ->  all problems joined into one CSV_IMPORT_ASSET_ERROR, row aborted

write
  |- save the asset (this is what triggers the cascade when it is being disabled)
  |- guarantors and holders: add only, or synchronise when replacerelations is on
  |- extended attribute values

The four relation columns can carry several values separated by the multi-value separator (default `|`). Whitespace around each value is trimmed.

jnovak|pdvorak|mmaly

The asset has four independent relation agendas: guarantors given by identity, guarantors given by role, holders by identity and holders by role. Each mapped column is processed on its own.

A relation that already exists is not duplicated, so repeated runs are idempotent. Assigning a guarantor or a holder does not grant the identity the techAssetGuarantorRole or techAssetHolderRole role; the task does not touch role assignments.

Values of extended (EAV) attributes are imported from pairs of prefixed columns. With eavcodeprefix set to `eavCode` and eavvalueprefix to `eavValue` the task reads `eavCode1` and `eavValue1`, then `eavCode2` and `eavValue2`, and so on for as long as both columns of the pair exist in the header. The number of pairs is not limited.

code;eavCode1;eavValue1;eavCode2;eavValue2
CORE-INFRA;costCentre;4711;environment;PROD

• The values always go into the main form definition of the technical asset. There is no parameter for choosing another definition.
• An attribute code that is not in the main definition fails the row.
• An empty value clears the attribute, consistently with the rule for ordinary columns.
• A multi-valued attribute is split by the multi-value separator.
• A pair whose code cell is empty is skipped - the value has nowhere to go.

The zone is an attribute of the asset. Two independent things guard it.

• canchangezone gates any change of the zone on an existing asset, clearing it included. Without the flag such a row fails.
• validatezone additionally checks the value against the items of the security-zones code list. The code list is created empty by the product and filled by the customer, so with an empty code list only an empty value passes.

Whether the resulting zone is acceptable for the accounts of the asset is a separate question, decided by the assignment check script below.

Whenever a row updates an existing asset that has technical accounts assigned, the pair (asset, account) is validated by a configurable Groovy script through TechnicalAssetService.isAssetAssignable. The script is named by the private configuration property idm.sec.tech.accountAssetAssignment.checkScript.

# Script deciding whether a technical asset may be assigned to an account.
# Default: nothing is enforced out of the box.
idm.sec.tech.accountAssetAssignment.checkScript=techAccountAssetAssignmentAllowAll

• techAccountAssetAssignmentAllowAll - the shipped default, always returns true.
• techAccountAssetAssignmentZoneMatch - requires the asset zone and the account zone to match; an asset without a zone is always accepted.

The check is evaluated on a candidate copy of the asset with the whole CSV row already applied, against every AccAccount the asset is assigned to. Because the script may decide by any attribute of the asset, the check runs for every row that updates an existing asset, not only when the zone column is mapped. When the script rejects a pair, the row fails with CSV_IMPORT_ASSET_ERROR before anything is written; the same happens in dry-run.

The transition to disabled = true on an existing asset is allowed only with candisable. When it happens, the item log of that row carries the number of accounts the cascade disabled, and the result code of the row is CSV_IMPORT_ASSET_UPDATED_WITH_CASCADE. Accounts that were already disabled are neither touched nor counted. A newly created asset has no accounts yet, so creating it as inactive is not gated.

The task supports CzechIdM's built-in dry-run flag. When dry-run is enabled:

• No asset is created or updated, no relation is changed and no extended attribute value is written.
• Rows that would be created or updated are logged with the WOULD_BE result codes and state NOT_EXECUTED.
• The full validation still runs, so a dry run reports the same row failures a real run would hit, a rejection by the assignment check script included.
• The size of the disabling cascade is reported as well, because it is counted during validation.
• Would-be operations are written to the application log at INFO level (prefix [DRY-RUN]).
• The task counter still increments, so the row count can be verified.

Creating assets with a code and a name only.

code;name
CORE-INFRA;Core Infrastructure
DATABASES;Databases
MAIL;Mail Platform

Task configuration:

code;name;description;externalId;validFrom;validTill;zone;disabled;pam;guarantors;holders;eavCode1;eavValue1
CORE-INFRA;Core Infrastructure;Shared infrastructure;EXT-1;2024-01-01;;ZONE_A;false;true;jnovak|pdvorak;mpolak;costCentre;4711
DATABASES;Databases;Database platform;EXT-2;2024-01-01;2026-12-31;ZONE_B;false;false;mpolak;jnovak;costCentre;4712

Task configuration:

• ImportTechnicalAccountsFromCSVExecutor - the sibling task importing Technical Accounts.